@t2000/sdk 0.2.5 → 0.2.7

package/README.md

@@ -24,7 +24,10 @@ yarn add @t2000/sdk
 ```typescript
 import { T2000 } from '@t2000/sdk';
 
-// Create or load a bank account
+// Create a new bank account
+const { agent, address } = await T2000.init({ pin: 'my-secret' });
+
+// Or load an existing one
 const agent = await T2000.create({ pin: 'my-secret' });
 
 // Check balance
@@ -46,30 +49,53 @@ await agent.borrow({ amount: 20, asset: 'USDC' });
 
 ## API Reference
 
-### `T2000.create(options)`
+### `T2000.init(options)` — Create a new wallet
+
+Creates a new bank account (generates keypair, encrypts, and saves to disk).
+
+```typescript
+const { agent, address, sponsored } = await T2000.init({
+  pin: 'my-secret',       // Required — encrypts the key
+  keyPath: '~/.t2000/wallet.key',  // Optional — custom key file path
+  name: 'my-agent',       // Optional — agent name for sponsor registration
+  sponsored: true,         // Optional — register with gas station (default: true)
+});
+```
+
+### `T2000.create(options)` — Load an existing wallet
 
-Creates a new bank account or loads an existing one.
+Loads an existing bank account from an encrypted key file. Throws `WALLET_NOT_FOUND` if no wallet exists.
 
 ```typescript
 const agent = await T2000.create({
-  pin: 'my-secret',               // Required — encrypts/decrypts the key
-  network: 'mainnet',             // 'mainnet' | 'testnet' (default: 'mainnet')
-  rpcUrl: 'https://...',          // Custom RPC endpoint (optional)
-  keyPath: '~/.t2000/wallet.key', // Custom key file path (optional)
+  pin: 'my-secret',                 // Required — decrypts the key
+  keyPath: '~/.t2000/wallet.key',   // Optional — custom key file path
+  rpcUrl: 'https://...',            // Optional — custom Sui RPC endpoint
 });
 ```
 
+### `T2000.fromPrivateKey(key, options?)` — Load from raw key
+
+Synchronous factory that creates an agent from a raw private key (bech32 `suiprivkey1...` or hex).
+
+```typescript
+const agent = T2000.fromPrivateKey('suiprivkey1q...');
+```
+
 ### Core Methods
 
 | Method | Description | Returns |
 |--------|-------------|---------|
+| `agent.address()` | Wallet Sui address | `string` |
 | `agent.balance()` | Available USDC + savings + gas reserve | `BalanceResponse` |
-| `agent.send({ to, amount })` | Transfer USDC to any Sui address | `SendResult` |
-| `agent.save({ amount, asset: 'USDC' })` | Deposit USDC to NAVI Protocol (earn APY) | `SaveResult` |
-| `agent.withdraw({ amount, asset: 'USDC' })` | Withdraw USDC from savings | `WithdrawResult` |
-| `agent.swap({ from, to, amount })` | Swap via Cetus CLMM DEX | `SwapResult` |
-| `agent.borrow({ amount, asset: 'USDC' })` | Borrow USDC against collateral | `BorrowResult` |
-| `agent.repay({ amount, asset: 'USDC' })` | Repay outstanding borrows | `RepayResult` |
+| `agent.send({ to, amount, asset? })` | Transfer USDC to any Sui address | `SendResult` |
+| `agent.save({ amount, asset })` | Deposit USDC to NAVI Protocol (earn APY). `amount` can be `'all'`. | `SaveResult` |
+| `agent.withdraw({ amount, asset })` | Withdraw USDC from savings. `amount` can be `'all'`. | `WithdrawResult` |
+| `agent.swap({ from, to, amount, maxSlippage? })` | Swap via Cetus CLMM DEX. `maxSlippage` in % (default: 3). | `SwapResult` |
+| `agent.swapQuote({ from, to, amount })` | Get swap quote without executing | `SwapQuote` |
+| `agent.borrow({ amount, asset })` | Borrow USDC against collateral | `BorrowResult` |
+| `agent.repay({ amount, asset })` | Repay outstanding borrows. `amount` can be `'all'`. | `RepayResult` |
+| `agent.exportKey()` | Export private key (bech32 format) | `string` |
 
 ### Query Methods
 
@@ -83,7 +109,15 @@ const agent = await T2000.create({
 | `agent.maxWithdraw()` | Max safe withdrawal amount | `MaxWithdrawResult` |
 | `agent.maxBorrow()` | Max safe borrow amount | `MaxBorrowResult` |
 | `agent.deposit()` | Wallet address + funding instructions | `DepositInfo` |
-| `agent.history()` | Transaction history | `TransactionRecord[]` |
+| `agent.history({ limit? })` | Transaction history (default: all) | `TransactionRecord[]` |
+
+### Sentinel Methods
+
+| Method | Description | Returns |
+|--------|-------------|---------|
+| `agent.sentinelList()` | List active sentinels with prize pools | `SentinelAgent[]` |
+| `agent.sentinelInfo(id)` | Get sentinel details (from API or on-chain) | `SentinelAgent` |
+| `agent.sentinelAttack(id, prompt, fee?)` | Full attack flow: request → TEE → settle | `SentinelAttackResult` |
 
 ### Key Management
 
@@ -93,6 +127,9 @@ import {
   keypairFromPrivateKey,
   exportPrivateKey,
   getAddress,
+  saveKey,
+  loadKey,
+  walletExists,
 } from '@t2000/sdk';
 
 // Generate a new keypair
@@ -106,21 +143,44 @@ const privkey = exportPrivateKey(keypair);
 
 // Get the Sui address
 const address = getAddress(keypair);
+
+// Check if wallet exists on disk
+const exists = await walletExists();
+
+// Save/load encrypted key
+await saveKey(keypair, 'my-pin');
+const loaded = await loadKey('my-pin');
 ```
 
 ### Events
 
 ```typescript
 agent.on('balanceChange', (e) => {
-  console.log(`${e.cause}: ${e.asset} changed`);
+  console.log(`${e.cause}: ${e.asset} ${e.previous} → ${e.current}`);
 });
 
 agent.on('healthWarning', (e) => {
-  console.log(`Health factor: ${e.healthFactor}`);
+  console.log(`Health factor: ${e.healthFactor} (warning)`);
+});
+
+agent.on('healthCritical', (e) => {
+  console.log(`Health factor: ${e.healthFactor} (critical — below 1.2)`);
 });
 
 agent.on('yield', (e) => {
-  console.log(`Earned: $${e.earned}`);
+  console.log(`Earned: $${e.earned}, total: $${e.total}`);
+});
+
+agent.on('gasAutoTopUp', (e) => {
+  console.log(`Auto-topped up gas: $${e.usdcSpent} USDC → ${e.suiReceived} SUI`);
+});
+
+agent.on('gasStationFallback', (e) => {
+  console.log(`Gas station fallback: ${e.reason}`);
+});
+
+agent.on('error', (e) => {
+  console.error(`Error: ${e.code} — ${e.message}`);
 });
 ```
 
