@veridex/sdk 1.0.0-beta.16 → 1.0.0-beta.18

package/README.md

@@ -3,142 +3,147 @@
 [![npm version](https://img.shields.io/npm/v/@veridex/sdk.svg)](https://www.npmjs.com/package/@veridex/sdk)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-Veridex Protocol SDK - Client library for **Passkey-based cross-chain authentication**.
+**Passkey-based cross-chain identity and authentication.** One passkey. Every chain.
 
-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
+Register a WebAuthn passkey once, get a deterministic vault address on every supported chain. No seed phrases, no private keys, no browser extensions.
 
 ```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
+// Register a passkey (biometric prompt)
 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);
+// Same vault address on every EVM chain
+const vault = sdk.getVaultAddress();
 
-// Transfer tokens
-await sdk.transfer({
-  token: '0x036CbD53842c5426634e7929541eC2318f3dCF7e', // USDC
-  recipient: '0x742d35Cc6634C0532925a3b844Bc9e7595f5A234',
-  amount: 1000000n, // 1 USDC (6 decimals)
+// Transfer tokens (gasless via relayer)
+await sdk.transferViaRelayer({
+  token: USDC_ADDRESS,
+  recipient: '0x742d35Cc...',
+  amount: 1000000n, // 1 USDC
 });
 ```
 
-## Networks
+## Architecture
 
-```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' 
-});
+```
+                    ┌─────────────────────┐
+                    │   WebAuthn Passkey   │
+                    │   (P-256 / secp256r1)│
+                    └──────────┬──────────┘
+                               │
+                    ┌──────────▼──────────┐
+                    │    Veridex Hub      │
+                    │   (Base / EVM)      │
+                    │  Identity + Vaults  │
+                    └──────────┬──────────┘
+                               │ Wormhole / Custom Bridge
+          ┌────────┬───────────┼───────────┬────────┬────────┐
+          ▼        ▼           ▼           ▼        ▼        ▼
+       Solana   Aptos       Sui      Starknet   Stacks    EVM Spokes
+      (Ed25519) (Ed25519) (secp256k1) (Stark)  (secp256r1) (Opt/Arb/Poly)
 ```
 
+**Hub-and-Spoke model**: Identity lives on the Hub (Base). Actions are dispatched to spoke chains via Wormhole guardian-attested messages or custom bridge attestations.
+
 ## 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 |
+| Chain | Type | Wormhole ID | Signature | Networks |
+|-------|------|-------------|-----------|----------|
+| **Base** | Hub (EVM) | 30 | secp256r1 (passkey) + secp256k1 (session) | Sepolia + Mainnet |
+| **Ethereum** | Spoke (EVM) | 2 | secp256r1 + secp256k1 | Sepolia + Mainnet |
+| **Optimism** | Spoke (EVM) | 24 | secp256r1 + secp256k1 | Sepolia + Mainnet |
+| **Arbitrum** | Spoke (EVM) | 23 | secp256r1 + secp256k1 | Sepolia + Mainnet |
+| **Polygon** | Spoke (EVM) | 5 | secp256r1 + secp256k1 | Amoy + Mainnet |
+| **Solana** | Spoke | 1 | Ed25519 | Devnet + Mainnet |
+| **Aptos** | Spoke | 22 | Ed25519 | Testnet + Mainnet |
+| **Sui** | Spoke | 21 | secp256k1 | Testnet + Mainnet |
+| **Starknet** | Spoke | 50001 | Stark ECDSA | Sepolia + Mainnet |
+| **Stacks** | Spoke | 60 | secp256r1 (native!) + secp256k1 | Testnet + Mainnet |
+
+## Key Features
 
-## Gasless Transactions
+### Passkey Authentication (No Seed Phrases)
 
 ```typescript
-const sdk = createSDK('base', {
-  relayerUrl: 'https://relayer.veridex.io',
-  relayerApiKey: 'your-api-key',
-});
+// Register — triggers biometric prompt
+const credential = await sdk.passkey.register('user@example.com', 'My Wallet');
 
-// Transfers are now gasless
-await sdk.transferViaRelayer({
-  token: USDC_ADDRESS,
-  recipient: '0x...',
-  amount: 1000000n,
-});
+// Authenticate — biometric verification
+const signature = await sdk.passkey.sign(challenge);
 ```
 
-## Session Keys
+- **RIP-7212** native P-256 verification on EVM (~3,450 gas)
+- **FCL fallback** for chains without precompile
+- **Stacks** has native `secp256r1-verify` in Clarity — no workarounds needed
 
-Enable seamless UX without repeated biometric prompts:
+### Deterministic Vaults
+
+```typescript
+// Same address on Base, Optimism, Arbitrum, Ethereum, Polygon
+const vault = sdk.getVaultAddress();
+
+// Vault is derived from your passkey — no deployment needed on spokes
+```
+
+### Session Keys
+
+Delegate temporary access with spending limits — no repeated biometric prompts:
 
 ```typescript
-// Create a 1-hour session with 0.1 ETH limit
 const session = await sdk.sessions.create({
-  duration: 3600,
+  duration: 3600,           // 1 hour
   maxValue: parseEther('0.1'),
+  allowedChains: [30, 1],  // Base + Solana
 });
 
-// Execute multiple transactions without prompts
-await sdk.sessions.transfer(session, { ... });
-await sdk.sessions.transfer(session, { ... });
+// Multiple transactions without prompts
+await sdk.sessions.transfer(session, { token, recipient, amount });
+await sdk.sessions.transfer(session, { token, recipient, amount });
 
-// Revoke when done
+// Revoke anytime
 await sdk.sessions.revoke(session);
 ```
 
-## Cross-Chain Bridging
+### Gasless Transactions
+
+```typescript
+const sdk = createSDK('base', {
+  relayerUrl: 'https://relayer.veridex.network',
+  relayerApiKey: 'your-api-key',
+});
+
+// Relayer sponsors gas — user pays nothing
+await sdk.transferViaRelayer({
+  token: USDC_ADDRESS,
+  recipient: '0x...',
+  amount: 1000000n,
+});
+```
+
+### Cross-Chain Bridging
 
 ```typescript
 import { parseUnits } from 'ethers';
 
+// Bridge USDC from Base to Optimism via Wormhole
 await sdk.bridge({
   targetChain: 'optimism',
   token: USDC_ADDRESS,
   amount: parseUnits('100', 6),
-  recipient: '0x...', // Optional, defaults to your vault
+  recipient: '0x...', // defaults to your vault
 });
 ```
 
-## API Reference
-
-### Core
+## Chain Clients
 
-| 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
+Each chain has a dedicated client implementing the `ChainClient` interface:
 
 ```typescript
 import { EVMClient } from '@veridex/sdk/chains/evm';
@@ -146,40 +151,93 @@ 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';
+import { StacksClient } from '@veridex/sdk/chains/stacks';
+```
+
+All clients support:
+- `buildTransferPayload()` — Build token transfer payloads
+- `buildExecutePayload()` — Build arbitrary execution payloads
+- `buildBridgePayload()` — Build cross-chain bridge payloads
+- `dispatch()` / `dispatchGasless()` — Submit signed actions
+- `getBalance()` / `getTokenBalance()` — Query balances
+- `createVault()` / `createVaultViaRelayer()` — Vault management
+
+### Stacks-Specific
+
+Stacks has unique capabilities leveraged by the SDK:
+
+```typescript
+import { StacksClient } from '@veridex/sdk/chains/stacks';
+import {
+  compressPublicKey,
+  rsToCompactSignature,
+  parseDERSignature,
+} from '@veridex/sdk/chains/stacks';
+
+// Native secp256r1 verification (no ZK proofs needed)
+// Native sponsored transactions (gasless built-in)
+// Post-conditions for protocol-level spending safety
 ```
 
+## API Reference
+
+### Core Exports
+
+| Export | Description |
+|--------|-------------|
+| `createSDK(chain, config?)` | Create SDK instance for a chain |
+| `VeridexSDK` | Main SDK class |
+| `PasskeyManager` | WebAuthn credential management |
+| `WalletManager` | Deterministic vault address derivation |
+| `SessionManager` | Session key lifecycle management |
+
 ### Utilities
 
 ```typescript
-import { 
+import {
   encodeTransferAction,
+  encodeExecuteAction,
   encodeBridgeAction,
   parseVAA,
   fetchVAA,
+  WORMHOLE_CHAIN_IDS,
+  TESTNET_CHAINS,
+  MAINNET_CHAINS,
 } from '@veridex/sdk';
 ```
 
-### Constants
+### Types
 
 ```typescript
-import { 
-  WORMHOLE_CHAIN_IDS,
-  TESTNET_CHAINS,
-  MAINNET_CHAINS,
+import type {
+  ChainName,
+  ChainClient,
+  ChainConfig,
+  NetworkType,
+  SimpleSDKConfig,
+  TransferParams,
+  ExecuteParams,
+  BridgeParams,
+  SessionKey,
+  WebAuthnSignature,
+  DispatchResult,
+  VaultCreationResult,
 } 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
+- **Passkeys only** — No EOA, no seed phrases, no browser extensions
+- **RIP-7212** — Native P-256 verification (~3,450 gas on EVM)
+- **FCL fallback** — Software verification when precompile unavailable
+- **Wormhole VAA** — 13/19 guardian quorum for cross-chain messages
+- **Custom bridge** — Multi-relayer threshold attestations for Starknet
+- **Replay protection** — Nonce-based action deduplication on all chains
+- **Post-conditions** — Protocol-level spending caps on Stacks
 
 ## Browser Support
 
-WebAuthn requires a secure context (HTTPS) and a compatible browser:
+WebAuthn requires HTTPS and a compatible browser:
 
 | Browser | Minimum Version |
 |---------|-----------------|
@@ -188,20 +246,13 @@ WebAuthn requires a secure context (HTTPS) and a compatible browser:
 | Safari | 14+ |
 | Edge | 18+ |
 
-## TypeScript
-
-Full TypeScript support with comprehensive type definitions:
+## Related Packages
 
-```typescript
-import type {
-  ChainName,
-  NetworkType,
-  SimpleSDKConfig,
-  TransferParams,
-  BridgeParams,
-  SessionKey,
-} from '@veridex/sdk';
-```
+| Package | Description |
+|---------|-------------|
+| [`@veridex/agentic-payments`](https://www.npmjs.com/package/@veridex/agentic-payments) | Agent payment SDK — x402, UCP, ACP, AP2 |
+| `@veridex/relayer` | Transaction relayer for gasless execution |
+| `@veridex/contracts` | Smart contracts (EVM, Solana, Aptos, Sui, Starknet, Stacks) |
 
 ## License
 
@@ -209,7 +260,8 @@ MIT
 
 ## Links
 
-- [Documentation](https://docs.veridex.io)
+- [Documentation](https://docs.veridex.network)
 - [GitHub](https://github.com/Veridex-Protocol/sdk)
+- [npm](https://www.npmjs.com/package/@veridex/sdk)
 - [Discord](https://discord.gg/veridex)
 - [Twitter](https://twitter.com/VeridexProtocol)

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

@@ -1,5 +1,5 @@
 import { Aptos } from '@aptos-labs/ts-sdk';
-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';
+import { f as ChainClient, a as ChainConfig, T as TransferParams, E as ExecuteParams, B as BridgeParams, w as WebAuthnSignature, D as DispatchResult, j as VaultCreationResult } from '../../types-DakHNZIP.mjs';
 
 /**
  * Veridex Protocol SDK - Aptos Chain Client

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

@@ -1,5 +1,5 @@
 import { Aptos } from '@aptos-labs/ts-sdk';
-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';
+import { f as ChainClient, a as ChainConfig, T as TransferParams, E as ExecuteParams, B as BridgeParams, w as WebAuthnSignature, D as DispatchResult, j as VaultCreationResult } from '../../types-DakHNZIP.js';
 
 /**
  * Veridex Protocol SDK - Aptos Chain Client

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

@@ -1,5 +1,5 @@
-export { c as EVMClient, e as EVMClientConfig, E as EVMHubClientAdapter } from '../../index-eadz7SCP.mjs';
+export { E as EVMClient, e as EVMClientConfig, c as EVMHubClientAdapter } from '../../index-Dy29mvBf.mjs';
 import '../../types.mjs';
 import 'ethers';
-import '../../types-ChIsqCiw.mjs';
-import '../../types-FJL7j6gQ.mjs';
+import '../../types-DakHNZIP.mjs';
+import '../../types-DvFRnIBd.mjs';

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

@@ -1,5 +1,5 @@
-export { c as EVMClient, e as EVMClientConfig, E as EVMHubClientAdapter } from '../../index-ruSjoF2m.js';
+export { E as EVMClient, e as EVMClientConfig, c as EVMHubClientAdapter } from '../../index-eXXqodd0.js';
 import '../../types.js';
 import 'ethers';
-import '../../types-ChIsqCiw.js';
-import '../../types-FJL7j6gQ.js';
+import '../../types-DakHNZIP.js';
+import '../../types-DvFRnIBd.js';

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

@@ -1,6 +1,6 @@
 import * as _solana_web3_js from '@solana/web3.js';
 import { Connection, PublicKey } from '@solana/web3.js';
-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';
+import { f as ChainClient, a as ChainConfig, T as TransferParams, E as ExecuteParams, B as BridgeParams, w as WebAuthnSignature, D as DispatchResult, j as VaultCreationResult } from '../../types-DakHNZIP.mjs';
 
 interface SolanaClientConfig {
     wormholeChainId: number;

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

@@ -1,6 +1,6 @@
 import * as _solana_web3_js from '@solana/web3.js';
 import { Connection, PublicKey } from '@solana/web3.js';
-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';
+import { f as ChainClient, a as ChainConfig, T as TransferParams, E as ExecuteParams, B as BridgeParams, w as WebAuthnSignature, D as DispatchResult, j as VaultCreationResult } from '../../types-DakHNZIP.js';
 
 interface SolanaClientConfig {
     wormholeChainId: number;