Skip to content

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:

  1. Take the Broadcaster’s callback at its callback URL.
  2. Open and check the callback token that came with it.
  3. Deliver a status envelope to the user and folder the token names, over Go-Ricochet.

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.

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.

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:

  1. Compute the X25519 shared secret of the bridge’s private key and the ephemeral key.
  2. Derive a 32-byte key with HKDF-SHA256: the shared secret as input, ephemeral key ‖ bridge X25519 public key as salt, and the ASCII string broadcast-bridge/token/v1 as info.
  3. Decrypt with ChaCha20-Poly1305, the nonce, and the single byte 01 as 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

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

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, type and net must 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: txid and txStatus, and blockHash, blockHeight, merklePath, timestamp, extraInfo and competingTxs when it has them. An item without a string txid, or whose fields can’t be read, is skipped. A txStatus libspiffy does not know is read as UNKNOWN.
  • source is 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.

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/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:

  • userSeedHex and bridgeSeedHex: the Ed25519 seeds of the user and the bridge;
  • userPeerId, bridgePeerId and bridgeX25519PubHex;
  • randHex: the 32-byte ephemeral seed, then the 12-byte nonce;
  • folder, txid (empty for none), exp and net;
  • bodyHex and token: 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.