@volr/sdk-core

Core cryptography, wallet providers, and EVM utilities for Volr SDK.

Installation

npm install @volr/sdk-core
# or
yarn add @volr/sdk-core

Features

• EVM Cryptography: secp256k1 and P-256 (WebAuthn) signing
• Passkey Providers: WebAuthn-based wallet providers
• Master Key Encryption: AES-256-GCM encryption with HKDF key derivation
• EIP-7702 Support: Authorization tuple signing
• Session Keys: EIP-712 session authentication
• Type-Safe: Full TypeScript support with strict types

Core Concepts

Wallet Providers

Wallet providers implement the WalletProviderPort interface for signing transactions:

import { createPasskeyProvider } from '@volr/sdk-core';

// Create a passkey-based provider
const provider = createPasskeyProvider(adapter, {
  prfInput: { projectId, credentialId },
  encryptedBlob: { cipher, nonce },
  aad: new TextEncoder().encode('volr/master-seed/v1|userId|passkey|v1'),
});

// Get EVM address
const address = await provider.getAddress();

// Sign message
const signature = await provider.signMessage(messageHash);

Signers

Signers are lightweight interfaces for signing operations:

import { createSecp256k1Signer } from '@volr/sdk-core';

// Create signer from private key
const signer = createSecp256k1Signer(privateKeyBytes);

// Sign message
const signature = await signer.signMessage(messageHash);

// Get address
const address = await signer.getAddress();

EIP-7702 Authorization

Sign authorization tuples for EIP-7702 transactions:

import { signAuthorization } from '@volr/sdk-core';

const authTuple = await signAuthorization({
  signer,
  chainId: 8453,
  address: invokerAddress,
  nonce: 0n,
});

Session Signing (EIP-712)

Sign session authentication for sponsored transactions:

import { signSession } from '@volr/sdk-core';

const { sessionSig } = await signSession({
  signer,
  from: userAddress,
  auth: {
    chainId: 8453,
    sessionKey: userAddress,
    expiresAt: Math.floor(Date.now() / 1000) + 900,
    nonce: 0n,
    policyId: '0x' + '0'.repeat(64),
  },
  calls: [{ target, data, value, gasLimit }],
  invokerAddress,
});

Master Key Encryption

Encrypt and decrypt master seeds with AES-256-GCM:

import { encryptMasterSeed, decryptMasterSeed } from '@volr/sdk-core';

// Encrypt
const { cipher, nonce } = await encryptMasterSeed({
  masterSeed: new Uint8Array(32),
  wrapKey: new Uint8Array(32),
  aad: new TextEncoder().encode('context'),
});

// Decrypt
const masterSeed = await decryptMasterSeed({
  cipher,
  nonce,
  wrapKey,
  aad,
});

Key Derivation (HKDF)

Derive keys using HMAC-based Key Derivation Function:

import { hkdf } from '@volr/sdk-core';

const derivedKey = await hkdf({
  ikm: inputKeyMaterial,
  salt: new Uint8Array(32),
  info: new TextEncoder().encode('context'),
  length: 32,
});

API Reference

Types

// Wallet provider interface
interface WalletProviderPort {
  getAddress(): Promise<`0x${string}`>;
  signMessage(messageHash: Uint8Array): Promise<Uint8Array>;
  lock?(): Promise<void>;
  ensureSession?(opts?: { interactive?: boolean; force?: boolean }): Promise<void>;
}

// Signer interface
interface SignerPort {
  getAddress(): Promise<`0x${string}`>;
  signMessage(messageHash: Uint8Array): Promise<Uint8Array>;
}

// EIP-7702 authorization tuple
interface AuthorizationTuple {
  chainId: bigint;
  address: `0x${string}`;
  nonce: bigint;
  v: bigint;
  r: `0x${string}`;
  s: `0x${string}`;
}

// Session authentication
interface SessionAuth {
  chainId: number;
  sessionKey: `0x${string}`;
  expiresAt: number;
  nonce: bigint;
  policyId: `0x${string}`;
}

// Call structure
interface Call {
  target: `0x${string}`;
  data: `0x${string}`;
  value: bigint;
  gasLimit: bigint;
}

Cryptography

• encryptMasterSeed(): Encrypt master seed with AES-256-GCM
• decryptMasterSeed(): Decrypt master seed
• hkdf(): HMAC-based key derivation
• zeroize(): Securely zero out sensitive data

Signers

• createSecp256k1Signer(): Create secp256k1 signer
• createPasskeyP256Signer(): Create P-256 passkey signer
• createExternalWalletSigner(): Create external wallet signer (MetaMask, etc.)

Providers

• createPasskeyProvider(): Create passkey-based wallet provider
• createMpcProvider(): Create MPC-based wallet provider

EVM Utilities

• signAuthorization(): Sign EIP-7702 authorization tuple
• signSession(): Sign EIP-712 session authentication
• getAuthNonce(): Get authorization nonce from RPC

Security

Key Management

• Master seeds are encrypted with AES-256-GCM
• Wrap keys are derived from passkey PRF
• Private keys are zeroized after use
• No keys are stored in plain text

Session Security

• Sessions expire after configurable TTL (default: 15 minutes)
• Each transaction requires fresh signature
• Policy constraints enforced on-chain
• Nonce prevents replay attacks

Testing

# Run tests
yarn test

# Run tests with coverage
yarn test:coverage

License

MIT