@veridex/sdk 1.0.0-beta.1

package/CHANGELOG.md

@@ -0,0 +1,73 @@
+# Changelog
+
+All notable changes to the Veridex SDK will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] - 2025-01-XX
+
+### Added
+
+- **Core SDK**
+  - `createSDK()` factory function for easy initialization
+  - `VeridexSDK` class with full passkey authentication support
+  - `PasskeyManager` for WebAuthn credential registration and authentication
+  - `WalletManager` for deterministic vault address derivation
+  - `BalanceManager` for multi-chain balance queries
+  - `TransactionTracker` for transaction status monitoring
+
+- **Chain Support**
+  - EVM chains: Base, Optimism, Arbitrum, Ethereum, Polygon, and more
+  - Solana: SPL token and SOL transfer support
+  - Aptos: Fungible asset and APT transfer support
+  - Sui: Coin and SUI transfer support
+  - Starknet: Custom bridge with multi-relayer attestations
+
+- **Cross-Chain Features**
+  - Wormhole VAA-based cross-chain messaging
+  - Cross-chain balance queries via Wormhole CCQ
+  - Bridge operations between supported chains
+  - Unified identity across all chains
+
+- **Session Keys**
+  - `SessionManager` for temporary delegated access
+  - Time-limited sessions with value caps
+  - Secure key generation and storage
+  - Session revocation support
+
+- **Gasless Transactions**
+  - `RelayerClient` for sponsored transactions
+  - `GasSponsor` for integrator-sponsored vault creation
+  - Automatic gas estimation and relaying
+
+- **Security**
+  - P-256 (secp256r1) signature verification
+  - RIP-7212 precompile support where available
+  - FCL fallback for chains without precompile
+  - Replay protection via nonces
+  - Guardian quorum validation (13/19)
+
+- **Utilities**
+  - Payload encoding/decoding functions
+  - VAA parsing and validation
+  - Chain ID mappings and constants
+  - Error handling with categorized error codes
+
+### Security
+
+- WebAuthn challenge binding enforced
+- Signature malleability protections
+- Cross-chain message validation
+- Nonce-based replay prevention
+
+---
+
+## [Unreleased]
+
+### Planned
+
+- React hooks package (`@veridex/react`)
+- Vue composables package (`@veridex/vue`)
+- Wallet adapter integrations
+- Additional chain support (NEAR, Cosmos)

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Veridex Protocol
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,212 @@
+# @veridex/sdk
+
+Veridex Protocol SDK - Client library for **Passkey-based cross-chain authentication**.
+
+Build applications with WebAuthn/Passkeys (P-256) that work across EVM, Solana, Aptos, Sui, and Starknet.
+
+## Features
+
+- **Passkey Authentication** - WebAuthn P-256 signature verification (no seed phrases)
+- **Cross-Chain Support** - EVM, Solana, Aptos, Sui, Starknet
+- **Deterministic Vaults** - Same address across all EVM chains
+- **Gasless Transactions** - Relayer-sponsored execution
+- **Session Keys** - Temporary delegated access for smooth UX
+- **Wormhole Integration** - Guardian-attested cross-chain messaging
+
+## Installation
+
+```bash
+npm install @veridex/sdk ethers
+# or
+yarn add @veridex/sdk ethers
+# or
+bun add @veridex/sdk ethers
+```
+
+## Quick Start
+
+```typescript
+import { createSDK } from '@veridex/sdk';
+
+// Initialize SDK (testnet by default)
+const sdk = createSDK('base');
+
+// Register a passkey
+const credential = await sdk.passkey.register('user@example.com', 'My Wallet');
+
+// Get your vault address (same on all EVM chains!)
+const vaultAddress = sdk.getVaultAddress();
+console.log('Your vault:', vaultAddress);
+
+// Transfer tokens
+await sdk.transfer({
+  token: '0x036CbD53842c5426634e7929541eC2318f3dCF7e', // USDC
+  recipient: '0x742d35Cc6634C0532925a3b844Bc9e7595f5A234',
+  amount: 1000000n, // 1 USDC (6 decimals)
+});
+```
+
+## Networks
+
+```typescript
+// Testnet (default)
+const testnetSdk = createSDK('base');
+
+// Mainnet
+const mainnetSdk = createSDK('base', { network: 'mainnet' });
+
+// Custom RPC
+const customSdk = createSDK('base', { 
+  rpcUrl: 'https://my-rpc.example.com' 
+});
+```
+
+## Supported Chains
+
+| Chain | Type | Status |
+|-------|------|--------|
+| Base | Hub (EVM) | Testnet + Mainnet |
+| Optimism | Spoke (EVM) | Testnet + Mainnet |
+| Arbitrum | Spoke (EVM) | Testnet + Mainnet |
+| Ethereum | Spoke (EVM) | Testnet + Mainnet |
+| Polygon | Spoke (EVM) | Testnet + Mainnet |
+| Solana | Spoke | Devnet + Mainnet |
+| Aptos | Spoke | Testnet + Mainnet |
+| Sui | Spoke | Testnet + Mainnet |
+| Starknet | Spoke | Sepolia + Mainnet |
+
+## Gasless Transactions
+
+```typescript
+const sdk = createSDK('base', {
+  relayerUrl: 'https://relayer.veridex.io',
+  relayerApiKey: 'your-api-key',
+});
+
+// Transfers are now gasless
+await sdk.transferViaRelayer({
+  token: USDC_ADDRESS,
+  recipient: '0x...',
+  amount: 1000000n,
+});
+```
+
+## Session Keys
+
+Enable seamless UX without repeated biometric prompts:
+
+```typescript
+// Create a 1-hour session with 0.1 ETH limit
+const session = await sdk.sessions.create({
+  duration: 3600,
+  maxValue: parseEther('0.1'),
+});
+
+// Execute multiple transactions without prompts
+await sdk.sessions.transfer(session, { ... });
+await sdk.sessions.transfer(session, { ... });
+
+// Revoke when done
+await sdk.sessions.revoke(session);
+```
+
+## Cross-Chain Bridging
+
+```typescript
+import { parseUnits } from 'ethers';
+
+await sdk.bridge({
+  targetChain: 'optimism',
+  token: USDC_ADDRESS,
+  amount: parseUnits('100', 6),
+  recipient: '0x...', // Optional, defaults to your vault
+});
+```
+
+## API Reference
+
+### Core
+
+| Export | Description |
+|--------|-------------|
+| `createSDK(chain, config?)` | Create SDK for a chain |
+| `VeridexSDK` | Main SDK class |
+| `PasskeyManager` | WebAuthn credential management |
+| `WalletManager` | Vault address derivation |
+| `SessionManager` | Session key management |
+
+### Chain Clients
+
+```typescript
+import { EVMClient } from '@veridex/sdk/chains/evm';
+import { SolanaClient } from '@veridex/sdk/chains/solana';
+import { AptosClient } from '@veridex/sdk/chains/aptos';
+import { SuiClient } from '@veridex/sdk/chains/sui';
+import { StarknetClient } from '@veridex/sdk/chains/starknet';
+```
+
+### Utilities
+
+```typescript
+import { 
+  encodeTransferAction,
+  encodeBridgeAction,
+  parseVAA,
+  fetchVAA,
+} from '@veridex/sdk';
+```
+
+### Constants
+
+```typescript
+import { 
+  WORMHOLE_CHAIN_IDS,
+  TESTNET_CHAINS,
+  MAINNET_CHAINS,
+} from '@veridex/sdk';
+```
+
+## Security
+
+- **Passkeys Only** - No EOA or seed phrase assumptions
+- **RIP-7212 Support** - Native P-256 verification (~3,450 gas)
+- **FCL Fallback** - Software verification when precompile unavailable
+- **Wormhole VAA** - 13/19 guardian quorum for cross-chain messages
+- **Replay Protection** - Nonce-based action deduplication
+
+## Browser Support
+
+WebAuthn requires a secure context (HTTPS) and a compatible browser:
+
+| Browser | Minimum Version |
+|---------|-----------------|
+| Chrome | 67+ |
+| Firefox | 60+ |
+| Safari | 14+ |
+| Edge | 18+ |
+
+## TypeScript
+
+Full TypeScript support with comprehensive type definitions:
+
+```typescript
+import type {
+  ChainName,
+  NetworkType,
+  SimpleSDKConfig,
+  TransferParams,
+  BridgeParams,
+  SessionKey,
+} from '@veridex/sdk';
+```
+
+## License
+
+MIT
+
+## Links
+
+- [Documentation](https://docs.veridex.io)
+- [GitHub](https://github.com/Veridex-Protocol/sdk)
+- [Discord](https://discord.gg/veridex)
+- [Twitter](https://twitter.com/VeridexProtocol)

package/dist/chains/aptos/index.d.mts

@@ -0,0 +1,140 @@
+import { AptosClient as AptosClient$1, Types } from 'aptos';
+import { C as ChainClient, a as ChainConfig, T as TransferParams, E as ExecuteParams, B as BridgeParams, W as WebAuthnSignature, D as DispatchResult, V as VaultCreationResult } from '../../types-ChIsqCiw.mjs';
+
+/**
+ * Veridex Protocol SDK - Aptos Chain Client
+ *
+ * Implementation of ChainClient interface for Aptos blockchain
+ */
+
+interface AptosClientConfig {
+    wormholeChainId: number;
+    rpcUrl: string;
+    moduleAddress: string;
+    wormholeCoreBridge: string;
+    tokenBridge: string;
+    network?: 'mainnet' | 'testnet' | 'devnet';
+}
+/**
+ * Aptos implementation of the ChainClient interface
+ */
+declare class AptosClient implements ChainClient {
+    private config;
+    private client;
+    private moduleAddress;
+    constructor(config: AptosClientConfig);
+    getConfig(): ChainConfig;
+    getNonce(userKeyHash: string): Promise<bigint>;
+    getMessageFee(): Promise<bigint>;
+    buildTransferPayload(params: TransferParams): Promise<string>;
+    buildExecutePayload(params: ExecuteParams): Promise<string>;
+    buildBridgePayload(params: BridgeParams): Promise<string>;
+    dispatch(signature: WebAuthnSignature, publicKeyX: bigint, publicKeyY: bigint, targetChain: number, actionPayload: string, nonce: bigint, signer: any): Promise<DispatchResult>;
+    /**
+     * Dispatch an action via relayer (gasless)
+     * Note: On Aptos, this still goes through the Hub chain
+     * Aptos is a spoke-only chain in Veridex architecture
+     */
+    dispatchGasless(signature: WebAuthnSignature, publicKeyX: bigint, publicKeyY: bigint, targetChain: number, actionPayload: string, nonce: bigint, relayerUrl: string): Promise<DispatchResult>;
+    getVaultAddress(userKeyHash: string): Promise<string | null>;
+    /**
+     * Compute vault address using resource account derivation
+     * On Aptos, vaults are derived from the module address + user key hash
+     */
+    computeVaultAddress(userKeyHash: string): string;
+    private computeVaultAddressFromHash;
+    /**
+     * Convert hex string to Uint8Array (browser-compatible)
+     */
+    private hexToBytes;
+    vaultExists(userKeyHash: string): Promise<boolean>;
+    createVault(userKeyHash: string, signer: any): Promise<VaultCreationResult>;
+    createVaultSponsored?(userKeyHash: string, sponsorPrivateKey: string, rpcUrl?: string): Promise<VaultCreationResult>;
+    /**
+     * Create a vault via the relayer (sponsored/gasless)
+     * This is the recommended way to create Aptos vaults
+     *
+     * The relayer will dispatch a vault creation action from Hub to Aptos spoke
+     */
+    createVaultViaRelayer(userKeyHash: string, relayerUrl: string): Promise<VaultCreationResult>;
+    /**
+     * Get vault info via relayer (includes existence check)
+     */
+    getVaultViaRelayer(userKeyHash: string, relayerUrl: string): Promise<{
+        vaultAddress: string;
+        exists: boolean;
+    }>;
+    estimateVaultCreationGas(userKeyHash: string): Promise<bigint>;
+    getFactoryAddress(): string | undefined;
+    getImplementationAddress(): string | undefined;
+    /**
+     * Get native APT balance
+     */
+    getNativeBalance(address: string): Promise<bigint>;
+    /**
+     * Get fungible asset (FA) or coin balance
+     */
+    getTokenBalance(tokenAddress: string, ownerAddress: string): Promise<bigint>;
+    /**
+     * Compute key hash from public key coordinates
+     * Matches EVM keccak256(abi.encode(publicKeyX, publicKeyY))
+     */
+    private computeKeyHash;
+    /**
+     * Build message for signing (matches Hub chain format)
+     */
+    private buildMessage;
+    /**
+     * Get Aptos client instance for advanced usage
+     */
+    getClient(): AptosClient$1;
+    /**
+     * Get module address
+     */
+    getModuleAddress(): string;
+    /**
+     * Get current ledger version
+     */
+    getLedgerVersion(): Promise<bigint>;
+    /**
+     * Get transaction by hash
+     */
+    getTransaction(txHash: string): Promise<Types.Transaction>;
+    /**
+     * Wait for transaction confirmation
+     */
+    waitForTransaction(txHash: string, timeoutSecs?: number): Promise<Types.Transaction>;
+    /**
+     * Get vault resource for an owner
+     *
+     * @param ownerKeyHash - Owner's passkey hash (32 bytes as hex)
+     * @returns Vault resource data or null if not found
+     */
+    getVaultResource(ownerKeyHash: string): Promise<{
+        ownerKeyHash: string;
+        authorizedSigners: string[];
+        nonce: bigint;
+    } | null>;
+    /**
+     * Get authorized signers for a vault
+     *
+     * @param ownerKeyHash - Owner's passkey hash (32 bytes as hex)
+     * @returns Array of authorized signer key hashes
+     */
+    getAuthorizedSigners(ownerKeyHash: string): Promise<string[]>;
+    /**
+     * Check if a VAA has been processed (for replay protection)
+     *
+     * @param vaaHash - VAA hash as hex string
+     * @returns Whether the VAA has been processed
+     */
+    isVaaProcessed(vaaHash: string): Promise<boolean>;
+    /**
+     * Check if protocol is paused
+     *
+     * @returns Whether the protocol is paused
+     */
+    isProtocolPaused(): Promise<boolean>;
+}
+
+export { AptosClient, type AptosClientConfig };

package/dist/chains/aptos/index.d.ts

@@ -0,0 +1,140 @@
+import { AptosClient as AptosClient$1, Types } from 'aptos';
+import { C as ChainClient, a as ChainConfig, T as TransferParams, E as ExecuteParams, B as BridgeParams, W as WebAuthnSignature, D as DispatchResult, V as VaultCreationResult } from '../../types-ChIsqCiw.js';
+
+/**
+ * Veridex Protocol SDK - Aptos Chain Client
+ *
+ * Implementation of ChainClient interface for Aptos blockchain
+ */
+
+interface AptosClientConfig {
+    wormholeChainId: number;
+    rpcUrl: string;
+    moduleAddress: string;
+    wormholeCoreBridge: string;
+    tokenBridge: string;
+    network?: 'mainnet' | 'testnet' | 'devnet';
+}
+/**
+ * Aptos implementation of the ChainClient interface
+ */
+declare class AptosClient implements ChainClient {
+    private config;
+    private client;
+    private moduleAddress;
+    constructor(config: AptosClientConfig);
+    getConfig(): ChainConfig;
+    getNonce(userKeyHash: string): Promise<bigint>;
+    getMessageFee(): Promise<bigint>;
+    buildTransferPayload(params: TransferParams): Promise<string>;
+    buildExecutePayload(params: ExecuteParams): Promise<string>;
+    buildBridgePayload(params: BridgeParams): Promise<string>;
+    dispatch(signature: WebAuthnSignature, publicKeyX: bigint, publicKeyY: bigint, targetChain: number, actionPayload: string, nonce: bigint, signer: any): Promise<DispatchResult>;
+    /**
+     * Dispatch an action via relayer (gasless)
+     * Note: On Aptos, this still goes through the Hub chain
+     * Aptos is a spoke-only chain in Veridex architecture
+     */
+    dispatchGasless(signature: WebAuthnSignature, publicKeyX: bigint, publicKeyY: bigint, targetChain: number, actionPayload: string, nonce: bigint, relayerUrl: string): Promise<DispatchResult>;
+    getVaultAddress(userKeyHash: string): Promise<string | null>;
+    /**
+     * Compute vault address using resource account derivation
+     * On Aptos, vaults are derived from the module address + user key hash
+     */
+    computeVaultAddress(userKeyHash: string): string;
+    private computeVaultAddressFromHash;
+    /**
+     * Convert hex string to Uint8Array (browser-compatible)
+     */
+    private hexToBytes;
+    vaultExists(userKeyHash: string): Promise<boolean>;
+    createVault(userKeyHash: string, signer: any): Promise<VaultCreationResult>;
+    createVaultSponsored?(userKeyHash: string, sponsorPrivateKey: string, rpcUrl?: string): Promise<VaultCreationResult>;
+    /**
+     * Create a vault via the relayer (sponsored/gasless)
+     * This is the recommended way to create Aptos vaults
+     *
+     * The relayer will dispatch a vault creation action from Hub to Aptos spoke
+     */
+    createVaultViaRelayer(userKeyHash: string, relayerUrl: string): Promise<VaultCreationResult>;
+    /**
+     * Get vault info via relayer (includes existence check)
+     */
+    getVaultViaRelayer(userKeyHash: string, relayerUrl: string): Promise<{
+        vaultAddress: string;
+        exists: boolean;
+    }>;
+    estimateVaultCreationGas(userKeyHash: string): Promise<bigint>;
+    getFactoryAddress(): string | undefined;
+    getImplementationAddress(): string | undefined;
+    /**
+     * Get native APT balance
+     */
+    getNativeBalance(address: string): Promise<bigint>;
+    /**
+     * Get fungible asset (FA) or coin balance
+     */
+    getTokenBalance(tokenAddress: string, ownerAddress: string): Promise<bigint>;
+    /**
+     * Compute key hash from public key coordinates
+     * Matches EVM keccak256(abi.encode(publicKeyX, publicKeyY))
+     */
+    private computeKeyHash;
+    /**
+     * Build message for signing (matches Hub chain format)
+     */
+    private buildMessage;
+    /**
+     * Get Aptos client instance for advanced usage
+     */
+    getClient(): AptosClient$1;
+    /**
+     * Get module address
+     */
+    getModuleAddress(): string;
+    /**
+     * Get current ledger version
+     */
+    getLedgerVersion(): Promise<bigint>;
+    /**
+     * Get transaction by hash
+     */
+    getTransaction(txHash: string): Promise<Types.Transaction>;
+    /**
+     * Wait for transaction confirmation
+     */
+    waitForTransaction(txHash: string, timeoutSecs?: number): Promise<Types.Transaction>;
+    /**
+     * Get vault resource for an owner
+     *
+     * @param ownerKeyHash - Owner's passkey hash (32 bytes as hex)
+     * @returns Vault resource data or null if not found
+     */
+    getVaultResource(ownerKeyHash: string): Promise<{
+        ownerKeyHash: string;
+        authorizedSigners: string[];
+        nonce: bigint;
+    } | null>;
+    /**
+     * Get authorized signers for a vault
+     *
+     * @param ownerKeyHash - Owner's passkey hash (32 bytes as hex)
+     * @returns Array of authorized signer key hashes
+     */
+    getAuthorizedSigners(ownerKeyHash: string): Promise<string[]>;
+    /**
+     * Check if a VAA has been processed (for replay protection)
+     *
+     * @param vaaHash - VAA hash as hex string
+     * @returns Whether the VAA has been processed
+     */
+    isVaaProcessed(vaaHash: string): Promise<boolean>;
+    /**
+     * Check if protocol is paused
+     *
+     * @returns Whether the protocol is paused
+     */
+    isProtocolPaused(): Promise<boolean>;
+}
+
+export { AptosClient, type AptosClientConfig };