UmbraWallet

Defined in: src/client/umbra-wallet.ts:153

Umbra Privacy wallet implementation providing cryptographic operations and transaction signing.

Remarks

The UmbraWallet class is the main interface for interacting with the Umbra Privacy protocol. It provides functionality for:

Deriving cryptographic keys from a signer
Creating and managing Rescue ciphers for encryption/decryption
Generating linker hashes for transaction privacy
Signing messages and transactions

The wallet derives its cryptographic material from a master signature seed obtained by signing a default message with the provided signer. This seed is used to derive:

X25519 key pair for Rescue cipher operations
Master viewing key for compliance and transaction linking

Key Derivation:

X25519 keys are derived using KMAC256 with domain separator "Umbra Privacy - X25519 Private Key"
Master viewing key is derived using KMAC128 with domain separator "Umbra Privacy - Master Viewing Key"

Rescue Ciphers: The wallet maintains a cache of Rescue ciphers for different public keys. The cipher for the MXE (Multi-Execution Environment) public key is automatically created during initialization.

Example

// Create wallet from a signer
const wallet = await UmbraWallet.fromSigner(signer);

// Generate linker hash for a transaction
const linkerHash = wallet.generateLinkerHash(
  'create_spl_deposit_with_hidden_amount',
  year, month, day, hour, minute, second
);

// Sign a message
const signature = await wallet.signMessage(message);

// Get Rescue cipher for a public key
const cipher = wallet.getRescueCipherForPublicKey(publicKey);

Properties

arciumX25519PublicKey

readonly arciumX25519PublicKey: ArciumX25519PublicKey

Defined in: src/client/umbra-wallet.ts:166

The X25519 public key derived from the master signature seed.

Remarks

This public key is used for establishing Rescue cipher shared secrets with other parties. It can be shared publicly to enable encrypted communication.

generateRandomSecret()

readonly generateRandomSecret: (index) => U128

Defined in: src/client/umbra-wallet.ts:236

Deterministic random secret generator derived from the wallet's master signature seed.

Parameters

index

U256

Domain-separated index (as U256) used to derive an independent secret.

Returns

U128

A 128-bit secret value as a U128.

Remarks

This function pointer is initialised in the constructor to a KMAC-based derivation that expands the master signature seed into an arbitrary number of cryptographically independent secrets. Each index produces a distinct secret while remaining deterministic for the same wallet and index.

It is typically used as a building block for higher-level blinding factors or protocol- specific secrets, ensuring that each usage has a unique domain separation via the index.

Example

const index: U256 = /* obtain index */;
const secret: U128 = wallet.generateRandomSecret(index);
console.log(secret.toString());

getRescueCipherForPublicKey()

readonly getRescueCipherForPublicKey: (publicKey) => RescueCipher

Defined in: src/client/umbra-wallet.ts:249

Function to get or create a Rescue cipher for a given X25519 public key.

Parameters

publicKey

ArciumX25519PublicKey

The X25519 public key to create a cipher for

Returns

RescueCipher

A Rescue cipher instance configured with the shared secret derived from the key exchange

Remarks

This function performs an X25519 key exchange between the wallet's private key and the provided public key to derive a shared secret, which is then used to initialize the Rescue cipher.

masterViewingKey

readonly masterViewingKey: U128

Defined in: src/client/umbra-wallet.ts:185

The master viewing key derived from the master signature seed.

Remarks

This 128-bit key is used for compliance and transaction linking in the Umbra protocol. It enables authorized parties to link transactions while maintaining privacy for others.

masterViewingKeyPoseidonBlindingFactor

readonly masterViewingKeyPoseidonBlindingFactor: U128

Defined in: src/client/umbra-wallet.ts:201

Blinding factor associated with the master viewing key.

Remarks

The blinding factor is a second 128-bit value derived from the same master signature seed as the master viewing key, but using a distinct domain separator. It is intended to be used as a randomness source in constructions that involve the master viewing key (for example, commitments, randomized encodings, or proof systems) so that the raw viewing key never needs to be used directly.

Keeping the viewing key and its blinding factor separate allows higher-level protocols to combine them in different ways without reusing the same derived value across multiple cryptographic contexts.

masterViewingKeySha3BlindingFactor

readonly masterViewingKeySha3BlindingFactor: U128

Defined in: src/client/umbra-wallet.ts:212

SHA-3 specific blinding factor associated with the master viewing key.

Remarks

