Docs/Prepaid stamps

Face value and price#

One stamp pays for one operation of an allowed template (a token transfer or approve, or an ETH send), with the gas limits of that template's published profile, inside the epoch's caps. It works for a first op (with its EIP-7702 delegation) as for any later one.

The price is set by the relay's keeper from its own gas quote, within bounds the PostOffice enforces on chain:

quote = max over templates (first and regular) of
          (verificationGasLimit + callGasLimit + PVG quote + pmVerificationGasLimit + stampPostOpGasLimit)
        × max(refFeePerGas, base fee) × PRICE_SAFETY_BPS / 10,000      // × 1.5
price = quote × (10,000 + markupBps) / 10,000                         // markup 25% on mainnet

• Bounded. The pricer moves the price by at most ±50% per update and at most once per 10 minutes, always inside the owner's [minPrice, maxPrice]. A pricer key alone cannot jump it.
• Split at purchase. Of each sale, the markup share markupBps / (10,000 + markupBps) (20% at a 25% markup) goes to the DeadLetterOffice; the rest is the gas share, credited to the paymaster's deposit as the stamp float.
• Never refunded. An unused stamp is not redeemable for ETH. Only its gas is ever spent.

Buy a booklet#

1. Read the issuer. stamp_getIssuer returns the key, the window and its metadata (info), and the price. The SDK checks them against the published pins first (checkStampIssuer, below): it never blinds anything for an unpublished key or window.
2. Blind. Your device draws N random 32-byte serials (1 ≤ N ≤ 100) and blinds each one for the issuer key under the public metadata info, with RFC 9474 partially blind RSA (@cloudflare/blindrsa-ts, suite RSAPBSSA-SHA384-PSS-Deterministic).
3. Store. The pending booklet (serials, blinded messages, blinding inverses) is saved before anything is paid: without the inverses, paid stamps cannot be unblinded.
4. Pay. Any wallet calls PostOffice.buy(commitment, N) with N × price; any excess comes back in the same transaction. A commitment can be paid for once.

info       = "paravion:v1;chain=4663;paymaster=<lowercase address>;key=<keyId>;face=1op;from=<unix>;until=<unix>"
commitment = keccak256( keccak256(utf8(info)) ‖ blinded_1 ‖ … ‖ blinded_N )   // plain concatenation

import { createWalletClient, custom } from 'viem'
import { robinhood, buyStamps, createRelayClient } from '@paravion/sdk'

const relay = createRelayClient('https://relay-production-fb81.up.railway.app')
const wallet = createWalletClient({ chain: robinhood, transport: custom(window.ethereum) })
const [buyer] = await wallet.getAddresses()  // any wallet, even your main one

const { stamps } = await buyStamps({
  relay,
  count: 10,                                  // 1 to 100 per booklet
  // PostOffice.buy(commitment, count) with count × price; the excess comes back
  pay: (call) => wallet.sendTransaction({ account: buyer, ...call }),
  // called before paying: the pending booklet holds the blinding inverses
  savePending: (booklet) => db.put('pending', booklet),
  onProgress: (p) => console.log(p.stage),    // issuer, blinding, paying, paid, issuing, done
})
await db.put('stamps', stamps)               // bearer tokens: guard them like cash

Issuance#

stamp_issue([{ orderTx, info, blinded }]) asks the relay to sign. It answers only when:

• the purchase transaction is mined, succeeded and has the required confirmations (1 by default), else ORDER_UNKNOWN or ORDER_PENDING;
• it emitted StampsBought from the PostOffice with count = N and exactly this commitment of info and the blinded messages, else ORDER_MISMATCH;
• its block time falls in the window info names (or at most an hour after it ends), and info names the key that issues in that window.

The relay then blind-signs exactly the committed messages under the key derived for info. Signing is deterministic, so asking again returns the same signatures and the relay stores nothing. It learns the buyer and the blinded messages; it never learns a serial.

Keeping stamps#

The SDK unblinds the signatures (finalizeBooklet) and verifies every stamp under the issuer key before keeping it. The pending booklet can then be dropped, and with it any trace of which purchase made which stamps.

• In the browser the app keeps your stamps in IndexedDB. Export them as an encrypted file (PBKDF2-SHA-256 with 600,000 iterations, then AES-256-GCM, format paravion-carnet v1) to move them to another device or to the agent, which keeps the same format in PARAVION_HOME/carnet/<network>.json under PARAVION_PASSPHRASE.
• A stamp is a bearer token. Whoever holds the serial and the signature can spend it. Lost stamps cannot be reissued: nobody, the relay included, knows which serials were yours.

import { decryptCarnet, encryptCarnet } from '@paravion/sdk'

// PBKDF2-SHA-256 (600,000 iterations) and AES-256-GCM: the same file the web app and the agent read
const file = await encryptCarnet({ stamps, pending }, passphrase)
const back = await decryptCarnet(file, passphrase) // CARNET_LOCKED on a wrong passphrase

Use a stamp for an operation#

A fresh address with 0 ETH builds its op with paymasterData version 2 and the stamp's nullifier, signs it, and sends it with stamp_sendUserOperation(op, entryPoint, { stamp: { info, serial, signature } }). The relay:

