@agirails/sdk 2.0.1-beta → 2.0.2

package/src/runtime/types/MockState.ts

@@ -0,0 +1,227 @@
+/**
+ * Mock State Type Definitions
+ *
+ * These interfaces define the structure of the persistent mock blockchain state
+ * stored in `.actp/mock-state.json`. This state is shared across CLI commands,
+ * SDK library usage, and Dashboard.
+ *
+ * @module runtime/types/MockState
+ * @see ADR-001 (Mock State Persistence Strategy)
+ * @see MOCK_STATE_MANAGER_SPEC.md
+ */
+
+/**
+ * ACTP Transaction State enum matching the smart contract states.
+ *
+ * State machine:
+ * - INITIATED (0) -> QUOTED (1, optional) -> COMMITTED (2) -> IN_PROGRESS (3, optional)
+ *                 -> DELIVERED (4) -> SETTLED (5)
+ * - Dispute path: DELIVERED -> DISPUTED (6) -> SETTLED
+ * - Cancel path: Any pre-DELIVERED state -> CANCELLED (7)
+ */
+export type TransactionState =
+  | 'INITIATED'
+  | 'QUOTED'
+  | 'COMMITTED'
+  | 'IN_PROGRESS'
+  | 'DELIVERED'
+  | 'SETTLED'
+  | 'DISPUTED'
+  | 'CANCELLED';
+
+/**
+ * Numeric state values matching the smart contract enum.
+ */
+export const TransactionStateValue: Record<TransactionState, number> = {
+  INITIATED: 0,
+  QUOTED: 1,
+  COMMITTED: 2,
+  IN_PROGRESS: 3,
+  DELIVERED: 4,
+  SETTLED: 5,
+  DISPUTED: 6,
+  CANCELLED: 7,
+};
+
+/**
+ * Mock blockchain event recorded during transaction lifecycle.
+ *
+ * Events are stored for debugging and can be queried to simulate
+ * blockchain event subscriptions.
+ */
+export interface MockEvent {
+  /** Event type (e.g., 'TransactionCreated', 'EscrowLinked', 'StateTransitioned') */
+  type: string;
+
+  /** Unix timestamp (seconds) when event was emitted */
+  timestamp: number;
+
+  /** Block number when event was included */
+  blockNumber: number;
+
+  /** Event-specific data payload */
+  data: Record<string, unknown>;
+}
+
+/**
+ * Mock transaction representing an ACTP transaction in the mock blockchain.
+ *
+ * Mirrors the on-chain Transaction struct but stored as JSON for human-readability.
+ * BigNumber values are stored as strings to preserve precision.
+ */
+export interface MockTransaction {
+  /** Unique transaction identifier (bytes32 hex string) */
+  id: string;
+
+  /** Requester's Ethereum address (checksummed) */
+  requester: string;
+
+  /** Provider's Ethereum address (checksummed) */
+  provider: string;
+
+  /** Transaction amount in USDC wei (string for BigNumber precision, 6 decimals) */
+  amount: string;
+
+  /** Current transaction state */
+  state: TransactionState;
+
+  /** Unix timestamp (seconds) when transaction was created */
+  createdAt: number;
+
+  /** Unix timestamp (seconds) when transaction was last updated */
+  updatedAt: number;
+
+  /** Unix timestamp (seconds) deadline for transaction acceptance */
+  deadline: number;
+
+  /** Dispute window duration in seconds */
+  disputeWindow: number;
+
+  /** Unix timestamp (seconds) when transaction was completed (null if not completed) */
+  completedAt: number | null;
+
+  /** Linked escrow ID (null if not linked yet) */
+  escrowId: string | null;
+
+  /** Service description or metadata hash */
+  serviceDescription: string;
+
+  /** Delivery proof hash (null if not delivered) */
+  deliveryProof: string | null;
+
+  /** List of events emitted during transaction lifecycle */
+  events: MockEvent[];
+}
+
+/**
+ * Mock escrow representing funds locked for a transaction.
+ *
+ * In mock mode, escrow is simulated without actual token transfers.
+ */
+export interface MockEscrow {
+  /** Unique escrow identifier */
+  id: string;
+
+  /** Current escrow balance in USDC wei (string for BigNumber precision) */
+  balance: string;
+
+  /** Whether funds are currently locked (cannot be withdrawn) */
+  locked: boolean;
+
+  /** List of transaction IDs using this escrow */
+  transactions: string[];
+
+  /** Unix timestamp (seconds) when escrow was created */
+  createdAt: number;
+}
+
+/**
+ * Mock account representing a user's wallet state.
+ *
+ * Tracks USDC balance for testing without real tokens.
+ */
+export interface MockAccount {
+  /** Ethereum address (checksummed) */
+  address: string;
+
+  /** USDC balance in wei (string for BigNumber precision, 6 decimals) */
+  usdcBalance: string;
+
+  /** Optional label for easier identification in tests */
+  label?: string;
+}
+
+/**
+ * Mock blockchain state simulating chain parameters.
+ *
+ * Allows time manipulation and block progression for testing
+ * deadline-based logic and dispute windows.
+ */
+export interface MockBlockchain {
+  /** Current simulated Unix timestamp (seconds) */
+  currentTime: number;
+
+  /** Current block number */
+  blockNumber: number;
+
+  /** Chain ID (84532 for Base Sepolia, 8453 for Base Mainnet) */
+  chainId: number;
+
+  /** Average block time in seconds (for time progression calculations) */
+  blockTime: number;
+}
+
+/**
+ * Complete mock state persisted to `.actp/mock-state.json`.
+ *
+ * This is the root interface for all mock blockchain state.
+ * Loaded/saved by MockStateManager.
+ */
+export interface MockState {
+  /** State schema version (e.g., "1.0") for migrations */
+  version: string;
+
+  /** Always "mock" for mock mode */
+  mode: 'mock';
+
+  /** Simulated blockchain parameters */
+  blockchain: MockBlockchain;
+
+  /** All mock transactions indexed by transaction ID */
+  transactions: Record<string, MockTransaction>;
+
+  /** All mock escrows indexed by escrow ID */
+  escrows: Record<string, MockEscrow>;
+
+  /** All mock accounts indexed by address */
+  accounts: Record<string, MockAccount>;
+
+  /**
+   * Global event log for all events (optional for backwards compatibility).
+   *
+   * SECURITY FIX (L-4): Events are now persisted to state file for
+   * debugging and audit purposes. This allows event history to survive
+   * across CLI invocations.
+   */
+  events?: MockEvent[];
+}
+
+/**
+ * Default values for creating new mock state.
+ */
+export const MOCK_STATE_DEFAULTS = {
+  /** Current state schema version */
+  VERSION: '1.0',
+
+  /** Default chain ID (Base Sepolia testnet) */
+  CHAIN_ID: 84532,
+
+  /** Default starting block number */
+  INITIAL_BLOCK_NUMBER: 1000,
+
+  /** Default block time in seconds (Base L2 ~2 seconds) */
+  BLOCK_TIME: 2,
+
+  /** Default initial USDC balance for new accounts (10,000 USDC = 10_000_000_000 wei) */
+  DEFAULT_USDC_BALANCE: '10000000000',
+} as const;

