> For the complete documentation index, see [llms.txt](https://wiki.4thtech.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://wiki.4thtech.io/protocols/occ-v1/message-flows.md).

# Message flows

Step-by-step flows for sending and reading a BlockMail and a BlockChat message on OCC v1.

{% hint style="warning" %}
**Status: Production-ready, stable.** OCC v1 is the 4thTech protocol for on-chain mail, chat and file transfer on any EVM chain. It is supported; no new features are planned. For agent-to-agent exchange, see OCC v2 ([AgentLink](https://wiki.4thtech.io/products/agentlink.md)).
{% endhint %}

## BlockMail: send and read

A mail is data-heavy, so only a link and a checksum go on chain.

```mermaid
sequenceDiagram
    participant S as Sender app
    participant R as Remote storage
    participant M as Mail contract
    participant X as Recipient app
    S->>S: Build envelope (subject, content, attachments)
    S->>R: Upload encrypted attachments
    S->>R: Upload encrypted envelope JSON
    R-->>S: Envelope link
    S->>M: Send mail (receiver, link, checksum, app ID, fee)
    M-->>X: Event: MailSent
    X->>M: Read mail record
    X->>R: Fetch envelope
    X->>X: Verify checksum
    X->>X: Decrypt envelope and attachments
    X->>M: Mark mail opened
```

*Figure: BlockMail stores encrypted content off chain and records its link and checksum on chain.*

1. The sender's app stores attachments (encrypted, if encryption is on), then the envelope.
2. The app sends the link and checksum to the Mail contract. If the receiver uses a whitelist, the sender must be on it.
3. The receiver's app sees the new-mail event, fetches the envelope, checks the checksum and decrypts.

## BlockChat: send a message

A chat message is short, so the encrypted message goes on chain directly.

```mermaid
sequenceDiagram
    participant A as Member A app
    participant C as Chat contract
    participant B as Member B app
    A->>A: Encrypt message (shared secret or group key)
    A->>C: Send message or add it to the group
    C-->>B: Event: MessageSent
    B->>C: Read message
    B->>B: Decrypt with the same key
    Note over A,C: Group: creator creates conversation with one encrypted key copy per member
    C-->>B: Events for members added or removed
```

*Figure: BlockChat records the encrypted message on chain; the recipient decrypts it with the shared secret (one-to-one) or their copy of the conversation key (group).*

1. One-to-one: the message is encrypted with the shared secret of the two accounts (AES with ECDH). Group: the creator creates the conversation, and each member gets an encrypted copy of the conversation key.
2. Messages are encrypted with that key (if encryption is on) and recorded on chain.
3. In a group, the creator can add members, which adds a key copy for them.

See [Encryption options](https://wiki.4thtech.io/protocols/occ-v1/encryption.md) for how keys are derived and [Storage](https://wiki.4thtech.io/protocols/occ-v1/storage.md) for where content lives.
