Guardian-AA SDK

Zero-Knowledge AI Wallet Copilot SDK for TypeScript/JavaScript

The Guardian-AA SDK provides a comprehensive TypeScript/JavaScript interface for building applications with Guardian-AA's zero-knowledge proof system, ERC-4337 account abstraction, and gasless transaction capabilities.

🎉 Status: Production Ready (Phase 3 Complete)

✨ Features

• 🔐 Zero-Knowledge Proofs: Generate and verify SHA256 ZK proofs using Halo2
• ⚡ Account Abstraction: ERC-4337 compliant smart contract wallets
• 🚫 Gasless Transactions: Meta-transaction support with paymaster integration
• 🔗 Multi-Signature: Advanced multi-sig wallet functionality
• 🛠️ Developer-Friendly: Full TypeScript support with comprehensive documentation
• 🧪 Production-Ready: Robust error handling and validation
• 📦 Tree-Shakable: Optimized bundle sizes with ESM support
• 🔄 Cross-Platform: CommonJS, ESM, and TypeScript definitions included

📦 Installation

# npm
npm install @tuaregsand/guardian-aa-sdk

# yarn
yarn add @tuaregsand/guardian-aa-sdk

# pnpm
pnpm add @tuaregsand/guardian-aa-sdk

Peer Dependencies

npm install @noble/hashes @noble/curves

🚀 Quick Start

Basic Setup

import { createSepoliaGuardianAA } from '@tuaregsand/guardian-aa-sdk';
import { ethers } from 'ethers';

// Create SDK instance for Sepolia testnet
const guardian = createSepoliaGuardianAA();

// Initialize with a signer
const privateKey = 'your-private-key';
const signer = new ethers.Wallet(privateKey);

await guardian.initialize(signer);

Generate Zero-Knowledge Proofs

// Get ZK client
const zkClient = guardian.getZkClient();

// Generate proof for sensitive data
const data = new TextEncoder().encode('sensitive transaction data');
const proof = await zkClient.generateProof(data);

console.log('Proof generated:', {
  hash: proof.hash,
  generationTime: proof.generationTime,
  proofSize: proof.proof.length
});

// Verify the proof
const verification = await zkClient.verifyProof(data, proof.proof, proof.hash);
console.log('Proof valid:', verification.status === 'VALID');

Deploy Smart Contract Wallets

// Get contracts client
const contracts = guardian.getContractsClient();

// Deploy a simple account
const simpleAccount = await contracts.deploySimpleAccount(
  signer.address, // owner
  0n // salt
);

console.log('Simple account deployed at:', simpleAccount.getAddress());

// Deploy a multi-sig account
const multiSigAccount = await contracts.deployMultiSigAccount(
  [signer.address, '0x...'], // owners
  2, // threshold
  0n // salt
);

console.log('Multi-sig account deployed at:', multiSigAccount.getAddress());

Execute Gasless Transactions

// Create a transaction
const transaction = {
  to: '0x...' as Address,
  value: ethers.parseEther('0.1'),
  data: '0x',
  operation: 0
};

// Sign the transaction
const signature = await signer.signMessage('transaction-hash');

// Execute with paymaster (gasless)
const txHash = await contracts.executeTransaction(
  simpleAccount,
  transaction,
  signature,
  true // use paymaster
);

console.log('Gasless transaction executed:', txHash);

📚 API Reference

Main SDK Class

GuardianAA

The main SDK client that provides unified access to all Guardian-AA functionality.

import { GuardianAA, createGuardianAA } from '@tuaregsand/guardian-aa-sdk';

const config = {
  network: {
    chainId: 11155111,
    name: 'Ethereum Sepolia',
    rpcUrl: 'https://sepolia.infura.io/v3/your-key',
    currency: 'ETH',
    isTestnet: true
  },
  zkConfig: {
    circuitK: 14,
    useCachedKeys: true,
    timeout: 30000
  },
  debug: true
};

const guardian = new GuardianAA(config);
await guardian.initialize(signer);

Methods:

• initialize(signer?: ethers.Wallet): Initialize the SDK
• getZkClient(): Get ZK proof client
• getContractsClient(): Get contracts client
• getProvider(): Get Ethereum provider
• getSigner(): Get current signer
• updateSigner(signer): Update the signer
• isReady(): Check if SDK is ready
• cleanup(): Cleanup resources

ZK Proof Client

ZkClient

Handles zero-knowledge proof generation and verification.

const zkClient = guardian.getZkClient();

// Generate single proof
const proof = await zkClient.generateProof(data);

// Generate batch proofs
const batchResult = await zkClient.generateBatchProofs({
  inputs: [data1, data2, data3],
  parallelization: true
});

// Verify proof
const verification = await zkClient.verifyProof(data, proof.proof, proof.hash);

// Combined prove and verify
const { proof, verification } = await zkClient.proveAndVerify(data);

Contracts Client

ContractsClient

Manages smart contract interactions and account operations.

