@agether/sdk 1.0.0

package/README.md

@@ -0,0 +1,480 @@
+# @agether/sdk
+
+> TypeScript SDK for Agether — autonomous credit for AI agents on Ethereum.
+
+## Installation
+
+```bash
+npm install @agether/sdk
+# or
+yarn add @agether/sdk
+```
+
+---
+
+## 📦 SDK Overview
+
+| Client | Purpose |
+|--------|---------|
+| **AgetherClient** | Main client for AI agents — apply, draw, repay credit |
+| **VaultClient** | LP operations — deposit, withdraw, check yields |
+| **ScoringClient** | Risk checks and scoring service integration |
+| **AgentIdentityClient** | ERC-8004 identity via ag0 integration |
+
+---
+
+## 🚀 Quick Start
+
+### For AI Agents
+
+```typescript
+import { AgetherClient, ChainId, parseUnits } from '@agether/sdk';
+
+// Initialize client
+const client = AgetherClient.fromPrivateKey(
+  process.env.AGENT_PRIVATE_KEY!,
+  BigInt(123), // Your ERC-8004 agent ID
+  {
+    chainId: ChainId.Ethereum,
+    rpcUrl: 'https://eth.llamarpc.com',
+    contracts: {
+      creditRegistry: '0x...',
+      creditVault: '0x...',
+    },
+    scoringEndpoint: 'https://scoring.agether.ai/v1',
+  }
+);
+
+// Apply for credit
+const creditLineId = await client.apply({
+  agentId: BigInt(123),
+  requestedLimit: parseUnits('1000', 6), // $1,000 USDC
+});
+
+// Scoring service will approve/reject automatically
+// Wait for approval event or poll status...
+
+// Draw funds
+const result = await client.draw({
+  creditLineId,
+  amount: parseUnits('50', 6), // $50 USDC
+  recipient: '0x...', // Service address
+});
+
+console.log('Draw TX:', result.txHash);
+
+// Check balance
+const available = await client.getAvailableCredit();
+console.log('Available:', available);
+
+// Repay
+await client.repay({
+  creditLineId,
+  amount: parseUnits('52', 6), // $52 (principal + interest)
+});
+```
+
+### For Liquidity Providers
+
+```typescript
+import { VaultClient, ChainId, parseUnits, formatUnits } from '@agether/sdk';
+
+const vault = new VaultClient({
+  config: {
+    chainId: ChainId.Ethereum,
+    rpcUrl: 'https://eth.llamarpc.com',
+    contracts: { creditVault: '0x...' },
+  },
+  signer: yourSigner,
+});
+
+// Deposit USDC
+await vault.deposit(parseUnits('10000', 6)); // $10,000
+
+// Check position
+const position = await vault.getPosition();
+console.log('Shares:', position.shares);
+console.log('Value:', formatUnits(position.assets, 6), 'USDC');
+
+// Get vault stats
+const stats = await vault.getStats();
+console.log('Utilization:', stats.utilizationRate, '%');
+
+// Withdraw
+await vault.withdraw(parseUnits('5000', 6));
+```
+
+---
+
+## 📚 API Reference
+
+### AgetherClient
+
+Main client for AI agents to manage credit lines.
+
+#### Constructor
+
+```typescript
+// From private key
+const client = AgetherClient.fromPrivateKey(privateKey, agentId, config);
+
+// From signer (ethers.js or viem)
+const client = new AgetherClient({ config, signer, agentId });
+```
+
+#### Methods
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `apply(application)` | `Promise<bigint>` | Apply for a credit line |
+| `getCreditLine(id?)` | `Promise<CreditLine>` | Get credit line details |
+| `getAvailableCredit()` | `Promise<bigint>` | Get available credit |
+| `getTotalDebt()` | `Promise<bigint>` | Get total debt (principal + interest) |
+| `draw(request)` | `Promise<DrawResult>` | Draw funds from credit line |
+| `repay(request)` | `Promise<RepayResult>` | Repay credit line |
+| `repayFull()` | `Promise<RepayResult>` | Repay entire debt |
+| `isHealthy()` | `Promise<boolean>` | Check if position is healthy |
+| `getStatus()` | `Promise<CreditStatus>` | Get credit line status |
+
+---
+
+### VaultClient
+
+Client for liquidity providers.
+
+#### Methods
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `deposit(amount)` | `Promise<DepositResult>` | Deposit USDC to vault |
+| `withdraw(amount)` | `Promise<WithdrawResult>` | Withdraw USDC from vault |
+| `redeem(shares)` | `Promise<WithdrawResult>` | Redeem shares for USDC |
+| `getStats()` | `Promise<VaultStats>` | Get vault statistics |
+| `getPosition(address?)` | `Promise<LPPosition>` | Get LP position |
+| `maxDeposit()` | `Promise<bigint>` | Max depositable amount |
+| `maxWithdraw()` | `Promise<bigint>` | Max withdrawable amount |
+
+---
+
+### ScoringClient
+
+Client for the off-chain scoring service.
+
+#### Methods
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `evaluateCredit(request)` | `Promise<ScoringResult>` | Request credit evaluation |
+| `checkRisk(agentId, amount)` | `Promise<RiskCheckResponse>` | Quick risk check |
+| `getStatus()` | `Promise<ServiceStatus>` | Get service status |
+
+#### Usage
+
+```typescript
+import { ScoringClient } from '@agether/sdk';
+
+const scoring = new ScoringClient('https://scoring.agether.ai/v1');
+
+// Check risk score for a potential draw
+const risk = await scoring.checkRisk(BigInt(123), parseUnits('50', 6));
+
+console.log('Risk score:', risk.riskScore);
+console.log('Level:', risk.level); // 'low' | 'medium' | 'high'
+console.log('Would approve:', risk.wouldApprove);
+
+// Get detailed evaluation
+const result = await scoring.evaluateCredit({
+  agentId: BigInt(123),
+  requestedLimit: parseUnits('1000', 6),
+  context: {
+    purpose: 'API payments',
+  },
+});
+
+if (result.approved) {
+  console.log('Credit limit:', result.creditLimit);
+  console.log('APR:', result.aprBps / 100, '%');
+}
+```
+
+---
+
+### AgentIdentityClient
+
+Client for ERC-8004 agent identity management via ag0 SDK.
+
+#### Methods
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `register()` | `Promise<{agentId}>` | Minimal agent registration |
+| `registerWithURI(uri)` | `Promise<{agentId}>` | Register with metadata URI |
+| `getReputation(agentId)` | `Promise<Reputation>` | Get ERC-8004 reputation |
+| `verifyForCredit(agentId)` | `Promise<CreditCheck>` | Verify credit eligibility |
+| `isOwner(agentId, address)` | `Promise<boolean>` | Check agent ownership |
+
+---
+
+## 📝 Types
+
+### CreditStatus
+
+```typescript
+enum CreditStatus {
+  Pending = 0,      // Application submitted
+  Active = 1,       // Approved and usable
+  Frozen = 2,       // Temporarily suspended
+  Liquidating = 3,  // In liquidation process
+  Defaulted = 4,    // Permanently defaulted
+  Closed = 5,       // Voluntarily closed
+}
+```
+
+### ChainId
+
+```typescript
+enum ChainId {
+  Ethereum = 1,
+  Sepolia = 11155111,
+}
+```
+
+### CreditLine
+
+```typescript
+interface CreditLine {
+  creditLineId: bigint;
+  agentId: bigint;
+  limit: bigint;
+  used: bigint;
+  aprBps: bigint;
+  accruedInterest: bigint;
+  status: CreditStatus;
+  createdAt: bigint;
+  lastActivityAt: bigint;
+}
+```
+
+---
+
+## ⚠️ Error Handling
+
+```typescript
+import { 
+  AgetherError, 
+  InsufficientCreditError, 
+  ScoringRejectedError,
+  CreditNotActiveError,
+} from '@agether/sdk';
+
+try {
+  await client.draw({ ... });
+} catch (error) {
+  if (error instanceof InsufficientCreditError) {
+    console.log('Not enough credit');
+    console.log('Available:', error.details?.available);
+    console.log('Requested:', error.details?.requested);
+  } else if (error instanceof ScoringRejectedError) {
+    console.log('Scoring rejected');
+    console.log('Risk score:', error.details?.riskScore);
+    console.log('Reason:', error.details?.reason);
+  } else if (error instanceof CreditNotActiveError) {
+    console.log('Credit line status:', error.details?.status);
+  } else if (error instanceof AgetherError) {
+    console.log('Agether error:', error.message);
+  }
+}
+```
+
+---
+
+## 🔧 Utilities
+
+```typescript
+import { 
+  parseUnits, 
+  formatUnits, 
+  formatUSD,
+  formatPercent,
+  formatAPR,
+  formatAddress,
+  getDefaultConfig,
+  getUSDCAddress,
+} from '@agether/sdk';
+
+// Parse $100 USDC
+const amount = parseUnits('100', 6); // 100000000n
+
+// Format for display
+console.log(formatUnits(amount, 6));  // "100.000000"
+console.log(formatUSD(amount));        // "$100.00"
+console.log(formatAPR(1200));          // "12.00%"
+
+// Get default config for a chain
+const config = getDefaultConfig(ChainId.Sepolia);
+```
+
+---
+
+## 🔗 ag0/ERC-8004 Integration
+
+The SDK integrates with [ag0](https://sdk.ag0.xyz) for ERC-8004 agent identity:
+
+**ERC-8004 Contracts (Sepolia):**
+- IdentityRegistry: `0x8004A818BFB912233c491871b3d84c89A494BD9e`
+- ReputationRegistry: `0x8004B663056A597Dffe9eCcC1965A193B7388713`
+
+---
+
+## �️ CLI Usage
+
+The SDK includes a command-line interface for easy testing and integration.
+
+### Installation
+
+```bash
+npm install -g @agether/sdk
+# or use npx
+npx agether help
+```
+
+### Commands
+
+```bash
+# Initialize with your private key
+agether init <private-key>
+
+# Register agent on ERC-8004 + submit code for KYA audit
+agether register --name "MyAgent" --code-url "https://github.com/user/agent"
+
+# Apply for credit (shows collateral requirements!)
+agether apply --limit 5000
+
+# Deposit collateral (if required)
+agether collateral --amount 4000
+
+# Draw funds from credit line
+agether draw --amount 1000
+
+# Repay debt
+agether repay --amount 500
+
+# Check status
+agether status
+
+# View credit scores (Bayesian, ChainRisk subscores)
+agether score
+
+# Check balances
+agether balance
+```
+
+### Example Flow
+
+```bash
+# 1. Initialize
+$ agether init 0x5de4...
+✅ Initialized Agether CLI
+   Address: 0x3C44C...
+   RPC:     http://95.179.189.214:8545
+   Backend: http://95.179.189.214
+
+# 2. Register agent
+$ agether register --name "OpenClaw" --code-url "https://github.com/user/openclaw"
+🤖 Registering agent: OpenClaw
+  [1/5] Fetching contract addresses...
+  [2/5] Registering on ERC-8004 IdentityRegistry...
+        ✓ Agent #42 registered
+  [3/5] Minting test USDC...
+        ✓ Minted $50,000 USDC
+  [4/5] Registering code (CodeRegistry)...
+        ✓ Code registered
+  [5/5] Code registered in Pending state
+
+  📊 Fetching initial credit scores...
+  Credit Score Summary:
+     Bayesian Score:    900/1000
+     Internal Score:    335/1000
+     External Score:    900/1000 (Cred Protocol)
+     Confidence:        0%
+
+✅ Agent #42 registered on ERC-8004!
+
+# 3. Apply for credit
+$ agether apply --limit 5000
+📋 Applying for $5000 credit line (Agent #42)...
+
+  [1/2] Evaluating credit application...
+
+  📊 Evaluation Results:
+     Approved:          ✅ Yes
+     Credit Limit:      $5000.00
+     APR:               8%
+     Risk Score:        10/100
+     Bayesian Score:    900/1000
+     Confidence:        0%
+
+  🏦 Collateral Required:
+     Amount:            $4000.00 USDC
+     Ratio:             80%
+
+  ⚠️  You will need to deposit collateral before drawing funds.
+     After approval, run: agether collateral --amount 4000
+
+  [2/2] Submitting application on-chain...
+        ✓ TX: 0x...
+
+✅ Credit Line #1 created (Pending)
+
+# 4. Admin approves (via /test Admin Panel)
+
+# 5. Deposit collateral
+$ agether collateral --amount 4000
+🏦 Depositing $4000 collateral...
+  [1/2] Approving USDC...
+        ✓ Approved
+  [2/2] Depositing collateral...
+✅ Deposited $4000 collateral
+
+# 6. Draw funds
+$ agether draw --amount 1000
+💸 Drawing $1000...
+✅ Drew $1000
+   Remaining credit: $4000.00
+```
+
+### Environment Variables
+
+```bash
+export AGETHER_RPC_URL=http://95.179.189.214:8545
+export AGETHER_BACKEND_URL=http://95.179.189.214
+```
+
+---
+
+## �📁 Project Structure
+
+```
+sdk/
+├── src/
+│   ├── clients/
+│   │   ├── AgetherClient.ts      # Main agent client
+│   │   ├── VaultClient.ts        # LP client
+│   │   ├── ScoringClient.ts      # Scoring service client
+│   │   └── AgentIdentityClient.ts # ERC-8004 client
+│   ├── types/
+│   │   └── index.ts              # Type definitions
+│   ├── utils/
+│   │   ├── format.ts             # Formatting utilities
+│   │   ├── config.ts             # Config helpers
+│   │   └── abis.ts               # Contract ABIs
+│   └── index.ts                  # Main exports
+├── package.json
+└── README.md                     # This file
+```
+
+---
+
+## 📄 License
+
+MIT

package/dist/cli.d.mts

@@ -0,0 +1,2 @@
+
+export {  }

package/dist/cli.d.ts

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+/**
+ * Agether CLI — Direct On-Chain Credit for AI Agents
+ *
+ * All commands sign transactions directly with the agent's private key.
+ * No simulation routes. No mocks. Production-grade.
+ *
+ * Usage:
+ *   agether init <private-key>                # Initialize with private key
+ *   agether register [--name] [--code-url]    # Register on real ERC-8004 + KYA
+ *   agether apply --limit 10000               # Apply for $10,000 credit (on-chain)
+ *   agether draw --amount 1000                # Draw $1,000 (on-chain)
+ *   agether repay --amount 500                # Repay $500 (on-chain)
+ *   agether status                            # Check credit line status (on-chain)
+ *   agether score                             # Get credit score (backend)
+ *   agether balance                           # Check ETH + USDC balances (on-chain)
+ */
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;GAeG"}