This 128-bit value is derived from the same master signature seed using a distinct "Master Viewing Key Sha3 Blinding Factor" domain separator. It is intended to be used anywhere SHA-3–based commitments or hashes depend on the master viewing key, so that Poseidon- and SHA-3–based constructions never reuse the exact same blinding material.

rescueCiphers

readonly rescueCiphers: Map<ArciumX25519PublicKey, RescueCipher>

Defined in: src/client/umbra-wallet.ts:176

Cache of Rescue ciphers keyed by X25519 public keys.

Remarks

This map caches Rescue cipher instances to avoid recreating them for the same public key. The cipher for the MXE (Multi-Execution Environment) public key is automatically created during wallet initialization.

signer

readonly signer: ISigner

Defined in: src/client/umbra-wallet.ts:157

The signer instance used for cryptographic operations and transaction signing.

Methods

addEncryptorForPublicKey()

addEncryptorForPublicKey(publicKey): void

Defined in: src/client/umbra-wallet.ts:822

Adds a Rescue cipher to the cache for a given X25519 public key.

Parameters

publicKey

ArciumX25519PublicKey

The X25519 public key to create and cache a Rescue cipher for

Returns

void

Remarks

This method creates a Rescue cipher that encrypts data using a shared secret derived from an X25519 key exchange between the wallet's X25519 secret key and the provided X25519 public key. The cipher is then cached in the rescueCiphers map for future use.

Key Exchange Process: The method performs an X25519 Diffie-Hellman key exchange: sharedSecret = X25519(walletSecretKey, providedPublicKey)

This shared secret is used to initialize the Rescue cipher, enabling encrypted communication with the party that owns the provided public key.

Caching: The cipher is stored in the rescueCiphers map, allowing efficient reuse without recreating the cipher for subsequent operations with the same public key. If a cipher already exists for the given public key, it will be overwritten with a new instance.

Use Cases:

Pre-caching ciphers for frequently used public keys
Setting up encryption for communication with specific parties
Optimizing performance by avoiding repeated cipher creation

Example

// Add a cipher for a specific public key
wallet.addEncryptorForPublicKey(recipientPublicKey);

// The cipher is now cached and can be retrieved
const cipher = wallet.rescueCiphers.get(recipientPublicKey);
const [ciphertext, nonce] = await cipher.encrypt([100n, 200n]);

generateIndividualTransactionViewingKey()

generateIndividualTransactionViewingKey(purpose, year, month, day, hour, minute, second): U256LeBytes

Defined in: src/client/umbra-wallet.ts:608

Generates a linker hash for transaction privacy and compliance.

Parameters

purpose

The transaction purpose (determines the purpose code)

"create_spl_deposit_with_hidden_amount" | "create_spl_deposit_with_public_amount" | "claim_spl_deposit_with_hidden_amount" | "claim_spl_deposit_with_public_amount"

year

I32

Transaction year

month

U32

Transaction month

day

U32

Transaction day

hour

U32

Transaction hour

minute

U32

Transaction minute

second

U32

Transaction second

Returns

U256LeBytes

A 32-byte Poseidon hash that links transactions with the same parameters

Throws

InvalidPurposeCodeError When the purpose string is not supported

Throws

PoseidonHasherError When Poseidon hashing fails

Remarks

The linker hash is computed using Poseidon over:

Master viewing key (for user identification)
Purpose code (for transaction type)
Timestamp components (year, month, day, hour, minute, second)

This hash enables:

Privacy: Different transactions produce different hashes
Compliance: Authorized parties can link transactions with the same parameters
Uniqueness: Each unique combination of parameters produces a unique hash

The hash is deterministic - the same inputs will always produce the same hash, allowing for transaction linking while maintaining privacy for unrelated transactions.

Example

const linkerHash = wallet.generateLinkerHash(
  'create_spl_deposit_with_hidden_amount',
  2024n, 1n, 15n, 10n, 30n, 0n
);
// Returns a 32-byte PoseidonHash

generateLinkerHash()

generateLinkerHash(purpose, time, address): U256LeBytes

Defined in: src/client/umbra-wallet.ts:634

Parameters

purpose

"create_spl_deposit_with_hidden_amount" | "create_spl_deposit_with_public_amount" | "claim_spl_deposit_with_hidden_amount" | "claim_spl_deposit_with_public_amount"

generateNullifier()

generateNullifier(index): U128

Defined in: src/client/umbra-wallet.ts:849

Derives a deterministic nullifier for a given index using the wallet's master viewing key.

Parameters

index

U256

The nullifier index (typically a position or counter) encoded as a U256.

Returns

U128

A 128-bit nullifier value as a U128.

Remarks

This function uses a two-step KMAC-based derivation:

