@agirails/sdk 2.0.0 → 2.0.1-beta

package/README.md

@@ -1,182 +1,174 @@
 # @agirails/sdk
 
-TypeScript SDK for the **ACTP (Agent Commerce Transaction Protocol)** - enabling AI agents to transact, escrow funds, and settle payments autonomously.
+Protocol SDK for ACTP (Agent Commerce Transaction Protocol)
 
 ## Installation
 
 ```bash
 npm install @agirails/sdk
+# or
+yarn add @agirails/sdk
 ```
 
 ## Quick Start
 
-### Simple API (Beginner)
-
 ```typescript
-import { ACTPClient } from '@agirails/sdk';
+import { ACTPClient, State } from '@agirails/sdk';
+import { ethers } from 'ethers';
 
+// Initialize client (async factory pattern ensures EIP-712 domain is ready)
 const client = await ACTPClient.create({
   network: 'base-sepolia',
   privateKey: process.env.PRIVATE_KEY
 });
 
-// One-liner: pay an AI agent for a service
-const result = await client.beginner.pay({
+// Create transaction
+const txId = await client.kernel.createTransaction({
   provider: '0xProviderAddress...',
-  amount: '10.00',  // 10 USDC
-  service: 'echo'
+  requester: await client.getAddress(),
+  amount: ethers.utils.parseUnits('100', 6), // 100 USDC
+  deadline: Math.floor(Date.now() / 1000) + 86400, // 24 hours
+  disputeWindow: 3600 // 1 hour
 });
 
-console.log('Transaction ID:', result.txId);
-console.log('Status:', result.status);
-```
-
-### Standard API (Intermediate)
-
-```typescript
-import { ACTPClient } from '@agirails/sdk';
+console.log(`Transaction created: ${txId}`);
 
-const client = await ACTPClient.create({
-  network: 'base-sepolia',
-  privateKey: process.env.PRIVATE_KEY
+// Watch transaction
+client.events.watchTransaction(txId, (state) => {
+  console.log(`State changed to: ${State[state]}`);
 });
 
-// 1. Create transaction
-const txId = await client.intermediate.createTransaction({
-  provider: '0xProviderAddress...',
-  amount: '10.00',
-  serviceRef: 'ipfs://Qm...'
-});
+// Get transaction
+const tx = await client.kernel.getTransaction(txId);
+console.log('Transaction:', tx);
+```
 
-// 2. Link escrow (funds locked, state → COMMITTED)
-await client.intermediate.linkEscrow(txId);
+## Features
 
-// 3. Provider delivers (after work is done)
-await client.intermediate.transitionState(txId, 'DELIVERED');
+- ✅ **Protocol SDK** - Direct blockchain interaction with ACTP Kernel
+- ✅ **State Machine** - Full ACTP state validation (8 states)
+- ✅ **Event Monitoring** - Real-time blockchain event listening
+- ✅ **Message Signing** - Cryptographic signing per Yellow Paper §11.4
+- ✅ **Proof Generation** - Content hashing & delivery proofs
+- ✅ **TypeScript** - Full type safety
+- ✅ **Base L2** - Optimized for Base Sepolia & Mainnet
 
-// 4. Release payment to provider
-await client.intermediate.releaseEscrow(txId);
-```
+## V1 Limitations
 
-### Check Transaction Status
+⚠️ **Important**: ACTP SDK v2.0.0-beta is designed for **Base Sepolia testnet** and controlled partner usage. The following limitations apply:
 
-```typescript
-const status = await client.beginner.checkStatus(txId);
-console.log(status.state);     // 'COMMITTED', 'DELIVERED', 'SETTLED', etc.
-console.log(status.amount);    // '10.00'
-console.log(status.provider);  // '0x...'
-```
+### 1. Attestation Validation is SDK-Enforced, Not Protocol-Enforced
 
-## CLI Usage
+The V1 ACTPKernel accepts attestation UIDs without on-chain validation. All verification (existence, schema, txId, revocation, expiry) is performed by SDK helpers like `releaseEscrowWithVerification()`.
 
-```bash
-# Install globally
-npm install -g @agirails/sdk
+**Security checks performed by SDK:**
+- Attestation exists and UID matches
+- Schema UID matches canonical delivery schema (`0x1b0e...ffce`)
+- txId in attestation matches expected transaction
+- Attestation is not revoked (`revocationTime === 0`)
+- Attestation has not expired
 
