canvas-website/docs/BLOCKCHAIN_IMPLEMENTATION_SUMMARY.md

Blockchain Integration Implementation Summary

Completed Components

1. Core Blockchain Signing Module ✅

• File: src/lib/auth/cryptoBlockchain.ts
• EIP-712 structured data signing
• Transaction authorization message creation
• Signature formatting utilities
• Key pair retrieval for signing

2. Ethereum Integration ✅

• File: src/lib/blockchain/ethereum.ts
• Wallet connection (MetaMask, etc.)
• Transaction building and submission
• Chain management (mainnet, sepolia, goerli)
• Proxy contract interaction utilities

3. Account Linking Service ✅

• File: src/lib/auth/blockchainLinking.ts
• Links Web Crypto accounts with Ethereum addresses
• Stores linked account mappings in localStorage
• Account verification utilities

4. Wallet Integration ✅

• File: src/lib/blockchain/walletIntegration.ts
• Proxy contract deployment preparation
• Public key coordinate extraction (P-256)
• Factory contract interaction

5. Key Storage ✅

• File: src/lib/auth/keyStorage.ts
• In-memory key pair storage (session-based)
• Placeholder for persistent storage implementation
• Key pair retrieval utilities

6. Smart Contracts ✅

• File: contracts/WebCryptoProxy.sol
  • Minimal proxy contract for each user
  • Stores P-256 public key
  • Transaction execution with signature verification
  • Replay protection via nonces
  • Deadline enforcement
• File: contracts/WebCryptoProxyFactory.sol
  • Factory for deploying proxy contracts
  • Deterministic proxy addresses

7. React Context ✅

• File: src/context/BlockchainContext.tsx
• Blockchain state management
• Wallet connection state
• Linked account management
• Event listeners for wallet changes

8. UI Components ✅

• File: src/components/auth/BlockchainLink.tsx
  • Link Web Crypto account with Ethereum wallet
  • Connection status display
• File: src/components/blockchain/WalletStatus.tsx
  • Display wallet connection status
  • Show linked account information
• File: src/components/blockchain/TransactionBuilder.tsx
  • Build and authorize transactions
  • Web Crypto API signing integration

9. Documentation ✅

• File: docs/BLOCKCHAIN_INTEGRATION.md
  • Complete integration guide
  • Architecture overview
  • Usage instructions
  • Security considerations

Dependencies Added

• viem - Ethereum interaction library
• @noble/curves - Cryptographic utilities (installed but not yet used for P-256 verification)

Integration Points

Updated Files

• src/lib/auth/cryptoAuthService.ts - Now stores key pairs during registration
• src/lib/auth/crypto.ts - Extended with blockchain utilities

Known Limitations & TODOs

Critical TODOs

1. P-256 Signature Verification in Smart Contract

   • The verifyP256Signature function in WebCryptoProxy.sol is a placeholder
   • Needs implementation using a P-256 verification library or precompile
   • Options:
     • Use @noble/curves compiled to Solidity
     • Import a P-256 verification library
     • Use a precompile (if available on target chain)

2. Persistent Key Storage

   • Currently uses in-memory storage (lost on page refresh)
   • Need to implement Web Crypto API's persistent key storage with IndexedDB
   • See src/lib/auth/keyStorage.ts for TODO

3. Nonce Management

   • Currently uses timestamp-based nonces
   • Should query nonce from contract state
   • Add nonce tracking utilities

4. Proxy Contract Deployment

   • Factory address needs to be configured per chain
   • Add deployment utilities
   • Add proxy address lookup

Nice-to-Have Features

• Support for multiple chains
• Transaction history tracking
• Gas estimation and optimization
• Error handling and retry logic
• Gnosis Safe multi-sig wallet support
• Transaction status monitoring
• Batch transaction support

Usage Example

// 1. Connect wallet
const { connect, wallet } = useBlockchain();
await connect();

// 2. Link accounts
const { linkWebCryptoAccount } = useBlockchain();
await linkWebCryptoAccount(username);

// 3. Build and sign transaction
const authorization = {
  to: '0x...',
  value: '0',
  data: '0x...',
  nonce: Date.now(),
  deadline: Math.floor(Date.now() / 1000) + 3600,
};

const signed = await signTransactionAuthorization(
  privateKey,
  authorization,
  domain
);

Testing Checklist

• Wallet connection (MetaMask)
• Account linking flow
• Transaction signing with Web Crypto API
• Proxy contract deployment (once factory is deployed)
• Transaction execution through proxy
• Replay protection (nonce checking)
• Deadline enforcement
• Error handling

Next Steps

1. Deploy WebCryptoProxyFactory.sol to a testnet
2. Update factory address in walletIntegration.ts
3. Implement P-256 signature verification in smart contract
4. Test end-to-end transaction flow
5. Implement persistent key storage
6. Add comprehensive error handling
7. Add transaction monitoring

Security Notes

• Private keys are stored in memory (session-based) - implement persistent storage for production
• P-256 signature verification must be properly implemented before production use
• Nonce management should use contract state, not timestamps
• Add rate limiting and gas limits to prevent abuse
• Implement proper error handling to prevent information leakage