First, it derives a nullifier master seed from the master viewing key and a fixed context string ("Umbra Privacy - Nullifier Master Seed").
It then derives the final nullifier from the provided index and the nullifier master seed.

The resulting nullifier is deterministic for a given (masterViewingKey, index) pair, while remaining unlinkable across different master viewing keys due to the domain-separated KMAC construction.

Example

const index: U256 = /* obtain index */;
const nullifier: U128 = wallet.generateNullifier(index);
console.log(nullifier.toString());

signMessage()

signMessage(message): Promise<SolanaSignature>

Defined in: src/client/umbra-wallet.ts:689

Signs a message using the wallet's signer.

Parameters

message

Bytes

The message bytes to sign

Returns

Promise<SolanaSignature>

A promise resolving to a 64-byte Ed25519 signature

Throws

SignerError When message signing fails

Remarks

This method delegates to the underlying signer's signMessage method. The signature is a standard Solana Ed25519 signature (64 bytes).

Example

const message = new TextEncoder().encode('Hello, Umbra!');
const signature = await wallet.signMessage(message);

signTransaction()

signTransaction(transaction): Promise<VersionedTransaction>

Defined in: src/client/umbra-wallet.ts:712

Signs a single Solana versioned transaction.

Parameters

transaction

VersionedTransaction

The versioned transaction to sign

Returns

Promise<VersionedTransaction>

A promise resolving to the signed transaction

Throws

SignerError When transaction signing fails

Remarks

This method delegates to the underlying signer's signTransaction method. The transaction is modified in-place with the signature attached.

Example

const signedTx = await wallet.signTransaction(transaction);
await connection.sendTransaction(signedTx);

signTransactions()

signTransactions(transactions): Promise<VersionedTransaction[]>

Defined in: src/client/umbra-wallet.ts:778

Signs multiple Solana versioned transactions in a batch.

Parameters

transactions

VersionedTransaction[]

Array of versioned transactions to sign

Returns

Promise<VersionedTransaction[]>

A promise resolving to an array of signed transactions in the same order as input

Throws

SignerError When batch transaction signing fails

Remarks

This method delegates to the underlying signer's signTransactions method. All transactions are signed in a single batch operation, which may be more efficient than signing them individually.

Example

const signedTxs = await wallet.signTransactions([tx1, tx2, tx3]);
// All transactions are now signed

signTransactionWithEphemeralKeypair()

signTransactionWithEphemeralKeypair(transaction): Promise<{ ephemeralPublicKey: Bytes; signedTransaction: VersionedTransaction; }>

Defined in: src/client/umbra-wallet.ts:733

Signs a Solana versioned transaction using a one-time ephemeral Ed25519 keypair.

Parameters

transaction

VersionedTransaction

The versioned transaction to sign

Returns

Promise<{ ephemeralPublicKey: Bytes; signedTransaction: VersionedTransaction; }>

A promise resolving to the signed transaction and the ephemeral public key bytes

Remarks

This method generates a fresh Ed25519 keypair for each call, constructs a Solana Keypair from it, and uses the transaction's sign method to attach the signature. The private key is scoped to this method and is not stored on the wallet instance.

The returned public key allows callers to add the ephemeral signer to account metas or verify the transaction signature as needed.

createX25519KeypairFromMasterSignatureSeed()

static createX25519KeypairFromMasterSignatureSeed(masterSignatureSeed): object

Defined in: src/client/umbra-wallet.ts:403

Derives an X25519 key pair from a master signature seed.

Parameters

masterSignatureSeed

Uint8Array

The master signature seed (64-byte signature)

Returns

object

An object containing the derived X25519 private and public keys

x25519PrivateKey

x25519PrivateKey: ArciumX25519SecretKey

x25519PublicKey

x25519PublicKey: ArciumX25519PublicKey

Remarks

This method derives an X25519 key pair using KMAC256 with a domain separator. The derivation process:

Uses KMAC256 to derive a 32-byte private key from the seed
Computes the corresponding public key using X25519 scalar multiplication

The domain separator "Umbra Privacy - X25519 Private Key" ensures the derived key is unique to this purpose and prevents key reuse across different contexts.

Example

const { x25519PrivateKey, x25519PublicKey } =
  UmbraWallet.createX25519KeypairFromMasterSignatureSeed(signatureSeed);

fromSigner()

static fromSigner(signer): Promise<UmbraWallet>

Defined in: src/client/umbra-wallet.ts:316

Creates a new UmbraWallet instance from a signer.

Parameters

signer

ISigner

