Run a callback bridge
This page specifies the callback bridge that pushed transaction status needs: a web service you run that takes the Broadcaster’s status callbacks and delivers them to each user’s Ricochet mailbox. libspiffy ships no bridge and names none. Build one from this page, and check it against libspiffy’s test vectors.
A bridge has three jobs:
- Take the Broadcaster’s callback at its callback URL.
- Open and check the callback token that came with it.
- Deliver a status envelope to the user and folder the token names, over Go-Ricochet.
The bridge’s identity and keys
Section titled “The bridge’s identity and keys”A bridge has a Ricochet peer ID, from its Ed25519 identity key, and an X25519 key pair that tokens are encrypted to. Apps are configured with three values: the callback URL, the peer ID and the X25519 public key as hex (Turn it on). Publish them to the apps you serve through your own configuration.
libspiffy takes the X25519 key as given. In libspiffy’s test vectors it is the bridge’s Ed25519 seed converted the usual way (the first 32 bytes of the seed’s SHA-512, clamped), so one seed gives both keys.
Take the callback
Section titled “Take the callback”The callback URL must be https. libspiffy sends it unchanged as X-CallbackUrl with each submission.
By convention its last path segment names the Broadcaster the app submits to (…/v1/callback/bsva), so
the bridge knows whose callbacks arrive there and can record it as each item’s source.
The Broadcaster returns the token with its callback: ARC’s API says X-CallbackToken is used as the
Authorization header of the callback. Check your Broadcaster’s documentation for the callback’s exact
form, and for its batched form (X-CallbackBatch). libspiffy does not ask for batched callbacks.
Open the token
Section titled “Open the token”A token is bb1. followed by the unpadded base64url of:
| Bytes | Content |
|---|---|
| 1 | Version, 01 |
| 32 | The ephemeral X25519 public key |
| 12 | The nonce |
| rest | The ChaCha20-Poly1305 ciphertext, with its 16-byte tag at the end |
To open it:
- Compute the X25519 shared secret of the bridge’s private key and the ephemeral key.
- Derive a 32-byte key with HKDF-SHA256: the shared secret as input,
ephemeral key ‖ bridge X25519 public keyas salt, and the ASCII stringbroadcast-bridge/token/v1as info. - Decrypt with ChaCha20-Poly1305, the nonce, and the single byte
01as associated data.
The plaintext is a CBOR array of two byte strings: the token body and a 64-byte Ed25519 signature over
broadcast-bridge/token/v1 ‖ body.
The body is a CBOR map with integer keys, in this order:
| Key | Type | Content |
|---|---|---|
| 0 | integer | Version, 1 |
| 1 | bytes | The user’s peer ID as multihash bytes: 00 24 08 01 12 20 and the 32-byte Ed25519 public key |
| 2 | text | The mailbox folder to deliver to, bsv/tx-status by default |
| 3 | bytes or null | The 32-byte txid, in the order it is displayed; null for a token a batch shares |
| 4 | integer | Expiry, Unix seconds |
| 5 | bytes | The bridge’s peer ID as multihash bytes |
| 6 | text | The network, main or test |
Check the token
Section titled “Check the token”Refuse the callback unless:
- the signature verifies under the public key in field 1;
- field 0 is
1; - field 5 is your bridge’s own peer ID;
- field 4 has not passed (libspiffy mints tokens valid for at most 30 days);
- field 6 is the network this bridge serves;
- field 3, when it is set, is the txid of the status in the callback.
libspiffy binds every token it mints for a submission to that transaction’s txid. A null txid comes only
from an app that mints its own token for a batch with mintCallbackToken(txid: null).
Deliver the envelope
Section titled “Deliver the envelope”Send the user (the peer ID in field 1) a message in the folder of field 2, over Go-Ricochet, from the bridge’s own peer ID. The app accepts messages in that folder only from your bridge’s peer ID. The user’s app creates the folder, shared, with write access for your peer, before it turns callbacks on: a first delivery to a folder that does not exist creates it open to anyone, for good.
The message is UTF-8 JSON:
{ "v": 1, "type": "bsv.tx-status", "net": "main", "items": [ { "txid": "…", "txStatus": "MINED", "timestamp": "2026-11-08T14:03:11Z", "blockHash": "…", "blockHeight": 921034, "merklePath": "…", "extraInfo": "", "competingTxs": [], "source": "https://arcade-v2-us-1.bsvblockchain.tech" } ]}v,typeandnetmust be exactly these. libspiffy refuses the whole envelope otherwise, or when it is not JSON.- Each item is the Broadcaster’s transaction status as its callback gave it:
txidandtxStatus, andblockHash,blockHeight,merklePath,timestamp,extraInfoandcompetingTxswhen it has them. An item without a stringtxid, or whose fields can’t be read, is skipped. AtxStatuslibspiffy does not know is read asUNKNOWN. sourceis optional: the Broadcaster that answered.
Pass on MINED with its merklePath: without one, libspiffy cannot confirm the transaction from the push
and waits for a proof. An envelope may carry several items, for one user.
Delivering the same status twice is harmless: libspiffy applies a duplicate or stale status as a no-op.
What the bridge is trusted with
Section titled “What the bridge is trusted with”The bridge reads each token, so it learns which users submit which transactions. Run it where you would keep that record.
It is not trusted with money. libspiffy confirms a MINED status only when its merkle path checks against the block header the wallet holds, and takes the other statuses no further than it takes a poll’s (How much a pushed status is trusted).
Test against libspiffy’s vectors
Section titled “Test against libspiffy’s vectors”test/data/broadcast_token_vectors.json
holds three tokens minted with test keys: a mainnet token bound to a txid, a batch token with no txid,
and a testnet token for another folder. Each vector gives:
userSeedHexandbridgeSeedHex: the Ed25519 seeds of the user and the bridge;userPeerId,bridgePeerIdandbridgeX25519PubHex;randHex: the 32-byte ephemeral seed, then the 12-byte nonce;folder,txid(empty for none),expandnet;bodyHexandtoken: the body and the token libspiffy mints from them.
A bridge that opens each token with the X25519 key of bridgeSeedHex, gets bodyHex back, and
verifies the signature under the user’s key implements the token as libspiffy does.