@t2000/sdk 4.0.0 → 4.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +16 -211
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,235 +1,40 @@
1
1
  # @t2000/sdk
2
2
 
3
- The TypeScript SDK for Agent Wallets on Sui. Send USDC + USDsui gasless, swap via Cetus Aggregator, and pay MPP-protected APIs — all from a single class.
4
-
5
- In [Audric](https://audric.ai), this SDK powers **Audric Passport** (wallet, signing), **Audric Finance** (NAVI lending/borrowing builders, Cetus swap), and **Audric Pay** (USDC transfers, payment links), and is wrapped by [`@t2000/engine`](https://www.npmjs.com/package/@t2000/engine) to implement **Audric Intelligence**'s Agent Harness.
3
+ The TypeScript SDK for Agent Wallets on Sui. One class (`T2000`) — wallet signing, gasless USDC + USDsui sends, Cetus swap routing, MPP paid API access, and programmatic NAVI lending builders.
6
4
 
7
5
  [![npm @t2000/sdk](https://img.shields.io/npm/v/@t2000/sdk?label=%40t2000%2Fsdk)](https://www.npmjs.com/package/@t2000/sdk)
8
6
  [![npm @t2000/cli](https://img.shields.io/npm/v/@t2000/cli?label=%40t2000%2Fcli)](https://www.npmjs.com/package/@t2000/cli)
9
- [![docs](https://img.shields.io/badge/docs-t2000.ai-00D395)](https://t2000.ai)
7
+ [![docs](https://img.shields.io/badge/docs-developers.t2000.ai-00D395)](https://developers.t2000.ai/agent-sdk)
10
8
  [![license](https://img.shields.io/badge/license-MIT-blue)](https://github.com/mission69b/t2000/blob/main/LICENSE)
11
9
 
12
- ## Installation
10
+ ## Install
13
11
 
14
12
  ```bash
15
- npm install @t2000/sdk # or pnpm add / yarn add
13
+ npm install @t2000/sdk
16
14
  ```
17
15
 
18
- **Requires** Node.js 18+ · TypeScript 5+ (recommended).
16
+ Requires Node.js 18+ · TypeScript 5+ recommended.
19
17
 
20
- ## Quick Start
18
+ ## Quick start
21
19
 
22
20
  ```typescript
23
21
  import { T2000 } from '@t2000/sdk';
24
22
 
25
- // Create a new wallet (plain Bech32, 0o600 perms, no PIN)
26
- const { agent, address } = await T2000.init();
27
-
28
- // Or load an existing wallet from ~/.t2000/wallet.key
29
- const agent = await T2000.create();
30
-
31
- // Or from a Bech32 secret in memory (no file)
32
- const agent = T2000.fromPrivateKey('suiprivkey1…');
33
-
34
- // Inspect
35
- const balance = await agent.balance();
36
- console.log(`$${balance.available} USDC available`);
37
-
38
- // Send — asset is REQUIRED; USDC + USDsui are gasless via 0x2::balance::send_funds
39
- await agent.send({ to: 'alice.sui', amount: 5, asset: 'USDC' });
40
- await agent.send({ to: '0x8b3e…', amount: 5, asset: 'USDsui' });
41
-
42
- // Swap — Cetus Aggregator V3 across 20+ Sui DEXs. Requires SUI for gas.
43
- await agent.swap({ from: 'USDC', to: 'SUI', amount: 100 });
44
-
45
- // Pay — MPP-protected API. Gasless USDC; handles HTTP 402 transparently.
46
- const result = await agent.pay({
47
- url: 'https://mpp.t2000.ai/openai/v1/chat/completions',
48
- method: 'POST',
49
- body: JSON.stringify({ model: 'gpt-4o-mini', messages: […] }),
50
- maxPrice: 0.10,
51
- });
52
- ```
53
-
54
- ## Factory Methods
55
-
56
- | Static | Returns | Use when |
57
- |---|---|---|
58
- | `T2000.init({ keyPath?, name? })` | `{ agent, address }` | Generating a brand-new wallet. Writes a plain Bech32 JSON file to `~/.t2000/wallet.key` (override with `keyPath`). |
59
- | `T2000.create({ keyPath?, rpcUrl? })` | `T2000` | Loading the existing wallet from disk. Throws `WALLET_NOT_FOUND` if the file is missing, `WALLET_CORRUPT` if it's a v3 PIN-encrypted file or otherwise malformed. |
60
- | `T2000.fromPrivateKey(secret, { network?, rpcUrl? })` | `T2000` | Synchronous in-memory load from a `suiprivkey1…` Bech32 or hex secret. No filesystem read or write. |
61
-
62
- > **v3 → v4.** `T2000.create({ pin })` is gone. The `pin` and `passphrase` fields are accepted (back-compat) but **ignored** — v4 wallets are plain Bech32 JSON with `0o600` perms. If you're upgrading a v3 PIN-encrypted wallet: export the secret from the v3 binary, then `T2000.init` followed by replacing the generated file with one carrying that secret (or just use [`@t2000/cli`](https://www.npmjs.com/package/@t2000/cli)'s `t2 init --import` flow).
63
-
64
- ## Agent Wallet API
65
-
66
- These methods cover the v4 Agent Wallet brand — sending USDC, receiving, swapping, paying for MPP APIs. They mirror the [`@t2000/cli`](https://www.npmjs.com/package/@t2000/cli) surface 1:1.
67
-
68
- | Method | Returns | Notes |
69
- |---|---|---|
70
- | `agent.address()` | `string` | Sui address. |
71
- | `agent.balance()` | `BalanceResponse` | USDC / USDsui / SUI + gas reserve + total USD. |
72
- | `agent.history({ limit? })` | `TransactionRecord[]` | Sends / swaps / MPP payments with Suiscan digests. |
73
- | `agent.send({ to, amount, asset })` | `SendResult` | **`asset` is required** (`'USDC'` / `'USDsui'` / `'SUI'`). USDC + USDsui are gasless via Sui foundation's `0x2::balance::send_funds` sponsor; SUI uses standard gas. `to` resolves in priority order: hex address > SuiNS name (`alice.sui`) > `@audric` handle > saved contact. |
74
- | `agent.resolveRecipient(input)` | `{ address, suinsName?, contactName? }` | Public resolver — same lookup `send` uses. Handy for dry-run previews. |
75
- | `agent.swap({ from, to, amount, slippage? })` | `SwapResult` | Cetus Aggregator V3 (20+ DEXs). User-friendly names (`'USDC'`, `'SUI'`, `'CETUS'`, …) or full coin types. Default slippage 1%, max 5%. **Requires SUI for gas** — Cetus is not in the gasless allowlist. |
76
- | `agent.swapQuote({ from, to, amount, slippage? })` | `SwapQuoteResult` | Preview route + output + price impact (no execution). |
77
- | `agent.pay(options)` | `PayResult` | MPP-protected paid API. Handles 402 → quote → USDC payment → retry. USDC transfer is gasless. `options.maxPrice` caps spend (default 1 USDC). |
78
- | `agent.receive({ amount?, currency?, memo?, label? })` | `PaymentRequest` | Builds a Payment Kit `sui:pay?…` URI with a unique nonce. Scannable by any Sui wallet. |
79
- | `agent.exportKey()` | `string` | Print the Bech32 (`suiprivkey1…`) secret for the underlying keypair. |
80
-
81
- ### Events
82
-
83
- ```typescript
84
- agent.on('balanceChange', (e) => { /* asset, previous, current, cause, tx? */ });
85
- agent.on('healthWarning', (e) => { /* healthFactor, threshold */ });
86
- agent.on('healthCritical', (e) => { /* healthFactor < 1.2 */ });
87
- agent.on('yield', (e) => { /* earned, total, apy, timestamp */ });
88
- agent.on('error', (e) => { /* T2000Error */ });
89
- ```
90
-
91
- ### Exposed Internals
92
-
93
- For integrations (`@suimpp/mpp`, `@t2000/engine`, audric web-v2):
94
-
95
- ```typescript
96
- agent.suiClient; // SuiJsonRpcClient
97
- agent.signer; // TransactionSigner (works for keypair + zkLogin)
98
- agent.keypair; // Ed25519Keypair (throws for zkLogin instances)
99
- ```
100
-
101
- ## Programmatic DeFi API (no CLI alias)
102
-
103
- These methods power [Audric Finance](https://audric.ai) — save (NAVI lend), borrow (NAVI), repay, withdraw, plus the supporting read tools. **They have no `t2` CLI alias in v4** by design: the CLI is a focused Agent Wallet (send / swap / pay); DeFi flows live in consumer apps and the `@t2000/engine` Agent Harness. They are still load-bearing for `@t2000/engine` 4.x and any consumer app building on the SDK.
104
-
105
- | Method | Notes |
106
- |---|---|
107
- | `agent.save({ amount, asset?, protocol? })` | Deposit **USDC or USDsui** to NAVI savings (default `'USDC'`). `amount` can be `'all'`. |
108
- | `agent.withdraw({ amount, asset?, protocol? })` | Withdraw from savings (default `'USDC'`; also supports USDsui + legacy USDe / SUI positions). `amount` can be `'all'`. |
109
- | `agent.borrow({ amount, asset?, protocol? })` | Borrow USDC or USDsui against collateral (default `'USDC'`). |
110
- | `agent.repay({ amount, asset?, protocol? })` | Repay outstanding debt. **Symmetry enforced** — USDsui debt is repaid with USDsui (USDC with USDC). `amount` can be `'all'`. |
111
- | `agent.claimRewards()` | Claim pending NAVI rewards. |
112
- | `agent.healthFactor()` | NAVI lending health factor. |
113
- | `agent.maxWithdraw()` · `agent.maxBorrow()` | Safe limits without breaching health factor. |
114
- | `agent.positions()` | Open save + borrow positions across protocols. |
115
- | `agent.rates()` | Best save/borrow APYs across protocols. |
116
- | `agent.earnings()` | Yield earned to date. |
117
- | `agent.fundStatus()` | Complete savings summary. |
118
- | `agent.deposit()` · `agent.fund()` | Wallet address + funding instructions (used by Audric's deposit UI). |
119
-
120
- ## Utility Exports
121
-
122
- ```typescript
123
- import {
124
- // Key management
125
- generateKeypair, keypairFromPrivateKey, exportPrivateKey, getAddress,
126
- saveKey, loadKey, walletExists,
127
-
128
- // Token data
129
- COIN_REGISTRY, TOKEN_MAP, SUI_TYPE, USDC_TYPE,
130
- isTier1, isTier2, isSupported, getTier,
131
- getDecimalsForCoinType, resolveSymbol, resolveTokenType,
132
-
133
- // Asset allowlist
134
- SUPPORTED_ASSETS, SENDABLE_ASSETS, assertAllowedAsset,
135
- GASLESS_MIN_STABLE_AMOUNT, GASLESS_STABLE_TYPES,
136
-
137
- // Numbers + formatting
138
- mistToSui, suiToMist, usdcToRaw, rawToUsdc,
139
- formatUsd, formatSui, truncateAddress, validateAddress,
140
-
141
- // Sui clients
142
- getSuiClient, getSuiGrpcClient, DEFAULT_GRPC_URL,
23
+ const { agent, address } = await T2000.init(); // new wallet (Bech32, 0o600 perms)
24
+ const agent = await T2000.create(); // load from ~/.t2000/wallet.key
25
+ const agent = T2000.fromPrivateKey('suiprivkey1…'); // in-memory load (no file)
143
26
 
144
- // Fees (consumer apps only — SDK + CLI are fee-free)
145
- addFeeTransfer, T2000_OVERLAY_FEE_WALLET,
146
- } from '@t2000/sdk';
27
+ await agent.send({ to: 'alice.sui', amount: 5, asset: 'USDC' }); // gasless
28
+ await agent.swap({ from: 'USDC', to: 'SUI', amount: 100 }); // Cetus, needs SUI
29
+ await agent.pay({ url: 'https://mpp.t2000.ai/openai/v1/chat/completions', method: 'POST', body, maxPrice: 0.10 });
147
30
  ```
148
31
 
149
- ## Supported Assets
32
+ USDC + USDsui sends and MPP USDC payments are gasless (Sui foundation's `0x2::balance::send_funds` sponsor). SUI sends and Cetus swaps need gas — keep ~0.05 SUI on hand.
150
33
 
151
- Token metadata + tiers live in `COIN_REGISTRY` (`packages/sdk/src/token-registry.ts`). **19 tokens** total.
34
+ ## Full reference
152
35
 
153
- - **Tier 1 — financial layer (1):** USDC. Save / borrow / receive / yield, marketplace, MPP.
154
- - **Tier 2 — swap assets (15):** SUI, wBTC, ETH, GOLD, DEEP, WAL, NS, IKA, CETUS, NAVX, vSUI, haSUI, afSUI, LOFI, MANIFEST. Hold + swap + send only.
155
- - **Legacy — no tier, display only (3):** USDT, USDe, USDsui. Kept so existing NAVI positions still render accurately.
156
-
157
- > **Strategic exception.** `OPERATION_ASSETS.save` and `OPERATION_ASSETS.borrow` accept **both** USDC and USDsui — USDsui is no-tier in the registry but saveable/borrowable via the allowlist (NAVI runs a separate USDsui pool, often at a different APY than the USDC pool, since v0.51.0). Repay symmetry is enforced: USDsui debt must be repaid with USDsui (USDC debt with USDC).
158
-
159
- **`OPERATION_ASSETS`** constrains each write:
160
-
161
- ```typescript
162
- import { OPERATION_ASSETS, assertAllowedAsset } from '@t2000/sdk';
163
-
164
- OPERATION_ASSETS.send; // ['USDC', 'USDsui', 'SUI']
165
- OPERATION_ASSETS.save; // ['USDC', 'USDsui']
166
- OPERATION_ASSETS.borrow; // ['USDC', 'USDsui']
167
-
168
- assertAllowedAsset('send', 'USDY'); // throws — not in the allowlist
169
- ```
170
-
171
- ## Gasless
172
-
173
- USDC + USDsui sends and MPP USDC payments are gasless. Build path goes through `SuiGrpcClient` so the SDK's gasless-eligibility resolver detects the `0x2::balance::send_funds` Move call at build time and zeroes out `gasPrice` / `gasBudget` / `gasPayment` automatically. Submission still goes through the JSON-RPC client (hybrid pattern documented at [`docs.sui.io`](https://docs.sui.io/develop/transaction-payment/gasless-stablecoin-transfers)).
174
-
175
- Other writes (SUI sends, Cetus swaps, NAVI save / borrow / withdraw / repay / claim) require gas. Keep ~0.05 SUI on hand. The SDK throws `INSUFFICIENT_GAS` if you run dry.
176
-
177
- > **Consumer apps:** sponsored gas via Enoki / zkLogin is the host's responsibility. The SDK is sponsorship-agnostic — Audric wires Enoki at the host layer (`audric/apps/web-v2`); the SDK doesn't know or care. See `audric/.cursor/rules/audric-transaction-flow.mdc` in the audric repo.
178
-
179
- ## Fees
180
-
181
- The SDK + CLI are **fee-free by design** (`@t2000/sdk@1.1.0+`). No t2000 protocol fees on any operation.
182
-
183
- Network gas (SUI) and third-party fees (Cetus routing, NAVI lending spread) still apply at on-chain rates.
184
-
185
- Consumer apps that want to charge an overlay fee — Audric does this on save / borrow / swap — call `addFeeTransfer(tx, paymentCoin, FEE_BPS, receiverAddress, amount)` inside the same PTB. The SDK never assumes a t2000 treasury; pass any receiver.
186
-
187
- ## Configuration
188
-
189
- | Env var | Effect |
190
- |---|---|
191
- | `T2000_RPC_URL` | Custom Sui JSON-RPC endpoint. |
192
- | `T2000_GRPC_URL` | Custom Sui gRPC endpoint (defaults to `fullnode.mainnet.sui.io`). Used during gasless USDC/USDsui send + pay build paths. |
193
-
194
- Per-call options like `keyPath` and `rpcUrl` are passed to `T2000.create()` / `T2000.init()`.
195
-
196
- ## Error Handling
197
-
198
- ```typescript
199
- import { T2000Error } from '@t2000/sdk';
200
-
201
- try {
202
- await agent.send({ to: 'alice.sui', amount: 1000, asset: 'USDC' });
203
- } catch (e) {
204
- if (e instanceof T2000Error) {
205
- // e.code + e.message
206
- }
207
- }
208
- ```
209
-
210
- Common codes:
211
-
212
- `WALLET_NOT_FOUND` · `WALLET_CORRUPT` · `INVALID_KEY` · `INSUFFICIENT_BALANCE` · `INSUFFICIENT_GAS` · `INVALID_ADDRESS` · `INVALID_AMOUNT` · `INVALID_ASSET` · `ASSET_NOT_SUPPORTED` · `SUINS_NOT_REGISTERED` · `CONTACT_NOT_FOUND` · `SWAP_NO_ROUTE` · `SWAP_FAILED` · `HEALTH_FACTOR_TOO_LOW` · `NO_COLLATERAL` · `WITHDRAW_WOULD_LIQUIDATE` · `PROTOCOL_PAUSED` · `SIMULATION_FAILED` · `TRANSACTION_FAILED`
213
-
214
- ## Architecture
215
-
216
- t2000 uses an MCP-first model for DeFi reads + thin transaction builders for writes. No protocol SDK dependencies needed in user code.
217
-
218
- | Protocol | Integration | Used for |
219
- |---|---|---|
220
- | Sui foundation gasless | `0x2::balance::send_funds` Move call (built via `SuiGrpcClient`) | USDC + USDsui transfers, MPP USDC payments |
221
- | Cetus Aggregator V3 | `@cetusprotocol/aggregator-sdk` (isolated to `protocols/cetus-swap.ts`) | Multi-DEX swap routing |
222
- | NAVI | NAVI MCP (reads) + thin tx builders (writes) | Save / borrow / withdraw / repay / rewards / positions / rates |
223
- | MPP | `mppx` + `@suimpp/mpp/client` | Paid API access — 40+ services on `mpp.t2000.ai` |
224
-
225
- Each NAVI op exposes both `buildXxxTx()` (standalone) and `addXxxToTx()` (composable fragment) so multi-step flows compose atomically as a single Programmable Transaction Block — any step failing reverts the whole bundle.
226
-
227
- ## Testing
228
-
229
- ```bash
230
- pnpm --filter @t2000/sdk test # unit
231
- SMOKE=1 pnpm --filter @t2000/sdk test -- src/__smoke__ # read-only mainnet smokes
232
- ```
36
+ Factory methods, full API surface, supported assets, NAVI lending builders, error handling, architecture →
37
+ **[developers.t2000.ai/agent-sdk](https://developers.t2000.ai/agent-sdk)**
233
38
 
234
39
  ## License
235
40
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@t2000/sdk",
3
- "version": "4.0.0",
3
+ "version": "4.0.1",
4
4
  "description": "TypeScript SDK for Agent Wallets on Sui — gasless USDC + USDsui transfers, Cetus swap routing, NAVI lending (programmatic), MPP paid API access, zkLogin compatible.",
5
5
  "type": "module",
6
6
  "main": "./dist/index.cjs",