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:
| Limitation | Details |
|---|---|
| 3954-byte messages | Maximum plaintext size (standard mode); 3950 bytes in PSK mode. Longer text needs application-level fragmentation. |
| Metadata visible | Sender/recipient addresses and timing are public on-chain |
| No message deletion | Blockchain is immutable; messages persist forever |
| Cost per message | 0.001 ALGO within 1024 note bytes. A full note costs 0.001308 ALGO (see Economics) |
| 4.5s latency | Algorand block finality time |
| No deniability | Sender 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:
| Method | Minimum | Notes |
|---|---|---|
| Solo staking | 30,000 ALGO | Run your own node |
| Delegated staking | 30,000 ALGO | Delegate to a node operator |
| Liquid staking | Any amount | Via protocols like Folks Finance |
| Staking pools | Any amount | Community-operated pools |
Example at ~5% APY:
| ALGO Staked | Annual Rewards | Messages 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
| Property | Status |
|---|---|
| Message content confidentiality | Protected (E2EE) |
| Message integrity | Protected (authenticated encryption) |
| Forward secrecy | Not provided. A long-term key or the recovery phrase can open old messages. |
| Replay attacks | A repeated signed transaction is rejected. Extra lock also checks a counter. |
| Post-quantum key exchange | A 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 privacy | Not protected (addresses, timing visible) |
| Traffic analysis | Not protected |
See SECURITY.md for the full threat model.
Documentation
| Document | Description |
|---|---|
| PROTOCOL.md | Full protocol specification |
| IMPLEMENTATION.md | Language-agnostic implementation guide |
| TEST-VECTORS.md | Canonical test vectors for verification |
| SECURITY.md | Security considerations and threat model |
Implementations
| Language | Monorepo path | Status |
|---|---|---|
| Swift | swift/ | Production |
| TypeScript | ts/ | Active |
| Python | py/ | Active |
| Rust | rs/ | Active |
| Kotlin | kt/ | Active |
| Go | go/ | Active |
The specification and all six libraries live in the AlgoChat monorepo. Use Raven for AlgoChat messaging in your browser.
Technical Summary
Cryptographic Primitives
| Function | Algorithm | Reference |
|---|---|---|
| Key Agreement | X25519 ECDH | RFC 7748 |
| Hybrid key encapsulation | ML-KEM-768, combined with X25519 | FIPS 203 |
| Encryption | ChaCha20-Poly1305 | RFC 8439 |
| Key Derivation | HKDF-SHA256 | RFC 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
Legal Notice
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.