@wisp_/flows

High-level, client-agnostic orchestration for Wisp transfers: fetch package → validate → prove → duplicate-check → approve → simulate → settle, with staged progress callbacks and duplicate-nullifier retry.

Beta / demo release only. Intended for evaluation and testnet integrations; interfaces may change.

Flows depend only on @wisp_/js and program against a TransferClientLike interface — so you can drive them with @wisp_/sdk's WispClient, a custom client, or a test double. Ideal for embedding the full transfer pipeline into your own UI or service.

Install

npm install @wisp_/[email protected]

Quick start

import {
  createAndSettleTransferWithRetry,
  type TransferStage,
} from "@wisp_/flows";

const result = await createAndSettleTransferWithRetry({
  client,        // any TransferClientLike (e.g. WispClient from @wisp_/sdk)
  issuer,        // ProofPackageSource (DemoIssuerClient or HttpIssuerAdapter)
  request,       // DemoTransferRequest
  validation: { issuerPublicKey, corridorId: 1 },
  walletSigner,  // { publicKey, signTransaction }
  senderAddress,
  onStage: (stage: TransferStage, payload) => console.log(stage, payload),
});

console.log("settled nullifier:", result.nullifier);

DemoIssuerClient drives the fixture route for local demos. HttpIssuerAdapter uses the canonical issuer API (/.well-known/wisp-issuer.json, POST /v1/proof-packages) for real integrations.

API surface

| Export | Purpose | | ------ | ------- | | createAndSettleTransfer | Full staged fetch → settle pipeline | | createAndSettleTransferWithRetry | Retries once on duplicate nullifier | | fetchTransferPackage | Create + validate a proof package | | validateTransferPackage | Validate a package against issuer + corridor | | proveTransferPackage | Prove (node or browser) | | DuplicateNullifierError | Thrown when a nullifier is already attested |

Interfaces: TransferClientLike, ProofPackageSource, WalletSigner, CreateAndSettleTransferInput, CreateAndSettleTransferResult, BrowserProofOptions, TransferStage.

Stages

fetch → validate → prove → duplicate-check → approve → simulate → settle

Subscribe via onStage to drive progress UI.

Build from source

pnpm build:js
pnpm --filter @wisp_/flows test

Related

• Default client: @wisp_/sdk (WispClient satisfies TransferClientLike; also @wisp_/sdk/flows)
• Transports + chain reads: @wisp_/client
• Protocol validation: @wisp_/core
• Crypto primitives: @wisp_/js