Pushed transaction status
This page shows how to have a transaction’s MINED or REJECTED status pushed to the device as soon as the Broadcaster knows it, instead of waiting for libspiffy’s next status poll. It needs libspiffy 5.17.0 or later, a callback bridge you run (Run a callback bridge), and a Go-Ricochet client in your app to receive what the bridge delivers.
Polling does not stop. Pushed status is a faster path next to it: a status that is never pushed is still found by the poll.
How it works
Section titled “How it works”- Each transaction libspiffy submits carries your bridge’s callback URL (
X-CallbackUrl) and a fresh callback token (X-CallbackToken). The token names the user’s Ricochet identity and mailbox folder. It is signed with the user’s identity key and encrypted to the bridge, so only the bridge can read it. - When the transaction is mined or rejected, the Broadcaster calls the bridge with the status and the token.
- The bridge opens the token and delivers a status envelope to that user’s mailbox folder over Ricochet.
- Your app’s Ricochet client receives the message and hands its payload to
applyBroadcastStatusEnvelope, which applies it like a polled answer.
libspiffy names no bridge. Its URL, peer ID and key are your app’s configuration.
Sign tokens with the user’s identity key
Section titled “Sign tokens with the user’s identity key”libspiffy never holds the user’s identity key. You give it a CallbackTokenSigner that signs with the key
your Ricochet client already uses:
// Sketch: assumes an initialized LibSpiffyActorSystem named `libspiffy`.import 'dart:typed_data';
import 'package:cryptography/cryptography.dart';import 'package:libspiffy/libspiffy.dart';
/// Signs callback tokens with the user's Ed25519 identity key: the key the/// app's Ricochet client already holds.class IdentityTokenSigner implements CallbackTokenSigner { IdentityTokenSigner(this._keyPair, Uint8List publicKey) : peerIdBytes = Uint8List.fromList([0x00, 0x24, 0x08, 0x01, 0x12, 0x20, ...publicKey]);
final SimpleKeyPair _keyPair;
@override final Uint8List peerIdBytes;
@override Future<Uint8List> sign(Uint8List message) async { final signature = await Ed25519().sign(message, keyPair: _keyPair); return Uint8List.fromList(signature.bytes); }}peerIdBytes is the user’s peer ID as multihash bytes: for an Ed25519 key, 00 24 08 01 12 20 and the
32-byte public key. sign returns a 64-byte Ed25519 signature. A signer that throws, or returns something
else, never holds a submission back: that transaction goes without callback headers and is followed by
polling.
Turn it on
Section titled “Turn it on”/// Your bridge's settings, read from your app's configuration.class BridgeSettings { BridgeSettings(this.callbackUrl, this.peerId, this.x25519PublicKeyHex); final String callbackUrl; final String peerId; final String x25519PublicKeyHex;}
/// Turns pushed status on, once the user's mailbox folder exists and grants/// the bridge write access.void enablePush(BridgeSettings bridge, CallbackTokenSigner signer) { libspiffy.enableBroadcastCallbacks( BroadcastCallbackConfig( callbackUrl: bridge.callbackUrl, bridgePeerId: bridge.peerId, bridgeX25519PubHex: bridge.x25519PublicKeyHex, net: 'main', ), signer, );}BroadcastCallbackConfig takes:
| Parameter | Meaning |
|---|---|
callbackUrl |
The bridge’s callback endpoint. It must be https. |
bridgePeerId |
The bridge’s Ricochet peer ID (12D3KooW…). |
bridgeX25519PubHex |
The bridge’s X25519 public key, 32 bytes as hex. Tokens are encrypted to it. |
net |
main or test. It must match the network libspiffy runs on, or enableBroadcastCallbacks throws. |
folder |
The mailbox folder the bridge delivers to. Default bsv/tx-status. |
tokenTtl |
How long a token is valid. Default and maximum 30 days. |
From then on every submission carries the callback headers, except the ancestors libspiffy submits ahead
of a transaction, whose status nothing follows. disableBroadcastCallbacks() turns them off. The setting
is not stored: call enableBroadcastCallbacks again after each initialize().
Apply what the bridge delivers
Section titled “Apply what the bridge delivers”/// Called by your Ricochet client for each message in the status folder./// Returns true when the message can be marked delivered.Future<bool> onStatusMessage(String senderPeerId, List<int> payload, BridgeSettings bridge) async { if (senderPeerId != bridge.peerId) return true; // not from the bridge: drop it final result = await libspiffy.applyBroadcastStatusEnvelope(payload); if (!result.accepted) { print('not a status envelope for this network'); } else { print('${result.applied} applied, ${result.unknown} for transactions this wallet does not hold'); } return true;}Accept messages in the folder only from the bridge’s peer ID, and pass libspiffy the opened payload: the
envelope’s UTF-8 JSON. applyBroadcastStatusEnvelope answers BroadcastStatusAppliedMessage:
acceptedis false when the payload is not a version 1bsv.tx-statusenvelope for this network, or not JSON. Nothing was applied.appliedcounts the items for transactions a wallet holds. Each is applied in every wallet that holds the transaction.unknowncounts the items for transactions no wallet holds. They are ignored.
Applying an envelope twice changes nothing: a duplicate or stale status is a no-op. So mark the message
delivered once applyBroadcastStatusEnvelope completes. If the app stops before that, the message is
applied again on the next start, which is harmless.
How much a pushed status is trusted
Section titled “How much a pushed status is trusted”Exactly as much as a polled one: each item goes through the same code as the Broadcaster’s answer to a poll.
- MINED confirms nothing on its own word. The transaction is confirmed only when the item’s merkle path checks against the block header the wallet holds at that height. A forged MINED fails that check, and a MINED without a merkle path waits for a proof.
- Other statuses are taken as the Broadcaster’s word, as on a poll. SEEN_ON_NETWORK (and MINED) apply the transaction’s spend of its inputs; REJECTED marks it failed. Only a later report that the network holds the transaction sets a failed one back.
Whoever holds a token can send the bridge a status for it. A token travels only in the submission’s headers to the Broadcaster and in the callback to your bridge, so that is the Broadcaster, which already answers your polls, and your bridge. A bridge that checks each callback’s txid against its token’s (Run a callback bridge) also keeps a token from being used for any other transaction.
Each submission gets a fresh token, with a fresh ephemeral key and nonce, so tokens can’t be linked to each other, or to the user, by anyone but the bridge.
See also
Section titled “See also”- Run a callback bridge: what the bridge receives, checks and delivers.
- Header sync via CDN: the headers a MINED status is checked against.