Smart Contracts

Production-ready Solidity smart contracts for zkVault. Audited, gas-optimized, and deployed across 8+ blockchain networks.

VaultManager.sol

Core vault management contract handling creation, ownership, beneficiaries, and asset release.

Key Functions

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;

interface IVaultManager {
    // Vault creation
    function createVault(
        string memory name,
        ReleaseType releaseType,
        address[] memory recipients,
        bool encrypted
    ) external returns (uint256 vaultId);

    // Vault queries
    function getVault(uint256 vaultId)
        external view returns (Vault memory);

    function getVaultsByOwner(address owner)
        external view returns (uint256[] memory);

    // Beneficiary management
    function updateBeneficiaries(
        uint256 vaultId,
        address[] memory beneficiaries,
        uint256[] memory shares
    ) external;

    // Content management
    function setContentCID(uint256 vaultId, string memory cid) external;
    function getContentCID(uint256 vaultId)
        external view returns (string memory);

    // Release mechanism
    function releaseVault(uint256 vaultId) external;
    function isUnlocked(uint256 vaultId) external view returns (bool);

    // Events
    event VaultCreated(
        uint256 indexed vaultId,
        address indexed owner,
        ReleaseType releaseType
    );
    event VaultReleased(uint256 indexed vaultId, uint256 timestamp);
    event BeneficiariesUpdated(uint256 indexed vaultId);
    event ContentUpdated(uint256 indexed vaultId, string cid);
}

// Data structures
struct Vault {
    uint256 id;
    address owner;
    string name;
    ReleaseType releaseType;
    uint256 unlockTime;
    uint256 checkInPeriod;
    uint256 lastCheckIn;
    address[] recipients;
    Beneficiary[] beneficiaries;
    VaultStatus status;
    string contentCID;
    uint256 createdAt;
    uint256 updatedAt;
}

struct Beneficiary {
    address addr;
    uint256 share; // Basis points (10000 = 100%)
}

enum ReleaseType { SCHEDULED, DEADMAN, HYBRID }
enum VaultStatus { ACTIVE, TRIGGERED, RELEASED }

Contract Integration

import { ethers } from 'ethers';
import VaultManagerABI from './abis/VaultManager.json';

// Connect to contract
const vaultManager = new ethers.Contract(
  '0x...', // VaultManager address
  VaultManagerABI,
  signer
);

// Create vault
const tx = await vaultManager.createVault(
  "My Inheritance Vault",
  0, // ReleaseType.SCHEDULED
  ["0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb"],
  true // encrypted
);

const receipt = await tx.wait();
const event = receipt.events.find(e => e.event === 'VaultCreated');
const vaultId = event.args.vaultId;

console.log('Vault created:', vaultId.toString());

// Query vault
const vault = await vaultManager.getVault(vaultId);
console.log('Owner:', vault.owner);
console.log('Status:', vault.status);

// Listen for events
vaultManager.on('VaultReleased', (vaultId, timestamp) => {
  console.log(`Vault ${vaultId} released at ${new Date(timestamp * 1000)}`);
});

TimeManager.sol

Time-lock and deadman switch logic with check-in mechanism and grace periods.

Key Functions

interface ITimeManager {
    // Configuration
    function configureScheduledRelease(
        uint256 vaultId,
        uint256 unlockTime
    ) external;

    function configureDeadmanSwitch(
        uint256 vaultId,
        uint256 checkInPeriod,
        uint256 gracePeriod
    ) external;

    // Check-in mechanism
    function checkIn(uint256 vaultId) external;
    function getLastCheckIn(uint256 vaultId)
        external view returns (uint256);

    // Time queries
    function isUnlockable(uint256 vaultId)
        external view returns (bool);

    function getTimeUntilUnlock(uint256 vaultId)
        external view returns (uint256);

    function isDeadmanTriggered(uint256 vaultId)
        external view returns (bool);

    // Events
    event ScheduledReleaseConfigured(
        uint256 indexed vaultId,
        uint256 unlockTime
    );
    event DeadmanSwitchConfigured(
        uint256 indexed vaultId,
        uint256 checkInPeriod,
        uint256 gracePeriod
    );
    event CheckInPerformed(
        uint256 indexed vaultId,
        uint256 timestamp
    );
    event DeadmanTriggered(uint256 indexed vaultId);
}

