API reference
Every endpoint of the Talaria API and of a relay, with parameters, bodies, responses, errors and the Log stream.
The API serves what the chain holds, as public data: the Log, the pool, inboxes, relays and figures. It builds and follows the wallet transactions that open an inbox, buy a pass and rotate a key. A relay serves two endpoints of its own, GET /info and POST /post. Nothing either serves is private, so there are no accounts, no sign-in and no keys to send.
The SDK calls these endpoints for you; this page is for reading the Log and the pool directly, and for building a client of your own.
Base URLs#
| Service | Local build |
|---|---|
| API | http://127.0.0.1:6710 |
| Relay 1 | http://127.0.0.1:6711 |
| Relay 2 | http://127.0.0.1:6712 |
@talaria/contract holds a typed client for both, built on the same schemas the servers validate with, and the OpenAPI 3.1 document as @talaria/contract/openapi.json.
import { createClient, createRelayClient } from '@talaria/contract'
const api = createClient('http://127.0.0.1:6710')
const relay = createRelayClient('http://127.0.0.1:6711')
Conventions#
- Values. Lamport amounts, counts, slots, days, Log positions and pool indices are unsigned decimal strings. Addresses and signatures are base58. Keys, proofs and payloads are padded canonical base64. Field elements (roots, nullifiers, commitments, the payload hash) are decimal BN254 scalars. Times are UTC ISO strings.
- Day. A day is
floor(unix seconds / dayLengthSeconds), with the day length fromGET /pool. - Requests. A
POSTsendsContent-Type: application/json. The API takes bodies up to 1 MiB and a relay up to 16,384 bytes. - Headers. Every response carries
X-Request-IdandX-Contract-Version(0.3.0), andCache-Control: no-storeunless the route sets its own. - Origins. A browser request is accepted from the Talaria web origins only (development: ports 6700 and 6701 on
127.0.0.1andlocalhost). Requests without anOriginheader, from servers and scripts, are accepted. - Whole downloads. No read takes a wallet, a recipient or a name. A client downloads the whole Log, every pool leaf and the whole inbox directory and filters on its own device, so the API never learns which entries or which pass are someone's, or which wallet a device looks up, writes to or hears from, its own included.
.solnames resolve on the device too (seelookup). The only requests that carry a wallet are the builds of that wallet's own transactions.
Errors#
Every failure answers with one envelope, whatever the endpoint: a JSON object whose error holds these fields.
- codestring
- The code to branch on. Every code and its HTTP status is in API errors.
Required
- messagestring
- A sentence to show.
Required
- retryableboolean
- Whether the same request can succeed later.
Required
- stagestring
- Where it failed:
validation,auth,read,upload,build,wallet,co_sign,simulation,sendorconfirmation.Required
- fieldErrorsobject
- For
VALIDATION_ERROR: messages per field path. - programErrorobject
- For a program refusal:
programId,nameandnumber. - retryAfterSecondsinteger
- When to try again.
- requestIdstring
- For
INTERNAL_ERROR: the request's id.
Every endpoint answers VALIDATION_ERROR (400) for a malformed path, query or body, UNSUPPORTED_MEDIA_TYPE (415) for a POST that is not JSON, PAYLOAD_TOO_LARGE (413) over the body limit, ORIGIN_NOT_ALLOWED (403) for an unknown browser origin and INTERNAL_ERROR (500, retryable) when the request could not be completed. An unknown route answers NOT_FOUND. The sections below list each endpoint's own codes. The contract client throws an ApiClientError with status, code and the body.
GET /health#
The service's readiness. The API and each relay serve it.
curl http://127.0.0.1:6710/health
const health = await api.health()
- status'ready' | 'waiting' | 'fixture'
fixturewhen the service serves fixtures.Required
- role'api' | 'relay' | 'indexer' | 'keeper'
- Which service answered.
Required
- contractVersionstring
- The contract version,
0.3.0.Required
- asOfTimestamp
- When it answered.
Required
GET /log/head#
Where the Log stands: how many entries it has, how many sealed segments, and every entry after the last sealed segment. A full download is every segment from 0 to segmentCount - 1, then tail.
curl http://127.0.0.1:6710/log/head
const head = await api.logHead()
- entriesU64
- Entries in the Log.
Required
- segmentCountU64
- Sealed segments.
Required
- segmentSizeinteger
- Entries per sealed segment: 256.
Required
- tailLogEntry[]
- The entries after the last sealed segment, in order.
Required
- lastIndexU64 | null
- The last entry's position.
Required
- lastSignatureSignature | null
- The last entry's signature.
Required
- slotU64
- The last entry's slot,
0for an empty Log.Required
- asOfTimestamp
- When it was read.
Required
GET /log/segments/:n#
One sealed segment of the Log: 256 complete entries that never change. Its response is cacheable for a year (Cache-Control: public, max-age=31536000, immutable).
- nU64
- The segment number, from
0tosegmentCount - 1.Required
curl http://127.0.0.1:6710/log/segments/0
const segment = await api.logSegment('0')
- numberU64
- The segment number.
Required
- firstIndexU64
- Its first entry's position.
Required
- lastIndexU64
- Its last entry's position.
Required
- entriesLogEntry[]
- Its entries, in order.
Required
Errors: LOG_SEGMENT_NOT_FOUND (404) for a segment that is not sealed.
GET /log/stream#
Every new Log entry as it is read, over Server-Sent Events. There is no filter: every client receives every entry.
- sessionstring
- Fixture mode only: a fixture session id, 1 to 64 of
A-Z a-z 0-9 _ -.
Each event is named by its type, carries an id, and has as its data one JSON envelope with type, id, timestamp and data:
event: entry
id: <event id>
data: {"type":"entry","id":"<event id>","timestamp":"<UTC time>","data":<LogEntry>}
| Event | data |
|---|---|
ready | status (ready, waiting or fixture) and head, a GET /log/head response. Sent first on every connection. |
entry | A complete LogEntry. |
resync | reason: reconnected or behind. |
Nothing is replayed. A client that reconnects with Last-Event-ID receives resync with reconnected before ready; a client more than 500 events behind has its queue replaced by resync with behind. On resync, fetch the head and any segments you are missing. During the handover from download to stream an entry can arrive twice: keep entries by index. An idle stream receives a comment line every 15 s. Validate each event with LogStreamEvent from the contract.
import { createClient, LogStreamEvent } from '@talaria/contract'
const api = createClient('http://127.0.0.1:6710')
const stream = new EventSource(api.logStreamUrl())
for (const type of ['ready', 'entry', 'resync']) {
stream.addEventListener(type, (event) => {
const parsed = LogStreamEvent.parse(JSON.parse((event as MessageEvent<string>).data))
if (parsed.type === 'entry') console.log(parsed.data.index, parsed.data.signature)
else if (parsed.type === 'resync') console.log('refetch the head and missing segments:', parsed.data.reason)
else console.log('ready at', parsed.data.head.entries)
})
}
curl -N http://127.0.0.1:6710/log/stream
GET /log/entries/:signature#
One Log entry by its transaction signature, with its decoded payload, public inputs and verification. This is what On chain shows for a message.
- signatureSignature
- The
posttransaction's signature.Required
curl http://127.0.0.1:6710/log/entries/27qt7MXJL62zFfqteY8N6g5jTaDohGCdiNcnqGUX9QKLSK1b5Dr1yZf3c3UxQrUH2YEcfAkvuqHjqVkscSt1fRTv
const entry = await api.logEntry(signature)
Returns a LogEntry. Errors: LOG_ENTRY_NOT_INDEXED (404, retryable) for a signature that is not, or not yet, an indexed post. The SDK reads this endpoint until the entry appears to report a part as landed.
GET /pool#
The pool and the pass prices, read from the program's Config and Pool accounts.
curl http://127.0.0.1:6710/pool
const pool = await api.pool()
- rootFieldElement
- The current root.
Required
- sizeU64
- Leaves in the pool: every pass ever bought.
Required
- treeHeight26
- The tree's height.
Required
- dayDay
- Today, from the latest block time.
Required
- dayLengthSecondsinteger
- The day length.
Required
- tiersPassTier[]
- Each tier:
id(light,daily,frequent) anddailyLimit.Required
- lengthsinteger[]
- The pass lengths offered, in days.
Required
- pricesPassPrice[]
- Every tier and length:
tierId,dailyLimit,days,priceLamports.Required
- messageFeeLamportsU64
- The message fee.
Required
- relayFeeLamportsU64
- The relay fee.
Required
- protocolShareBpsinteger | null
- The protocol's share of pass sales, in basis points.
Required
- feeVaultBalanceLamportsU64
- The FeeVault's balance.
Required
- vaultBalanceLamportsU64
- The Vault's balance.
Required
- asOfTimestamp
- When it was read.
Required
A price is dailyLimit × days × messageFeeLamports. Configuration covers each value.
GET /pool/leaves#
Every pool leaf from an index on, so a client can build the tree and its own Merkle path without saying which leaf is its own.
- fromU64
- The first leaf index, inclusive.
Default
0
curl "http://127.0.0.1:6710/pool/leaves?from=0"
const leaves = await api.poolLeaves({ from: '0' })
- fromU64
- The first index returned.
Required
- nextU64
- The index after the last leaf: the
fromof the next call.Required
- totalU64
- Leaves in the pool.
Required
- rootFieldElement
- The root these leaves build.
Required
- leavesPoolLeaf[]
- Every leaf from
fromthroughnext - 1, up to 4,096 a call.Required
- asOfTimestamp
- When it was read.
Required
Call again with from set to next until next equals total.
GET /inboxes/head#
Where the inbox directory stands. The directory is every open_inbox and rotate_inbox_key that landed, one InboxEvent each, in chain order. Like the Log, it is downloaded whole: every sealed segment from 0 to segmentCount - 1, then tail. No request names a wallet, so the API never learns which wallet a device looks up.
curl http://127.0.0.1:6710/inboxes/head
const head = await api.inboxHead()
await talaria.syncDirectory()
- eventsU64
- Events in the directory.
Required
- segmentCountU64
- Sealed segments.
Required
- segmentSizeinteger
- Events per sealed segment: 256.
Required
- tailInboxEvent[]
- The events after the last sealed segment, in order.
Required
- asOfTimestamp
- When it was read.
Required
A wallet's Inbox is the fold of its events in order: the latest event gives inboxKey and keyVersion, the first gives openedSlot and openedAt, and each event's key is valid from its slot until the slot of the wallet's next event. The SDK folds it on the device through syncDirectory.
GET /inboxes/segments/:n#
One sealed segment of the inbox directory: 256 events that never change. Its response is cacheable for a year (Cache-Control: public, max-age=31536000, immutable).
- nU64
- The segment number, from
0tosegmentCount - 1.Required
curl http://127.0.0.1:6710/inboxes/segments/0
const segment = await api.inboxSegment('0')
- numberU64
- The segment number.
Required
- firstIndexU64
- Its first event's position.
Required
- lastIndexU64
- Its last event's position.
Required
- eventsInboxEvent[]
- Its events, in order.
Required
Errors: LOG_SEGMENT_NOT_FOUND (404) for a segment that is not sealed.
A full download with the contract client:
const head = await api.inboxHead()
const events = []
for (let n = 0n; n < BigInt(head.segmentCount); n++) events.push(...(await api.inboxSegment(String(n))).events)
events.push(...head.tail)
GET /relays#
The relays the API knows, with what each has carried. Each relay in the API's list is read live from its own GET /info. A relay the indexed record holds, because it has carried a post, and that is not in the list or does not answer, is listed with status: 'waiting', the fee recorded for it and the endpoint https://relay.unknown. A relay in the list that does not answer and has carried no post is left out. The call does not fail when a relay is unreachable.
curl http://127.0.0.1:6710/relays
const { relays } = await api.relays()
- relaysRelay[]
- Each relay: the fields of
RelayInfoplus the four below.Required
- asOfTimestamp
- When it was read.
Required
- postsTodayU64
- Log entries it submitted today.
Required
- postsAllTimeU64
- Log entries it submitted.
Required
- earnedLamportsU64
postsAllTime × feeLamports.Required
- lastPostAtTimestamp | null
- Block time of its latest entry.
Required
This is the list Relays shows, and the list the SDK posts through when it has no relayUrls of its own.
GET /stats#
The figures the Log shows.
curl http://127.0.0.1:6710/stats
const stats = await api.stats()
- passesInPoolU64
- Leaves in the pool.
Required
- messagesTodayU64
- Log entries of today.
Required
- messagesAllTimeU64
- Log entries.
Required
- relaysActiveU64
- Relays
GET /relayslists with statusready.Required
- entriesPerRelayobject[]
- Each relay's
address,postsTodayandpostsAllTime.Required
- feeVaultBalanceLamportsU64
- The FeeVault's balance.
Required
- dayDay
- Today.
Required
- asOfTimestamp
- When it was read.
Required
POST /tx/open-inbox#
Builds an unsigned open_inbox transaction for the wallet to sign. The API simulates it before answering, so a transaction the program would refuse is refused here.
- walletAddress
- The wallet opening its inbox. It signs and pays.
Required
- inboxKeybase64, 32 bytes
- The X25519 inbox public key.
Required
curl -X POST http://127.0.0.1:6710/tx/open-inbox \
-H 'Content-Type: application/json' \
-d '{"wallet":"<wallet address>","inboxKey":"<32 bytes, base64>"}'
const { inbox, transaction } = await talaria.openInbox()
Returns a TxBuild. Sign its transaction in the wallet, then send it with POST /transactions/submit. Errors: INBOX_ALREADY_OPEN (409) when the wallet has opened its inbox already, INSUFFICIENT_FUNDS (422) when the wallet holds under 10,000 lamports for the network fee or cannot pay the Inbox's rent, and the program's other refusals at simulation, mapped to codes in API errors, with programError set.
POST /tx/buy-pass#
Builds an unsigned buy_pass transaction.
- walletAddress
- The buyer. It signs and pays the price.
Required
- idCommitmentFieldElement
Poseidon(secret)of the new pass.Required
- tierstring
- A tier id from
GET /pool.Required
- daysinteger
- A length from
GET /pool.Required
curl -X POST http://127.0.0.1:6710/tx/buy-pass \
-H 'Content-Type: application/json' \
-d '{"wallet":"<wallet address>","idCommitment":"<decimal field element>","tier":"light","days":30}'
const pass = await talaria.buyPass({ tier: 'light', days: 30 })
Returns a TxBuild. Errors: INVALID_TIER (400) for an unknown tier id, INVALID_PASS_LENGTH (400) for a length the program does not offer, INSUFFICIENT_FUNDS (422) when the wallet holds under 10,000 lamports for the network fee or cannot pay the price, and the program's other refusals at simulation.
POST /tx/rotate-inbox-key#
Builds an unsigned rotate_inbox_key transaction. The body is that of POST /tx/open-inbox, with the new key.
curl -X POST http://127.0.0.1:6710/tx/rotate-inbox-key \
-H 'Content-Type: application/json' \
-d '{"wallet":"<wallet address>","inboxKey":"<new key, 32 bytes, base64>"}'
const { inbox } = await talaria.rotateInboxKey()
Returns a TxBuild. Errors: INSUFFICIENT_FUNDS (422) when the wallet holds under 10,000 lamports for the network fee, and the program's refusals at simulation.
POST /transactions/submit#
Hands the API a transaction it built, signed by the wallet, or registers one the wallet sent itself. The API checks that the signed copy is the transaction it built, records the signed bytes, then broadcasts them.
mode | Other fields |
|---|---|
relay | buildId, signedTransactionBase64 (the signed transaction), idempotencyKey |
wallet-sent | buildId, signature (the signature the wallet sent), idempotencyKey |
buildId is the id of the TxBuild. idempotencyKey is 1 to 128 characters of your choosing: the same submission sent again with the same key answers with the first one's status.
curl -X POST http://127.0.0.1:6710/transactions/submit \
-H 'Content-Type: application/json' \
-d '{"mode":"relay","buildId":"<TxBuild id>","signedTransactionBase64":"<signed transaction, base64>","idempotencyKey":"<uuid>"}'
// openInbox, rotateInboxKey and buyPass submit in relay mode and follow the status.
await talaria.openInbox()
Returns a TxStatus, usually submitted. Errors: TRANSACTION_NOT_FOUND (404, retryable) for a build this API did not make or has forgotten, so build it again; IDEMPOTENCY_CONFLICT (409) for a build already submitted under another key; CHAIN_REFUSED (422) for a signed copy that differs from the build or is not a transaction; and the program's refusals when the signed copy is simulated, mapped as for the builds.
GET /transactions/:id#
A submitted transaction's status. Each read checks the chain once: it records confirmed, finalized or failed, broadcasts the same signed bytes again while their blockhash is valid, and records expired once the blockhash has expired with no trace of the transaction. Read it until the status is settled.
- idstring
- The
TxBuildid.Required
curl http://127.0.0.1:6710/transactions/<TxBuild id>
const status = await api.transaction(id)
Returns a TxStatus. An expired transaction spent nothing; build it again. Errors: TRANSACTION_NOT_FOUND (404, retryable) for an id this API does not hold.
GET /info#
Served by a relay. Its address and fee; the address is the relay public input a proof for it must carry.
curl http://127.0.0.1:6711/info
const info = await relay.info()
Returns a RelayInfo. The fee is read from the program's Config on each request. Before Config exists, while the program is not initialized, it answers status: 'waiting' and feeLamports: '0'.
POST /post#
Served by a relay. Puts a proof and a payload into one post transaction, signs it as its only signer, simulates it, submits it as a Transaction V1 and answers once it is confirmed. Relays gives each step.
- proofBase64base64, 256 bytes
- The Groth16 proof.
Required
- publicInputsPublicInputs
- Root, day, nullifier, payload hash and relay. See
PublicInputs.Required
- payloadBase64base64
- The version 1 payload. The relay takes up to 3,408 bytes.
Required
curl -X POST http://127.0.0.1:6711/post \
-H 'Content-Type: application/json' \
-d '{"proofBase64":"<256 bytes, base64>","publicInputs":{"root":"<root>","day":"<day>","nullifier":"<nullifier>","payloadHash":"<payload hash>","relay":"<this relay address>"},"payloadBase64":"<payload, base64>"}'
await talaria.send(to, text)
- signatureSignature
- The post's transaction signature.
Required
- relayAddress
- The relay that signed it.
Required
- status'submitted'
- Always
submitted. The transaction is confirmed when the answer comes.Required
- transactionVersion1
- Transaction V1.
Required
Errors: RELAY_MISMATCH (422, retryable) when publicInputs.relay is another relay; PAYLOAD_TOO_LARGE (413) over the payload size; INVALID_PAYLOAD (422) when the payload does not hash to payloadHash or is not version 1; at simulation or on chain, UNKNOWN_ROOT and WRONG_DAY (409, retryable), SPENT_NULLIFIER (409), PROOF_INVALID (422), VAULT_EMPTY (503, retryable) when the Vault cannot pay the relay fee, INSUFFICIENT_FUNDS (422) when the relay's own key cannot front the Nullifier's rent, RELAY_UNAVAILABLE (503, retryable) when its key cannot pay for the transaction at all, and CHAIN_REFUSED (422); TRANSACTION_EXPIRED (409, retryable) when it expired without landing. A refused post spends nothing and records no nullifier.
Shared types#
LogEntry#
What the chain holds for one message, decoded. Log entry format gives the bytes.
- indexU64
- Its zero-based position in the Log.
Required
- signatureSignature
- The
posttransaction's signature.Required
- slotU64
- The slot it landed in.
Required
- blockTimeTimestamp
- The block's time.
Required
- relayAddress
- The relay, the transaction's only signer.
Required
- dayDay
- The day the proof is for.
Required
- nullifierFieldElement
- The nullifier.
Required
- rootFieldElement
- The pool root the proof is under.
Required
- proofBase64base64, 256 bytes
- The proof.
Required
- payloadBase64base64
- The whole payload.
Required
- payloadPayloadParts
- The payload, split. See
PayloadParts.Required
- publicInputsPublicInputs
- The five public inputs.
Required
- publicSignalsFieldElement[6]
- The circuit's signals: root, day, nullifier, payload hash, relay low 128 bits, relay high 128 bits.
Required
- verificationVerification
- See
Verification.Required
PayloadParts#
- version1
- The payload version.
Required
- keySlotsKeySlot[2]
- Two slots, each with
ephemeralKey(32 bytes, base64),viewTag(0 to 255) andwrappedContentKey(72 bytes, base64).Required
- ciphertextBase64base64
- The ciphertext with its nonce and tag.
Required
- ciphertextLengthinteger
- Its length in bytes.
Required
PublicInputs#
- rootFieldElement
- A recent pool root.
Required
- dayDay
- Today.
Required
- nullifierFieldElement
- The message's nullifier.
Required
- payloadHashFieldElement
- SHA-256 of the payload, first 31 bytes, as an integer under 2^248.
Required
- relayAddress
- The relay that submits it.
Required
The proof says what each input binds.
Verification#
- status'verified' | 'invalid' | 'unavailable' | 'fixture'
verified: the confirmed program transaction verified this proof against these inputs.fixture: no verification ran.Required
- scheme'groth16-bn254'
- The proof system.
Required
- checkedAtTimestamp | null
- When it was checked.
Required
- messagestring
- A sentence saying what was checked.
Required
InboxEvent#
One open_inbox or rotate_inbox_key in the inbox directory.
- indexU64
- Its zero-based position in the directory.
Required
- walletAddress
- The wallet whose inbox it opened or rotated.
Required
- inboxKeybase64, 32 bytes
- The X25519 inbox key it set.
Required
- keyVersioninteger
- That key's version: 1 for
open_inbox, one more for each rotation.Required
- slotU64
- The slot it landed in.
Required
- blockTimeTimestamp
- The block's time.
Required
Inbox#
A wallet's inbox as a device folds it from its InboxEvents, described in GET /inboxes/head. No endpoint returns it; the SDK's findInbox and lookup do.
- walletAddress
- The wallet.
Required
- inboxKeybase64, 32 bytes
- The current X25519 inbox key.
Required
- openedSlotU64
- The slot it was opened in.
Required
- openedAtTimestamp
- When it was opened.
Required
- keyVersioninteger
- The key version, 1 when opened, raised by each rotation.
Required
- updatedAtTimestamp
- When its key last changed.
Required
- keyHistoryInboxKeyHistory[]
- Every key it has had:
inboxKey,keyVersion,validFromSlot, andvalidUntilSlot(nullfor the current key). A reader checks a writer's key at the entry's slot against it. The SDK always sets it.
PoolLeaf#
- indexU64
- Its position in the pool.
Required
- leafFieldElement
Poseidon(idCommitment, dailyLimit, expiryDay).Required
- idCommitmentFieldElement
- The pass's commitment.
Required
- dailyLimitinteger
- Messages a day.
Required
- expiryDayDay
- The last day it can send, included.
Required
- signatureSignature
- The purchase transaction.
Required
- slotU64
- Its slot.
Required
- blockTimeTimestamp
- Its block time.
Required
RelayInfo#
- addressAddress
- The relay's signing address.
Required
- endpointURL
- Its base URL.
Required
- feeLamportsU64
- The relay fee the program pays per post.
Required
- transactionVersion1
- It submits Transaction V1.
Required
- status'ready' | 'waiting' | 'fixture'
- Its state.
Required
TxBuild#
- idstring
- The build id, for
POST /transactions/submitandGET /transactions/:id.Required
- transactionBase64base64
- The unsigned versioned transaction, the wallet as fee payer.
Required
- blockhashstring
- Its blockhash.
Required
- lastValidBlockHeightinteger
- The last block height it can land at.
Required
- cosignedboolean
- Whether the API signs it too.
falsefor every Talaria build.Required
TxStatus#
- idstring
- The build id.
Required
- statusstring
submitted,unconfirmed,confirmed,finalized,failedorexpired.Required
- signatureSignature
- Its signature, once signed.
- errorTxFailure
- For
failedandexpired:stage(build,wallet-rejected,wallet-changed,simulation,send,confirm),message,nextStep,retryable, andprogramwith the refusing program'saddress,codeandname.