Docs/Quickstart

1. 1

   Install#

   shell

   $ npm i @paravion/sdk @paravion/miner viem

   The SDK builds the UserOperation itself (fixed gas profiles, EntryPoint v0.9, nonce key 0) on top of viem, blinds and unblinds stamps with @cloudflare/blindrsa-ts, and mines free stamps in Web Workers (WASM, with a JavaScript fallback) or Node worker threads through @paravion/miner.

2. 2

   Point it at the relay#

   There is no project id: the relay URL is the only setting. This deployment's relay is https://relay-production-fb81.up.railway.app. It issues stamps, checks each operation, co-signs it and forwards it to its own bundler.

3. 3

   Get a stamp#

   Buy a booklet of 1 to 100 stamps in ETH, from any wallet, even your main one (buy.ts below), and keep them safe. Or skip this step and mine a free stamp per operation (mined.ts): free stamps share a small budget per 15-minute epoch, so they can run out. Prepaid stamps explains the purchase, the blind signature and what the relay can and cannot see.

4. 4

   Send the op#

   send.tsbuy.tsmined.tscURL

   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)

   Relay URL: https://relay-production-fb81.up.railway.app. The SDK builds every op itself (fixed gas profiles, EntryPoint v0.9, nonce key 0).

   The first op of a fresh key carries an EIP-7702 authorization for Simple7702Account v0.9. The bundler's own type-4 transaction applies it, so the key never needs ETH. Keep the returned state for the next op: the SDK never reads it from the chain before sending.

Show progress and let people stop#

A stamped send goes through the same stages as a mined one, without the mining. Mining is memoryless: every hash has the same odds, so show the found sub-solutions (x/8) and an honest estimate, never a fake percentage. Pass an AbortSignal for a Stop button.

const res = await sendPowUserOperation({
  relay, epochs, owner, state, call,
  delaySec: 120,              // optional: the relay holds the op 2 min
  signal: controller.signal,  // your Stop button
  onProgress: (p) => {
    if (p.stage === 'waiting') show(`Next epoch in ${p.seconds} s`)
    if (p.stage === 'mining') show(`${p.found}/8 · ~${Math.ceil(p.eta)} s`)
    if (p.stage === 'included') show(p.success ? 'Sponsored' : 'Reverted')
  },
  onState: (s) => save(s),    // persist the state as it advances
})

Imported keys#

A fresh key starts at freshAccountState(address) with no read at all. A key that already has history (an address that received tokens, say) needs its state once:

import { loadAccountState } from '@paravion/sdk'

// An imported key may already have history: read its state once, through the relay only.
let state = await loadAccountState(relay, owner.address)

Handle failures#

A failed send never costs ETH. Either the op was not sponsored, and its stamp is not spent; or it was included and only the call reverted, and its stamp is cancelled like any other, since its gas was paid. The SDK rebuilds by itself, at most twice, when the epoch rolls or the bundler's quotes move.

Next steps#

• Prepaid stampsHow a stamp is bought, issued, kept, used and cancelled.
• How it worksBoth postages, the wire format, validation and epochs.
• Privacy guideWhat stays hidden, what does not, and what to do about it.