@volr/sdk-core 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,1338 @@
+import { AxiosInstance } from 'axios';
+
+/**
+ * HKDF-SHA256 key derivation
+ *
+ * @param ikm - Input Key Material (32 bytes recommended)
+ * @param salt - Salt (can be empty, but 32 bytes recommended)
+ * @param info - Application-specific info string
+ * @param len - Output length in bytes (default: 32)
+ * @returns Derived key material
+ * @throws VolrError if info is empty or other validation fails
+ *
+ * @example
+ * ```ts
+ * const ikm = new Uint8Array(32).fill(0x01);
+ * const salt = new Uint8Array(32).fill(0x02);
+ * const key = hkdfSha256(ikm, salt, 'volr/wrap-key/v1', 32);
+ * ```
+ */
+declare function hkdfSha256(ikm: Uint8Array, salt: Uint8Array, info: string, len?: number): Uint8Array;
+
+/**
+ * AES-GCM encryption parameters
+ */
+type AesGcmParams = {
+    /** 32-byte encryption key */
+    key: Uint8Array;
+    /** 12-byte nonce (optional, will be generated if not provided) */
+    nonce?: Uint8Array;
+    /** Additional Authenticated Data (optional) */
+    aad?: Uint8Array;
+};
+/**
+ * AES-256-GCM encryption
+ *
+ * @param plain - Plaintext to encrypt
+ * @param params - Encryption parameters (key, optional nonce, optional AAD)
+ * @returns Object containing ciphertext and nonce
+ * @throws VolrError if key is not 32 bytes, nonce is not 12 bytes, or encryption fails
+ *
+ * @example
+ * ```ts
+ * const key = getRandomBytes(32);
+ * const plaintext = new TextEncoder().encode('secret data');
+ * const { cipher, nonce } = await aesGcmEncrypt(plaintext, { key });
+ * ```
+ */
+declare function aesGcmEncrypt(plain: Uint8Array, params: AesGcmParams): Promise<{
+    cipher: Uint8Array;
+    nonce: Uint8Array;
+}>;
+/**
+ * AES-256-GCM decryption
+ *
+ * @param cipher - Ciphertext to decrypt
+ * @param params - Decryption parameters (key, nonce, optional AAD)
+ * @returns Decrypted plaintext
+ * @throws VolrError if decryption fails (wrong key, wrong AAD, corrupted data)
+ *
+ * @example
+ * ```ts
+ * const plaintext = await aesGcmDecrypt(cipher, { key, nonce });
+ * ```
+ */
+declare function aesGcmDecrypt(cipher: Uint8Array, params: AesGcmParams & {
+    nonce: Uint8Array;
+}): Promise<Uint8Array>;
+
+/**
+ * Zeroize (overwrite with zeros) a buffer in place
+ * This helps prevent sensitive data from remaining in memory
+ *
+ * @param buf - Uint8Array or ArrayBuffer to zeroize
+ */
+declare function zeroize(buf: Uint8Array | ArrayBuffer): void;
+
+/**
+ * Get secure random bytes using WebCrypto API
+ * Falls back to Node.js crypto.webcrypto if WebCrypto is not available
+ *
+ * @param len - Number of bytes to generate
+ * @returns Uint8Array of random bytes
+ * @throws VolrError if random generation fails
+ */
+declare function getRandomBytes(len: number): Uint8Array;
+
+/**
+ * Opaque type for WrapKey (32 bytes)
+ * This is a type-level marker to prevent accidental misuse
+ */
+type WrapKey = Uint8Array & {
+    readonly __brand: 'WrapKey';
+};
+/**
+ * Opaque type for MasterSeed (32 bytes)
+ * This is a type-level marker to prevent accidental misuse
+ */
+type MasterSeed = Uint8Array & {
+    readonly __brand: 'MasterSeed';
+};
+
+/**
+ * Opaque handle to master seed
+ * Provides controlled access and ensures cleanup via destroy()
+ */
+type MasterSeedHandle = {
+    /** Read-only access to master seed bytes */
+    readonly bytes: MasterSeed;
+    /** Destroy the handle and zeroize the seed */
+    destroy(): void;
+};
+/**
+ * Master key provider interface
+ * Handles generation and unsealing of master seeds
+ */
+interface MasterKeyProvider {
+    /**
+     * Unseal master seed from encrypted blob
+     *
+     * @param blob - Encrypted blob containing ciphertext, nonce, and AAD
+     * @param wrapKey - Wrap key for decryption
+     * @returns Handle to unsealed master seed
+     */
+    unsealFromBlob(blob: {
+        cipher: Uint8Array;
+        nonce: Uint8Array;
+        aad: Uint8Array;
+    }, wrapKey: WrapKey): Promise<MasterSeedHandle>;
+    /**
+     * Generate a new master seed
+     *
+     * @returns Handle to newly generated master seed
+     */
+    generate(): Promise<MasterSeedHandle>;
+}
+/**
+ * Create a master key provider instance
+ *
+ * @returns MasterKeyProvider instance
+ *
+ * @example
+ * ```ts
+ * const provider = createMasterKeyProvider();
+ * const handle = await provider.generate();
+ * // Use handle.bytes for key derivation
+ * handle.destroy(); // Cleanup
+ * ```
+ */
+declare function createMasterKeyProvider(): MasterKeyProvider;
+
+/**
+ * Seal (encrypt) master seed with wrap key
+ *
+ * @param masterSeed - 32-byte master seed to encrypt
+ * @param wrapKey - 32-byte wrap key
+ * @param aad - Additional Authenticated Data
+ * @returns Object containing ciphertext and nonce
+ *
+ * @example
+ * ```ts
+ * const masterSeed = getRandomBytes(32);
+ * const wrapKey = deriveWrapKey({ origin, projectId, credentialId });
+ * const aad = new TextEncoder().encode('volr/master-seed/v1');
+ * const { cipher, nonce } = await sealMasterSeed(masterSeed, wrapKey, aad);
+ * ```
+ */
+declare function sealMasterSeed(masterSeed: Uint8Array, wrapKey: WrapKey, aad: Uint8Array): Promise<{
+    cipher: Uint8Array;
+    nonce: Uint8Array;
+}>;
+/**
+ * Unseal (decrypt) master seed with wrap key
+ *
+ * @param cipher - Encrypted master seed
+ * @param wrapKey - 32-byte wrap key
+ * @param aad - Additional Authenticated Data (must match encryption)
+ * @param nonce - 12-byte nonce used during encryption
+ * @returns Decrypted master seed (32 bytes)
+ * @throws Error if decryption fails (wrong key, wrong AAD, corrupted data)
+ *
+ * @example
+ * ```ts
+ * const masterSeed = await unsealMasterSeed(cipher, wrapKey, aad, nonce);
+ * // Use masterSeed, then zeroize it
+ * zeroize(masterSeed);
+ * ```
+ */
+declare function unsealMasterSeed(cipher: Uint8Array, wrapKey: WrapKey, aad: Uint8Array, nonce: Uint8Array): Promise<MasterSeed>;
+
+/**
+ * PRF input parameters for wrap key derivation
+ */
+type PrfInput = {
+    /** Origin (e.g., "https://example.com") */
+    origin: string;
+    /** Project ID */
+    projectId: string;
+    /** Credential ID from WebAuthn */
+    credentialId: string;
+    /** Optional salt (defaults to SHA256 of concatenated inputs) */
+    salt?: Uint8Array;
+};
+/**
+ * Derive wrap key from PRF inputs using HKDF
+ *
+ * PRF input domain is fixed: rpId|projectId (credentialId excluded)
+ * This ensures consistent wrap key derivation across sessions
+ *
+ * Note: credentialId is NOT included in salt derivation because:
+ * - During enrollment, actual credentialId is not known until after credential creation
+ * - Using credentialId would create different salts for enrollment vs authentication
+ * - This would cause PRF to return different outputs, breaking decryption
+ *
+ * This function maps PRF output (from WebAuthn) to a 32-byte wrap key.
+ * In the real implementation, the PRF output would come from WebAuthn PRF API.
+ * For now, we simulate it by using SHA256 of the inputs.
+ *
+ * @param input - PRF input parameters
+ * @returns 32-byte wrap key
+ *
+ * @example
+ * ```ts
+ * const wrapKey = deriveWrapKey({
+ *   origin: 'https://example.com',
+ *   projectId: 'project-123',
+ *   credentialId: 'cred-456' // stored for authentication, but not used in salt derivation
+ * });
+ * ```
+ */
+declare function deriveWrapKey(input: PrfInput): WrapKey;
+
+/**
+ * Default BIP-32 derivation path for Ethereum
+ * m / purpose' / coin_type' / account' / change / address_index
+ * 60' = Ethereum coin type
+ */
+declare const DEFAULT_EVM_PATH = "m/60'/0'/0'/0/0";
+/**
+ * Arguments for EVM key derivation
+ */
+type DeriveArgs = {
+    /** Master seed (32 bytes recommended) */
+    masterSeed: Uint8Array;
+    /** BIP-32 derivation path (default: m/60'/0'/0'/0/0) */
+    path?: string;
+};
+/**
+ * EVM keypair derived from master seed
+ */
+type EvmKeypair = {
+    /** 32-byte private key */
+    privateKey: Uint8Array;
+    /** 65-byte uncompressed public key (0x04 prefix) */
+    publicKey: Uint8Array;
+    /** 20-byte EOA address (checksummed) */
+    address: `0x${string}`;
+    /** Derivation path used */
+    path: string;
+};
+/**
+ * Derive EVM keypair from master seed using BIP-32
+ *
+ * @param args - Derivation arguments
+ * @returns EVM keypair with private key, public key, and address
+ *
+ * @example
+ * ```ts
+ * const masterSeed = getRandomBytes(32);
+ * const keypair = deriveEvmKey({ masterSeed });
+ * // Use keypair.privateKey for signing
+ * // Use keypair.address as EOA address
+ * ```
+ */
+declare function deriveEvmKey(args: DeriveArgs): EvmKeypair;
+
+/**
+ * Convert Ethereum address to EIP-55 checksum format
+ *
+ * EIP-55: Mixed-case checksum address encoding
+ * https://eips.ethereum.org/EIPS/eip-55
+ *
+ * @param addr - Lowercase Ethereum address (0x prefix required)
+ * @returns Checksummed address
+ * @throws Error if address is invalid (wrong length, non-hex, missing 0x prefix)
+ *
+ * @example
+ * ```ts
+ * const checksummed = toChecksumAddress('0x742d35cc6634c0532925a3b844bc9e7595f0bebd');
+ * // Returns: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEbD'
+ * ```
+ */
+declare function toChecksumAddress(addr: `0x${string}`): `0x${string}`;
+
+/**
+ * EVM signature structure
+ */
+type Sig$1 = {
+    /** 32-byte r value */
+    r: Uint8Array;
+    /** 32-byte s value (low-S canonicalized) */
+    s: Uint8Array;
+    /** y-parity (0 or 1) */
+    yParity: 0 | 1;
+};
+/**
+ * Sign a message hash with secp256k1 private key
+ *
+ * Produces deterministic, low-S canonicalized signatures compatible with EVM.
+ *
+ * @param privKey - 32-byte private key
+ * @param msgHash32 - 32-byte message hash
+ * @returns Signature with r, s, and yParity
+ * @throws Error if private key or message hash is invalid
+ *
+ * @example
+ * ```ts
+ * const privateKey = getRandomBytes(32);
+ * const msgHash = sha256(new TextEncoder().encode('Hello'));
+ * const sig = evmSign(privateKey, msgHash);
+ * // Use sig.r, sig.s, sig.yParity for transaction signing
+ * ```
+ */
+declare function evmSign(privKey: Uint8Array, msgHash32: Uint8Array): Sig$1;
+
+/**
+ * Provider types for EVM wallet operations
+ */
+
+/**
+ * RPC client interface for capability detection
+ */
+interface RpcLike {
+    call(args: {
+        to: `0x${string}`;
+        data: `0x${string}`;
+    }): Promise<`0x${string}`>;
+}
+/**
+ * EIP-712 typed data structure
+ */
+type TypedDataInput = {
+    domain: any;
+    types: any;
+    message: any;
+};
+/**
+ * Common wallet provider port interface
+ * Both Passkey and MPC providers implement this interface
+ */
+interface WalletProviderPort {
+    /** Key storage type: 'passkey' or 'mpc' */
+    keyStorageType: KeyStorageType;
+    /**
+     * Ensure session is established
+     * - Passkey: PRF → unwrap master seed
+     * - MPC: Backend proxy session setup
+     *
+     * @param opts - Session options
+     * @param opts.interactive - If true, requires user gesture (WebAuthn prompt)
+     * @param opts.force - If true, invalidates existing session and re-authenticates
+     */
+    ensureSession(opts?: {
+        interactive?: boolean;
+        force?: boolean;
+    }): Promise<void>;
+    /**
+     * Lock the provider (zeroize sensitive data from memory)
+     * Should be called after each transaction for TTL=0 behavior
+     */
+    lock?(): Promise<void>;
+    /**
+     * Get EOA address
+     * @returns Ethereum address (checksummed)
+     */
+    getAddress(): Promise<`0x${string}`>;
+    /**
+     * Sign message hash with secp256k1
+     * @param hash32 - 32-byte message hash
+     * @returns Signature components
+     */
+    signMessage(hash32: Uint8Array): Promise<{
+        r: Uint8Array;
+        s: Uint8Array;
+        yParity: 0 | 1;
+    }>;
+    /**
+     * Sign EIP-712 typed data
+     * @param input - Typed data structure
+     * @returns Signature hex string
+     */
+    signTypedData(input: TypedDataInput): Promise<`0x${string}`>;
+    /**
+     * Get public key (optional, for signer creation)
+     * @returns 65-byte uncompressed public key (0x04 prefix)
+     */
+    getPublicKey?(): Promise<Uint8Array>;
+    /**
+     * Optional capability hints
+     * - p256: Whether P-256 signing is supported
+     * - secp256k1: Whether secp256k1 signing is supported (default: true)
+     */
+    capabilities?: {
+        p256?: boolean;
+        secp256k1?: boolean;
+    };
+}
+/**
+ * MPC transport interface for backend proxy communication
+ * Vendor-agnostic: no vendor names in interface
+ */
+interface MpcTransport {
+    /**
+     * Ensure session is established with backend
+     */
+    ensureSession(): Promise<void>;
+    /**
+     * Get EOA address from backend
+     * @returns Ethereum address
+     */
+    getAddress(): Promise<`0x${string}`>;
+    /**
+     * Sign message hash via backend proxy
+     * @param hash32 - 32-byte message hash
+     * @returns Signature components
+     */
+    signMessage(hash32: Uint8Array): Promise<{
+        r: Uint8Array;
+        s: Uint8Array;
+        yParity: 0 | 1;
+    }>;
+    /**
+     * Sign EIP-712 typed data via backend proxy
+     * @param input - Typed data structure
+     * @returns Signature hex string
+     */
+    signTypedData(input: TypedDataInput): Promise<`0x${string}`>;
+    /**
+     * Get public key from backend (optional, for signer creation)
+     * @returns 65-byte uncompressed public key (0x04 prefix)
+     */
+    getPublicKey?(): Promise<Uint8Array>;
+}
+
+/**
+ * Signer port interface for abstracting signing operations
+ * Supports both P-256 (TEE/passkey) and secp256k1 (software) signing
+ */
+interface SignerPort {
+    /**
+     * Get public key in uncompressed format
+     * - secp256k1: 65 bytes (0x04 || x || y)
+     * - P-256: 65 bytes (0x04 || x || y)
+     *
+     * @returns Uncompressed public key
+     */
+    getPublicKey(): Promise<Uint8Array>;
+    /**
+     * Sign a message hash
+     *
+     * @param msgHash32 - 32-byte message hash (already hashed)
+     * @returns Signature with r, s, and yParity
+     */
+    signMessage(msgHash32: Uint8Array): Promise<{
+        r: Uint8Array;
+        s: Uint8Array;
+        yParity: 0 | 1;
+    }>;
+    /**
+     * Sign raw hash without EIP-191 prefix (for EIP-7702)
+     *
+     * @param digest - 32-byte digest to sign (raw, no prefix)
+     * @returns Signature with r, s, and yParity
+     */
+    signRawHash(digest: Uint8Array): Promise<{
+        r: Uint8Array;
+        s: Uint8Array;
+        yParity: 0 | 1;
+    }>;
+    /**
+     * Sign typed data (optional, for future EIP-712 support)
+     *
+     * @param typed - Typed data structure
+     * @returns Signature hex string
+     */
+    signTyped?(typed: unknown): Promise<`0x${string}`>;
+}
+/**
+ * Passkey provider port interface
+ * Abstracts WebAuthn passkey operations (to be implemented in react package)
+ */
+interface PasskeyProviderPort {
+    /**
+     * Get P-256 public key from passkey
+     *
+     * @returns Public key coordinates (x, y)
+     */
+    getPublicKey(): Promise<{
+        x: Uint8Array;
+        y: Uint8Array;
+    }>;
+    /**
+     * Sign message hash using P-256 passkey
+     *
+     * @param msgHash32 - 32-byte message hash
+     * @returns Signature components (r, s)
+     */
+    signP256(msgHash32: Uint8Array): Promise<{
+        r: Uint8Array;
+        s: Uint8Array;
+    }>;
+    /**
+     * Authenticate with WebAuthn and get PRF output
+     * This triggers a user gesture (biometric/PIN prompt)
+     *
+     * @param prfInput - PRF evaluation input (salt)
+     * @param credentialId - Optional credential ID to use
+     * @returns PRF output (32 bytes)
+     */
+    authenticate(prfInput: {
+        salt: Uint8Array;
+        credentialId?: string;
+    }): Promise<{
+        prfOutput: Uint8Array;
+        credentialId: string;
+    }>;
+}
+/**
+ * Key storage type identifier
+ * Represents the method used to store cryptographic keys: Passkey (hardware-based) or MPC (Multi-Party Computation)
+ */
+type KeyStorageType = 'passkey' | 'mpc';
+/**
+ * Signer kind identifier
+ */
+type SignerKind = 'secp256k1' | 'passkey-p256';
+/**
+ * Signer context for routing
+ */
+type SignerContext = {
+    /** RPC client for capability detection */
+    client: any;
+    /** Chain ID */
+    chainId: number;
+    /** Optional wallet provider (for provider-based routing) */
+    provider?: WalletProviderPort;
+    /** Optional passkey provider (for P-256 path) */
+    passkey?: PasskeyProviderPort;
+    /** Optional secp256k1 private key (for fallback path) */
+    secpKey?: Uint8Array;
+};
+
+/**
+ * Select appropriate signer based on chain capabilities and available inputs
+ *
+ * Routing logic:
+ * 1. If provider provided → ProviderBackedSigner (delegates to provider)
+ * 2. Else if secpKey provided → Secp256k1SoftwareSigner
+ * 3. Else → throw error
+ *
+ * @param ctx - Signer context
+ * @returns Selected signer with kind identifier
+ * @throws VolrError if no signer input is available
+ *
+ * @example
+ * ```ts
+ * const ctx = {
+ *   client: rpcClient,
+ *   chainId: 10,
+ *   provider: walletProvider,
+ * };
+ * const { kind, signer } = await selectSigner(ctx);
+ * const sig = await signer.signMessage(msgHash);
+ * ```
+ */
+declare function selectSigner$1(ctx: SignerContext): Promise<{
+    kind: SignerKind;
+    signer: SignerPort;
+}>;
+
+/**
+ * EVM signature structure
+ */
+type Sig = {
+    /** 32-byte r value */
+    r: Uint8Array;
+    /** 32-byte s value (low-S canonicalized) */
+    s: Uint8Array;
+    /** y-parity (0 or 1) */
+    yParity: 0 | 1;
+};
+/**
+ * Secp256k1 software signer implementation
+ * Uses existing master-key → BIP-32 → secp256k1 derivation path
+ *
+ * @example
+ * ```ts
+ * const privateKey = getRandomBytes(32);
+ * const signer = new Secp256k1SoftwareSigner(privateKey);
+ * const sig = await signer.signMessage(msgHash);
+ * ```
+ */
+declare class Secp256k1SoftwareSigner implements SignerPort {
+    private privateKey;
+    constructor(privateKey: Uint8Array);
+    /**
+     * Get uncompressed public key (65 bytes)
+     *
+     * @returns Uncompressed public key with 0x04 prefix
+     */
+    getPublicKey(): Promise<Uint8Array>;
+    /**
+     * Sign message hash with deterministic, low-S canonicalization
+     *
+     * @param msgHash32 - 32-byte message hash
+     * @returns Signature with r, s, and yParity
+     * @throws Error if message hash is invalid
+     */
+    signMessage(msgHash32: Uint8Array): Promise<{
+        r: Uint8Array;
+        s: Uint8Array;
+        yParity: 0 | 1;
+    }>;
+    /**
+     * Sign raw hash without EIP-191 prefix (for EIP-7702)
+     *
+     * @param digest - 32-byte digest to sign
+     * @returns Signature with r, s, and yParity
+     * @throws Error if digest is invalid
+     */
+    signRawHash(digest: Uint8Array): Promise<{
+        r: Uint8Array;
+        s: Uint8Array;
+        yParity: 0 | 1;
+    }>;
+    /**
+     * Sign EIP-712 typed data
+     */
+    signTyped(data: {
+        domain: any;
+        types: any;
+        primaryType: string;
+        message: any;
+    }): Promise<`0x${string}`>;
+}
+/**
+ * Verify a secp256k1 signature against a public key and message hash
+ *
+ * @param pubKeyUncompressed - 65-byte uncompressed public key (0x04 prefix)
+ * @param msgHash32 - 32-byte message hash
+ * @param sig - Signature to verify
+ * @returns true if signature is valid, false otherwise
+ * @throws Error if public key or message hash is invalid
+ *
+ * @example
+ * ```ts
+ * const isValid = evmVerify(publicKey, msgHash, sig);
+ * if (isValid) {
+ *   console.log('Signature is valid');
+ * }
+ * ```
+ */
+declare function evmVerify(pubKeyUncompressed: Uint8Array, msgHash32: Uint8Array, sig: Sig): boolean;
+
+/**
+ * Passkey P-256 signer implementation
+ * Uses device TEE/passkey for signing (P-256 curve)
+ *
+ * @example
+ * ```ts
+ * const passkeyProvider = createPasskeyProvider();
+ * const signer = new PasskeyP256Signer(passkeyProvider);
+ * const sig = await signer.signMessage(msgHash);
+ * ```
+ */
+declare class PasskeyP256Signer implements SignerPort {
+    private provider;
+    constructor(provider: PasskeyProviderPort);
+    /**
+     * Get uncompressed P-256 public key (65 bytes)
+     *
+     * @returns Uncompressed public key with 0x04 prefix
+     */
+    getPublicKey(): Promise<Uint8Array>;
+    /**
+     * Sign message hash using P-256 passkey
+     *
+     * @param msgHash32 - 32-byte message hash
+     * @returns Signature with r, s, and yParity
+     * @throws Error if message hash is invalid
+     */
+    signMessage(msgHash32: Uint8Array): Promise<{
+        r: Uint8Array;
+        s: Uint8Array;
+        yParity: 0 | 1;
+    }>;
+    /**
+     * Sign raw hash without EIP-191 prefix (for EIP-7702)
+     *
+     * @param _digest - 32-byte digest to sign
+     * @returns Signature with r, s, and yParity
+     * @throws Error - P-256 cannot be used for EIP-7702
+     */
+    signRawHash(_digest: Uint8Array): Promise<{
+        r: Uint8Array;
+        s: Uint8Array;
+        yParity: 0 | 1;
+    }>;
+    /**
+     * Sign EIP-712 typed data
+     */
+    signTyped(data: {
+        domain: any;
+        types: any;
+        primaryType: string;
+        message: any;
+    }): Promise<`0x${string}`>;
+}
+
+/**
+ * EIP-1193 Provider interface
+ * https://eips.ethereum.org/EIPS/eip-1193
+ */
+interface EIP1193Provider {
+    request(args: {
+        method: string;
+        params?: unknown[] | object;
+    }): Promise<unknown>;
+    on?(event: string, listener: (...args: any[]) => void): void;
+    removeListener?(event: string, listener: (...args: any[]) => void): void;
+}
+/**
+ * External Wallet Signer
+ *
+ * Uses an external wallet (MetaMask, WalletConnect, etc.) via EIP-1193 provider
+ * for signing operations. This signer performs network validation before each
+ * signing operation to prevent cross-chain replay attacks.
+ *
+ * Security features:
+ * - Network validation before signing
+ * - Error normalization for consistent error handling
+ * - Support for EIP-712 typed data signing
+ *
+ * @example
+ * ```ts
+ * const provider = window.ethereum;
+ * const signer = new ExternalWalletSigner(provider, 1, '0xAbC...');
+ * const sig = await signer.signMessage(msgHash);
+ * ```
+ */
+declare class ExternalWalletSigner implements SignerPort {
+    private readonly provider;
+    private readonly expectedChainId;
+    private readonly address;
+    constructor(provider: EIP1193Provider, expectedChainId: number, address: string);
+    /**
+     * Verify that the wallet is on the correct network
+     * @throws WrongNetworkError if network mismatch
+     */
+    private verifyNetwork;
+    /**
+     * Get the wallet address
+     */
+    getAddress(): Promise<`0x${string}`>;
+    /**
+     * Get public key - not directly supported by EIP-1193
+     * Returns a placeholder as external wallets don't expose raw public keys
+     *
+     * For external wallets, we rely on address-based verification instead
+     */
+    getPublicKey(): Promise<Uint8Array>;
+    /**
+     * Sign a message hash using personal_sign
+     *
+     * Note: personal_sign automatically adds EIP-191 prefix
+     *
+     * @param msgHash32 - 32-byte message hash
+     * @returns Signature components (r, s, yParity)
+     */
+    signMessage(msgHash32: Uint8Array): Promise<{
+        r: Uint8Array;
+        s: Uint8Array;
+        yParity: 0 | 1;
+    }>;
+    /**
+     * Sign raw hash for EIP-7702 authorization
+     *
+     * External wallets don't support raw hash signing directly (eth_sign is deprecated/disabled).
+     * Instead, we use personal_sign which adds EIP-191 prefix, then we need to account for this
+     * when verifying the signature on-chain.
+     *
+     * ⚠️ IMPORTANT: This creates a signature over the EIP-191 prefixed message, NOT the raw digest.
+     * The backend/contract must verify accordingly.
+     *
+     * Alternative approach: Use EIP-712 typed data for authorization (more wallet-friendly)
+     *
+     * @param digest - 32-byte digest to sign
+     * @returns Signature components (r, s, yParity)
+     * @throws WalletError if signing fails
+     */
+    signRawHash(digest: Uint8Array): Promise<{
+        r: Uint8Array;
+        s: Uint8Array;
+        yParity: 0 | 1;
+    }>;
+    /**
+     * Sign typed data (EIP-712)
+     *
+     * @param typed - Typed data structure with domain, types, and message
+     * @returns Signature hex string
+     */
+    signTyped(typed: unknown): Promise<`0x${string}`>;
+    /**
+     * Switch to the expected network
+     *
+     * @returns true if switch successful, false if user rejected
+     * @throws Error if switch fails for other reasons
+     */
+    switchNetwork(): Promise<boolean>;
+    /**
+     * Add a new network to the wallet
+     *
+     * @param chainConfig - Network configuration
+     * @returns true if add successful, false if user rejected
+     */
+    addNetwork(chainConfig: {
+        chainId: string;
+        chainName: string;
+        nativeCurrency: {
+            name: string;
+            symbol: string;
+            decimals: number;
+        };
+        rpcUrls: string[];
+        blockExplorerUrls?: string[];
+    }): Promise<boolean>;
+}
+
+/**
+ * EIP-1193 Provider Error Codes
+ * https://eips.ethereum.org/EIPS/eip-1193#provider-errors
+ */
+declare enum EIP1193ErrorCode {
+    USER_REJECTED = 4001,
+    UNAUTHORIZED = 4100,
+    UNSUPPORTED_METHOD = 4200,
+    DISCONNECTED = 4900,
+    CHAIN_DISCONNECTED = 4901,
+    UNRECOGNIZED_CHAIN = 4902,
+    RESOURCE_UNAVAILABLE = -32002,
+    RESOURCE_NOT_FOUND = -32001,
+    INVALID_INPUT = -32000,
+    INTERNAL_ERROR = -32603,
+    INVALID_REQUEST = -32600,
+    METHOD_NOT_FOUND = -32601,
+    INVALID_PARAMS = -32602,
+    PARSE_ERROR = -32700
+}
+/**
+ * Normalized wallet error types
+ */
+declare class WalletError extends Error {
+    readonly code: EIP1193ErrorCode | number;
+    readonly originalError?: unknown | undefined;
+    constructor(message: string, code: EIP1193ErrorCode | number, originalError?: unknown | undefined);
+}
+declare class UserRejectedError extends WalletError {
+    constructor(message?: string, originalError?: unknown);
+}
+declare class UnauthorizedError extends WalletError {
+    constructor(message?: string, originalError?: unknown);
+}
+declare class UnsupportedMethodError extends WalletError {
+    constructor(message?: string, originalError?: unknown);
+}
+declare class WrongNetworkError extends WalletError {
+    readonly expectedChainId?: number | undefined;
+    readonly actualChainId?: number | undefined;
+    constructor(message?: string, expectedChainId?: number | undefined, actualChainId?: number | undefined, originalError?: unknown);
+}
+declare class ChainNotAddedError extends WalletError {
+    constructor(message?: string, originalError?: unknown);
+}
+declare class RequestPendingError extends WalletError {
+    constructor(message?: string, originalError?: unknown);
+}
+/**
+ * Normalize EIP-1193 provider errors to typed error classes
+ */
+declare function normalizeWalletError(error: unknown): WalletError;
+
+/**
+ * Cross‑platform helper to upload an encrypted blob via backend (backend handles S3 upload).
+ * Uses axios for consistent error handling and request/response interceptors.
+ */
+
+interface UploadBlobOptions {
+    /** Backend base URL, e.g. https://api.example.com */
+    baseUrl: string;
+    /** Project API key to send as X-API-Key header */
+    apiKey: string;
+    /** Bearer token for Authorization header */
+    accessToken: string;
+    /** Blob or binary content to upload */
+    blob: Blob | ArrayBuffer | Uint8Array;
+    /** Optional axios instance (if you want to reuse an existing instance with interceptors) */
+    axiosInstance?: AxiosInstance;
+}
+/**
+ * Uploads blob to backend, which handles S3 upload directly.
+ * Returns `{ key: string }` (S3 key) on success.
+ *
+ * This helper intentionally lives in @volr/sdk-core (not UI, not backend) so it can be reused
+ * by web, React Native, Node, etc. It uses axios for consistent error handling.
+ */
+declare function uploadBlob(options: UploadBlobOptions): Promise<{
+    key: string;
+}>;
+/**
+ * Cross‑platform helper to upload an encrypted blob via S3 presigned PUT.
+ * Runs in browsers (uses global fetch) and in Node 18+ (built‑in fetch).
+ */
+interface UploadViaPresignOptions {
+    /** Backend base URL, e.g. https://api.example.com */
+    baseUrl: string;
+    /** Project API key to send as X-API-Key header (optional if backend not requiring it) */
+    apiKey?: string | null;
+    /** Bearer token for Authorization header (optional if cookie-based auth is sufficient) */
+    accessToken?: string | null;
+    /** Blob or binary content to upload */
+    blob: Blob | ArrayBuffer | Uint8Array;
+    /** MIME type for the uploaded object; defaults to application/octet-stream */
+    contentType?: string;
+    /** Optional fetch implementation override (e.g. pass global fetch in RN) */
+    fetchFn?: typeof fetch;
+}
+/**
+ * Calls backend `/blob/presign` with `{ op:'put', contentType }`, then uploads `blob`
+ * to the returned S3 presigned URL. Returns `{ s3Key, url }` on success.
+ *
+ * This helper intentionally lives in @volr/sdk-core (not UI, not backend) so it can be reused
+ * by web, React Native, Node, etc. It uses fetch instead of axios to avoid extra deps.
+ */
+declare function uploadBlobViaPresign(options: UploadViaPresignOptions): Promise<{
+    s3Key: string;
+    url: string;
+}>;
+
+/**
+ * Base error class for Volr SDK
+ */
+declare class VolrError extends Error {
+    readonly code: string;
+    readonly cause?: Error | undefined;
+    constructor(code: string, message: string, cause?: Error | undefined);
+}
+/**
+ * Error codes
+ */
+declare const ERR_INVALID_PARAM = "ERR_INVALID_PARAM";
+declare const ERR_CRYPTO_FAIL = "ERR_CRYPTO_FAIL";
+declare const ERR_AAD_MISMATCH = "ERR_AAD_MISMATCH";
+declare const ERR_NONCE_SIZE = "ERR_NONCE_SIZE";
+declare const ERR_LOW_ENTROPY = "ERR_LOW_ENTROPY";
+declare const ERR_CHAIN_MISMATCH = "ERR_CHAIN_MISMATCH";
+
+/**
+ * EVM constants
+ */
+/**
+ * Zero hash (32 bytes of zeros)
+ * Equivalent to ethers.ZeroHash or keccak256("")
+ */
+declare const ZERO_HASH: `0x${string}`;
+/**
+ * Zero address (20 bytes of zeros)
+ */
+declare const ZERO_ADDRESS: `0x${string}`;
+
+/**
+ * Public types for EVM chain operations
+ * These types match backend DTOs 1:1 for consistency
+ */
+/**
+ * Session authorization data
+ */
+type SessionAuth = {
+    chainId: number;
+    sessionKey: `0x${string}`;
+    sessionId: bigint;
+    expiresAt: number;
+    nonce: bigint;
+    policyId: `0x${string}`;
+    policySnapshotHash: `0x${string}`;
+    gasLimitMax: bigint;
+    maxFeePerGas: bigint;
+    maxPriorityFeePerGas: bigint;
+    totalGasCap: bigint;
+};
+/**
+ * Call structure for batch execution
+ */
+type Call = {
+    target: `0x${string}`;
+    data: `0x${string}`;
+    value: bigint;
+    gasLimit: bigint;
+};
+/**
+ * Precheck input (matches PrecheckDto)
+ */
+type PrecheckInput = {
+    auth: SessionAuth;
+    calls: Call[];
+};
+/**
+ * Precheck quote response
+ */
+type PrecheckQuote = {
+    maxGas: bigint;
+    chainId: number;
+    currentOpNonce?: string;
+    gasCost?: bigint;
+    fee?: bigint;
+    policyId: `0x${string}`;
+    policySnapshotHash: `0x${string}`;
+};
+/**
+ * Authorization tuple for EIP-7702
+ */
+type AuthorizationTuple = {
+    chainId: number;
+    address: `0x${string}`;
+    nonce: bigint;
+    yParity: 0 | 1;
+    r: `0x${string}`;
+    s: `0x${string}`;
+};
+/**
+ * Relay input (matches RelayDto)
+ */
+type RelayInput = {
+    chainId: number;
+    from: `0x${string}`;
+    auth: SessionAuth;
+    calls: Call[];
+    sessionSig: `0x${string}`;
+    authorizationList: [AuthorizationTuple] | [];
+};
+/**
+ * Relay result
+ */
+type RelayResult = {
+    txId: string;
+    status: 'QUEUED' | 'PENDING';
+    txHash?: `0x${string}`;
+} | {
+    txId: string;
+    status: 'CONFIRMED';
+    txHash: `0x${string}`;
+} | {
+    txId: string;
+    status: 'FAILED';
+    txHash?: `0x${string}`;
+};
+
+declare function computeCallsHash(calls: Call[]): `0x${string}`;
+
+declare const DOMAIN: (chainId: number, verifyingContract: `0x${string}`) => {
+    name: string;
+    version: string;
+    chainId: number;
+    verifyingContract: `0x${string}`;
+};
+declare const EIP712_DOMAIN: (chainId: number, verifyingContract: `0x${string}`) => {
+    name: string;
+    version: string;
+    chainId: number;
+    verifyingContract: `0x${string}`;
+};
+declare const TYPES: {
+    readonly Call: readonly [{
+        readonly name: "target";
+        readonly type: "address";
+    }, {
+        readonly name: "data";
+        readonly type: "bytes";
+    }, {
+        readonly name: "value";
+        readonly type: "uint256";
+    }, {
+        readonly name: "gasLimit";
+        readonly type: "uint256";
+    }];
+    readonly SessionAuth: readonly [{
+        readonly name: "chainId";
+        readonly type: "uint256";
+    }, {
+        readonly name: "sessionKey";
+        readonly type: "address";
+    }, {
+        readonly name: "sessionId";
+        readonly type: "uint64";
+    }, {
+        readonly name: "nonce";
+        readonly type: "uint64";
+    }, {
+        readonly name: "expiresAt";
+        readonly type: "uint64";
+    }, {
+        readonly name: "policyId";
+        readonly type: "bytes32";
+    }, {
+        readonly name: "policySnapshotHash";
+        readonly type: "bytes32";
+    }, {
+        readonly name: "gasLimitMax";
+        readonly type: "uint256";
+    }, {
+        readonly name: "maxFeePerGas";
+        readonly type: "uint256";
+    }, {
+        readonly name: "maxPriorityFeePerGas";
+        readonly type: "uint256";
+    }, {
+        readonly name: "totalGasCap";
+        readonly type: "uint256";
+    }];
+    readonly SignedBatch: readonly [{
+        readonly name: "auth";
+        readonly type: "SessionAuth";
+    }, {
+        readonly name: "calls";
+        readonly type: "Call[]";
+    }, {
+        readonly name: "revertOnFail";
+        readonly type: "bool";
+    }, {
+        readonly name: "callsHash";
+        readonly type: "bytes32";
+    }];
+};
+type SessionAuthExtended = SessionAuth;
+/**
+ * Build EIP-712 signed batch message
+ */
+declare function buildSignedBatchMessage(input: {
+    auth: SessionAuthExtended;
+    calls: Call[];
+    revertOnFail?: boolean;
+    invokerAddress: `0x${string}`;
+}): {
+    domain: ReturnType<typeof DOMAIN>;
+    primaryType: "SignedBatch";
+    message: {
+        auth: any;
+        calls: Call[];
+        revertOnFail: boolean;
+        callsHash: `0x${string}`;
+    };
+    callsHash: `0x${string}`;
+};
+/**
+ * Sign EIP-712 session
+ */
+declare function signSession(input: {
+    signer: SignerPort;
+    from: `0x${string}`;
+    auth: SessionAuthExtended;
+    calls: Call[];
+    invokerAddress: `0x${string}`;
+}): Promise<{
+    sessionSig: `0x${string}`;
+    callsHash: `0x${string}`;
+}>;
+
+/**
+ * EIP-7702 authorization tuple signing
+ */
+
+/**
+ * Sign EIP-7702 authorization tuple
+ *
+ * Authorization tuple signs: chainId || address || nonce
+ * This is separate from session signature
+ *
+ * @param input - Signing parameters
+ * @returns Authorization tuple with signature
+ */
+declare function signAuthorization(input: {
+    signer: SignerPort;
+    chainId: number;
+    address: `0x${string}`;
+    nonce: bigint;
+}): Promise<AuthorizationTuple>;
+
+/**
+ * Authorization nonce utilities for EIP-7702
+ */
+/**
+ * Relay mode for nonce calculation
+ */
+type RelayMode = 'self' | 'sponsored';
+/**
+ * Get authorization nonce based on relay mode
+ *
+ * Rules (EIP-7702):
+ * - self: getTransactionCount(latest) + 1
+ * - sponsored: getTransactionCount(latest)
+ *
+ * Note: 'latest' is safer than 'pending' for sponsored mode to avoid race conditions.
+ * The nonce MUST exactly match the user EOA's current account nonce for Authorization validation.
+ *
+ * @param client - Extended RPC client with getTransactionCount method
+ * @param from - EOA address
+ * @param mode - Relay mode
+ * @returns Authorization nonce
+ */
+declare function getAuthNonce(client: ExtendedRPCClient, from: `0x${string}`, mode: RelayMode): Promise<bigint>;
+/**
+ * Extended RPC client interface with transaction count method
+ * This should be implemented by the actual RPC client in React SDK
+ */
+interface ExtendedRPCClient {
+    /**
+     * Low-level eth_call (optional, not required here)
+     */
+    call?: (args: {
+        to: `0x${string}`;
+        data: `0x${string}`;
+    }) => Promise<`0x${string}`>;
+    /**
+     * Get transaction count for an address
+     *
+     * @param address - Address to query
+     * @param blockTag - Block tag ('pending', 'latest', etc.)
+     * @returns Transaction count as bigint
+     */
+    getTransactionCount(address: `0x${string}`, blockTag?: 'pending' | 'latest'): Promise<bigint>;
+}
+
+/**
+ * Passkey provider implementation
+ * Uses PRF/HKDF to unwrap master seed and derive secp256k1 key
+ */
+
+/**
+ * Options for passkey provider
+ */
+type PasskeyProviderOptions = {
+    /** PRF input parameters */
+    prfInput: PrfInput;
+    /** Encrypted master seed blob */
+    encryptedBlob: {
+        cipher: Uint8Array;
+        nonce: Uint8Array;
+    };
+    /** Additional Authenticated Data for unwrapping */
+    aad?: Uint8Array;
+};
+/**
+ * Create passkey provider
+ *
+ * @param passkey - Passkey provider port (for WebAuthn PRF authentication)
+ * @param options - Provider options (PRF input, encrypted blob)
+ * @returns Wallet provider port
+ *
+ * @example
+ * ```ts
+ * const provider = createPasskeyProvider(passkeyAdapter, {
+ *   prfInput: { origin, projectId, credentialId },
+ *   encryptedBlob: { cipher, nonce }
+ * });
+ * await provider.ensureSession({ interactive: true, force: true });
+ * const address = await provider.getAddress();
+ * ```
+ */
+declare function createPasskeyProvider(passkey: PasskeyProviderPort, options: PasskeyProviderOptions): WalletProviderPort;
+
+/**
+ * MPC provider implementation
+ * Delegates to backend proxy via transport
+ */
+
+/**
+ * Create MPC provider
+ *
+ * @param transport - MPC transport interface (backend proxy)
+ * @returns Wallet provider port
+ *
+ * @example
+ * ```ts
+ * const transport = createMpcTransport({ backendUrl: '...' });
+ * const provider = createMpcProvider(transport);
+ * await provider.ensureSession();
+ * const address = await provider.getAddress();
+ * ```
+ */
+declare function createMpcProvider(transport: MpcTransport): WalletProviderPort;
+
+/**
+ * Provider-based signer selection (simplified, no 7212 probing)
+ * Always uses secp256k1 path today.
+ */
+
+/**
+ * Context for signer selection
+ */
+type SelectSignerContext = {
+    /** Wallet provider */
+    provider: WalletProviderPort;
+    /** Chain ID */
+    chainId: number;
+};
+/**
+ * Select appropriate signer based on provider
+ *
+ * Routing logic:
+ * 1. Provider-backed signer (delegates to provider, secp256k1)
+ *
+ * Note: 7702 authorization always uses secp256k1
+ *
+ * @param ctx - Selection context
+ * @returns Signer port
+ * @throws Error if provider cannot provide required signing capability
+ *
+ * @example
+ * ```ts
+ * const signer = await selectSigner({
+ *   provider: passkeyProvider,
+ *   chainId: 10,
+ *   client: rpcClient
+ * });
+ * const sig = await signer.signMessage(msgHash);
+ * ```
+ */
+declare function selectSigner(ctx: SelectSignerContext): Promise<SignerPort>;
+
+export { type AesGcmParams, type AuthorizationTuple, type Call, ChainNotAddedError, DEFAULT_EVM_PATH, DOMAIN, type DeriveArgs, EIP1193ErrorCode, type EIP1193Provider, EIP712_DOMAIN, ERR_AAD_MISMATCH, ERR_CHAIN_MISMATCH, ERR_CRYPTO_FAIL, ERR_INVALID_PARAM, ERR_LOW_ENTROPY, ERR_NONCE_SIZE, type EvmKeypair, type ExtendedRPCClient, ExternalWalletSigner, type KeyStorageType, type Sig$1 as LegacySig, type MasterKeyProvider, type MasterSeed, type MasterSeedHandle, type MpcTransport, PasskeyP256Signer, type PasskeyProviderOptions, type PasskeyProviderPort, type PrecheckInput, type PrecheckQuote, type PrfInput, type RelayInput, type RelayMode, type RelayResult, RequestPendingError, type RpcLike, Secp256k1SoftwareSigner, type SelectSignerContext, type SessionAuth, type Sig, type SignerContext, type SignerKind, type SignerPort, TYPES, type TypedDataInput, UnauthorizedError, UnsupportedMethodError, type UploadBlobOptions, type UploadViaPresignOptions, UserRejectedError, VolrError, WalletError, type WalletProviderPort, type WrapKey, WrongNetworkError, ZERO_ADDRESS, ZERO_HASH, aesGcmDecrypt, aesGcmEncrypt, buildSignedBatchMessage, computeCallsHash, createMasterKeyProvider, createMpcProvider, createPasskeyProvider, deriveEvmKey, deriveWrapKey, evmSign, evmVerify, getAuthNonce, getRandomBytes, hkdfSha256, normalizeWalletError, sealMasterSeed, selectSigner, selectSigner$1 as selectSignerLegacy, signAuthorization, signSession, toChecksumAddress, unsealMasterSeed, uploadBlob, uploadBlobViaPresign, zeroize };