Branded types
Branded types prevent accidentally mixing different kinds of hex strings.
| Type | Shape | Description |
|---|
ZkpAddress | `zk${string}` | Bech32m ZK balance address |
EvmAddress | `0x${string}` | EVM account or contract address |
HexSignature | `0x${string}` | ECDSA secp256k1 signature (65 bytes) |
Token types
| Type | Description |
|---|
Token | Token name string (e.g., 'zkUSD', 'zkEUR') |
TokenMap | Record<string, EvmAddress> -- maps token names to contract addresses |
Cryptographic types
| Type | Description |
|---|
Point | { x: bigint, y: bigint } -- Grumpkin curve point |
GrumpkinPublicKey | Alias for Point -- encryption public key (EPK) |
ElGamalCiphertext | { R: Point, C: Point } -- encrypted value |
EncryptionSecretKey | Branded bigint -- Grumpkin scalar |
ControllerSpendingKey | Branded Uint8Array -- secp256k1 private key |
Transaction types
| Type | Description |
|---|
PreparedTransaction | { tokenAddress, functionName, args } -- ready to submit |
UnsignedTransaction | { tokenAddress, functionName, args, typedData, nonce, signatureArgName } -- needs EIP-712 signature before submission |
UnsignedTransaction details
Used for any action whose calldata embeds an EIP-712 signature — controller auth for ZKP actions, permit for publicToEncryptedTransferWithAuth.
args -- named by ABI parameter, excludes the signature itself.signatureArgName -- which ABI input (or dotted path) the signature is placed under when assembling a PreparedTransaction. Closed set: 'signature' (permit) or 'auth.signature' (controller-signed ZKP actions — inserted inside the auth tuple).- Produced by
prepareEncryptedTransfer, prepareEncryptedToPublicTransfer, preparePublicToEncryptedTransferWithAuth. Consumed by signTransaction / signAuthorization / toSignedTransaction.
Log types
| Type | Description |
|---|
EncryptedBalanceLog | Raw on-chain event (amounts may be ciphertexts) |
DecryptedBalanceLog | Plaintext version (amounts are bigint) |
Both are discriminated unions with type: 'deposit' | 'withdrawal' | 'transfer_in' | 'transfer_out'. Common fields: txHash, blockNumber, amount. Transfer types also include transferId and counterparty info.
Callback types
| Type | Description |
|---|
ProgressCallback | (info: { step: number, total: number, stage: string }) => void |
Backend interfaces
| Type | Description |
|---|
Solver | { init(), solve(point), destroy() } -- discrete log solver |
Prover | { prove(inputs), prewarm?(), destroy() } -- ZK proof generator |
EIP-712 types
| Type | Description |
|---|
TypedDataToSign | { domain, types, primaryType, message } -- EIP-712 typed data |