Migration: V4 → V5

// package.json
{
  "dependencies": {
    "@umbra-privacy/sdk": "^4.0.0",
    "@umbra-privacy/web-zk-prover": "^2.0.0"
  }
}

// app code
import { getCreateReceiverClaimableUtxoFromPublicBalanceProver } from "@umbra-privacy/web-zk-prover";
import { getCdnZkAssetProvider } from "@umbra-privacy/web-zk-prover/cdn";

{
  "dependencies": {
    "@umbra-privacy/sdk": "5.0.0-rc.3"
  }
}

// Creator prover factories were renamed in V5:
import { getATAIntoStealthPoolNoteCreatorProver } from "@umbra-privacy/sdk/zk-prover";
// Burner prover factories kept V4 spellings:
import { getClaimReceiverClaimableUtxoIntoEncryptedBalanceProver } from "@umbra-privacy/sdk/zk-prover";
import { getCdnZkAssetProvider } from "@umbra-privacy/sdk/zk-prover/cdn";

// next.config.ts — before
transpilePackages: ["@umbra-privacy/sdk", "@umbra-privacy/web-zk-prover"]
// after
transpilePackages: ["@umbra-privacy/sdk"]

import { getClaimableUtxoScannerFunction } from "@umbra-privacy/sdk";

const scan   = getClaimableUtxoScannerFunction({ client });
const result = await scan(0, 0); // (treeIndex, startInsertionIndex, endInsertionIndex?)

console.log("Self-burnable from ETA:", result.selfBurnable.length);
console.log("Receiver from ETA:",      result.received.length);
console.log("Self-burnable from ATA:", result.publicSelfBurnable.length);
console.log("Receiver from ATA:",      result.publicReceived.length);

// Pass directly to a V4 claimer — the UTXOs come with Merkle proofs attached.
await claim(result.received);

import { getBurnableStealthPoolNoteScannerFunction } from "@umbra-privacy/sdk/burn";

const scan   = getBurnableStealthPoolNoteScannerFunction({ client });
const result = await scan(); // zero-arg

console.log("Self-burnable from ETA:    ", result.etaToStealthPoolSelfBurnable.length);
console.log("Receiver from ETA:         ", result.etaToStealthPoolReceiverBurnable.length);
console.log("Self-burnable from ATA:   ", result.ataToStealthPoolSelfBurnable.length);
console.log("Receiver from ATA:        ", result.ataToStealthPoolReceiverBurnable.length);
console.log("Scanned trees:             ", result.scannedTrees.length);

// Pass directly to a V5 burner — it fetches per-batch proofs internally.
await burn(result.etaToStealthPoolReceiverBurnable);

import {
  getReceiverClaimableUtxoToEncryptedBalanceClaimerFunction,
  getUmbraRelayer,
} from "@umbra-privacy/sdk";
import { getClaimReceiverClaimableUtxoIntoEncryptedBalanceProver } from "@umbra-privacy/web-zk-prover";

const relayer  = getUmbraRelayer({ apiEndpoint });
const zkProver = getClaimReceiverClaimableUtxoIntoEncryptedBalanceProver();

const claim = getReceiverClaimableUtxoToEncryptedBalanceClaimerFunction(
  { client },
  { zkProver, relayer }, // V4: pass the relayer object as-is
);

await claim(utxos);

import { getReceiverBurnableStealthPoolNoteIntoETABurnerFunction } from "@umbra-privacy/sdk/burn";
import { getUmbraRelayer } from "@umbra-privacy/sdk";
import { getClaimReceiverClaimableUtxoIntoEncryptedBalanceProver } from "@umbra-privacy/sdk/zk-prover";

const r        = getUmbraRelayer({ apiEndpoint });
const zkProver = getClaimReceiverClaimableUtxoIntoEncryptedBalanceProver();

const burn = getReceiverBurnableStealthPoolNoteIntoETABurnerFunction(
  { client },
  {
    fetchBatchMerkleProof: client.fetchBatchMerkleProof!,
    zkProver,
    relayer: {
      submitBurn:        r.submitClaim,         // alias: BurnSubmitter ≡ ClaimSubmitter
      pollBurnStatus:    r.pollClaimStatus,     // alias: BurnStatusPoller ≡ ClaimStatusPoller
      getRelayerAddress: r.getRelayerAddress,
    },
  },
);

await burn(notes);

interface BurnStealthPoolNoteIntoETAResult {
  readonly signatures: readonly TransactionSignature[]; // from OperationOutcome — every tx submitted
  readonly batches: Map<U32, BurnBatchResult>;          // keyed by batch index
}

interface BurnBatchResult {
  readonly requestId: string;                  // relayer-assigned tracking ID
  readonly status: BurnStatus;
  readonly txSignature?: string;               // on-chain burn tx (when landed)
  readonly callbackSignature?: string;         // MPC callback tx (when finalised)
  readonly resolvedVariant?: string;           // e.g. "claim_into_existing_shared_balance_v17"
  readonly failureReason?: string | null;
  readonly stealthPoolNoteIds?: readonly string[]; // "treeIndex:leafIndex" pairs
}

type BurnStatus =
  | "received" | "validating" | "offsets_reserved" | "building_tx" | "tx_built"
  | "submitting" | "submitted" | "awaiting_callback" | "callback_received"
  | "finalizing" | "completed" | "failed" | "timed_out" | "refunded";

type ReceiverBurnerFn = (
  stealthPoolNotes: readonly (DecryptedStealthPoolNoteData & { kind: "receiver-burnable" })[],
  optionalData?: OptionalData32,
  microLamportsPerAcu?: MicroLamportsPerAcu,  // NEW in V5 — per-call priority fee
) => Promise<BurnStealthPoolNoteIntoETAResult>;