1. runs the same checks as for any op (EntryPoint, epoch, nonce key 0, authorization, userOpHash, templates, exact gas profile, PVG, fees, pending ops), without proof of work;
2. verifies the stamp under its window's derived key, refuses it within 60 s of its until (STAMP_EXPIRED), and checks that the op's nullifier is keccak256(abi.encode(NULLIFIER_TAG, serial));
3. refuses a stamp already used by an op in flight (STAMP_IN_FLIGHT) or already cancelled on chain, from the paymaster's cancelledAt(nullifier) (STAMP_SPENT);
4. admits it against the deposit's headroom only (prepaid gas does not compete for the free lane's budget or pacing);
5. co-signs stampDigest(userOpHash, nullifier) with the epoch's co-signer key and forwards the op to its bundler.

import { generatePrivateKey, privateKeyToAccount } from 'viem/accounts'
import {
  createRelayClient, freshAccountState, listedTokens,
  sendStampedUserOperation, startEpochPolling, transferCall,
} from '@paravion/sdk'

const relay = createRelayClient('https://relay-production-fb81.up.railway.app')
const epochs = startEpochPolling(relay)      // fixed 60 s background poll
const owner = privateKeyToAccount(generatePrivateKey()) // 0 ETH, never funded
const NVDA = listedTokens(4663).find((t) => t.symbol === 'NVDA')!.address
const stamp = saved.shift()!                 // bought days ago, not right now

const { receipt, state } = await sendStampedUserOperation({
  relay, epochs, owner, stamp,
  state: freshAccountState(owner.address),   // first op: carries the EIP-7702 delegation
  call: transferCall(NVDA, to, 10n ** 18n),
})
console.log(receipt.success)                  // the paymaster cancelled the stamp (StampCancelled)

Cancellation#

• Validation checks the policy, the delegate, a non-zero nullifier and the relay's co-signature over the op and that nullifier. Only the relay, which checked the stamp, can produce it. Validation never reads a nullifier: it reads only the epoch's write-once slots, so no other op's postOp can invalidate an op the bundler already simulated (ERC-7562).
• postOp takes the op's cost (actualGasCost plus 36,000 gas for itself and the EntryPoint's bookkeeping) from the float, records the nullifier with the time of its first cancellation, and emits StampCancelled. This happens whether the call succeeded or reverted: the gas was paid either way.
• A double spend is public. If a nullifier is ever recorded twice (a relay that co-signed one stamp twice), postOp emits DoubleSpend with the first cancellation's time, for anyone to see. postOp is accounting only and never reverts.

The free stamp#

No ETH at all? The original path is still there: the client mines 8 keccak sub-solutions bound to the op's hash (paymasterData version 1), and the relay co-signs it like any other op. Free stamps are paid from the free lane, a small budget per 15-minute epoch, refilled from the treasury (which the $STAMP creator fees fund), with difficulty and pacing rationing demand. When the epoch's budget is spent, wait for the next epoch or use a bought stamp. How it works has the challenge and the work formula.

Windows, keys and pins#

• Windows. Stamps are issued in 30-day windows aligned on multiples of the window length, and stay valid 120 days after their window closes. Every stamp bought in one window carries the same info, so it hides among all the stamps of that window.
• Per-window keys. The relay signs each window with a key derived from its master key and that window's info (the partially blind scheme's key derivation). A new window, or a new master key, never invalidates a stamp in circulation: each verifies under the key of its own info until its until.
• Rotation. A new master key is added with a later activeFrom and issues from the first window starting at or after it; the old key stays until its last window expires.
• Pins. The issuer keys and the window policy are published in contracts/deployments/<chainId>.json under stamps (windowSec, validitySec, issuers[{ keyId, n, e, activeFrom }]). The SDK refuses (ISSUER_MISMATCH) a key that is not pinned, a window that is not aligned or has another length or validity, or a window that is not the current one. A relay therefore cannot hand one buyer a private key or window that would mark that buyer's stamps.

Where the money goes#

Use cases#

• Stock tokens out of Robinhood, without a top-up. Robinhood's terms cover network fees on Robinhood Chain only for in-app swaps above $0.50, until December 31, 2026, and not for wallet-to-wallet transfers (Robinhood support (opens a new tab)); the wider 90-day gas subsidy of Robinhood Wallet transactions was reported to end on September 29, 2026. Send your Stock Tokens to a fresh address once; from there, every later transfer is paid with a stamp, and the fresh address is never funded. The transfer in links your Robinhood wallet to the fresh address, publicly: plan for it.
• Fresh receive addresses. One address per payer, invoice or counterparty. Whatever it receives, it can forward later with a stamp, without a funding transaction from your main wallet.
• New identities. A fresh key has no past. Stamps let it act on chain without the one transaction that would give it one.
• AI agents. The MCP server buys booklets from a payer account (paravion_buy_stamps), keeps its stamps encrypted (paravion_list_stamps) and sends from fresh accounts with postage stamp. See For AI agents.

What stamps do not hide#

The privacy guide goes through each line.

Next steps#

• Privacy guideTiming, IP addresses and what to do about them.
• Contract referenceStampPaymaster, PostOffice, DeadLetterOffice, CreatorFeeSink.
• Run your own relayThe stamp methods, the issuer keyring and the postal keeper.