@bigmaxwatermelon/sdk 0.4.0

package/README.md

@@ -0,0 +1,326 @@
+# @isometry/sdk
+
+> TypeScript SDK for the Isometry DeFi protocol — Ethereum Sepolia.
+
+**npm:** `@isometry/sdk`  
+**version:** `0.4.0`  
+**network:** Ethereum Sepolia (chain ID 11155111)  
+**registry:** npm
+
+---
+
+## Installation
+
+```bash
+npm install @isometry/sdk ethers
+```
+
+Requires Node.js ≥ 20.
+
+---
+
+## Quick Start
+
+```typescript
+import { createClient } from '@isometry/sdk'
+
+const client = createClient({
+  rpcUrl: process.env.SEPOLIA_RPC_URL,
+  graphUrl: process.env.GRAPH_URL,
+})
+
+// Read token info
+const info = await client.rpc.getTokenInfo('0xd0473e07c68797f387fbe6c23981f7997d3ed5e3')
+console.log(info)
+// { name: 'Test USDC', symbol: 'USDC', decimals: 6, totalSupply: ..., paused: false }
+```
+
+---
+
+## SDK — Complete Usage
+
+### Initialize Client
+
+```typescript
+import { createClient } from '@isometry/sdk'
+
+const client = createClient({
+  // Required for RPC calls
+  rpcUrl: 'https://eth-sepolia.g.alchemy.com/v2/YOUR_KEY',
+
+  // Optional: for write operations
+  privateKey: process.env.ISOMETRY_PRIVATE_KEY,
+
+  // Optional: defaults to Isometry's public subgraph
+  graphUrl: 'https://console.isometry.network/graph/subgraphs/name/isometry',
+
+  // Optional: override contract addresses
+  addresses: {
+    platform: '0x062B11C5Ed0F2b1f9B7dFaa7B95737dD221863F7',
+    factory:  '0x73D6BC64f4f54F9dF05851216F70F42135d56864',
+    beacon:   '0x99d6512B5483DFA003F73F737f87e7DAE9482F89',
+  },
+})
+```
+
+### Read — RPC
+
+```typescript
+// Platform state
+const platform = await client.rpc.platform.getPlatformInfo()
+console.log(platform.paused, platform.tokenCount)
+
+// Token info
+const info = await client.rpc.getTokenInfo('0xd0473e07c68797f387fbe6c23981f7997d3ed5e3')
+
+// Account roles on a token
+const roles = await client.rpc.platform.getAccountRoles(
+  '0xd0473e07c68797f387fbe6c23981f7997d3ed5e3',
+  '0x6BacA041C42edB76660F399fA0f4a7Dd0Cfb361e'
+)
+// { isTokenOwner, isMasterMinter, isMinter, isPauser, isBlacklister, isBlacklisted }
+
+// Factory info
+const factory = await client.rpc.factory.getFactoryInfo()
+```
+
+### Read — GraphQL (historical data)
+
+```typescript
+// Mint history
+const mints = await client.graph.token.mintHistory(
+  '0xd0473e07c68797f387fbe6c23981f7997d3ed5e3',
+  { first: 100 }
+)
+console.log(mints[0].amount, mints[0].to, mints[0].blockNumber)
+
+// Token stats
+const stats = await client.graph.analytics.tokenStats('0xd0473e07c68797f387fbe6c23981f7997d3ed5e3')
+console.log(stats.totalMints, stats.totalBurns, stats.holderCount)
+
+// Platform stats
+const platformStats = await client.graph.analytics.platformStats()
+```
+
+### Write — Simulate Before Execute
+
+```typescript
+import { WriteExecutor } from '@isometry/sdk'
+
+// Create client with private key for signing
+const writeClient = createClient({
+  rpcUrl: process.env.SEPOLIA_RPC_URL,
+  privateKey: process.env.ISOMETRY_PRIVATE_KEY,
+})
+
+const wallet = writeClient.rpc.getWallet()
+const stablecoin = writeClient.rpc.getStableCoin('0xd0473e07c68797f387fbe6c23981f7997d3ed5e3')
+const executor = new WriteExecutor({ wallet, contract: stablecoin })
+
+// Step 1: Simulate (safe — no gas, no signature)
+const sim = await executor.simulate({
+  method: 'mint',
+  args: ['0x6BacA041C42edB76660F399fA0f4a7Dd0Cfb361e', 1000n, 'memo'],
+})
+
+if (!sim.ok) {
+  console.error(`[${sim.code}] ${sim.message}`)
+  process.exit(1)
+}
+
+console.log(`Gas estimate: ${sim.estimatedGas}`)
+
+// Step 2: Execute (only after simulate succeeds)
+const result = await executor.execute({
+  method: 'mint',
+  args: ['0x6BacA041C42edB76660F399fA0f4a7Dd0Cfb361e', 1000n, 'memo'],
+})
+
+if (!result.ok) {
+  console.error(`[${result.code}] ${result.message}`)
+  process.exit(1)
+}
+
+console.log(`Confirmed: ${result.receipt.txHash}`)
+```
+
+---
+
+## CLI
+
+The CLI is included in the same package.
+
+### Install globally
+
+```bash
+npm install -g @isometry/sdk
+isometry --version
+```
+
+### Or run via npx
+
+```bash
+npx @isometry/sdk token info 0xd0473e07c68797f387fbe6c23981f7997d3ed5e3
+```
+
+### Or link locally
+
+```bash
+npm link
+isometry token info 0xd0473e07c68797f387fbe6c23981f7997d3ed5e3
+```
+
+### Environment
+
+```bash
+# Required for write commands
+ISOMETRY_PRIVATE_KEY=0x...
+
+# Required for RPC commands
+SEPOLIA_RPC_URL=https://eth-sepolia.g.alchemy.com/v2/YOUR_KEY
+
+# Optional (defaults to Isometry's public subgraph)
+GRAPH_URL=https://console.isometry.network/graph/subgraphs/name/isometry
+```
+
+### CLI Examples
+
+```bash
+# Read token info
+isometry token info 0xd0473e07c68797f387fbe6c23981f7997d3ed5e3
+
+# Read token history (GraphQL — no RPC key needed)
+isometry token history 0xd0473e07c68797f387fbe6c23981f7997d3ed5e3 --json
+
+# Simulate mint (safe, no gas)
+isometry token mint 0xd0473e07c68797f387fbe6c23981f7997d3ed5e3 \
+  0x6BacA041C42edB76660F399fA0f4a7Dd0Cfb361e 1000 \
+  --simulate --json
+
+# Execute mint (real transaction)
+isometry token mint 0xd0473e07c68797f387fbe6c23981f7997d3ed5e3 \
+  0x6BacA041C42edB76660F399fA0f4a7Dd0Cfb361e 1000 \
+  --json
+
+# Add platform admin
+isometry platform admin add 0x6BacA041C42edB76660F399fA0f4a7Dd0Cfb361e --simulate --json
+```
+
+---
+
+## API Reference
+
+Full API reference at [docs/API.md](docs/API.md).
+
+### Public Exports
+
+```typescript
+// Client
+import { createClient } from '@isometry/sdk'
+import type { IsometryClient, IsometryConfig } from '@isometry/sdk'
+
+// Wallet
+import { createWallet, ReadOnlyWallet, PrivateKeyWallet } from '@isometry/sdk'
+import type { IWallet, WalletMode } from '@isometry/sdk'
+
+// Write executor
+import { WriteExecutor, makeWriteMeta } from '@isometry/sdk'
+import type { WriteResult, SimulateResult, ExecuteResult, WriteError, WriteOpts, WriteMeta, TxReceipt } from '@isometry/sdk'
+
+// Error decoding
+import { decodeError, ERROR_SELECTOR_MAP } from '@isometry/sdk'
+import type { DecodedError } from '@isometry/sdk'
+
+// Graph
+import { createGraphClient, GraphClient, GraphError } from '@isometry/sdk'
+import type { IsometryGraphConfig } from '@isometry/sdk'
+import { TokenHistoryService, PlatformHistoryService, AnalyticsService } from '@isometry/sdk'
+
+// Contract helpers
+import { getContracts, getStableCoin } from '@isometry/sdk'
+import type { ContractAddresses } from '@isometry/sdk'
+
+// Types
+import type { PlatformInfo, PlatformRoles, TokenInfo, TokenStats, TokenRoles } from '@isometry/sdk'
+```
+
+---
+
+## Write Result Contract
+
+All write operations return a typed `WriteResult`:
+
+### Simulate — success
+```typescript
+{ ok: true, estimatedGas: 123456n, functionFragment: 'mint(address,uint256,string)', params: {...} }
+```
+
+### Execute — success
+```typescript
+{ ok: true, receipt: { txHash: '0x...', blockNumber: 10609809, status: 1, gasUsed: 121791n, from: '0x...', to: '0x...', logs: [...] } }
+```
+
+### Error
+```typescript
+{ ok: false, code: 'ACCESS_DENIED', message: 'Missing MASTER_MINTER_ROLE' }
+```
+
+### Error Codes
+
+| Code | Meaning |
+|------|---------|
+| `NO_SIGNER` | `privateKey` not set |
+| `INVALID_KEY` | Key format invalid |
+| `ACCESS_DENIED` | Missing required role |
+| `SIMULATION_FAILED` | `estimateGas` reverted |
+| `REVERT` | On-chain revert |
+| `INSUFFICIENT_BALANCE` | Not enough tokens or ETH |
+| `PAUSED` | Token is paused |
+| `RPC_ERROR` | Network error |
+
+---
+
+## Known Contract Addresses (Sepolia)
+
+| Contract | Address |
+|----------|---------|
+| Platform | `0x062B11C5Ed0F2b1f9B7dFaa7B95737dD221863F7` |
+| Factory | `0x73D6BC64f4f54F9dF05851216F70F42135d56864` |
+| Beacon | `0x99d6512B5483DFA003F73F737f87e7DAE9482F89` |
+| Test Token | `0xd0473e07c68797f387fbe6c23981f7997d3ed5e3` |
+
+---
+
+## Design Principles
+
+1. **SDK returns objects, CLI returns text** — SDK methods return native JS objects; CLI outputs formatted strings
+2. **Simulate before execute** — always estimate gas first to validate inputs and permissions
+3. **Read-only by default** — private key is optional; most use cases need reads only
+4. **Typed errors** — all errors have a `code` field for programmatic handling
+5. **No magic** — no hidden state; everything is explicit
+
+---
+
+## Architecture
+
+```
+@isometry/sdk
+├── dist/index.js       # SDK entry
+├── dist/cli.js         # CLI entry (bin: isometry)
+└── docs/
+    ├── API.md          # Full API reference
+    └── examples/       # CLI, SDK, Agent examples
+```
+
+**RPC channel** — real-time state (balances, roles, pause status)  
+**GraphQL channel** — historical data (events, mint/burn history, snapshots)
+
+---
+
+## Links
+
+- [API Reference](docs/API.md)
+- [CLI Examples](docs/examples/CLI.md)
+- [SDK Examples](docs/examples/SDK.md)
+- [Agent Examples](docs/examples/AGENT.md)
+- [Gitee Repository](https://gitee.com/middear/isometry-cli)

package/dist/cli.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node