-# Initialize configuration
-actp init
+**Integrators who bypass the SDK must implement equivalent verification logic.**
 
-# Create a transaction
-actp create --provider 0x... --amount 10 --service "echo service"
+### 2. Multiple Attestations Per Transaction Are Possible
 
-# Check transaction status
-actp status <txId>
+EAS does not enforce uniqueness - multiple attestations can exist for the same `txId`. The SDK uses the **first valid (non-revoked) attestation** provided. This policy is testnet-appropriate; V2 will enforce uniqueness at the protocol level.
 
-# List your transactions
-actp list
-```
+### 3. This SDK is Not For Unrestricted Mainnet Usage
 
-## Mock Mode (Testing)
+V2 will move critical verification on-chain. Until then, use only on Base Sepolia testnet with testnet USDC.
 
-Test without blockchain - no gas fees, instant transactions:
+### Additional Limitations
 
-```typescript
-import { ACTPClient } from '@agirails/sdk';
+| Area | Limitation | Workaround |
+|------|------------|------------|
+| Network Resilience | No automatic retry | Manual retry required |
+| Timeout Handling | `tx.wait()` may hang | Set custom timeout |
+| State Transitions | TOCTOU race condition | Contract provides final validation |
+| Revocation Window | Attestation can be revoked between verify and settle | Use `releaseEscrowWithVerification()` |
 