@@ -140,11 +200,20 @@ import {
 
 mistToSui(1_000_000_000n);      // 1.0
 usdcToRaw(10.50);               // 10_500_000n
-formatUsd(1234.5);              // "$1,234.50"
-truncateAddress('0xabcd...1234'); // "0xabcd...1234"
+formatUsd(1234.5);              // "$1234.50"
+truncateAddress('0xabcdef...1234'); // "0xabcd...1234"
 validateAddress('0x...');        // throws if invalid
 ```
 
+### Advanced: Exposed Internals
+
+For integrations (like `@t2000/x402`), the agent exposes:
+
+```typescript
+agent.suiClient;   // SuiClient instance
+agent.signer;      // Ed25519Keypair
+```
+
 ## Gas Abstraction
 
 Every operation (send, save, borrow, repay, withdraw, swap) routes through a 3-step gas resolution chain via `executeWithGas()`. The agent never fails due to low gas if it has USDC or the Gas Station is reachable:
@@ -164,12 +233,10 @@ Every transaction result includes a `gasMethod` field (`'self-funded'` | `'auto-
 
 | Environment Variable | Description | Default |
 |---------------------|-------------|---------|
-| `T2000_PIN` | Bank account PIN | — |
-| `T2000_NETWORK` | `mainnet` or `testnet` | `mainnet` |
-| `T2000_RPC_URL` | Custom Sui RPC URL | Sui public fullnode |
-| `T2000_KEY_PATH` | Path to encrypted key file | `~/.t2000/wallet.key` |
 | `T2000_API_URL` | t2000 API base URL | `https://api.t2000.ai` |
 
+Options like `pin`, `keyPath`, and `rpcUrl` are passed directly to `T2000.create()` or `T2000.init()`. The CLI handles env vars like `T2000_PIN` — see the [CLI README](https://www.npmjs.com/package/@t2000/cli).
+
 ## Supported Assets
 
 | Asset | Type | Decimals |
@@ -192,12 +259,12 @@ try {
 }
 ```
 
-Common error codes: `INSUFFICIENT_BALANCE` · `INVALID_ADDRESS` · `INVALID_AMOUNT` · `HEALTH_FACTOR_TOO_LOW` · `NO_COLLATERAL` · `WALLET_NOT_FOUND` · `SIMULATION_FAILED` · `TRANSACTION_FAILED` · `PROTOCOL_PAUSED` · `INSUFFICIENT_GAS` · `SLIPPAGE_EXCEEDED` · `ASSET_NOT_SUPPORTED` · `WITHDRAW_WOULD_LIQUIDATE`
+Common error codes: `INSUFFICIENT_BALANCE` · `INVALID_ADDRESS` · `INVALID_AMOUNT` · `HEALTH_FACTOR_TOO_LOW` · `NO_COLLATERAL` · `WALLET_NOT_FOUND` · `WALLET_LOCKED` · `WALLET_EXISTS` · `SIMULATION_FAILED` · `TRANSACTION_FAILED` · `PROTOCOL_PAUSED` · `INSUFFICIENT_GAS` · `SLIPPAGE_EXCEEDED` · `ASSET_NOT_SUPPORTED` · `WITHDRAW_WOULD_LIQUIDATE` · `AUTO_TOPUP_FAILED` · `GAS_STATION_UNAVAILABLE`
 
 ## Testing
 
 ```bash
-# Run all SDK unit tests (92 tests)
+# Run all SDK unit tests (122 tests)
 pnpm --filter @t2000/sdk test
 ```
 
@@ -210,6 +277,10 @@ pnpm --filter @t2000/sdk test
 | `keyManager.test.ts` | Key generation, encryption, decryption, import/export |
 | `errors.test.ts` | `T2000Error` construction, serialization, `mapWalletError`, `mapMoveAbortCode` |
 | `navi.test.ts` | NAVI math utilities (health factor, APY, position calculations) |
+| `send.test.ts` | Send transaction building and validation |
+| `manager.test.ts` | Gas resolution chain (self-fund, auto-topup, sponsored fallback) |
+| `autoTopUp.test.ts` | Auto-topup threshold logic and swap execution |
+| `serialization.test.ts` | Transaction JSON serialization roundtrip |
 
 ## Protocol Fees
 

package/dist/index.cjs

@@ -12,6 +12,7 @@ var os = require('os');
 var transactions = require('@mysten/sui/transactions');
 var lending = require('@naviprotocol/lending');
 var suiClmmSdk = require('@cetusprotocol/sui-clmm-sdk');
+var bcs = require('@mysten/sui/bcs');
 
 // src/t2000.ts
 
@@ -47,6 +48,18 @@ var DEFAULT_RPC_URL = "https://fullnode.mainnet.sui.io:443";
 var DEFAULT_KEY_PATH = "~/.t2000/wallet.key";
 var API_BASE_URL = process.env.T2000_API_URL ?? "https://api.t2000.ai";
 var CETUS_USDC_SUI_POOL = "0x51e883ba7c0b566a26cbc8a94cd33eb0abd418a77cc1e60ad22fd9b1f29cd2ab";
+var SENTINEL = {
+  PACKAGE: "0x88b83f36dafcd5f6dcdcf1d2cb5889b03f61264ab3cee9cae35db7aa940a21b7",
+  AGENT_REGISTRY: "0xc47564f5f14c12b31e0dfa1a3dc99a6380a1edf8929c28cb0eaa3359c8db36ac",
+  ENCLAVE: "0xfb1261aeb9583514cb1341a548a5ec12d1231bd96af22215f1792617a93e1213",
+  PROTOCOL_CONFIG: "0x2fa4fa4a1dd0498612304635ff9334e1b922e78af325000e9d9c0e88adea459f",
+  TEE_API: "https://app.suisentinel.xyz/api/consume-prompt",
+  SENTINELS_API: "https://api.suisentinel.xyz/agents/mainnet",
+  RANDOM: "0x8",
+  MIN_FEE_MIST: 100000000n,
+  // 0.1 SUI
+  MAX_PROMPT_TOKENS: 600
+};
 
 // src/errors.ts
 var T2000Error = class extends Error {
@@ -701,6 +714,190 @@ async function getFundStatus(client, keypair) {
     projectedMonthly: earnings.dailyEarning * 30
   };
 }
+function mapAgent(raw) {
+  return {
+    id: raw.agent_id,
+    objectId: raw.agent_object_id,
+    name: raw.agent_name,
+    model: raw.model ?? "unknown",
+    systemPrompt: raw.prompt,
+    attackFee: BigInt(raw.cost_per_message),
+    prizePool: BigInt(raw.total_balance),
+    totalAttacks: raw.total_attacks,
+    successfulBreaches: raw.successful_breaches ?? 0,
+    state: raw.state
+  };
+}
+async function listSentinels() {
+  const res = await fetch(SENTINEL.SENTINELS_API);
+  if (!res.ok) {
+    throw new T2000Error("SENTINEL_API_ERROR", `Sentinel API returned ${res.status}`);
+  }
+  const data = await res.json();
+  if (!Array.isArray(data.agents)) {
+    throw new T2000Error("SENTINEL_API_ERROR", "Unexpected API response shape");
+  }
+  return data.agents.filter((a) => a.state === "active").map(mapAgent);
+}
+async function getSentinelInfo(client, sentinelObjectId) {
+  const agents = await listSentinels();
+  const match = agents.find((a) => a.objectId === sentinelObjectId || a.id === sentinelObjectId);
+  if (match) return match;
+  const obj = await client.getObject({
+    id: sentinelObjectId,
+    options: { showContent: true, showType: true }
+  });
+  if (!obj.data) {
+    throw new T2000Error("SENTINEL_NOT_FOUND", `Sentinel ${sentinelObjectId} not found on-chain`);
+  }
+  const content = obj.data.content;
+  if (!content || content.dataType !== "moveObject") {
+    throw new T2000Error("SENTINEL_NOT_FOUND", `Object ${sentinelObjectId} is not a Move object`);
+  }
+  const fields = content.fields;
+  return {
+    id: fields.id?.id ?? sentinelObjectId,
+    objectId: sentinelObjectId,
+    name: fields.name ?? "Unknown",
+    model: fields.model ?? "unknown",
+    systemPrompt: fields.system_prompt ?? "",
+    attackFee: BigInt(fields.cost_per_message ?? "0"),
+    prizePool: BigInt(fields.balance ?? "0"),
+    totalAttacks: Number(fields.total_attacks ?? "0"),
+    successfulBreaches: Number(fields.successful_breaches ?? "0"),
+    state: fields.state ?? "unknown"
+  };
+}
+async function requestAttack(client, signer, sentinelObjectId, feeMist) {
+  if (feeMist < SENTINEL.MIN_FEE_MIST) {
+    throw new T2000Error("INVALID_AMOUNT", `Attack fee must be at least 0.1 SUI (${SENTINEL.MIN_FEE_MIST} MIST)`);
+  }
+  const tx = new transactions.Transaction();
+  const [coin] = tx.splitCoins(tx.gas, [Number(feeMist)]);
+  const [attack2] = tx.moveCall({
+    target: `${SENTINEL.PACKAGE}::sentinel::request_attack`,
+    arguments: [
+      tx.object(SENTINEL.AGENT_REGISTRY),
+      tx.object(sentinelObjectId),
+      tx.object(SENTINEL.PROTOCOL_CONFIG),
+      coin,
+      tx.object(SENTINEL.RANDOM),
+      tx.object(CLOCK_ID)
+    ]
+  });
+  const address = signer.toSuiAddress();
+  tx.transferObjects([attack2], address);
+  const result = await client.signAndExecuteTransaction({
+    signer,
+    transaction: tx,
+    options: { showObjectChanges: true, showEffects: true }
+  });
+  await client.waitForTransaction({ digest: result.digest });
+  const attackObj = result.objectChanges?.find(
+    (c) => c.type === "created" && c.objectType?.includes("::sentinel::Attack")
+  );
+  const attackObjectId = attackObj && "objectId" in attackObj ? attackObj.objectId : void 0;
+  if (!attackObjectId) {
+    throw new T2000Error("SENTINEL_TX_FAILED", "Attack object was not created \u2014 transaction may have failed");
+  }
+  return { attackObjectId, digest: result.digest };
+}
+async function submitPrompt(agentId, attackObjectId, prompt) {
+  const res = await fetch(SENTINEL.TEE_API, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({
+      agent_id: agentId,
+      attack_object_id: attackObjectId,
+      message: prompt
+    })
+  });
+  if (!res.ok) {
+    const body = await res.text().catch(() => "");
+    throw new T2000Error("SENTINEL_TEE_ERROR", `TEE returned ${res.status}: ${body.slice(0, 200)}`);
+  }
+  const raw = await res.json();
+  const envelope = raw.response ?? raw;
+  const data = envelope.data ?? envelope;
+  const signature = raw.signature ?? data.signature;
+  const timestampMs = envelope.timestamp_ms ?? data.timestamp_ms;
+  if (typeof signature !== "string") {
+    throw new T2000Error("SENTINEL_TEE_ERROR", "TEE response missing signature");
+  }
+  return {
+    success: data.success ?? data.is_success,
+    score: data.score,
+    agentResponse: data.agent_response,
+    juryResponse: data.jury_response,
+    funResponse: data.fun_response ?? "",
+    signature,
+    timestampMs
+  };
+}
+async function settleAttack(client, signer, sentinelObjectId, attackObjectId, prompt, verdict) {
+  const sigBytes = Array.from(Buffer.from(verdict.signature.replace(/^0x/, ""), "hex"));
+  const tx = new transactions.Transaction();
+  tx.moveCall({
+    target: `${SENTINEL.PACKAGE}::sentinel::consume_prompt`,
+    arguments: [
+      tx.object(SENTINEL.AGENT_REGISTRY),
+      tx.object(SENTINEL.PROTOCOL_CONFIG),
+      tx.object(sentinelObjectId),
+      tx.pure.bool(verdict.success),
+      tx.pure.string(verdict.agentResponse),
+      tx.pure.string(verdict.juryResponse),
+      tx.pure.string(verdict.funResponse),
+      tx.pure.string(prompt),
+      tx.pure.u8(verdict.score),
+      tx.pure.u64(verdict.timestampMs),
+      tx.pure(bcs.bcs.vector(bcs.bcs.u8()).serialize(sigBytes)),
+      tx.object(SENTINEL.ENCLAVE),
+      tx.object(attackObjectId),
+      tx.object(CLOCK_ID)
+    ]
+  });
+  const result = await client.signAndExecuteTransaction({
+    signer,
+    transaction: tx,
+    options: { showEffects: true }
+  });
+  await client.waitForTransaction({ digest: result.digest });
+  const txSuccess = result.effects?.status?.status === "success";
+  return { digest: result.digest, success: txSuccess };
+}
+async function attack(client, signer, sentinelId, prompt, feeMist) {
+  const sentinel = await getSentinelInfo(client, sentinelId);
+  const fee = feeMist ?? sentinel.attackFee;
+  if (fee < SENTINEL.MIN_FEE_MIST) {
+    throw new T2000Error("INVALID_AMOUNT", `Attack fee must be at least 0.1 SUI`);
+  }
+  const { attackObjectId, digest: requestTx } = await requestAttack(
+    client,
+    signer,
+    sentinel.objectId,
+    fee
+  );
+  const verdict = await submitPrompt(sentinel.id, attackObjectId, prompt);
+  const { digest: settleTx } = await settleAttack(
+    client,
+    signer,
+    sentinel.objectId,
+    attackObjectId,
+    prompt,
+    verdict
+  );
+  const won = verdict.success && verdict.score >= 70;
+  return {
+    attackObjectId,
+    sentinelId: sentinel.id,
+    prompt,
+    verdict,
+    requestTx,
+    settleTx,
+    won,
+    feePaid: Number(fee) / Number(MIST_PER_SUI)
+  };
+}
 function hasLeadingZeroBits(hash, bits) {
   const fullBytes = Math.floor(bits / 8);
   const remainingBits = bits % 8;
@@ -1318,6 +1515,16 @@ var T2000 = class _T2000 extends eventemitter3.EventEmitter {
   async fundStatus() {
     return getFundStatus(this.client, this.keypair);
   }
+  // -- Sentinel --
+  async sentinelList() {
+    return listSentinels();
+  }
+  async sentinelInfo(id) {
+    return getSentinelInfo(this.client, id);
+  }
+  async sentinelAttack(id, prompt, fee) {
+    return attack(this.client, this.keypair, id, prompt, fee);
+  }
   // -- Helpers --
   emitBalanceChange(asset, amount, cause, tx) {
     this.emit("balanceChange", { asset, previous: 0, current: 0, cause, tx });
@@ -1421,6 +1628,7 @@ exports.BPS_DENOMINATOR = BPS_DENOMINATOR;
 exports.CLOCK_ID = CLOCK_ID;
 exports.DEFAULT_NETWORK = DEFAULT_NETWORK;
 exports.MIST_PER_SUI = MIST_PER_SUI;
+exports.SENTINEL = SENTINEL;
 exports.SUI_DECIMALS = SUI_DECIMALS;
 exports.SUPPORTED_ASSETS = SUPPORTED_ASSETS;
 exports.T2000 = T2000;
@@ -1437,17 +1645,23 @@ exports.getAddress = getAddress;
 exports.getGasStatus = getGasStatus;
 exports.getPoolPrice = getPoolPrice;
 exports.getRates = getRates;
+exports.getSentinelInfo = getSentinelInfo;
 exports.getSwapQuote = getSwapQuote;
 exports.keypairFromPrivateKey = keypairFromPrivateKey;
+exports.listSentinels = listSentinels;
 exports.loadKey = loadKey;
 exports.mapMoveAbortCode = mapMoveAbortCode;
 exports.mapWalletError = mapWalletError;
 exports.mistToSui = mistToSui;
 exports.rawToUsdc = rawToUsdc;
+exports.requestAttack = requestAttack;
 exports.saveKey = saveKey;
+exports.sentinelAttack = attack;
+exports.settleAttack = settleAttack;
 exports.shouldAutoTopUp = shouldAutoTopUp;
 exports.simulateTransaction = simulateTransaction;
 exports.solveHashcash = solveHashcash;
+exports.submitPrompt = submitPrompt;
 exports.suiToMist = suiToMist;
 exports.throwIfSimulationFailed = throwIfSimulationFailed;
 exports.truncateAddress = truncateAddress;