import { getUmbraClient } from "@umbra-privacy/sdk";
import {
  createBrowserStorageBackend,
  createShardedUtxoDataStore,
  createShardedNullifierStore,
} from "@umbra-privacy/sdk/store-adapters";

const storageBackend = createBrowserStorageBackend({ dbName: `umbra-${walletPubkey}` });
const utxoDataStore  = createShardedUtxoDataStore({ storageBackend });
const nullifierStore = createShardedNullifierStore({ storageBackend });

const client = await getUmbraClient({
  signer,
  network: "mainnet",
  rpcUrl,
  rpcSubscriptionsUrl,
  indexerApiEndpoint,
  utxoDataStore,   // NEW in V5
  nullifierStore,  // NEW in V5
});

// V4
import { UMBRA_MESSAGE_TO_SIGN } from "@umbra-privacy/sdk";

// V5
import { UMBRA_MESSAGE_TO_SIGN } from "@umbra-privacy/sdk/shared";

// V4 — callbacks: { pre, post } shape
await register({
  confidential: true,
  anonymous: true,
  callbacks: {
    userAccountInitialisation:     { pre: async (tx) => …,         post: async (tx, sig) => … },
    registerX25519PublicKey:       { pre: async (tx) => …,         post: async (tx, sig) => … },
    registerUserForAnonymousUsage: { pre: async (tx) => …,         post: async (tx, sig) => … },
  },
});

// V5 — hooks: RegistrationHooks shape (renamed slot + new hook event shape)
await register({
  confidential: true,
  anonymous: true,
  hooks: {
    // Top-level phase hooks (new in V5)
    onValidationStart:      async () => …,
    onAccountFetchComplete: async ({ userAccountExists, hasX25519Key, isAnonymous }) => …,
    onKeyDerivationComplete: async ({ elapsedMs }) => …,

    // Per-step slots — { onPreSend, onPostSend, onSkipped }
    initUserAccount: {
      onSkipped:  async ({ reason }) => …,
      onPreSend:  async ({ signedTransaction }) => …,
      onPostSend: async ({ signature }) => …,
    },
    registerX25519PublicKey: {
      onSkipped:  async ({ reason }) => …,
      onPreSend:  async () => …,
      onPostSend: async ({ signature }) => …,
    },
    registerAnonymousUsage: {
      onSkipped:  async ({ reason }) => …,
      onPreSend:  async () => …,
      onPostSend: async ({ signature }) => …,
    },

    onComplete: async (result) => …,
    onError:    async ({ phase, error }) => …,
  },
});

import {
  getUmbraClient,
  getClaimableUtxoScannerFunction,
  getReceiverClaimableUtxoToEncryptedBalanceClaimerFunction,
  getUmbraRelayer,
} from "@umbra-privacy/sdk";
import { getClaimReceiverClaimableUtxoIntoEncryptedBalanceProver } from "@umbra-privacy/web-zk-prover";

const client = await getUmbraClient({
  signer,
  network: "mainnet",
  rpcUrl,
  rpcSubscriptionsUrl,
  indexerApiEndpoint,
});

const scan   = getClaimableUtxoScannerFunction({ client });
const result = await scan(0, 0);

const relayer = getUmbraRelayer({ apiEndpoint });
const claim   = getReceiverClaimableUtxoToEncryptedBalanceClaimerFunction(
  { client },
  { zkProver: getClaimReceiverClaimableUtxoIntoEncryptedBalanceProver(), relayer },
);

if (result.received.length > 0) {
  const out = await claim(result.received);
  console.log("Signatures:", out.signatures);
}

import { getUmbraClient, getUmbraRelayer } from "@umbra-privacy/sdk";
import {
  createBrowserStorageBackend,
  createShardedUtxoDataStore,
  createShardedNullifierStore,
} from "@umbra-privacy/sdk/store-adapters";
import {
  getBurnableStealthPoolNoteScannerFunction,
  getReceiverBurnableStealthPoolNoteIntoETABurnerFunction,
} from "@umbra-privacy/sdk/burn";
import { getClaimReceiverClaimableUtxoIntoEncryptedBalanceProver } from "@umbra-privacy/sdk/zk-prover";

const storageBackend = createBrowserStorageBackend({ dbName: `umbra-${signer.address}` });
const utxoDataStore  = createShardedUtxoDataStore({ storageBackend });
const nullifierStore = createShardedNullifierStore({ storageBackend });

const client = await getUmbraClient({
  signer,
  network: "mainnet",
  rpcUrl,
  rpcSubscriptionsUrl,
  indexerApiEndpoint,
  utxoDataStore,
  nullifierStore,
});

const scan   = getBurnableStealthPoolNoteScannerFunction({ client });
const result = await scan();

// The relayer is constructed separately — it is not a getUmbraClient argument.
const r    = getUmbraRelayer({ apiEndpoint: "https://relayer.api.umbraprivacy.com" });
const burn = getReceiverBurnableStealthPoolNoteIntoETABurnerFunction(
  { client },
  {
    fetchBatchMerkleProof: client.fetchBatchMerkleProof!,
    zkProver: getClaimReceiverClaimableUtxoIntoEncryptedBalanceProver(),
    relayer: {
      submitBurn:        r.submitClaim,
      pollBurnStatus:    r.pollClaimStatus,
      getRelayerAddress: r.getRelayerAddress,
    },
  },
);

const notes = result.etaToStealthPoolReceiverBurnable;
if (notes.length > 0) {
  const out = await burn(notes);
  for (const [batchIndex, b] of out.batches) {
    console.log(
      "Batch",   batchIndex,
      "status:", b.status,
      "id:",     b.requestId,
      "sig:",    b.callbackSignature ?? b.txSignature,
    );
  }
}