@agirails/sdk 2.0.0-beta → 2.0.0

package/LICENSE

@@ -0,0 +1,190 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to the Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2024-2025 AGIRAILS Inc.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,183 +1,182 @@
 # @agirails/sdk
 
-Protocol SDK for ACTP (Agent Commerce Transaction Protocol)
+TypeScript SDK for the **ACTP (Agent Commerce Transaction Protocol)** - enabling AI agents to transact, escrow funds, and settle payments autonomously.
 
 ## Installation
 
 ```bash
 npm install @agirails/sdk
-# or
-yarn add @agirails/sdk
 ```
 
 ## Quick Start
 
+### Simple API (Beginner)
+
 ```typescript
-import { ACTPClient, State } from '@agirails/sdk';
-import { ethers } from 'ethers';
+import { ACTPClient } from '@agirails/sdk';
 
-// Initialize client (async factory pattern ensures EIP-712 domain is ready)
 const client = await ACTPClient.create({
   network: 'base-sepolia',
   privateKey: process.env.PRIVATE_KEY
 });
 
-// Create transaction
-const txId = await client.kernel.createTransaction({
+// One-liner: pay an AI agent for a service
+const result = await client.beginner.pay({
   provider: '0xProviderAddress...',
-  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
+  amount: '10.00',  // 10 USDC
+  service: 'echo'
 });
 
-console.log(`Transaction created: ${txId}`);
-
-// Watch transaction
-client.events.watchTransaction(txId, (state) => {
-  console.log(`State changed to: ${State[state]}`);
-});
-
-// Get transaction
-const tx = await client.kernel.getTransaction(txId);
-console.log('Transaction:', tx);
+console.log('Transaction ID:', result.txId);
+console.log('Status:', result.status);
 ```
 
-## Features
+### Standard API (Intermediate)
 
-- ✅ **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
+```typescript
+import { ACTPClient } from '@agirails/sdk';
 
-## V1 Limitations
+const client = await ACTPClient.create({
+  network: 'base-sepolia',
+  privateKey: process.env.PRIVATE_KEY
+});
 
-⚠️ **Important**: ACTP SDK v2.0.0-beta is designed for **Base Sepolia testnet** and controlled partner usage. The following limitations apply:
+// 1. Create transaction
+const txId = await client.intermediate.createTransaction({
+  provider: '0xProviderAddress...',
+  amount: '10.00',
+  serviceRef: 'ipfs://Qm...'
+});
 
-### 1. Attestation Validation is SDK-Enforced, Not Protocol-Enforced
+// 2. Link escrow (funds locked, state → COMMITTED)
+await client.intermediate.linkEscrow(txId);
 
-The V1 ACTPKernel accepts attestation UIDs without on-chain validation. All verification (existence, schema, txId, revocation, expiry) is performed by SDK helpers like `releaseEscrowWithVerification()`.
+// 3. Provider delivers (after work is done)
+await client.intermediate.transitionState(txId, 'DELIVERED');
 
-**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
+// 4. Release payment to provider
+await client.intermediate.releaseEscrow(txId);
+```
 
-**Integrators who bypass the SDK must implement equivalent verification logic.**
+### Check Transaction Status
 
-### 2. Multiple Attestations Per Transaction Are Possible
+```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...'
+```
 
-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.
+## CLI Usage
 
-### 3. This SDK is Not For Unrestricted Mainnet Usage
+```bash
+# Install globally
+npm install -g @agirails/sdk
 
-V2 will move critical verification on-chain. Until then, use only on Base Sepolia testnet with testnet USDC.
+# Initialize configuration
+actp init
 
-### Additional Limitations
+# Create a transaction
+actp create --provider 0x... --amount 10 --service "echo service"
 
-| 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()` |
+# Check transaction status
+actp status <txId>
 
-See **[KNOWN_LIMITATIONS.md](./KNOWN_LIMITATIONS.md)** for detailed explanations and roadmap.
+# List your transactions
+actp list
+```
 
-For full details, see the [EAS V1 Scope Governance Document](../../Docs/Governance/).
+## Mock Mode (Testing)
 
-**V2.0 Planned**: On-chain attestation validation, uniqueness enforcement, multi-provider fallback
+Test without blockchain - no gas fees, instant transactions:
 
----
+```typescript
+import { ACTPClient } from '@agirails/sdk';
 
