@txtcel/protocol

TypeScript SDK for the Txtcel Solana program: instruction builders, account codecs and PDA derivation.

latest

Source

npm

Version: 0.12.0

Version published: 2 weeks ago

Maintainers: 1

Created: 2 months ago

Source

@txtcel/protocol

TypeScript SDK for the Txtcel on-chain program: instruction builders, PDA derivation, account codecs, and high-level messaging helpers. This document is the instruction reference.

npm install @txtcel/protocol

Every builder takes the deployed programId explicitly — the SDK hardcodes no program address and no RPC endpoint. The 32-byte seed used throughout is the thread's identity: the thread account's pubkey bytes (deriveThreadPda(programId, seed) simply returns new PublicKey(seed)).

High-level helpers

The usual way to talk to the program. They load on-chain state, pick candidate slots and shards, size fees with the max_fee slippage cap, and split long messages into FillSlot + AppendContent chunks automatically.

Helper	What it does
`createRootAlloc(connection, programId, payer, messageFee?, title?)`	Creates a channel (fresh thread keypair + seq-0 page); returns `{ signature, seed, threadPda, allocPda }`
`createRootAllocWithWallet(connection, programId, wallet, messageFee?, title?)`	Same, signing with a wallet adapter instead of a `Keypair`
`sendMessageWithWallet(connection, programId, wallet, seed, text, replyTo?)`	Posts a message end-to-end with one wallet approval; chains an extend transaction when the tail page qualifies
`buildSendMessageTransactions(connection, programId, payerKey, seed, text, replyTo?)`	Builds the unsigned post transactions (chunked for long messages) over a rolling 2-page candidate window
`buildExtendAllocTransaction(connection, programId, payerKey, seed)`	Builds a witnessed `PrepareAlloc` transaction when the tail page is extendable, otherwise `null`
`sendWithWallet` / `signAllWithWallet` / `pollConfirmation`	Wallet-adapter signing and confirmation utilities

Sizing utilities: maxFillSlotTextLen() / maxAppendChunkLen() (how much text fits per transaction), ensureTextBytes(text) (validate + encode), pageCandidates(programId, seed, allocSeq) (candidate slot list for a page).

Instruction builders

One builder per on-chain instruction. Each returns a TransactionInstruction with all PDAs derived internally from programId and seed; you only supply wallets, indexes, and amounts. Signer requirements mirror the program (see the program README for account-level detail).

Threads & messaging

On-chain instruction	Builder	Notes
`CreateRootAlloc` (0)	`buildCreateRootAllocInstruction(programId, payer, seed, messageFee, title)`	`seed` must be the pubkey of a fresh thread keypair that co-signs
`FillSlot` (1)	`buildFillSlotInstruction(opts)`	Options object: payer, seed, kind, body, candidate slots, shard indexes, reply pointer, `maxFee`
`PrepareAlloc` (2)	`buildPrepareAllocInstruction(programId, payer, seed, allocSeq, witnessSlots?)`	Empty `witnessSlots` on the author/time-hatch paths; 24 occupied tail slots on the witness path
`AppendContent` (23)	`buildAppendContentInstruction(...)`	Author-only, within 120 s of the message's creation
`CloseAccount` (5)	`buildCloseAccountInstruction(...)`	Author-only; resets the slot's like counter
`LikeContent` (20)	`buildLikeContentInstruction(...)`	Paid like; split between author and treasury

Access control

On-chain instruction	Builder
`InitThreadAccess` (8)	`buildInitThreadAccessInstruction(...)`
`SetThreadAccess` (9)	`buildSetThreadAccessInstruction(...)`
`AddToWhitelist` (10)	`buildAddToWhitelistInstruction(...)`
`RemoveFromWhitelist` (11)	`buildRemoveFromWhitelistInstruction(...)`
`AddToBlacklist` (21)	`buildAddToBlacklistInstruction(...)`
`RemoveFromBlacklist` (22)	`buildRemoveFromBlacklistInstruction(...)`
`AddToFeeWhitelist` (25)	`buildAddToFeeWhitelistInstruction(...)`
`RemoveFromFeeWhitelist` (26)	`buildRemoveFromFeeWhitelistInstruction(...)`
`RequestAccess` (19)	`buildRequestAccessInstruction(...)` — self-admission, pays the entry fee with a `maxFee` cap

Follows