-const client = await ACTPClient.create({
-  mode: 'mock'
-});
+For detailed documentation, visit the [GitHub repository](https://github.com/agirails/sdk-js).
 
-// Full ACTP flow works identically
-const result = await client.beginner.pay({
-  provider: '0x1234...',
-  amount: '5.00',
-  service: 'test-service'
-});
-```
+**V2.0 Planned**: On-chain attestation validation, uniqueness enforcement, multi-provider fallback
 
-## Networks
+---
 
-| Network | Chain ID | Status |
-|---------|----------|--------|
-| Base Sepolia | 84532 | ✅ Active (Testnet) |
-| Base Mainnet | 8453 | ⏳ Not Deployed |
+## Network Support
 
-> **Note**: Mainnet contracts are not yet deployed. Using `network: 'base-mainnet'` will throw an error. Use `'base-sepolia'` for development and testing.
+- **Base Sepolia** (testnet) - `chainId: 84532`
+- **Base Mainnet** - `chainId: 8453`
 
-## Transaction States
+## Documentation
 
-```
-INITIATED → QUOTED → COMMITTED → IN_PROGRESS → DELIVERED → SETTLED
-                                      ↓
-                                  DISPUTED → SETTLED
-```
+For full documentation, examples, and specifications, visit the [GitHub repository](https://github.com/agirails/sdk-js).
 
-## API Layers
+## Development
 
-### Beginner (Simple)
+```bash
+# Install dependencies
+npm install
 
-```typescript
-client.beginner.pay(params)         // Create, fund, and track in one call
-client.beginner.checkStatus(txId)   // Get human-readable status
-```
+# Build
+npm run build
 
-### Intermediate (Standard)
+# Unit tests (Jest - fast, no network)
+npm test
 
-```typescript
-client.intermediate.createTransaction(params)  // Create transaction
-client.intermediate.linkEscrow(txId)           // Lock funds in escrow
-client.intermediate.transitionState(txId, state)  // Change state
-client.intermediate.releaseEscrow(txId)        // Release funds to provider
-client.intermediate.getTransaction(txId)       // Get transaction details
-client.intermediate.getEscrowBalance(escrowId) // Check locked amount
+# Integration tests (Hardhat - requires Base Sepolia RPC)
+npm run test:integration
+
+# Lint
+npm run lint
 ```
 
-### Runtime (Low-Level)
+### Integration Testing
 
-```typescript
-client.runtime  // Direct access to BlockchainRuntime or MockRuntime
-```
+Integration tests run against **deployed contracts** on Base Sepolia testnet:
 
-## Environment Variables
+**Prerequisites:**
+1. Create `.env` file:
+   ```bash
+   BASE_SEPOLIA_RPC=https://sepolia.base.org  # or your Alchemy URL
+   PRIVATE_KEY=0x...  # Account with Base Sepolia ETH for gas
+   ```
 
-```bash
-# Required for blockchain mode
-PRIVATE_KEY=0x...
-BASE_SEPOLIA_RPC=https://...
+2. Get testnet ETH:
+   - [Base Sepolia Faucet](https://www.coinbase.com/faucets/base-ethereum-goerli-faucet)
 
-# Optional
-IPFS_GATEWAY=https://...
+**Run tests:**
+```bash
+npx hardhat test --network base-sepolia
 ```
 
-## Fee Structure
+Tests will:
+- ✅ Connect to deployed ACTPKernel, EscrowVault, MockUSDC
+- ✅ Mint test USDC (MockUSDC has open minting on testnet)
+- ✅ Run full transaction lifecycle (INITIATED → SETTLED)
+- ✅ Verify escrow release and fund transfers
 
-- **Platform Fee**: 1% of transaction amount
-- **Minimum Fee**: $0.05 USDC
+## Contract Addresses
 
-## Security
+### Base Sepolia (Testnet) ✅ Deployed & Verified
+- **ACTPKernel:** `0x6aDB650e185b0ee77981AC5279271f0Fa6CFe7ba` ([view](https://sepolia.basescan.org/address/0x6aDB650e185b0ee77981AC5279271f0Fa6CFe7ba#code))
+- **EscrowVault:** `0x921edE340770db5DB6059B5B866be987d1b7311F` ([view](https://sepolia.basescan.org/address/0x921edE340770db5DB6059B5B866be987d1b7311F#code))
+- **MockUSDC:** `0x444b4e1A65949AB2ac75979D5d0166Eb7A248Ccb` ([view](https://sepolia.basescan.org/address/0x444b4e1A65949AB2ac75979D5d0166Eb7A248Ccb#code))
+- **EAS Contract:** `0x4200000000000000000000000000000000000021` (Base native)
+- **EAS Schema Registry:** `0x4200000000000000000000000000000000000020` (Base native)
+- **Delivery Schema UID:** `0x1b0ebdf0bd20c28ec9d5362571ce8715a55f46e81c3de2f9b0d8e1b95fb5ffce`
 
-- Non-custodial escrow (2-of-2 release)
-- EIP-712 typed message signing
-- EAS (Ethereum Attestation Service) for delivery proofs
-- Replay protection with nonce management
+*Redeployed: 2025-11-25 | Fixed auto-transition in linkEscrow, optimizer-runs 200 | Matches src/config/networks.ts*
 
-## Links
-
-- [Documentation](https://docs.agirails.io)
-- [GitHub](https://github.com/agirails/sdk)
-- [Discord](https://discord.gg/agirails)
+### Base Mainnet (Production)
+- **ACTPKernel:** TBD *(pending mainnet deployment)*
+- **EscrowVault:** TBD *(pending mainnet deployment)*
+- **USDC:** `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913` (official USDC on Base)
 
 ## License
 
 Apache-2.0
+
+## Support
+
+- **Email:** developers@agirails.io
+- **GitHub:** [github.com/agirails/sdk-js](https://github.com/agirails/sdk-js)
+