package/src/types/agent.ts

@@ -0,0 +1,79 @@
+/**
+ * Agent Registry Types (AIP-7)
+ *
+ * Types for AI agent identity, registration, and reputation
+ */
+
+/**
+ * Service descriptor metadata for an agent
+ */
+export interface ServiceDescriptor {
+  /** keccak256(lowercase(serviceType)) */
+  serviceTypeHash: string;
+  /** Human-readable service type (lowercase, alphanumeric + hyphens) */
+  serviceType: string;
+  /** IPFS/HTTPS URL to JSON Schema for inputData */
+  schemaURI: string;
+  /** Minimum price in USDC base units (6 decimals) */
+  minPrice: bigint;
+  /** Maximum price in USDC base units */
+  maxPrice: bigint;
+  /** Average completion time in seconds */
+  avgCompletionTime: number;
+  /** IPFS CID to full service descriptor JSON */
+  metadataCID: string;
+}
+
+/**
+ * Agent profile stored on-chain
+ */
+export interface AgentProfile {
+  /** Agent's Ethereum address (controller of DID) */
+  agentAddress: string;
+  /** Full DID (e.g., did:ethr:8453:0x...) */
+  did: string;
+  /** HTTPS endpoint or IPFS gateway URL */
+  endpoint: string;
+  /** Supported service type hashes */
+  serviceTypes: string[];
+  /** USDC staked (V1: always 0, V2: slashing for disputes) */
+  stakedAmount: bigint;
+  /** Aggregated reputation (scale: 0-10000, 2 decimals precision) */
+  reputationScore: number;
+  /** Count of completed SETTLED transactions */
+  totalTransactions: number;
+  /** Count of transactions that went to DISPUTED state */
+  disputedTransactions: number;
+  /** Cumulative transaction volume (6 decimals) */
+  totalVolumeUSDC: bigint;
+  /** Block timestamp of registration */
+  registeredAt: number;
+  /** Last profile update timestamp */
+  updatedAt: number;
+  /** Agent is accepting new requests */
+  isActive: boolean;
+}
+
+/**
+ * Parameters for registering a new agent
+ */
+export interface RegisterAgentParams {
+  /** HTTPS endpoint or IPFS gateway URL */
+  endpoint: string;
+  /** List of services the agent provides */
+  serviceDescriptors: ServiceDescriptor[];
+}
+
+/**
+ * Query parameters for finding agents by service
+ */
+export interface QueryAgentsParams {
+  /** Service type hash to search for */
+  serviceTypeHash: string;
+  /** Minimum reputation score (0-10000) */
+  minReputation?: number;
+  /** Skip first N results (for pagination) */
+  offset?: number;
+  /** Maximum number of results to return */
+  limit?: number;
+}