Usage Example

import TimeManagerABI from './abis/TimeManager.json';

const timeManager = new ethers.Contract(
  '0x...', // TimeManager address
  TimeManagerABI,
  signer
);

// Configure deadman switch
await timeManager.configureDeadmanSwitch(
  vaultId,
  90 * 24 * 60 * 60,  // 90 days check-in period
  7 * 24 * 60 * 60    // 7 days grace period
);

// Perform check-in
await timeManager.checkIn(vaultId);

// Check if triggered
const isTriggered = await timeManager.isDeadmanTriggered(vaultId);
if (isTriggered) {
  console.log('Deadman switch triggered - vault unlockable');
}

// Get time remaining
const timeRemaining = await timeManager.getTimeUntilUnlock(vaultId);
console.log('Days until unlock:', timeRemaining / (24 * 60 * 60));

VaultFactory.sol

Factory pattern for gas-efficient vault deployment with minimal proxy (EIP-1167).

Factory Pattern

interface IVaultFactory {
    // Deployment
    function deployVault(
        bytes memory initData
    ) external returns (address vaultAddress);

    // Queries
    function getVaultImplementation()
        external view returns (address);

    function isVault(address addr)
        external view returns (bool);

    // Events
    event VaultDeployed(
        address indexed vaultAddress,
        address indexed owner,
        uint256 timestamp
    );
}

// Gas-efficient deployment using minimal proxy
await vaultFactory.deployVault(initData);
// ~50K gas vs ~500K for regular deployment

Deployment Addresses

opBNB Mainnet

Chain ID: 204

VaultManager

0x...

TimeManager

0x...

VaultFactory

0x...

opBNB Testnet

Chain ID: 5611

VaultManager

0x...

TimeManager

0x...

VaultFactory

0x...

Ethereum Mainnet

Chain ID: 1

VaultManager

0x...

TimeManager

0x...

VaultFactory

0x...

BSC Mainnet

Chain ID: 56

VaultManager

0x...

TimeManager

0x...

VaultFactory

0x...

Polygon Mainnet

Chain ID: 137

VaultManager

0x...

TimeManager

0x...

VaultFactory

0x...

Note: Always verify contract addresses from official repository before integration.

Contract ABIs

Installation

# NPM
npm install @vault-protocol/contracts

# Import ABIs
import {
  VaultManagerABI,
  TimeManagerABI,
  VaultFactoryABI
} from '@vault-protocol/contracts';

Gas Optimization

Vault Creation

Standard deployment: ~500K gas

Factory (minimal proxy): ~50K gas (90% savings)

Batch creation: ~35K gas per vault

Check-in Operations

Single check-in: ~30K gas

Batch check-in: ~22K gas per vault

Recommendation: Check-in monthly to minimize costs

Content Updates

Set content CID: ~45K gas

Optimization: Store large data off-chain (IPFS/Arweave)

CID only on-chain: Minimal storage costs

Network Recommendations

opBNB: $0.001 per transaction (recommended primary)

Polygon: $0.01-0.05 per transaction

Ethereum: $5-50 per transaction (use for high-value vaults)

Cross-chain: Consider LayerZero fees (~$1-5)

Security Best Practices

Audit Status

All contracts have been audited by CertiK and OpenZeppelin.

No critical vulnerabilities found

Gas optimizations implemented

Reentrancy protection verified

Access control thoroughly tested

Integration Guidelines

  • • Always validate vault ownership before operations
  • • Implement rate limiting for check-in operations
  • • Use event listeners for real-time vault status updates
  • • Store content CIDs off-chain when possible
  • • Test on testnet thoroughly before mainnet deployment
  • • Implement proper error handling for all contract calls

Common Pitfalls

  • Not checking vault status before unlock attempts
  • Hardcoding gas limits (use estimateGas)
  • Ignoring event emissions for state changes
  • Insufficient check-in frequency for deadman vaults
  • Not handling cross-chain sync delays

Next Steps