const contracts = guardian.getContractsClient();

// Account deployment
const simpleAccount = await contracts.deploySimpleAccount(owner, salt);
const multiSigAccount = await contracts.deployMultiSigAccount(owners, threshold, salt);

// Transaction execution
const txHash = await contracts.executeTransaction(account, transaction, signature);
const batchTxHash = await contracts.executeBatchTransaction(account, batch, signature);

// Gas estimation
const gasEstimate = await contracts.estimateUserOpGas(userOp);

// Account management
const balance = await contracts.getAccountBalance(accountAddress);
await contracts.depositForAccount(accountAddress, amount);

Account Classes

SimpleAccount

ERC-4337 account with ECDSA signature verification.

// Get account instance
const account = contracts.getSimpleAccount(accountAddress);

// Build user operation
const userOp = await account.buildUserOperation(transaction);

// Execute transaction
const result = await account.execute(transaction, signature);

// Execute batch
const batchResult = await account.executeBatch(batch, signature);

MultiSigAccount

Multi-signature account with threshold-based execution.

// Get multi-sig account
const multiSig = contracts.getMultiSigAccount(address, threshold, signers);

// Signer management
await multiSig.addSigner(newSigner, signatures);
await multiSig.removeSigner(oldSigner, signatures);
await multiSig.changeThreshold(newThreshold, signatures);

// Get signer info
const { signers, threshold } = await multiSig.getSignerInfo();

Utility Functions

Validation

import { 
  isValidAddress, 
  isValidSignature, 
  isValidUserOperation,
  validateAccountDeployment 
} from '@tuaregsand/guardian-aa-sdk';

const isValid = isValidAddress('0x...');
const isValidSig = isValidSignature('0x...');
const { isValid, errors } = validateAccountDeployment({ owner, threshold });

Formatting

import { 
  formatAddress, 
  formatEther, 
  formatGwei,
  truncateAddress 
} from '@tuaregsand/guardian-aa-sdk';

const checksummed = formatAddress(address);
const ethAmount = formatEther(weiAmount);
const gasPrice = formatGwei(weiGasPrice);
const short = truncateAddress(address);

Cryptography

import { 
  generatePrivateKey,
  signMessage,
  verifySignature,
  hashSHA256,
  getUserOpHash 
} from '@tuaregsand/guardian-aa-sdk';

const privateKey = generatePrivateKey();
const signature = await signMessage(message, privateKey);
const isValid = verifySignature(message, signature, address);
const hash = hashSHA256(data);

🏗️ Advanced Usage

Custom Network Configuration

import { createGuardianAA } from '@guardian-aa/sdk';

const customNetwork = {
  chainId: 31337,
  name: 'Local Network',
  rpcUrl: 'http://localhost:8545',
  currency: 'ETH',
  isTestnet: true
};

const guardian = createGuardianAA(customNetwork, {
  zkConfig: {
    circuitK: 16, // Higher for better security
    useCachedKeys: true,
    enableBenchmarking: true
  },
  debug: true
});

Batch Operations

// Batch ZK proof generation
const batchProofs = await zkClient.generateBatchProofs({
  inputs: [data1, data2, data3],
  parallelization: true,
  batchId: 'batch-001'
});

// Batch verification
const verifications = await zkClient.verifyBatchProofs([
  { input: data1, proof: proof1, expectedHash: hash1 },
  { input: data2, proof: proof2, expectedHash: hash2 }
]);

// Batch transactions
const batchTx = {
  transactions: [
    { to: address1, value: amount1, data: '0x' },
    { to: address2, value: amount2, data: callData }
  ],
  failOnError: true
};

const result = await account.executeBatch(batchTx, signature);

Error Handling

import { 
  GuardianAAError, 
  ZkProofError, 
  ContractError, 
  ValidationError 
} from '@tuaregsand/guardian-aa-sdk';

try {
  await zkClient.generateProof(data);
} catch (error) {
  if (error instanceof ZkProofError) {
    console.error('ZK proof failed:', error.message, error.details);
  } else if (error instanceof ContractError) {
    console.error('Contract interaction failed:', error.message);
  } else if (error instanceof ValidationError) {
    console.error('Validation failed:', error.message);
  }
}

🧪 Testing

# Run all tests
npm test

# Run with coverage
npm run test:ci

# Run in watch mode
npm run test:dev

🔧 Development

Building

# Build the SDK
npm run build

# Build in watch mode
npm run dev

# Type check
npm run typecheck

# Lint
npm run lint
npm run lint:fix

Documentation

# Generate API documentation
npm run docs

📄 License

Guardian-AA Custom License © Guardian-AA Team

Free for non-commercial use. Commercial use requires permission. See LICENSE for full terms.

🤝 Contributing

Please read our Contributing Guide for details on our code of conduct and the process for submitting pull requests.

🆘 Support

• 📚 Documentation
• 💬 Discord
• 🐛 Issues
• 📧 Email

Built with ❤️ by the Guardian-AA team