package/src/types/did.ts

@@ -0,0 +1,223 @@
+/**
+ * DID (Decentralized Identity) Types - AIP-7 §2
+ *
+ * Implements W3C DID specification for Ethereum-based identities
+ * using the did:ethr method with ERC-1056 registry
+ */
+
+/**
+ * DID format: did:ethr:<chainId>:<address>
+ * Example: did:ethr:84532:0x742d35cc6634c0532925a3b844bc9e7595f0beb
+ */
+export type DID = string;
+
+/**
+ * W3C DID Document structure
+ * @see https://www.w3.org/TR/did-core/
+ */
+export interface DIDDocument {
+  '@context': string | string[];
+  id: DID;
+  verificationMethod?: VerificationMethod[];
+  authentication?: (string | VerificationMethod)[];
+  assertionMethod?: (string | VerificationMethod)[];
+  keyAgreement?: (string | VerificationMethod)[];
+  capabilityInvocation?: (string | VerificationMethod)[];
+  capabilityDelegation?: (string | VerificationMethod)[];
+  service?: ServiceEndpoint[];
+}
+
+/**
+ * Verification method for cryptographic key
+ */
+export interface VerificationMethod {
+  id: string;
+  type: string;
+  controller: DID;
+  blockchainAccountId?: string; // CAIP-10 format: address@eip155:chainId
+  publicKeyHex?: string;
+  publicKeyBase58?: string;
+  publicKeyMultibase?: string;
+  ethereumAddress?: string;
+  validTo?: number | bigint; // Unix timestamp for delegate validity (ERC-1056)
+}
+
+/**
+ * Service endpoint in DID Document
+ */
+export interface ServiceEndpoint {
+  id: string;
+  type: string;
+  serviceEndpoint: string | string[] | Record<string, unknown>;
+  description?: string;
+}
+
+/**
+ * DID Resolution result
+ */
+export interface DIDResolutionResult {
+  didDocument: DIDDocument | null;
+  didResolutionMetadata: DIDResolutionMetadata;
+  didDocumentMetadata: DIDDocumentMetadata;
+}
+
+/**
+ * DID Resolution metadata
+ */
+export interface DIDResolutionMetadata {
+  contentType?: string;
+  error?: 'invalidDid' | 'notFound' | 'representationNotSupported' | 'unsupportedDidMethod' | string;
+  message?: string;
+}
+
+/**
+ * DID Document metadata
+ */
+export interface DIDDocumentMetadata {
+  created?: string;
+  updated?: string;
+  deactivated?: boolean;
+  versionId?: string;
+  nextUpdate?: string;
+  nextVersionId?: string;
+}
+
+/**
+ * Configuration for DID Resolver
+ */
+export interface DIDResolverConfig {
+  /**
+   * Network to use (base-sepolia or base-mainnet)
+   */
+  network?: string;
+
+  /**
+   * Custom RPC URL (overrides network default)
+   */
+  rpcUrl?: string;
+
+  /**
+   * Custom Identity Registry address (overrides network default)
+   */
+  registryAddress?: string;
+
+  /**
+   * Chain ID (required if not using predefined network)
+   */
+  chainId?: number;
+}
+
+/**
+ * Parsed DID components
+ */
+export interface ParsedDID {
+  method: string; // Always 'ethr' for AGIRAILS
+  chainId: number;
+  address: string; // Lowercase checksummed address
+}
+
+/**
+ * ERC-1056 Identity Changed Event
+ */
+export interface DIDOwnerChangedEvent {
+  identity: string;
+  owner: string;
+  previousChange: bigint;
+}
+
+/**
+ * ERC-1056 Delegate Changed Event
+ */
+export interface DIDDelegateChangedEvent {
+  identity: string;
+  delegateType: string; // bytes32 as hex string
+  delegate: string;
+  validTo: bigint;
+  previousChange: bigint;
+}
+
+/**
+ * ERC-1056 Attribute Changed Event
+ */
+export interface DIDAttributeChangedEvent {
+  identity: string;
+  name: string; // bytes32 as hex string
+  value: Uint8Array;
+  validTo: bigint;
+  previousChange: bigint;
+}
+
+/**
+ * Delegate types for ERC-1056
+ */
+export enum DelegateType {
+  /** Can sign on behalf of identity */
+  SIGNING = 'veriKey',
+
+  /** Can encrypt messages for identity */
+  ENCRYPTION = 'encryptionKey',
+
+  /** Can perform general actions */
+  GENERAL = 'delegate',
+
+  /** Custom delegate type */
+  CUSTOM = 'custom'
+}
+
+/**
+ * Attribute names for ERC-1056
+ */
+export enum AttributeName {
+  /** Service endpoint (e.g., AGIRAILS API endpoint) */
+  SERVICE_ENDPOINT = 'did/svc/AGIRAILSProvider',
+
+  /** Public key for verification */
+  PUBLIC_KEY = 'did/pub/Secp256k1/veriKey',
+
+  /** Encryption public key */
+  ENCRYPTION_KEY = 'did/pub/X25519/enc',
+
+  /** Custom attribute */
+  CUSTOM = 'custom'
+}
+
+/**
+ * Options for DID signature verification
+ */
+export interface VerifySignatureOptions {
+  /** Chain ID to verify against (prevents cross-chain replay) */
+  chainId: number;
+
+  /** Expected DID (optional additional check) */
+  expectedDID?: DID;
+
+  /** Timestamp for delegate validity check */
+  timestamp?: number;
+
+  /**
+   * Use domain separation to prevent cross-protocol replay attacks
+   * Default: true (recommended for security)
+   * Set to false only for backwards compatibility with old signatures
+   */
+  useDomainSeparation?: boolean;
+}
+
+/**
+ * Result of signature verification
+ */
+export interface SignatureVerificationResult {
+  /** Whether signature is valid */
+  valid: boolean;
+
+  /** Recovered signer address */
+  signer?: string;
+
+  /** Error message if verification failed */
+  error?: string;
+
+  /** Whether signer is a delegate (not the owner) */
+  isDelegate?: boolean;
+
+  /** Delegate type if signer is a delegate */
+  delegateType?: string;
+}

