Core Concepts

Understanding the fundamental concepts of Veridex will help you build better integrations.

Passkeys (WebAuthn)

Passkeys are a modern authentication standard that replaces passwords with biometrics (FaceID, TouchID) or hardware security keys.

How Passkeys Work

User taps "Connect" → Device prompts for biometric → 
Passkey signs challenge → Signature verified on-chain

Key Properties

• Phishing-resistant: Passkeys are bound to domains
• Cross-device: Sync via iCloud Keychain, Google Password Manager
• Non-exportable: Private key never leaves the device

Cryptography

Veridex uses the P-256 (secp256r1) curve, supported natively by:

• WebAuthn standard
• RIP-7212 precompile on Base/Optimism/Arbitrum
• All modern secure enclaves (TPM, Secure Enclave)

Cross-Domain Passkeys

By default, WebAuthn passkeys are bound to a single domain. A passkey created on app-a.com cannot be used on app-b.com. Veridex solves this with Related Origin Requests (ROR) — a WebAuthn Level 3 standard that allows passkeys to be shared across approved domains.

How It Works

1. All Veridex-integrated apps use veridex.network as the canonical Relying Party ID (rpId).
2. A .well-known/webauthn file at veridex.network lists all approved origins.
3. When a user visits a third-party app, the browser checks the whitelist and allows the passkey if the origin is listed.
4. For browsers without ROR support, the SDK falls back to an Auth Portal at auth.veridex.network (popup or redirect).

Key Points for Developers

• Register your origin at developers.veridex.network (opens in a new tab) before integrating.
• Use createCrossOriginAuth() from the SDK — it handles ROR detection and fallback automatically.
• Create server-side session tokens via the relayer for backend-verifiable sessions.
• HTTPS is required — WebAuthn does not work on insecure origins (except localhost).
• Chrome limits .well-known/webauthn to 5 unique eTLD+1 labels. Origins beyond this limit use the Auth Portal fallback seamlessly.

See the Cross-Domain Passkeys Guide for full integration instructions.

Hub and Spoke Architecture

Veridex uses a hub-and-spoke model for cross-chain operations.

Hub (Base)

• Stores passkey credentials (public key, credential ID)
• Verifies WebAuthn signatures (P-256)
• Emits cross-chain authorization messages
• Single source of truth for identity
• Also functions as a Spoke — can hold funds and execute transactions directly (no cross-chain hop needed for Base operations)

Spokes (All Chains)

• Hold user assets in deterministic vaults
• Execute actions upon receiving Hub authorization via Wormhole (or direct relay for Stacks)
• Support native token + ERC20/SPL/SIP-010 transfers

Deterministic Vaults

Each passkey generates a deterministic vault address that's the same across all EVM chains.

How It Works

vaultAddress = CREATE2(
  factory,
  keccak256(publicKeyX, publicKeyY),
  vaultBytecode
)

Benefits

• Single address: Share one address for all EVM chains
• No deployment needed: Address is known before vault exists
• Counterfactual: Can receive funds before vault is deployed

Non-EVM Chains

For Solana, Aptos, Sui, Starknet, and Stacks, vault addresses are derived using chain-specific methods but still deterministic from the passkey.

Stacks is unique because Clarity natively supports secp256r1-verify for passkey signatures — no ZK proofs or precompiles needed.

Session Keys

Session keys enable smooth UX by delegating limited authority to a temporary key.

Why Session Keys?

Without session keys:

Action 1 → Biometric prompt
Action 2 → Biometric prompt
Action 3 → Biometric prompt

With session keys:

Create session → Biometric prompt (once)
Action 1 → Auto-signed
Action 2 → Auto-signed
Action 3 → Auto-signed

Session Constraints

Sessions can be limited by:

Core SDK Session Example

import { SessionManager, generateSecp256k1KeyPair, computeSessionKeyHash } from '@veridex/sdk';
 
// Generate a session key pair
const keyPair = generateSecp256k1KeyPair();
const sessionHash = computeSessionKeyHash(keyPair.publicKey);
 
// SessionManager handles lifecycle
const sessionManager = new SessionManager({ /* hub client config */ });