-## Network Support
+const client = await ACTPClient.create({
+  mode: 'mock'
+});
 
-- **Base Sepolia** (testnet) - `chainId: 84532`
-- **Base Mainnet** - `chainId: 8453`
+// Full ACTP flow works identically
+const result = await client.beginner.pay({
+  provider: '0x1234...',
+  amount: '5.00',
+  service: 'test-service'
+});
+```
 
-## Documentation
+## Networks
 
-- [SDK Specification](./sdk-specification.md)
-- [Yellow Paper](../../Docs/99. Final Public Papers/Core/AGIRAILS_Yellow_Paper.md)
-- [Examples](./examples/) *(coming soon)*
+| Network | Chain ID | Status |
+|---------|----------|--------|
+| Base Sepolia | 84532 | ✅ Active (Testnet) |
+| Base Mainnet | 8453 | ⏳ Not Deployed |
 
-## Development
+> **Note**: Mainnet contracts are not yet deployed. Using `network: 'base-mainnet'` will throw an error. Use `'base-sepolia'` for development and testing.
 
-```bash
-# Install dependencies
-npm install
+## Transaction States
 
-# Build
-npm run build
+```
+INITIATED → QUOTED → COMMITTED → IN_PROGRESS → DELIVERED → SETTLED
+                                      ↓
+                                  DISPUTED → SETTLED
+```
 
-# Unit tests (Jest - fast, no network)
-npm test
+## API Layers
 
-# Integration tests (Hardhat - requires Base Sepolia RPC)
-npm run test:integration
+### Beginner (Simple)
 
-# Lint
-npm run lint
+```typescript
+client.beginner.pay(params)         // Create, fund, and track in one call
+client.beginner.checkStatus(txId)   // Get human-readable status
 ```
 
-### Integration Testing
-
-Integration tests run against **deployed contracts** on Base Sepolia testnet:
+### Intermediate (Standard)
 
-**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
-   ```
+```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
+```
 
-2. Get testnet ETH:
-   - [Base Sepolia Faucet](https://www.coinbase.com/faucets/base-ethereum-goerli-faucet)
+### Runtime (Low-Level)
 
-**Run tests:**
-```bash
-npx hardhat test --network base-sepolia
+```typescript
+client.runtime  // Direct access to BlockchainRuntime or MockRuntime
 ```
 
-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
+## Environment Variables
 
-## Contract Addresses
+```bash
+# Required for blockchain mode
+PRIVATE_KEY=0x...
+BASE_SEPOLIA_RPC=https://...
 
-### 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`
+# Optional
+IPFS_GATEWAY=https://...
+```
 
-*Redeployed: 2025-11-25 | Fixed auto-transition in linkEscrow, optimizer-runs 200 | Matches src/config/networks.ts*
+## Fee Structure
 
-### Base Mainnet (Production)
-- **ACTPKernel:** TBD *(pending mainnet deployment)*
-- **EscrowVault:** TBD *(pending mainnet deployment)*
-- **USDC:** `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913` (official USDC on Base)
+- **Platform Fee**: 1% of transaction amount
+- **Minimum Fee**: $0.05 USDC
 
-## License
+## Security
 
-Apache-2.0
-
-## Contributing
+- Non-custodial escrow (2-of-2 release)
+- EIP-712 typed message signing
+- EAS (Ethereum Attestation Service) for delivery proofs
+- Replay protection with nonce management
 
-See [CONTRIBUTING.md](./CONTRIBUTING.md) *(coming soon)*
+## Links
 
-## Support
+- [Documentation](https://docs.agirails.io)
+- [GitHub](https://github.com/agirails/sdk)
+- [Discord](https://discord.gg/agirails)
 
-- **Email:** developers@agirails.io
-- **GitHub:** [github.com/agirails/actp-sdk-typescript](https://github.com/agirails/actp-sdk-typescript)
-- **Discord:** [discord.gg/agirails](https://discord.gg/agirails)
+## License
 
+Apache-2.0

package/bin/actp

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+
+/**
+ * ACTP CLI Binary Entry Point
+ *
+ * This file is the executable entry point for the `actp` command.
+ * It loads the compiled TypeScript from dist/cli/index.js
+ */
+
+require('../dist/cli/index.js');