package/src/types/escrow.ts

@@ -2,25 +2,26 @@
  * Escrow creation parameters
  */
 export interface CreateEscrowParams {
-  kernelAddress: string;
-  txId: string;
-  token: string;
+  /** Escrow identifier (bytes32). In ACTP standard this is typically the txId. */
+  escrowId: string;
+  /** Consumer/requester who funds the escrow */
+  requester: string;
+  /** Provider who receives payout on settlement */
+  provider: string;
+  /** Amount locked in escrow (USDC wei, 6 decimals) */
   amount: bigint;
-  beneficiary: string;
 }
 
 /**
- * Escrow state
+ * Escrow state (matches on-chain EscrowVault.EscrowData struct)
  */
 export interface Escrow {
   escrowId: string;
-  kernel: string;
-  txId: string;
-  token: string;
+  requester: string;
+  provider: string;
   amount: bigint;
-  beneficiary: string;
-  createdAt: number;
-  released: boolean;
+  releasedAmount: bigint;
+  active: boolean;
 }
 
 

package/src/types/index.ts

@@ -7,4 +7,8 @@ export * from './transaction';
 export * from './escrow';
 export * from './message';
 export * from './eip712';
-
+export * from './agent';
+export * from './did';
+// Note: storage and archive types are not yet implemented in this version
+// export * from './storage';
+// export * from './archive';

