SDK Reference

Complete TypeScript SDK reference for zkVault. Type-safe methods, comprehensive examples, and best practices.

VaultManager

Core vault operations: creation, management, content upload, and unlocking.

createVault(config: VaultConfig)

Creates a new vault with specified configuration.

Parameters:

interface VaultConfig {
  name: string;
  releaseType: 'SCHEDULED' | 'DEADMAN' | 'HYBRID';
  unlockTime?: number;           // Unix timestamp for SCHEDULED
  checkInPeriod?: number;        // Seconds for DEADMAN
  recipients: string[];          // Beneficiary addresses
  encrypted: boolean;
  metadata?: {
    description?: string;
    tags?: string[];
  };
}

Returns:

Promise<{
  id: string;
  owner: string;
  name: string;
  releaseType: string;
  createdAt: number;
  transactionHash: string;
}>

Example:

const vault = await sdk.vaultManager.createVault({
  name: "My Crypto Inheritance Vault",
  releaseType: "DEADMAN",
  checkInPeriod: 90 * 24 * 60 * 60, // 90 days
  recipients: [
    "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
    "0x1234567890abcdef1234567890abcdef12345678"
  ],
  encrypted: true,
  metadata: {
    description: "Emergency wallet recovery vault",
    tags: ["inheritance", "emergency"]
  }
});

console.log('Vault ID:', vault.id);
console.log('Transaction:', vault.transactionHash);

getVault(vaultId: string)

Retrieves complete vault details by ID.

Returns:

Promise<{
  id: string;
  owner: string;
  name: string;
  releaseType: string;
  unlockTime?: number;
  checkInPeriod?: number;
  lastCheckIn?: number;
  recipients: string[];
  beneficiaries: Array<{ address: string; share: number }>;
  status: 'ACTIVE' | 'TRIGGERED' | 'RELEASED';
  contentCID?: string;
  createdAt: number;
  updatedAt: number;
}>

Example:

const vault = await sdk.vaultManager.getVault(vaultId);

console.log('Status:', vault.status);
console.log('Last Check-in:', new Date(vault.lastCheckIn * 1000));
console.log('Beneficiaries:', vault.beneficiaries);

uploadContent(vaultId: string, content: VaultContent)

Upload encrypted content to vault (seed phrases, private keys, documents).

Parameters:

interface VaultContent {
  data: string | Uint8Array;       // Content to encrypt and store
  encrypted: boolean;              // Whether to encrypt with Lit Protocol
  storageLocation: 'arweave' | 'ipfs' | 'ceramic';
  contentType: string;             // MIME type (text/plain, application/json, etc.)
  metadata?: Record<string, any>;
}

Example:

// Upload seed phrase
const seedPhrase = "word1 word2 word3 ... word24";
const cid = await sdk.vaultManager.uploadContent(vaultId, {
  data: seedPhrase,
  encrypted: true,
  storageLocation: 'arweave',
  contentType: 'text/plain',
  metadata: {
    walletType: 'BIP39',
    createdAt: Date.now()
  }
});

console.log('Content CID:', cid);

// Upload JSON configuration
const config = { keys: [...], addresses: [...] };
const jsonCid = await sdk.vaultManager.uploadContent(vaultId, {
  data: JSON.stringify(config),
  encrypted: true,
  storageLocation: 'arweave',
  contentType: 'application/json'
});

unlockVault(vaultId: string)

Decrypt and retrieve vault content (beneficiaries only after trigger).

Returns:

Promise<{
  data: string | Uint8Array;
  contentType: string;
  metadata?: Record<string, any>;
  unlockedAt: number;
}>

Example:

try {
  const content = await sdk.vaultManager.unlockVault(vaultId);

  if (content.contentType === 'text/plain') {
    console.log('Decrypted seed phrase:', content.data);
  } else if (content.contentType === 'application/json') {
    const config = JSON.parse(content.data as string);
    console.log('Wallet configuration:', config);
  }

  console.log('Unlocked at:', new Date(content.unlockedAt));
} catch (error) {
  console.error('Unlock failed:', error.message);
  // Common errors: "Vault not triggered", "Not authorized", "Content not found"
}

