tusdt-sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 tensorusd
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,167 @@
+# tusdt-sdk
+
+TypeScript SDK for the TUSDT ERC20 ink! smart contract on Substrate, built with [Dedot](https://docs.dedot.dev/).
+
+Three entry points for different environments:
+
+| Entry point | Import path | Use case |
+|---|---|---|
+| Root | `tusdt-sdk` | Shared types, queries, transactions, events |
+| Client | `tusdt-sdk/client` | Browser-safe (same as root, no Node.js APIs) |
+| Server | `tusdt-sdk/server` | Node.js backend: `createSigner`, `TusdtPaymentListener` |
+
+## Install
+
+```bash
+npm install tusdt-sdk
+```
+
+For server-side signing, also install the optional peer dependencies:
+
+```bash
+npm install @polkadot/keyring @polkadot/util-crypto
+```
+
+## Quick start
+
+### Client (browser / frontend)
+
+```ts
+import { DedotClient, WsProvider } from 'dedot';
+import { TusdtContract } from 'tusdt-sdk/client';
+
+const client = await DedotClient.legacy(new WsProvider('wss://test.finney.opentensor.ai:443'));
+const tusdt = new TusdtContract(client, '5Cp7QWW...');
+
+// Read-only queries
+const balance = await tusdt.balanceOf('5HhJ...');
+const supply = await tusdt.totalSupply();
+const allowance = await tusdt.allowance(owner, spender);
+
+// Transactions (with browser wallet signer)
+const result = await tusdt.transfer(signer, '5HhJ...', 1000n);
+await tusdt.approve(signer, spender, 500n);
+
+// Event subscriptions (best-chain, real-time)
+const unsub = await tusdt.onTransfer((event) => {
+  console.log(`${event.from} -> ${event.to}: ${event.value}`);
+});
+```
+
+### Server (Node.js backend)
+
+```ts
+import { DedotClient, WsProvider } from 'dedot';
+import { TusdtContract, createSigner, TusdtPaymentListener } from 'tusdt-sdk/server';
+
+const client = await DedotClient.legacy(new WsProvider('wss://test.finney.opentensor.ai:443'));
+const tusdt = new TusdtContract(client, '5Cp7QWW...');
+
+// Create a signer from a secret URI
+const alice = await createSigner('//Alice');
+await tusdt.transfer(alice, '5HhJ...', 1000n);
+
+// Production payment listener (finalized blocks, reconnection, deduplication)
+const listener = new TusdtPaymentListener(client, '5Cp7QWW...', {
+  receiverWallet: '5HhJ...',
+  onPayment: (event) => {
+    console.log(`Payment: ${event.value} from ${event.from} at block ${event.blockNumber}`);
+    // Trigger webhook, update DB, etc.
+  },
+  onError: (err) => console.error('Listener error:', err),
+});
+
+await listener.start();
+// listener.isRunning === true
+// listener.lastBlockNumber === <latest finalized block>
+
+// Later: graceful shutdown
+await listener.stop();
+```
+
+## API
+
+### `TusdtContract`
+
+Main SDK class. Wraps a deployed TUSDT ERC20 ink! contract.
+
+**Constructor:** `new TusdtContract(client, contractAddress, options?)`
+
+| Method | Returns | Description |
+|---|---|---|
+| `controller()` | `Promise<string>` | Controller account address |
+| `totalSupply()` | `Promise<bigint>` | Total token supply |
+| `balanceOf(owner)` | `Promise<bigint>` | Token balance of an account |
+| `allowance(owner, spender)` | `Promise<bigint>` | Remaining allowance |
+| `transfer(signer, to, value, options?)` | `Promise<TxResult>` | Transfer tokens |
+| `approve(signer, spender, value, options?)` | `Promise<TxResult>` | Approve spender |
+| `transferFrom(signer, from, to, value, options?)` | `Promise<TxResult>` | Transfer using allowance |
+| `safeApprove(signer, spender, value, options?)` | `Promise<TxResult>` | Reset-and-set approve |
+| `onTransfer(callback, options?)` | `Promise<Unsubscribe>` | Subscribe to Transfer events |
+| `onApproval(callback, options?)` | `Promise<Unsubscribe>` | Subscribe to Approval events |
+| `onTransferFrom(account, callback, options?)` | `Promise<Unsubscribe>` | Transfers from account |
+| `onTransferTo(account, callback, options?)` | `Promise<Unsubscribe>` | Transfers to account |
+| `onFinalizedTransfer(callback, options?)` | `Promise<Unsubscribe>` | Finalized Transfer events |
+| `onFinalizedTransferTo(account, callback, options?)` | `Promise<Unsubscribe>` | Finalized transfers to account |
+
+### `TusdtPaymentListener`
+
+Production-grade payment listener for server-side use.
+
+- Listens on **finalized blocks** only (no reorg risk)
+- Automatic **reconnection** with exponential backoff
+- **Event deduplication** (monotonic block tracking + bounded event ID set)
+- **Error isolation** (callback errors don't kill the subscription)
+
+```ts
+new TusdtPaymentListener(client, contractAddress, {
+  receiverWallet: '5HhJ...',
+  onPayment: (event) => { /* ... */ },
+  onError: (err) => { /* ... */ },
+  reconnect: {             // optional, defaults shown
+    maxRetries: Infinity,
+    baseDelayMs: 1000,
+    maxDelayMs: 30000,
+  },
+});
+```
+
+| Method/Property | Description |
+|---|---|
+| `start()` | Begin listening |
+| `stop()` | Unsubscribe and clean up |
+| `isRunning` | Whether the listener is active |
+| `lastBlockNumber` | Last processed finalized block number |
+
+### Standalone functions
+
+All tree-shakeable -- import only what you need:
+
+```ts
+import { queryBalanceOf, executeTransfer } from 'tusdt-sdk';
+import { watchFinalizedTransfers } from 'tusdt-sdk';
+```
+
+### Error types
+
+| Error | Thrown when |
+|---|---|
+| `InsufficientBalanceError` | Sender has insufficient balance |
+| `InsufficientAllowanceError` | Spender has insufficient allowance |
+| `ValidationError` | Invalid address, negative value, or u64 overflow |
+| `DryRunError` | Dry-run query fails |
+| `DispatchError` | Transaction dispatch fails on chain |
+
+## Finality levels
+
+| Option | Use case |
+|---|---|
+| `waitFor: 'bestChainBlockIncluded'` | Default. Fast confirmation, may reorg. |
+| `waitFor: 'finalized'` | Slower but immutable. Use for payments. |
+
+Event subscriptions via `onTransfer`/`onApproval` use best-chain blocks.
+Event subscriptions via `onFinalizedTransfer`/`onFinalizedTransferTo` and `TusdtPaymentListener` use finalized blocks.
+
+## License
+
+MIT