On-chain instruction	Builder
`Subscribe` (27)	`buildSubscribeInstruction(opts)` — options: `programId`, `user`, `seed`
`Unsubscribe` (28)	`buildUnsubscribeInstruction(opts)` — same options; refunds the freed registry rent

Thread fees & sweeps

On-chain instruction	Builder
`SetMessageFee` (12)	`buildSetMessageFeeInstruction(...)` — author-only
`SetLikeFee` (17)	`buildSetLikeFeeInstruction(...)` — author-only
`SetEntryFee` (18)	`buildSetEntryFeeInstruction(...)` — access-admin-only
`SweepWalletFees` (41)	`buildSweepWalletFeesInstruction(...)` — owner-signed payout of the wallet's fee shards (message, entry, like and subthread fees)
`SweepTreasury` (3)	`buildSweepTreasuryInstruction(...)` — permissionless crank; pays out to the configured treasury only

Instructions 4 (SweepAuthorFees) and 40 (SweepSubthreadFees) are retired on-chain and return an error; all author-side fees now accrue into per-wallet fee shards swept by SweepWalletFees.

Channel metadata

On-chain instruction	Builder
`SetDescription` (42)	`buildSetDescriptionInstruction(programId, authority, seed, description, treasuryShardIdx)` — author-only; sets/updates the channel description (≤ 512 UTF-8 bytes) in its sidecar PDA, empty string clears it and refunds the rent

Program administration

On-chain instruction	Builder
`InitSettings` (6)	`buildInitSettingsInstruction(...)` — upgrade-authority-signed bootstrap
`SetTreasury` (7)	`buildSetTreasuryInstruction(...)` — admin-only
`SetAdmin` (24)	`buildSetAdminInstruction(...)` — admin-only; proposes a new admin (step 1 of 2, all-zero pubkey cancels)
`AcceptAdmin` (29)	`buildAcceptAdminInstruction(...)` — signed by the proposed wallet; promotes `pendingAdmin` to `admin` (step 2 of 2)
`SetBaseFee` (13)	`buildSetBaseFeeInstruction(...)` — admin-only, ≤ 5 000 bps
`SetAuthorFeeCut` (14)	`buildSetAuthorFeeCutInstruction(...)` — admin-only, ≤ 5 000 bps
`SetEntryCut` (15)	`buildSetEntryCutInstruction(...)` — admin-only, ≤ 5 000 bps
`SetLikeCut` (16)	`buildSetLikeCutInstruction(...)` — admin-only, ≤ 5 000 bps

The raw instruction tags are exported as the Instruction constant (e.g. Instruction.FillSlot === 1).

PDA derivation

Function	Seeds
`deriveThreadPda(programId, seed)`	not a PDA — returns `new PublicKey(seed)`
`deriveAllocPda(programId, seed, allocSeq)`	`["alloc", seed, u32(allocSeq)]`
`deriveContentPda(programId, seed, allocSeq, slot)`	`["content", seed, u32(allocSeq), u8(slot)]`
`deriveSettingsPda(programId)`	`["settings"]`
`deriveAccessPda(programId, seed)`	`["access", seed]`
`deriveAccessEntryPda(programId, seed, wallet)`	`["acl", seed, wallet]`
`deriveLikesPda(programId, seed, allocSeq)`	`["likes", seed, u32(allocSeq)]`
`deriveTreasuryShardPda(programId, idx)`	`["treasury_shard", u16(idx)]`
`deriveWalletFeePda(programId, owner, idx)`	`["wallet_fee", owner, u8(idx)]`
`deriveFollowRegistryPda(programId, wallet)`	`["follows", wallet]`
`deriveFollowerShardPda(programId, seed, idx)`	`["follower_count", seed, u8(idx)]`
`deriveDescriptionPda(programId, seed)`	`["description", seed]`
`deriveProgramDataPda(programId)`	canonical BPF-loader `ProgramData` address

Shard pickers: randomTreasuryShard() (0–511), randomWalletFeeShard() (0–31), followerShardIndex(wallet) (0–7, derived from the wallet).

Account loaders

Typed fetch + Borsh decode of program accounts:

loadThreadNode, loadAllocNode, loadContentNode, loadProgramSettings, loadThreadAccess, loadAllocLikes, loadAccessEntries, loadFollowRegistry, loadFollowerCount, loadWalletFeeBalances (per-shard earnings + sweepable total for a wallet), loadThreadDescription (returns null when the channel has no description), and loadThreadNodesBatched (tolerant batch loader for channel lists).