Signed receipts

When a fill settles, StellarBook issues a receipt signed with an ed25519 key. Anyone can verify it offline, without calling our API.

Receipt format

json
{
  "payload": {
    "v": 1,
    "fill_id": "fill_…",
    "order_id": "ord_…",
    "provider": "stellarbook-labs",
    "buyer": "<buyer wallet>",
    "recipient": "<provider wallet>",
    "amount": "0.002000",
    "currency": "USDC",
    "mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
    "network": "solana-mainnet",
    "payment_sig": "<Solana transaction signature>",
    "slot": 0,
    "ledger_seq": 0,
    "ledger_hash": "<hex>",
    "settled_at": "2026-11-16T12:00:00.000Z"
  },
  "signature": "<base58 ed25519 signature>",
  "signer": "<base58 public key>"
}

How to verify

  1. Serialise payload as canonical JSON: object keys sorted alphabetically at every level, no whitespace.
  2. Verify signature over the UTF-8 bytes with ed25519 and the signer public key.
  3. Check that signer matches the key published at https://stellarbook.xyz/api/v1/receipts/public-key and on the Trust page.
  4. Optionally, look up payment_sig on Solana to confirm the transfer itself.
verify-receipt.ts
import nacl from "tweetnacl";
import bs58 from "bs58";

const canonical = (v: unknown): string =>
  v === null || typeof v !== "object" ? JSON.stringify(v)
  : Array.isArray(v) ? `[${v.map(canonical).join(",")}]`
  : `{${Object.keys(v).sort().map((k) => `${JSON.stringify(k)}:${canonical((v as any)[k])}`).join(",")}}`;

export function verify(r: { payload: object; signature: string; signer: string }) {
  return nacl.sign.detached.verify(
    new TextEncoder().encode(canonical(r.payload)),
    bs58.decode(r.signature),
    bs58.decode(r.signer),
  );
}

Providers receive the receipt with every delivery request and should verify it before answering.