Agent SDK Session Example

The Agent SDK provides a higher-level SessionKeyManager with USD-denominated spending limits:

import { createAgentWallet } from '@veridex/agentic-payments';
 
const agent = await createAgentWallet({
  masterCredential: { /* passkey credential */ },
  session: {
    dailyLimitUSD: 50,           // $50/day budget
    perTransactionLimitUSD: 10,  // $10 max per tx
    expiryHours: 24,             // 24-hour session
    allowedChains: [10004],      // Base Sepolia only
  },
});
 
// Agent uses session key automatically for payments
await agent.pay({ chain: 10004, token: 'USDC', amount: '1000000', recipient: '0x...' });

Cross-Chain Messaging

Veridex uses Wormhole for secure cross-chain communication.

Message Flow

1. Hub signs action → WebAuthn signature verified
2. Wormhole guardians attest → 13/19 signatures required
3. Spoke verifies VAA → Executes authorized action

Verification Paths

The relayer automatically chooses the optimal path based on transaction value.

Wallet Backup & Recovery

Passkeys live in your device's secure enclave. If you lose all your devices, you need a way to recover access. Veridex provides encrypted credential backup via the relayer.

How Backup Works

┌─────────────┐                    ┌─────────────┐
│ Your Device  │                    │   Relayer    │
│              │                    │   (Cloud)    │
│  Credentials ├── PRF encrypt ───▶│  Encrypted   │
│  (keyHash,   │                    │    Blob      │
│   credId)    │                    │  (can't read │
│              │                    │   contents)  │
└─────────────┘                    └─────────────┘

1. Your passkey generates a PRF seed — a deterministic secret only your authenticator can produce.
2. The SDK derives an AES-256-GCM encryption key from that seed.
3. All credential metadata is encrypted and uploaded to the Veridex relayer.
4. On recovery, the same passkey (or a synced copy) regenerates the PRF seed and decrypts the archive.

PRF (Pseudo-Random Function)

PRF is a WebAuthn extension that lets an authenticator produce a deterministic secret for a given input. Key properties:

• Deterministic: Same passkey + same salt = same secret, every time
• Non-exportable: The secret is generated inside the secure enclave
• Domain-bound: Different RP IDs produce different outputs

PRF is supported in Chrome 116+, Safari 17+, and Edge 116+. On browsers without PRF, the SDK falls back to a credential-ID-based key — functional but less secure.

Recovery Scenarios

Key Points

• The relayer cannot read your backup — it only stores an encrypted blob.
• Passkeys typically sync within your platform ecosystem (Apple → Apple, Google → Google).
• For cross-ecosystem backup (iPhone → Windows PC), use the Add Device flow.
• Back up after adding new devices or registering new passkeys.

See the Wallet Backup & Recovery Guide for step-by-step instructions.

Gasless Transactions

Users never need to hold gas tokens — the relayer pays gas fees.

How It Works

Fee Model

• User pays: Token amount only
• Relayer pays: Gas fees
• Relayer recovers: Via protocol fee or sponsorship

Security Model

Trust Assumptions

Attack Resistance

• Replay attacks: Nonces prevent replay
• Cross-chain replay: Chain ID in signature
• Signature malleability: Canonical encoding enforced
• Phishing: Passkeys are domain-bound

Agent SDK Concepts

The Agent SDK (@veridex/agentic-payments) extends the core SDK for autonomous AI agent operations, including payments, on-chain identity, reputation, and multi-protocol support.

AgentWallet

The central orchestration class that manages session keys, payments, on-chain identity (ERC-8004), reputation, trust gates, agent discovery, and audit logging.

import { createAgentWallet } from '@veridex/agentic-payments';
 
const agent = await createAgentWallet({
  masterCredential: { /* passkey credential */ },
  session: { dailyLimitUSD: 50, perTransactionLimitUSD: 10, expiryHours: 24 },
  erc8004: { enabled: true, testnet: true, minReputationScore: 30 },
});

Protocol Abstraction Layer

The SDK supports multiple payment protocols with automatic detection. When agent.fetch() encounters a paywall, it auto-detects the protocol and handles payment:

