@axonfi/sdk 0.1.2 → 0.2.0

package/README.md

@@ -0,0 +1,184 @@
+# @axonfi/sdk
+
+Treasury and payment infrastructure for autonomous AI agents. Non-custodial vaults, gasless bots, AI verification.
+
+## Why Axon
+
+Giving bots funded wallets is risky: scattered keys, no spending controls, one compromised key drains everything. Axon flips this model:
+
+- **Non-custodial vaults** — each Principal deploys their own vault. Only the owner can withdraw. Enforced on-chain.
+- **Bounded risk** — per-tx caps, daily limits, velocity windows, destination whitelists. Bots can only operate within the policies you set.
+- **AI verification** — 3-agent LLM consensus (safety, behavioral, reasoning) for flagged transactions. 2/3 consensus required.
+- **Gasless bots** — bots sign EIP-712 intents off-chain. Axon's relayer handles gas, simulation, and on-chain execution.
+- **Multi-chain** — Base, Arbitrum, Optimism, Polygon. USDC as base asset.
+
+Your agents pay. You stay in control.
+
+## Install
+
+```bash
+npm install @axonfi/sdk viem
+```
+
+## Quick Start
+
+```typescript
+import { AxonClient } from '@axonfi/sdk';
+
+const axon = new AxonClient({
+  vaultAddress: '0x...',
+  chainId: 8453,                         // Base
+  botPrivateKey: '0x...',
+  relayerUrl: 'https://relay.axonfi.xyz',
+});
+
+// Pay 5 USDC — SDK handles decimals automatically
+const result = await axon.pay({
+  to: '0xRecipient',
+  token: 'USDC',
+  amount: 5,
+  memo: 'API call payment',
+});
+
+console.log(result.status, result.txHash);
+```
+
+### Human-Friendly Amounts
+
+The SDK accepts amounts in three formats:
+
+```typescript
+// Human-readable number — SDK converts using token decimals
+await axon.pay({ to, token: 'USDC', amount: 5.2 });
+
+// Human-readable string — recommended for computed values
+await axon.pay({ to, token: 'USDC', amount: '5.2' });
+
+// Raw bigint — base units, passed through as-is
+await axon.pay({ to, token: 'USDC', amount: 5_200_000n });
+```
+
+Token field accepts addresses, `Token` enum values, or symbol strings:
+
+```typescript
+import { Token, USDC } from '@axonfi/sdk';
+
+token: 'USDC'                                    // bare symbol string
+token: Token.USDC                                // type-safe enum
+token: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'  // raw address
+```
+
+### Encrypted Bot Keys
+
+```typescript
+import { AxonClient, decryptKeystore } from '@axonfi/sdk';
+import fs from 'fs';
+
+const keystore = fs.readFileSync('./axon-bot.json', 'utf8');
+const botPrivateKey = await decryptKeystore(keystore, process.env.BOT_PASSPHRASE!);
+
+const axon = new AxonClient({
+  vaultAddress: '0x...',
+  chainId: 8453,
+  botPrivateKey,
+  relayerUrl: 'https://relay.axonfi.xyz',
+});
+```
+
+## API
+
+### Payments
+
+```typescript
+// Send a payment
+const result = await axon.pay({
+  to: '0xRecipient',
+  token: 'USDC',           // or Token.USDC, or an address
+  amount: 25,              // or '25', or 25_000_000n
+  memo: 'Invoice #42',
+});
+
+// Poll async payments
+const status = await axon.poll(result.requestId);
+```
+
+### In-Vault Swaps
+
+```typescript
+const result = await axon.swap({
+  toToken: 'WETH',
+  minToAmount: 0.001,
+  memo: 'Rebalance to WETH',
+});
+```
+
+### DeFi Protocol Execution
+
+```typescript
+const result = await axon.execute({
+  protocol: '0xUniswapRouter',
+  callData: '0x...',
+  token: 'USDC',
+  amount: 100,
+});
+```
+
+### Vault Reads
+
+```typescript
+await axon.getBalance('0xUSDC...');       // vault token balance
+await axon.isActive();                     // bot registered + active?
+await axon.isPaused();                     // vault paused?
+await axon.getVaultInfo();                 // owner, operator, version
+await axon.canPayTo('0xRecipient');        // destination allowed?
+```
+
+### Utilities
+
+```typescript
+import { parseAmount, resolveTokenDecimals, resolveToken, encodeRef } from '@axonfi/sdk';
+
+parseAmount(5.2, 'USDC');                 // 5_200_000n
+resolveTokenDecimals('WETH');             // 18
+resolveToken('USDC', 8453);              // 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913
+encodeRef('invoice-042');                 // keccak256 → bytes32
+```
+
+## Response Paths
+
+Payments resolve through one of three paths:
+
+| Path | Trigger | Timing | Response |
+|------|---------|--------|----------|
+| **Fast** | Below all thresholds | ~2s | `status: "approved"`, `txHash` |
+| **AI Scan** | Exceeds AI threshold | ~30s | `status: "approved"` or routes to review |
+| **Human Review** | No AI consensus | Async | `status: "pending_review"`, poll for result |
+
+## Security Model
+
+- **Principals** (vault owners) control everything: bot whitelist, spending limits, withdrawal. Hardware wallet recommended.
+- **Bots** only sign payment intents. They never hold ETH, never submit transactions, and can be removed instantly.
+- **Relayer** (Axon) can only execute bot-signed intents within configured limits. Cannot withdraw or modify vault config.
+- **If Axon goes offline**, the Principal retains full withdrawal access directly through the on-chain vault contract.
+
+## Chains
+
+| Chain | ID | Status |
+|-------|----|--------|
+| Base | 8453 | Live |
+| Arbitrum One | 42161 | Live |
+| Optimism | 10 | Live |
+| Polygon PoS | 137 | Live |
+| Base Sepolia | 84532 | Testnet |
+
+## Documentation
+
+- [Full SDK Reference](https://axonfi.xyz/docs/sdk/typescript/client)
+- [Quickstart Guide](https://axonfi.xyz/docs/getting-started/quickstart)
+- [How It Works](https://axonfi.xyz/docs/getting-started/how-it-works)
+- [Security Model](https://axonfi.xyz/docs/architecture/security-model)
+- [HTTP 402 Payments](https://axonfi.xyz/docs/guides/http-402)
+
+## License
+
+MIT

package/dist/index.cjs

@@ -3007,6 +3007,42 @@ function resolveToken(token, chainId) {
   }
   return addr;
 }
+function resolveTokenDecimals(token, chainId) {
+  if (typeof token === "string" && token.startsWith("0x")) {
+    const symbol = getTokenSymbolByAddress(token);
+    if (!symbol) {
+      throw new Error(
+        `Unknown token address ${token} \u2014 cannot determine decimals. Use a bigint amount instead, or pass a known token symbol.`
+      );
+    }
+    const entry2 = KNOWN_TOKENS[symbol];
+    return entry2.decimals;
+  }
+  const entry = KNOWN_TOKENS[token];
+  if (!entry) {
+    throw new Error(
+      `Unknown token symbol "${token}" \u2014 cannot determine decimals. Use a bigint amount instead, or use a known symbol (${Object.keys(KNOWN_TOKENS).join(", ")}).`
+    );
+  }
+  return entry.decimals;
+}
+function parseAmount(amount, token, chainId) {
+  if (typeof amount === "bigint") {
+    return amount;
+  }
+  const decimals = resolveTokenDecimals(token);
+  const str = typeof amount === "number" ? amount.toString() : amount;
+  const dotIndex = str.indexOf(".");
+  if (dotIndex !== -1) {
+    const decimalPlaces = str.length - dotIndex - 1;
+    if (decimalPlaces > decimals) {
+      throw new Error(
+        `Amount "${str}" has ${decimalPlaces} decimal places, but ${typeof token === "string" && token.startsWith("0x") ? "this token" : token} only supports ${decimals}. Truncate or round your amount.`
+      );
+    }
+  }
+  return viem.parseUnits(str, decimals);
+}
 
 // src/utils.ts
 function generateUuid() {
@@ -3284,7 +3320,7 @@ Timestamp: ${timestamp}`;
       bot: this.botAddress,
       to: input.to,
       token: resolveToken(input.token, this.chainId),
-      amount: input.amount,
+      amount: parseAmount(input.amount, input.token, this.chainId),
       deadline: input.deadline ?? this._defaultDeadline(),
       ref: this._resolveRef(input.memo, input.ref)
     };
@@ -3295,7 +3331,7 @@ Timestamp: ${timestamp}`;
       protocol: input.protocol,
       calldataHash: viem.keccak256(input.callData),
       token: resolveToken(input.token, this.chainId),
-      amount: input.amount,
+      amount: parseAmount(input.amount, input.token, this.chainId),
       deadline: input.deadline ?? this._defaultDeadline(),
       ref: this._resolveRef(input.memo, input.ref)
     };
@@ -3304,7 +3340,7 @@ Timestamp: ${timestamp}`;
     return {
       bot: this.botAddress,
       toToken: resolveToken(input.toToken, this.chainId),
-      minToAmount: input.minToAmount,
+      minToAmount: parseAmount(input.minToAmount, input.toToken, this.chainId),
       deadline: input.deadline ?? this._defaultDeadline(),
       ref: this._resolveRef(input.memo, input.ref)
     };
@@ -3336,6 +3372,8 @@ Timestamp: ${timestamp}`;
   }
   async _submitExecute(intent, signature, input) {
     const idempotencyKey = input.idempotencyKey ?? generateUuid();
+    const fromToken = input.fromToken !== void 0 ? resolveToken(input.fromToken, this.chainId) : void 0;
+    const maxFromAmount = input.maxFromAmount !== void 0 ? parseAmount(input.maxFromAmount, input.fromToken ?? input.token, this.chainId) : void 0;
     const body = {
       chainId: this.chainId,
       vaultAddress: this.vaultAddress,
@@ -3351,8 +3389,8 @@ Timestamp: ${timestamp}`;
       // Protocol calldata
       callData: input.callData,
       // Optional pre-swap
-      ...input.fromToken !== void 0 && { fromToken: input.fromToken },
-      ...input.maxFromAmount !== void 0 && { maxFromAmount: input.maxFromAmount.toString() },
+      ...fromToken !== void 0 && { fromToken },
+      ...maxFromAmount !== void 0 && { maxFromAmount: maxFromAmount.toString() },
       // Off-chain metadata
       idempotencyKey,
       ...input.memo !== void 0 && { memo: input.memo },
@@ -3363,6 +3401,8 @@ Timestamp: ${timestamp}`;
   }
   async _submitSwap(intent, signature, input) {
     const idempotencyKey = input.idempotencyKey ?? generateUuid();
+    const fromToken = input.fromToken !== void 0 ? resolveToken(input.fromToken, this.chainId) : void 0;
+    const maxFromAmount = input.maxFromAmount !== void 0 ? parseAmount(input.maxFromAmount, input.fromToken ?? input.toToken, this.chainId) : void 0;
     const body = {
       chainId: this.chainId,
       vaultAddress: this.vaultAddress,
@@ -3374,8 +3414,8 @@ Timestamp: ${timestamp}`;
       ref: intent.ref,
       signature,
       // Optional source token
-      ...input.fromToken !== void 0 && { fromToken: input.fromToken },
-      ...input.maxFromAmount !== void 0 && { maxFromAmount: input.maxFromAmount.toString() },
+      ...fromToken !== void 0 && { fromToken },
+      ...maxFromAmount !== void 0 && { maxFromAmount: maxFromAmount.toString() },
       // Off-chain metadata
       idempotencyKey,
       ...input.memo !== void 0 && { memo: input.memo }
@@ -3929,7 +3969,9 @@ exports.isDestinationAllowed = isDestinationAllowed;
 exports.isRebalanceTokenWhitelisted = isRebalanceTokenWhitelisted;
 exports.isVaultPaused = isVaultPaused;
 exports.operatorMaxDrainPerDay = operatorMaxDrainPerDay;
+exports.parseAmount = parseAmount;
 exports.resolveToken = resolveToken;
+exports.resolveTokenDecimals = resolveTokenDecimals;
 exports.signExecuteIntent = signExecuteIntent;
 exports.signPayment = signPayment;
 exports.signSwapIntent = signSwapIntent;