getVaultsByOwner(address: string, options?: QueryOptions)

List all vaults owned by an address with pagination.

Example:

const vaults = await sdk.vaultManager.getVaultsByOwner(
  "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
  {
    page: 1,
    limit: 20,
    status: 'ACTIVE'
  }
);

console.log('Total vaults:', vaults.total);
console.log('Active vaults:', vaults.items);

TimeManager

Time-lock configurations: scheduled release, deadman switch, and hybrid modes.

configureScheduledRelease(vaultId: string, unlockTime: number)

Set specific unlock date/time for vault release.

Example:

// Release on January 1, 2030
const releaseDate = new Date('2030-01-01T00:00:00Z');
const unlockTime = Math.floor(releaseDate.getTime() / 1000);

await sdk.timeManager.configureScheduledRelease(vaultId, unlockTime);

console.log('Vault will unlock on:', releaseDate.toISOString());

configureDeadmanSwitch(vaultId: string, checkInPeriod: number, gracePeriod: number)

Configure inactivity-based trigger with grace period.

Example:

await sdk.timeManager.configureDeadmanSwitch(
  vaultId,
  90 * 24 * 60 * 60,  // Check-in period: 90 days
  7 * 24 * 60 * 60    // Grace period: 7 days
);

// Vault triggers if no check-in for 90 days
// Beneficiaries have 7-day grace period to cancel if false alarm

checkIn(vaultId: string)

Reset deadman switch timer to prevent vault trigger.

Example:

await sdk.timeManager.checkIn(vaultId);

const vault = await sdk.vaultManager.getVault(vaultId);
console.log('Next check-in due:', new Date(
  (vault.lastCheckIn + vault.checkInPeriod) * 1000
));

// Automate check-ins
setInterval(async () => {
  await sdk.timeManager.checkIn(vaultId);
  console.log('Automatic check-in completed');
}, 30 * 24 * 60 * 60 * 1000); // Every 30 days

getTimeUntilUnlock(vaultId: string)

Calculate remaining time until vault unlock.

Example:

const secondsRemaining = await sdk.timeManager.getTimeUntilUnlock(vaultId);

const days = Math.floor(secondsRemaining / (24 * 60 * 60));
const hours = Math.floor((secondsRemaining % (24 * 60 * 60)) / 3600);

console.log(`Time until unlock: ${days} days, ${hours} hours`);

AttestationClient

Decentralized attestation network for vault state verification and proof generation.

submitAttestation(vaultId: string, proof: AttestationProof)

Submit cryptographic proof for vault state attestation.

Parameters:

interface AttestationProof {
  vaultState: {
    id: string;
    owner: string;
    status: string;
    lastCheckIn: number;
  };
  timestamp: number;
  signature: string;          // Agent's signature
  agentAddress: string;
  metadata?: Record<string, any>;
}

Example:

const vault = await sdk.vaultManager.getVault(vaultId);

const proof: AttestationProof = {
  vaultState: {
    id: vault.id,
    owner: vault.owner,
    status: vault.status,
    lastCheckIn: vault.lastCheckIn
  },
  timestamp: Date.now(),
  signature: await signer.signMessage(/* ... */),
  agentAddress: await signer.getAddress()
};

const attestation = await sdk.attestationClient.submitAttestation(
  vaultId,
  proof
);

console.log('Attestation ID:', attestation.id);

verifyAttestation(attestationId: string)

Verify attestation signature and proof validity.

Example:

const isValid = await sdk.attestationClient.verifyAttestation(attestationId);

if (isValid) {
  console.log('Attestation verified successfully');
} else {
  console.error('Invalid attestation - possible tampering detected');
}

getAttestationStatus(vaultId: string)

Get consensus status from attestation network.

Example:

const status = await sdk.attestationClient.getAttestationStatus(vaultId);

console.log('Total attestations:', status.totalAttestations);
console.log('Verified attestations:', status.verifiedCount);
console.log('Consensus reached:', status.consensusReached);
console.log('Confidence score:', status.confidenceScore);

