Skip to main content

​
Key Rotation via Offsets

Key rotation is a distinct mechanism from dependency injection. Rather than replacing the generator function, you increment a numeric offset at client construction time. This causes the KMAC256 derivation to produce a completely different key for the same wallet, without changing any code. 
const client = await getUmbraClient({
  signer,
  network: "mainnet",
  rpcUrl,
  rpcSubscriptionsUrl,
  offsets: {
    x25519UserAccountPrivateKey: 1n,   // rotate the token encryption key
    poseidonPrivateKey: 0n,
    masterViewingKey: 0n,
    x25519MasterViewingKeyEncryptingPrivateKey: 0n,
    mintX25519PrivateKey: 0n,
    rescueCommitmentBlindingFactor: 0n,
    randomCommitmentFactor: 0n,
  },
});
Available offset keys:
  • masterViewingKey
  • poseidonPrivateKey
  • x25519UserAccountPrivateKey
  • x25519MasterViewingKeyEncryptingPrivateKey
  • mintX25519PrivateKey
  • rescueCommitmentBlindingFactor
  • randomCommitmentFactor
Rotating an offset produces a different derived key. Any on-chain state — registered X25519 keys, encrypted balances, compliance grants — was created under the old key and cannot be accessed with the rotated key. Always re-register after rotating the user-account key, and update any grants that referenced the old MVK X25519 key.
For active on-chain key rotation (issue a new key, re-encrypt existing state, retire the old key), use the rotators exported from @umbra-privacy/sdk/account — see Recovery & Rotation.

​
Per-Factory Deps Reference (V18)

A complete map of which injectable deps each factory accepts. Subpath in parens.

​
Registration — @umbra-privacy/sdk/registration

getUserRegistrationFunction
  • accountInfoProvider, getLatestBlockhash, transactionForwarder.
  • masterViewingKeyDeriver, masterViewingKeyBlindingFactorDeriver.
  • poseidonPrivateKeyDeriver, poseidonBlindingFactorDeriver.
  • userAccountX25519KeypairGenerator, masterViewingKeyEncryptingX25519KeypairGenerator.
  • mintX25519KeypairGenerator.
  • rescueCommitmentBlindingFactorDeriver, randomFactorDeriver.
  • getRcKeyGenerator, getRcEncryptor, rescueCommitmentGenerator.
  • userCommitmentGenerator.
  • fiatShamirChallengeGenerator, challengePowersFunction, polynomialEvaluator.
  • poseidonAggregator.
  • bn254ModInverter, computeLimbwiseSumInverse.
  • zkProver (IZkProverForUserRegistration) — required.

​
Deposit — @umbra-privacy/sdk/deposit

getATAIntoETADirectDepositorFunction
  • accountInfoProvider, getLatestBlockhash, transactionForwarder, getEpochInfo.

​
Withdrawal — @umbra-privacy/sdk/withdrawal

getETAIntoATAWithdrawerFunction
  • accountInfoProvider, getLatestBlockhash, transactionForwarder.

​
Query — @umbra-privacy/sdk/query

getUserAccountQuerierFunction
  • accountInfoProvider.
getEncryptedBalanceQuerierFunction
  • accountInfoProvider.
  • rcDecryptor — override to provide a custom Rescue cipher decryption backend.

​
Stealth Pool Note creation — @umbra-privacy/sdk/deposit

getETAIntoSelfBurnableStealthPoolNoteCreatorFunction (ETA-source, MPC)
  • accountInfoProvider, blockhashProvider, transactionForwarder.
  • All MVK / Poseidon / ephemeral-note key derivers.
  • Cryptographic operation functions (Poseidon, Rescue, AES, Fiat-Shamir).
  • zkProver (IZkProverForETAIntoStealthPoolNote) — required.
getETAIntoReceiverBurnableStealthPoolNoteCreatorFunction
  • Same as above.
  • zkProver (IZkProverForETAIntoStealthPoolNote) — required.
getATAIntoSelfBurnableStealthPoolNoteCreatorFunction (ATA-source, no MPC)
  • accountInfoProvider, blockhashProvider, transactionForwarder.
  • All MVK / Poseidon / ephemeral-note key derivers.
  • Cryptographic operation functions.
  • zkProver (IZkProverForETAIntoStealthPoolNote) — required.
getATAIntoReceiverBurnableStealthPoolNoteCreatorFunction
  • Same as above.
  • zkProver (IZkProverForETAIntoStealthPoolNote) — required.

​
Stealth Pool Note scan + burn — @umbra-privacy/sdk/burn

getBurnableStealthPoolNoteScannerFunction (zero-arg scanner)
  • fetchStealthPoolNoteData — override note-data fetcher.
  • fetchMerkleProof — override single-leaf Merkle proof fetcher used internally for sanity checks. (Per-batch proofs are a separate dep on the burner factories, not the scanner.)
  • additionalX25519PrivateKeys — extra X25519 keys to try when decrypting (multi-key wallets).
getReceiverBurnableStealthPoolNoteIntoETABurnerFunction
  • accountInfoProvider, getLatestBlockhash, transactionForwarder.
  • All key derivers + cryptographic op functions.
  • fetchBatchMerkleProof — required (use client.fetchBatchMerkleProof).
  • zkProver (IZkProverForClaimReceiverClaimableUtxoIntoEncryptedBalance) — required.
  • relayer: { submitBurn, pollBurnStatus, getRelayerAddress } — required (TS aliases of the relayer client’s submitClaim, pollClaimStatus, getRelayerAddress).
getSelfBurnableStealthPoolNoteIntoETABurnerFunction
  • Same shape; zkProver is IZkProverForClaimSelfClaimableUtxoIntoEncryptedBalance.
getSelfBurnableStealthPoolNoteIntoATABurnerFunction
  • Same shape; zkProver is IZkProverForClaimSelfClaimableUtxoIntoPublicBalance.

​
Conversion — @umbra-privacy/sdk/conversion

getNetworkEncryptionToSharedEncryptionConverterFunction
  • accountInfoProvider, getLatestBlockhash, transactionForwarder.

​
Account — @umbra-privacy/sdk/account

getStagedSolRecovererFunction, getStagedSplRecovererFunction
  • accountInfoProvider, getLatestBlockhash, transactionForwarder.
Key rotators (rotation submodule):
  • getUserEncryptionKeyRotator… — sync, no MPC.
  • getMintEncryptionKeyRotator… — MPC; re-encrypts on-chain balance under the new per-mint key.
  • getMasterViewingKeyRotator… — MPC + ZK; rotates MVK X25519 + user commitment.
Maintenance:
  • getUserEntropySeedRotatorFunction, getTokenEntropySeedRotatorFunction — sync, no MPC.

​
Compliance — @umbra-privacy/sdk/compliance

getComplianceGrantIssuerFunction, getComplianceGrantRevokerFunction, getSharedCiphertextReencryptorForUserGrantFunction, getNetworkCiphertextReencryptorForNetworkGrantFunction, getSharedCiphertextReencryptorForNetworkGrantFunction
  • accountInfoProvider, getLatestBlockhash, transactionForwarder (those that submit transactions).
getUserComplianceGrantQuerierFunction, getNetworkComplianceGrantQuerierFunction, getSharedComplianceGrantQuerierFunction
  • accountInfoProvider.