Skip to content

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.

  1. 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.
  2. When the transaction is mined or rejected, the Broadcaster calls the bridge with the status and the token.
  3. The bridge opens the token and delivers a status envelope to that user’s mailbox folder over Ricochet.
  4. 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:

lib/status_push.dart
// 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.

lib/status_push.dart (continued)
/// 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().

lib/status_push.dart (continued)
/// 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:

  • accepted is false when the payload is not a version 1 bsv.tx-status envelope for this network, or not JSON. Nothing was applied.
  • applied counts the items for transactions a wallet holds. Each is applied in every wallet that holds the transaction.
  • unknown counts 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.

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.