Skip to content

Overview: AlgoChat protocol docs

Getting started

Encrypted, immutable annotations for Algorand transactions.

What Is This?

AlgoChat is a protocol for attaching end-to-end encrypted messages to Algorand transactions. Think of it as cryptographic memos that only the sender and recipient can read, permanently recorded on-chain.

AlgoChat is the protocol. Raven is the messenger. A new Raven chat starts as a hybrid session. The protocol is encrypted communication tied to an Algorand payment.

Use Cases

  • Payment Memos - Attach private notes to payments ("Invoice #1234", "March rent")
  • On-Chain Attestations - Cryptographic proof that you said X to Y at time Z
  • Transaction Receipts - Encrypted confirmation details readable by both parties
  • Audit Trails - Immutable, timestamped communication records
  • Escrow Instructions - Private terms attached to smart contract interactions

Limitations

Be aware of what this protocol cannot do:

LimitationDetails
3954-byte messagesMaximum plaintext size (standard mode); 3950 bytes in PSK mode. Longer text needs application-level fragmentation.
Metadata visibleSender/recipient addresses and timing are public on-chain
No message deletionBlockchain is immutable; messages persist forever
Cost per message0.001 ALGO within 1024 note bytes. A full note costs 0.001308 ALGO (see Economics)
4.5s latencyAlgorand block finality time
No deniabilitySender attribution is included in the envelope

Economics

A message whose note stays within 1024 bytes costs 0.001 ALGO. A longer note adds a small per-byte surcharge, and a full 4096-byte note costs 0.001308 ALGO. Algorand staking rewards can offset or exceed this cost.

Staking Options:

MethodMinimumNotes
Solo staking30,000 ALGORun your own node
Delegated staking30,000 ALGODelegate to a node operator
Liquid stakingAny amountVia protocols like Folks Finance
Staking poolsAny amountCommunity-operated pools

Example at ~5% APY:

ALGO StakedAnnual RewardsMessages Funded/Year
30,000~1,500 ALGO~1,500,000
100,000~5,000 ALGO~5,000,000

Note: APY rates are illustrative and vary by governance period. Actual rewards depend on total network participation and governance proposals. Check current rates at Algorand Foundation.

Users with less than 30K ALGO can participate through liquid staking or pools. The more you contribute to Algorand infrastructure, the more utility you extract: active participants get free encrypted communications, while casual users pay minimal per-message fees.

Security Properties

PropertyStatus
Message content confidentialityProtected (E2EE)
Message integrityProtected (authenticated encryption)
Forward secrecyNot provided. A long-term key or the recovery phrase can open old messages.
Replay attacksA repeated signed transaction is rejected. Extra lock also checks a counter.
Post-quantum key exchangeA hybrid session is category 3: X25519 plus ML-KEM-768. Everyday chat is level 0. Extra lock is level 1 only while its 32-byte secret stays secret.
Metadata privacyNot protected (addresses, timing visible)
Traffic analysisNot protected

See SECURITY.md for the full threat model.

Documentation

DocumentDescription
PROTOCOL.mdFull protocol specification
IMPLEMENTATION.mdLanguage-agnostic implementation guide
TEST-VECTORS.mdCanonical test vectors for verification
SECURITY.mdSecurity considerations and threat model

Implementations

LanguageMonorepo pathStatus
Swiftswift/Production
TypeScriptts/Active
Pythonpy/Active
Rustrs/Active
Kotlinkt/Active
Gogo/Active

The specification and all six libraries live in the AlgoChat monorepo. Use Raven for AlgoChat messaging in your browser.

Technical Summary

Cryptographic Primitives

FunctionAlgorithmReference
Key AgreementX25519 ECDHRFC 7748
Hybrid key encapsulationML-KEM-768, combined with X25519FIPS 203
EncryptionChaCha20-Poly1305RFC 8439
Key DerivationHKDF-SHA256RFC 5869

These are the same primitives used by Signal, WireGuard, and TLS 1.3.

Wire Format (v1 Standard - 0x01)

[version: 1][protocol: 1][sender_pubkey: 32][ephemeral_pubkey: 32][nonce: 12][encrypted_sender_key: 48][ciphertext: variable]
  • Header size: 126 bytes (fixed overhead)
  • Max plaintext: 3954 bytes
  • Total envelope: 4096 bytes (Algorand note field limit)

Wire Format (v1.1 PSK - 0x02)

[version: 1][protocol: 2][ratchet_counter: 4][sender_pubkey: 32][ephemeral_pubkey: 32][nonce: 12][encrypted_sender_key: 48][ciphertext: variable]
  • Header size: 130 bytes (126 + 4-byte ratchet counter)
  • Max plaintext: 3950 bytes
  • Extra lock: X25519 plus a 32-byte secret that stays off the chain. Category 1 only while that secret stays secret. Not a stronger post-quantum choice than hybrid.

Hybrid session (0x04 then 0x05)

A new Raven chat starts here. One handshake establishes a session key from X25519 and ML-KEM-768. Later messages reuse that key. The message header is 78 bytes. This is category 3. It is not forward secrecy, and it does not stack on Extra lock. If the other person has not published a hybrid key, Raven says so and does not switch that chat to everyday.

Transport

Messages are the note field of standard Algorand payment transactions:

sender  → recipient
amount  = 0 ALGO (or any payment amount)
note    = <encrypted AlgoChat envelope>
fee     = 0.001 ALGO within 1024 note bytes, more past that

This software is provided for legitimate uses including:

  • Private payment annotations
  • Confidential business communications
  • Research and educational purposes

Users are responsible for compliance with applicable laws. This includes but is not limited to:

  • Export controls on cryptographic software
  • AML/KYC regulations in your jurisdiction
  • Data protection laws (GDPR, CCPA, etc.)
  • Sanctions compliance

This protocol does not provide lawful intercept capabilities and cannot comply with key escrow requirements. Consult legal counsel before deploying in regulated environments.

Contributing

Contributions are welcome. Please read the protocol specification before proposing changes.

License

MIT License - see LICENSE for details.