package/src/types/state.ts

@@ -17,14 +17,23 @@ export enum State {
 export class StateMachine {
   /**
    * Valid state transitions per Yellow Paper §3.2.2
+   *
+   * SECURITY FIX (CRITICAL-1): State machine must match ACTPKernel contract exactly
+   * Per CLAUDE.md §Architecture Overview - ACTP Protocol State Machine:
+   * - COMMITTED can transition to IN_PROGRESS, DELIVERED, or CANCELLED
+   * - IN_PROGRESS can transition to DELIVERED or CANCELLED (not DISPUTED)
+   * - DISPUTED can only transition to SETTLED (not CANCELLED)
    */
   private static readonly TRANSITIONS: Record<State, State[]> = {
     [State.INITIATED]: [State.QUOTED, State.COMMITTED, State.CANCELLED], // Allow direct INITIATED → COMMITTED (AIP-3)
     [State.QUOTED]: [State.COMMITTED, State.CANCELLED],
-    [State.COMMITTED]: [State.IN_PROGRESS, State.CANCELLED],
-    [State.IN_PROGRESS]: [State.DELIVERED, State.DISPUTED],
+    // SECURITY FIX (CRITICAL-1): Add DELIVERED (can skip IN_PROGRESS)
+    [State.COMMITTED]: [State.IN_PROGRESS, State.DELIVERED, State.CANCELLED],
+    // SECURITY FIX (CRITICAL-1): Remove DISPUTED, add CANCELLED
+    [State.IN_PROGRESS]: [State.DELIVERED, State.CANCELLED],
     [State.DELIVERED]: [State.SETTLED, State.DISPUTED],
-    [State.DISPUTED]: [State.SETTLED, State.CANCELLED],
+    // SECURITY FIX (CRITICAL-1): Remove CANCELLED (disputes resolve to SETTLED only)
+    [State.DISPUTED]: [State.SETTLED],
     [State.SETTLED]: [], // Terminal state
     [State.CANCELLED]: [] // Terminal state
   };

package/src/types/transaction.ts

@@ -11,11 +11,15 @@ export interface Transaction {
   amount: bigint;
   state: State;
   createdAt: number;
+  updatedAt: number;
   deadline: number;
   disputeWindow: number;
   escrowContract: string;
   escrowId: string;
+  serviceHash: string;
+  attestationUID: string;
   metadata: string;
+  platformFeeBpsLocked: number;
 }
 
 /**
@@ -51,4 +55,3 @@ export interface EconomicParams {
   providerPenaltyBps: number;
 }
 
-