@bigmaxwatermelon/sdk

TypeScript SDK for the Isometry DeFi protocol — Ethereum Sepolia.

npm: @bigmaxwatermelon/sdk
version: 0.4.0
network: Ethereum Sepolia (chain ID 11155111)
registry: npm

Installation

# npm (recommended)
npm install @bigmaxwatermelon/sdk

# 国内镜像未同步时，使用 tarball 直装
npm install https://registry.npmjs.org/@bigmaxwatermelon/sdk/-/sdk-0.4.0.tgz

Requires:

• Node.js ≥ 18
• ESM only (type: module in your project)

⚠️ This package is ESM-only. Use import, not require. If you use TypeScript, set "module": "NodeNext" or "moduleResolution": "Bundler".

Quick Start — SDK

import { createClient } from '@bigmaxwatermelon/sdk'

const client = createClient({
  rpcUrl: process.env.SEPOLIA_RPC_URL ?? 'https://ethereum-sepolia.publicnode.com',
  graphUrl: 'https://console.isometry.network/graph/subgraphs/name/isometry',
  addresses: {
    platform: '0x062B11C5Ed0F2b1f9B7dFaa7B95737dD221863F7',
    factory:  '0x73D6BC64f4f54F9dF05851216F70F42135d56864',
  },
})

// Read platform info
const info = await client.rpc.platform.getPlatformInfo()
console.log(info)

Quick Start — CLI

# Check version / connectivity
npx @bigmaxwatermelon/sdk isometry system version

# Read data
npx @bigmaxwatermelon/sdk isometry platform info --json
npx @bigmaxwatermelon/sdk isometry token info <token-address> --json

# Simulate a write (dry-run, no signer needed)
npx @bigmaxwatermelon/sdk isometry token mint <token> <to> <amount> --simulate --json

💡 All CLI commands support --json for machine-readable output.

Write Operations

Write operations (mint, burn, pause, etc.) require a signer.

Environment variable:

export ISOMETRY_PRIVATE_KEY=0x_your_private_key_here

Always simulate before executing:

isometry token mint <token> <to> <amount> --simulate --json
# → Confirms the transaction looks correct, then:
isometry token mint <token> <to> <amount> --json

Quick Start

import { createClient } from '@bigmaxwatermelon/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

import { createClient } from '@bigmaxwatermelon/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

// 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)

// 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

import { WriteExecutor } from '@bigmaxwatermelon/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

npm install -g @bigmaxwatermelon/sdk
isometry --version

Or run via npx

npx @bigmaxwatermelon/sdk token info 0xd0473e07c68797f387fbe6c23981f7997d3ed5e3

Or link locally

npm link
isometry token info 0xd0473e07c68797f387fbe6c23981f7997d3ed5e3

Environment

# 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

# 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.

Public Exports

// Client
import { createClient } from '@bigmaxwatermelon/sdk'
import type { IsometryClient, IsometryConfig } from '@bigmaxwatermelon/sdk'

// Wallet
import { createWallet, ReadOnlyWallet, PrivateKeyWallet } from '@bigmaxwatermelon/sdk'
import type { IWallet, WalletMode } from '@bigmaxwatermelon/sdk'

// Write executor
import { WriteExecutor, makeWriteMeta } from '@bigmaxwatermelon/sdk'
import type { WriteResult, SimulateResult, ExecuteResult, WriteError, WriteOpts, WriteMeta, TxReceipt } from '@bigmaxwatermelon/sdk'

// Error decoding
import { decodeError, ERROR_SELECTOR_MAP } from '@bigmaxwatermelon/sdk'
import type { DecodedError } from '@bigmaxwatermelon/sdk'

// Graph
import { createGraphClient, GraphClient, GraphError } from '@bigmaxwatermelon/sdk'
import type { IsometryGraphConfig } from '@bigmaxwatermelon/sdk'
import { TokenHistoryService, PlatformHistoryService, AnalyticsService } from '@bigmaxwatermelon/sdk'

// Contract helpers
import { getContracts, getStableCoin } from '@bigmaxwatermelon/sdk'
import type { ContractAddresses } from '@bigmaxwatermelon/sdk'

// Types
import type { PlatformInfo, PlatformRoles, TokenInfo, TokenStats, TokenRoles } from '@bigmaxwatermelon/sdk'

Write Result Contract

All write operations return a typed WriteResult:

Simulate — success

{ ok: true, estimatedGas: 123456n, functionFragment: 'mint(address,uint256,string)', params: {...} }

Execute — success

{ ok: true, receipt: { txHash: '0x...', blockNumber: 10609809, status: 1, gasUsed: 121791n, from: '0x...', to: '0x...', logs: [...] } }

Error

{ 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

@bigmaxwatermelon/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
• CLI Examples
• SDK Examples
• Agent Examples
• Gitee Repository