Skip to content
Open app

SDK and APIAPI reference

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#

ServiceLocal build
APIhttp://127.0.0.1:6710
Relay 1http://127.0.0.1:6711
Relay 2http://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.

TypeScript
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 from GET /pool.
  • Requests. A POST sends Content-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-Id and X-Contract-Version (0.3.0), and Cache-Control: no-store unless 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.1 and localhost). Requests without an Origin header, 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. .sol names resolve on the device too (see lookup). 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, send or confirmation.

Required

fieldErrorsobject
For VALIDATION_ERROR: messages per field path.
programErrorobject
For a program refusal: programId, name and number.
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.

Shell
curl http://127.0.0.1:6710/health
status'ready' | 'waiting' | 'fixture'
fixture when 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.

Shell
curl http://127.0.0.1:6710/log/head
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, 0 for 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 0 to segmentCount - 1.

Required

Shell
curl http://127.0.0.1:6710/log/segments/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:

Text
event: entry
id: <event id>
data: {"type":"entry","id":"<event id>","timestamp":"<UTC time>","data":<LogEntry>}
Eventdata
readystatus (ready, waiting or fixture) and head, a GET /log/head response. Sent first on every connection.
entryA complete LogEntry.
resyncreason: 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.

TypeScript
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)
  })
}

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 post transaction's signature.

Required

Shell
curl http://127.0.0.1:6710/log/entries/27qt7MXJL62zFfqteY8N6g5jTaDohGCdiNcnqGUX9QKLSK1b5Dr1yZf3c3UxQrUH2YEcfAkvuqHjqVkscSt1fRTv

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.

Shell
curl http://127.0.0.1:6710/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) and dailyLimit.

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

Shell
curl "http://127.0.0.1:6710/pool/leaves?from=0"
fromU64
The first index returned.

Required

nextU64
The index after the last leaf: the from of the next call.

Required

totalU64
Leaves in the pool.

Required

rootFieldElement
The root these leaves build.

Required

leavesPoolLeaf[]
Every leaf from from through next - 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.

Shell
curl http://127.0.0.1:6710/inboxes/head
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 0 to segmentCount - 1.

Required

Shell
curl http://127.0.0.1:6710/inboxes/segments/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:

TypeScript
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.

Shell
curl http://127.0.0.1:6710/relays
relaysRelay[]
Each relay: the fields of RelayInfo plus 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.

Shell
curl http://127.0.0.1:6710/stats
passesInPoolU64
Leaves in the pool.

Required

messagesTodayU64
Log entries of today.

Required

messagesAllTimeU64
Log entries.

Required

relaysActiveU64
Relays GET /relays lists with status ready.

Required

entriesPerRelayobject[]
Each relay's address, postsToday and postsAllTime.

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

Shell
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>"}'

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

Shell
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}'

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.

Shell
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>"}'

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.

modeOther fields
relaybuildId, signedTransactionBase64 (the signed transaction), idempotencyKey
wallet-sentbuildId, 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.

Shell
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>"}'

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 TxBuild id.

Required

Shell
curl http://127.0.0.1:6710/transactions/<TxBuild 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.

Shell
curl http://127.0.0.1:6711/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

Shell
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>"}'
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 post transaction'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

Required

PayloadParts#

version1
The payload version.

Required

keySlotsKeySlot[2]
Two slots, each with ephemeralKey (32 bytes, base64), viewTag (0 to 255) and wrappedContentKey (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, and validUntilSlot (null for 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/submit and GET /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. false for every Talaria build.

Required

TxStatus#

idstring
The build id.

Required

statusstring
submitted, unconfirmed, confirmed, finalized, failed or expired.

Required

signatureSignature
Its signature, once signed.
errorTxFailure
For failed and expired: stage (build, wallet-rejected, wallet-changed, simulation, send, confirm), message, nextStep, retryable, and program with the refusing program's address, code and name.