if (status.consensusReached && status.confidenceScore > 0.9) {
  console.log('High confidence - vault state verified');
}

CrossChainClient

Multi-chain vault management using LayerZero for cross-chain messaging.

deployVaultCrossChain(config: VaultConfig, targetChains: number[])

Deploy vault across multiple blockchain networks simultaneously.

Example:

// Deploy to opBNB, Ethereum, and Polygon
const result = await sdk.crossChainClient.deployVaultCrossChain(
  {
    name: "Multi-Chain Inheritance Vault",
    releaseType: "DEADMAN",
    checkInPeriod: 90 * 24 * 60 * 60,
    recipients: ["0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb"],
    encrypted: true
  },
  [204, 101, 137] // opBNB, Ethereum, Polygon chain IDs
);

console.log('Primary vault ID:', result.primaryVaultId);
console.log('Cross-chain vaults:', result.crossChainVaults);

// Monitor deployment status
result.crossChainVaults.forEach(vault => {
  console.log(`Chain ${vault.chainId}: ${vault.status}`);
});

syncVaultState(vaultId: string, targetChainId: number)

Synchronize vault state changes across chains.

Example:

// Sync check-in from opBNB to Ethereum
await sdk.crossChainClient.syncVaultState(
  vaultId,
  101 // Ethereum chain ID
);

console.log('Vault state synced to Ethereum');

// Verify sync
const ethereumVault = await sdk.vaultManager.getVault(
  vaultId,
  { chainId: 101 }
);
console.log('Ethereum last check-in:', ethereumVault.lastCheckIn);

Type Definitions

Core Types

// Release Types
type ReleaseType = 'SCHEDULED' | 'DEADMAN' | 'HYBRID';

// Vault Status
type VaultStatus = 'ACTIVE' | 'TRIGGERED' | 'RELEASED';

// Storage Locations
type StorageLocation = 'arweave' | 'ipfs' | 'ceramic';

// Vault Configuration
interface VaultConfig {
  name: string;
  releaseType: ReleaseType;
  unlockTime?: number;
  checkInPeriod?: number;
  recipients: string[];
  encrypted: boolean;
  metadata?: Record<string, any>;
}

// Vault Content
interface VaultContent {
  data: string | Uint8Array;
  encrypted: boolean;
  storageLocation: StorageLocation;
  contentType: string;
  metadata?: Record<string, any>;
}

// Attestation Proof
interface AttestationProof {
  vaultState: {
    id: string;
    owner: string;
    status: string;
    lastCheckIn: number;
  };
  timestamp: number;
  signature: string;
  agentAddress: string;
  metadata?: Record<string, any>;
}

// Attestation Status
interface AttestationStatus {
  vaultId: string;
  totalAttestations: number;
  verifiedCount: number;
  consensusReached: boolean;
  confidenceScore: number;
  lastUpdated: number;
}

// Query Options
interface QueryOptions {
  page?: number;
  limit?: number;
  status?: VaultStatus;
  sortBy?: string;
  sortOrder?: 'asc' | 'desc';
}

Error Handling

Common Error Codes

VaultNotFound

Vault ID does not exist or was deleted

Unauthorized

Caller is not vault owner or authorized beneficiary

VaultNotTriggered

Attempted to unlock vault before trigger conditions met

ContentNotFound

Vault has no uploaded content

DecryptionFailed

Failed to decrypt vault content with Lit Protocol

Error Handling Pattern

try {
  const vault = await sdk.vaultManager.createVault(config);
  console.log('Vault created:', vault.id);
} catch (error) {
  if (error.code === 'InsufficientBalance') {
    console.error('Not enough balance for transaction');
  } else if (error.code === 'InvalidConfig') {
    console.error('Invalid vault configuration:', error.details);
  } else {
    console.error('Unexpected error:', error.message);
  }

  // Log for debugging
  console.error('Full error:', error);
}

Next Steps

Smart Contracts →

Solidity interfaces, deployment addresses, and gas optimization

Integration Guides →

Step-by-step tutorials for common use cases

API Reference →

REST and GraphQL endpoint documentation