Documentation Index
Fetch the complete documentation index at: https://sdk.umbraprivacy.com/llms.txt
Use this file to discover all available pages before exploring further.
Key Derivation Generator Overrides
All cryptographic keys are derived from the master seed via KMAC256 or Poseidon. Every derivation step is injectable. The following generator types appear as optional deps across the functions that use them.
Master Viewing Key Generators
type MasterViewingKeyGeneratorFunction = () => Promise<MasterViewingKey>;
type MasterViewingKeyBlindingFactorGeneratorFunction = () => Promise<Bn254FieldElement>;
Poseidon Private Key Generators
type PoseidonPrivateKeyGeneratorFunction = () => Promise<Bn254FieldElement>;
type PoseidonBlindingFactorGeneratorFunction = () => Promise<Bn254FieldElement>;
X25519 / Curve25519 Keypair Generators
// User account X25519 key - used for token account encryption
type Curve25519KeypairGeneratorFunction = () => Promise<Curve25519KeypairResult>;
// Per-mint X25519 key - used for UTXO ciphertext addressing
type MintX25519KeypairGeneratorFunction = (mint: Address) => Promise<Curve25519KeypairResult>;
getMintEncryptionKeyRotatorFunction deps.
Viewing Key Generators (Poseidon sub-hierarchy)
type MintViewingKeyGeneratorFunction = (
mint: Address,
options?: ViewingKeyGeneratorOptions,
) => Promise<MintViewingKey>;
type YearlyViewingKeyGeneratorFunction = (
mint: Address,
year: Year,
options?: ViewingKeyGeneratorOptions,
) => Promise<YearlyViewingKey>;
type MonthlyViewingKeyGeneratorFunction = (
mint: Address,
year: Year,
month: Month,
options?: ViewingKeyGeneratorOptions,
) => Promise<MonthlyViewingKey>;
type DailyViewingKeyGeneratorFunction = (
mint: Address,
year: Year,
month: Month,
day: Day,
options?: ViewingKeyGeneratorOptions,
) => Promise<DailyViewingKey>;
type SecondViewingKeyGeneratorFunction = (
mint: Address,
year: Year,
month: Month,
day: Day,
hour: Hour,
minute: Minute,
second: Second,
options?: ViewingKeyGeneratorOptions,
) => Promise<SecondViewingKey>;
Commitment Factor Generators
type RescueEncryptionCommitmentBlindingFactorGeneratorFunction = () => Promise<Bn254FieldElement>;
type RandomFactorForPolynomialCommitmentGeneratorFunction = () => Promise<Curve25519FieldElement>;
type PoseidonKeystreamBlindingFactorGeneratorFunction = () => Promise<Bn254FieldElement>;
Ephemeral UTXO Key Generators
Each UTXO operation uses per-UTXO ephemeral keys parameterized by the on-chain generation index. All are injectable:
type EphemeralUtxoMasterViewingKeyGeneratorFunction = (offset: U256) => Promise<MasterViewingKey>;
type EphemeralUtxoMasterViewingKeyBlindingFactorGeneratorFunction = (offset: U256) => Promise<Bn254FieldElement>;
type EphemeralUtxoPoseidonPrivateKeyGeneratorFunction = (offset: U256) => Promise<Bn254FieldElement>;
type EphemeralUtxoPoseidonPrivateKeyBlindingFactorGeneratorFunction = (offset: U256) => Promise<Bn254FieldElement>;
type EphemeralUtxoNullifierGeneratorFunction = (offset: U256) => Promise<Bn254FieldElement>;
type EphemeralUtxoH2RandomSecretGeneratorFunction = (offset: U256) => Promise<Curve25519FieldElement>;
Cryptographic Operation Overrides
Beyond key generation, the low-level cryptographic operations themselves are injectable.
Rescue Cipher (RC) - Encryption and Decryption
The Rescue cipher is used to encrypt UTXO payloads and encrypted token account balances.
type RcEncryptorFunction = (
plaintext: readonly RcPlaintext[],
) => Promise<{ ciphertexts: RcCiphertext[]; nonce: RcEncryptionNonce }>;
type RcEncryptorWithNonceFunction = (
plaintext: readonly RcPlaintext[],
nonce: RcEncryptionNonce,
) => Promise<RcCiphertext[]>;
type RcDecryptorFunction = (
ciphertext: readonly RcCiphertext[],
nonce: RcEncryptionNonce,
) => Promise<RcPlaintext[]>;
type RcKeyGeneratorFunction = (
counters: readonly RcCounter[],
nonce: RcEncryptionNonce,
) => Promise<RcKey[]>;
getRcEncryptor and getRcKeyGenerator appear in: registration, UTXO creation depsrcDecryptor appears in: getEncryptedBalanceQuerierFunction deps - override to provide a custom decryption backend
AES Encryption
AES-GCM is used for symmetric encryption of UTXO commitment payloads within the mixer.
type AesEncryptorFunction = (
key: AesKey,
plaintext: AesPlaintext,
) => Promise<AesCiphertextWithMetadata>;
type AesDecryptorFunction = (
key: AesKey,
ciphertext: AesCiphertextWithMetadata,
) => Promise<AesPlaintext>;
Poseidon Hash, Encryption, and Keystream
See Poseidon for the hash construction and security properties.
type PoseidonHashFunction = (
dataPoints: readonly Bn254FieldElement[],
) => Promise<Bn254FieldElement>;
type PoseidonAggregatorHashFunction = (
dataPoints: readonly Bn254FieldElement[],
) => Promise<PoseidonHash>;
type PoseidonEncryptorFunction = (
plaintext: readonly PoseidonPlaintext[],
key: PoseidonKey,
) => Promise<PoseidonCiphertext[]>;
type PoseidonKeystreamGeneratorFunction = (
counters: readonly PoseidonCounter[],
key: PoseidonKey,
) => Promise<Map<PoseidonCounter, PoseidonKeystream>>;
type KeystreamCommitmentFunction = (
keystream: Bn254FieldElement,
blindingFactor: Bn254FieldElement,
) => Promise<Bn254FieldElement>;
Fiat-Shamir Challenge and Polynomial Evaluation
type FiatShamirChallengeGeneratorFunction = (
input: Uint8Array,
) => Curve25519FieldElement;
type ChallengePowersFunction = (
challenge: Curve25519FieldElement,
maxPower: number,
) => Curve25519FieldElement[];
type PolynomialEvaluatorFunction = (
coefficients: Curve25519FieldElement[],
point: Curve25519FieldElement,
) => Curve25519FieldElement;
User Commitment Generator
type UserCommitmentGeneratorFunction = (
masterViewingKey: Bn254FieldElement,
masterViewingKeyBlindingFactor: Bn254FieldElement,
poseidonPrivateKey: Bn254FieldElement,
poseidonBlindingFactor: Bn254FieldElement,
) => Promise<Bn254FieldElement>;