The signer instance to use for wallet operations

Returns

Promise<UmbraWallet>

A promise resolving to a new UmbraWallet instance

Throws

UmbraWalletInitializationError When wallet initialization fails

Throws

SignerError When message signing fails during initialization

Remarks

This factory method initializes a new UmbraWallet by:

Signing the default message to obtain a master signature seed
Deriving X25519 key pair from the master signature seed
Deriving the master viewing key from the master signature seed
Creating a function to generate Rescue ciphers for any public key
Pre-creating the Rescue cipher for the MXE public key

The master signature seed is obtained by signing a default message that warns users about the security implications. This signature is used as a seed for all key derivation.

Example

const wallet = await UmbraWallet.fromSigner(signer);
console.log(`Wallet public key: ${wallet.arciumX25519PublicKey}`);
console.log(`Master viewing key: ${wallet.masterViewingKey}`);

generateMasterViewingKeyBlindingFactorFromMasterSignatureSeed()

static generateMasterViewingKeyBlindingFactorFromMasterSignatureSeed(masterSignatureSeed): U128

Defined in: src/client/umbra-wallet.ts:516

Derives a blinding factor for the master viewing key from a master signature seed.

Parameters

masterSignatureSeed

Uint8Array

The master signature seed (64-byte signature)

Returns

U128

A 128-bit blinding factor (U128) for use alongside the master viewing key

Remarks

This method derives a second 128-bit value using KMAC128 with a dedicated domain separator "Umbra Privacy - Master Viewing Key Blinding Factor". It is computed from the same master signature seed as the master viewing key, but with a different derivation label so that:

The blinding factor is cryptographically independent from the master viewing key
The viewing key never needs to be reused directly as randomness in other schemes

Typical uses include:

Adding noise/randomness to commitments that depend on the master viewing key
Generating per-user randomness in zero-knowledge proofs or encrypted metadata

Example

const blindingFactor =
  UmbraWallet.generateMasterViewingKeyBlindingFactorFromMasterSignatureSeed(signatureSeed);

generateMasterViewingKeyFromMasterSignatureSeed()

static generateMasterViewingKeyFromMasterSignatureSeed(masterSignatureSeed): U128

Defined in: src/client/umbra-wallet.ts:447

Derives a master viewing key from a master signature seed.

Parameters

masterSignatureSeed

Uint8Array

The master signature seed (64-byte signature)

Returns

U128

A 128-bit master viewing key (U128)

Remarks

This method derives a 128-bit master viewing key using KMAC128 with a domain separator. The master viewing key is used for:

Compliance and transaction linking
Generating linker hashes for transaction privacy
Enabling authorized parties to link related transactions

The domain separator "Umbra Privacy - Master Viewing Key" ensures the derived key is unique to this purpose and prevents key reuse across different contexts.

Example

const masterViewingKey =
  UmbraWallet.generateMasterViewingKeyFromMasterSignatureSeed(signatureSeed);

generateMasterViewingKeySha3BlindingFactorFromMasterSignatureSeed()

static generateMasterViewingKeySha3BlindingFactorFromMasterSignatureSeed(masterSignatureSeed): U128

Defined in: src/client/umbra-wallet.ts:477

Derives a SHA-3-specific blinding factor for the master viewing key from a master signature seed.

Parameters

masterSignatureSeed

Uint8Array

The master signature seed (64-byte signature)

Returns

U128

A 128-bit blinding factor (U128) for use with SHA-3–based commitments

Remarks

This method derives a 128-bit value using KMAC128 with the domain separator "Umbra Privacy - Master Viewing Key Sha3 Blinding Factor". It is computed from the same master signature seed as the master viewing key and Poseidon blinding factor, but uses a distinct label so that SHA-3–based and Poseidon-based constructions never reuse the exact same randomness.

Use this factor anywhere you need per-user randomness in SHA-3 commitments or hashes that are tied to the master viewing key, without exposing the viewing key itself.

getPurposeCode()

static getPurposeCode(purpose): U128

Defined in: src/client/umbra-wallet.ts:555

Gets the purpose code for a given transaction purpose string.

claim_spl_deposit_with_hidden_amount → 0
claim_spl_deposit_with_public_amount → 1
create_spl_deposit_with_hidden_amount → 2
create_spl_deposit_with_public_amount → 3

Purpose codes are included in linker hash generation to ensure different transaction types produce different hashes even with the same timestamp.

Example

const purposeCode = UmbraWallet.getPurposeCode('create_spl_deposit_with_hidden_amount');
// Returns 2n

UmbraWallet

On this page