Skip to main content

Threads & Inboxes

Inboxes​

An Inbox is an on-chain account a wallet creates to receive threads. It acts as a public directory: senders look up your inbox to find where to deliver threads and what rules to follow.

Inbox Kinds​

KindDescription
StandardPersists across uses; the default for most applications
EphemeralLightweight, single-use style inbox for throwaway contexts

Inbox Metadata​

An inbox can store a name and metadata uri on-chain. The URI can point to an off-chain JSON file describing the inbox further (icon, description, etc.).

Thread Directory​

The inbox maintains a paginated list of all threads addressed to it. Each page is a separate on-chain account. Apps walk the pages to display a conversation list.

A wallet can have multiple inboxes (inbox 0, 1, 2, …), each with separate rules and thread lists.

Threads​

A Thread is the conversation container between exactly two wallets. It is created by the sender in the same transaction as the first message.

Thread Lifecycle​

1. Sender calls createThread(to, ...)  →  Thread account is created on-chain
2. Both parties can send messages (sendMessage)
3. Thread stays open indefinitely — there is no close operation

Thread Identity​

Each thread has:

  • A numeric thread ID (auto-assigned or caller-supplied)
  • On-chain addresses for both from and to wallets
  • A totalMsgs counter
  • An optional escrowPayment balance (if the inbox required escrow)

Messages​

Messages are appended to the thread by either party. Each message has:

  • A sequential msgSeq number
  • A messageType: Text, Url, or Irys
  • A content field: the text body, a URL, or an Irys CID
  • An optional attached payment

Loading Threads​

Threads are compressed accounts stored via Light Protocol. Reading them requires querying the Photon RPC indexer rather than the standard Solana RPC.

// Load a thread by numeric ID
const thread = await client.thread(42).load();

// Load all threads in an inbox
const threads = await inbox.loadThreadsAcrossBodies({ limit: 25 });

// Load all threads a wallet has sent or received
const activity = client.activity();
const threads = await activity.loadThreadsAcrossHistory({ limit: 50 });

Addressing​

When creating a thread, the sender must specify which inbox to target:

await client.createThread({
  to: recipientPublicKey,
  // targetInbox is optional; defaults to the receiver's inbox 0
});

If the receiver has a payment rule on their inbox, the SDK automatically includes the required payment. You can also explicitly specify the inbox:

const targetInbox = await client.inbox(1); // inbox ID 1 of the connected wallet
await client.createThread({ to, targetInbox });

SDK Reference​