ERC-8004 On-Chain Identity

The ERC-8004 (opens in a new tab) standard provides on-chain identity for AI agents via three singleton registries deployed on every EVM chain:

When an agent registers, it receives an ERC-721 NFT that represents its on-chain identity. The NFT's tokenURI points to a registration file containing the agent's name, description, services, and capabilities.

// Register an agent on-chain
const { agentId, agentURI } = await agent.register({
  name: 'Sentiment Analyzer',
  description: 'NLP-powered sentiment analysis',
  services: [{ name: 'analyze', endpoint: 'https://my-agent.com/analyze' }],
});

Reputation & Trust Gates

After every payment, the SDK can automatically submit reputation feedback to the ERC-8004 Reputation Registry. Before paying a merchant, the SDK can check their reputation score:

// Check merchant reputation before paying
const trust = await agent.checkMerchantTrust('https://data-provider.com');
// trust.score: 0-100, trust.trusted: boolean
 
// Get detailed reputation
const summary = await agent.getReputation(agentId);
// summary.feedbackCount, summary.normalizedScore, summary.tags

The TrustGate enforces minimum reputation thresholds:

• If minReputationScore is set, agent.fetch() will reject merchants below that score
• trustedReviewers can filter which feedback counts toward the score

Agent Discovery

Agents can discover other agents on-chain by capability, chain, or reputation:

// Find sentiment analysis agents
const agents = await agent.discover({ category: 'sentiment' });
 
// Resolve an agent from a URL, UAI, or address
const resolved = await agent.resolveAgent('https://my-agent.com');

The AgentDiscovery client supports resolution from:

• UAI (Universal Agent Identifier) — CAIP-2 extended format
• Endpoint URL — via /.well-known/agent-registration.json
• Chain address — reverse lookup on Identity Registry
• Search — by name, category, or tags

Registration File Management

The RegistrationFileManager builds, validates, and publishes ERC-8004 registration files:

import { RegistrationFileManager } from '@veridex/agentic-payments';
 
// Build a registration file
const file = RegistrationFileManager.buildRegistrationFile({
  name: 'My Agent',
  description: 'Does cool things',
  services: [{ name: 'api', endpoint: 'https://my-agent.com/api' }],
});
 
// Validate against ERC-8004 schema
const { valid, errors } = RegistrationFileManager.validate(file);
 
// Publish to IPFS or encode as data URI
const dataURI = RegistrationFileManager.buildDataURI(file);

Modular Identity Clients

The identity module is composed of independent, chain-agnostic clients:

Spending Limits (Three Layers)

Veridex enforces spending limits at three levels:

MCP Tools

The Agent SDK provides Model Context Protocol (MCP) tools for integration with AI assistants like Claude and Cursor:

const agent = await createAgentWallet({
  // ...
  mcp: { enabled: true },
});
 
const tools = agent.getMCPTools();
// Tools: check_balance, send_payment, get_session_status, discover_agents, get_reputation, etc.

Pyth Oracle

Real-time price feeds for USD-denominated spending limits:

import { PythOracle } from '@veridex/agentic-payments';
 
const oracle = new PythOracle();
const ethPrice = await oracle.getPrice('ETH');
const stxPrice = await oracle.getPrice('STX');

Veridex Agent Fabric Concepts

The newer framework layer extends Veridex beyond commerce-specific agents into broader agentic software.

Core idea

@veridex/agents is designed to work for:

• ordinary assistants
• workflow automation
• multi-agent systems
• agents that later need payments, approvals, or stronger enterprise controls

Payments are optional. Governance-ready runtime primitives are not.

Core runtime primitives

The framework is organized around:

• AgentDefinition
• Run
• Turn
• ToolContract
• RuntimeHook
• MemoryStore
• ContextPlan
• CheckpointStore
• transports for MCP, ACP, and A2A

Companion packages

Why it matters

This lets teams start with a normal agent and then add:

• passkey identity
• payment capabilities
• approvals
• policy packs
• audit-ready trace retention
• external runtime interop

without changing framework families later.

Next Steps