tusdt-sdk 0.1.0

package/dist/contract/tusdt-contract.d.ts

@@ -0,0 +1,186 @@
+import { Contract } from 'dedot/contracts';
+import type { AccountId, Balance, TusdtSigner, TxOptions, TxResult, TransferEvent, ApprovalEvent, FinalizedTransferEvent, Unsubscribe, EventSubscriptionOptions } from '../core/types.js';
+import type { WatchFinalizedOptions } from './finalized-events.js';
+export interface TusdtContractOptions {
+    /**
+     * Default caller address for read-only queries.
+     * If not provided, a zero address is used.
+     * This only affects the context of dry-run queries, not authorization.
+     */
+    defaultCaller?: AccountId;
+}
+/**
+ * Minimal client interface that both DedotClient and LegacyClient satisfy.
+ * This allows the SDK to work with any Dedot-compatible client regardless
+ * of whether it uses the new JSON-RPC v2 spec or the legacy spec.
+ *
+ * For nodes that only support legacy JSON-RPC (e.g., most Substrate nodes),
+ * create the client with: `await DedotClient.legacy(provider)`
+ * or `await LegacyClient.new(provider)`.
+ */
+export interface SubstrateClient {
+    rpc: any;
+    query: any;
+    disconnect(): Promise<void>;
+}
+/**
+ * Primary SDK class for interacting with the TUSDT ERC20 ink! smart contract.
+ *
+ * The SDK does NOT create or manage RPC connections. The user must provide
+ * a pre-connected Dedot client instance (DedotClient or LegacyClient).
+ *
+ * Usage with legacy RPC nodes (most Substrate nodes):
+ * ```ts
+ * import { DedotClient, WsProvider } from 'dedot';
+ * import { TusdtContract } from 'tusdt-sdk';
+ *
+ * // Use DedotClient.legacy() for nodes that don't support JSON-RPC v2
+ * const client = await DedotClient.legacy(new WsProvider('wss://...'));
+ * const tusdt = new TusdtContract(client, '5GGq...');
+ *
+ * const balance = await tusdt.balanceOf('5HhJ...');
+ * ```
+ *
+ * Usage with JSON-RPC v2 nodes:
+ * ```ts
+ * const client = await DedotClient.new(new WsProvider('wss://...'));
+ * const tusdt = new TusdtContract(client, '5GGq...');
+ * ```
+ */
+export declare class TusdtContract {
+    /** The underlying Dedot typed contract instance */
+    readonly contract: Contract<any>;
+    /** The Dedot client (stored for event subscriptions) */
+    private readonly client;
+    /**
+     * Create a TusdtContract attached to a deployed TUSDT ERC20 contract.
+     *
+     * @param client - A connected Dedot client instance (DedotClient or LegacyClient).
+     *   For nodes using legacy JSON-RPC, create with `DedotClient.legacy(provider)`.
+     *   The user is responsible for creating and managing the client lifecycle.
+     * @param contractAddress - The SS58 address of the deployed contract.
+     * @param options - Optional configuration.
+     */
+    constructor(client: SubstrateClient, contractAddress: AccountId, options?: TusdtContractOptions);
+    /**
+     * Factory: create from user-provided metadata JSON.
+     *
+     * Use this when the metadata JSON is loaded externally (e.g., in browser builds
+     * where JSON import paths may differ, or when using a custom contract build).
+     */
+    static fromMetadata(client: SubstrateClient, contractAddress: AccountId, metadata: Record<string, unknown>, options?: TusdtContractOptions): TusdtContract;
+    /**
+     * Returns the controller account address.
+     * The controller is authorized to mint/burn tokens.
+     */
+    controller(): Promise<AccountId>;
+    /**
+     * Returns the total supply of tokens in circulation.
+     * Returns bigint (u64).
+     */
+    totalSupply(): Promise<Balance>;
+    /**
+     * Returns the token balance of the specified account.
+     * Returns 0n if the account has no balance.
+     */
+    balanceOf(owner: AccountId): Promise<Balance>;
+    /**
+     * Returns the remaining allowance that spender can withdraw from owner.
+     * Returns 0n if no allowance has been set.
+     */
+    allowance(owner: AccountId, spender: AccountId): Promise<Balance>;
+    /**
+     * Transfer tokens from the signer's account to a recipient.
+     *
+     * Performs a dry-run first to check for errors and estimate gas.
+     * Self-transfers and zero-value transfers are allowed.
+     *
+     * @throws InsufficientBalanceError if signer has insufficient balance
+     * @throws ValidationError if inputs are invalid or would cause overflow
+     */
+    transfer(signer: TusdtSigner, to: AccountId, value: Balance, options?: TxOptions): Promise<TxResult>;
+    /**
+     * Approve a spender to withdraw up to `value` tokens from the signer's account.
+     *
+     * WARNING: Uses set-overwrite pattern (standard ERC20). Subject to front-running attack.
+     * Use `safeApprove()` for safer approval changes.
+     *
+     * @throws ValidationError if inputs are invalid
+     */
+    approve(signer: TusdtSigner, spender: AccountId, value: Balance, options?: TxOptions): Promise<TxResult>;
+    /**
+     * Transfer tokens from one account to another using the signer's allowance.
+     *
+     * The signer must have been granted sufficient allowance by the `from` account.
+     * On success, the allowance is decreased by `value`.
+     * On failure (insufficient balance), the allowance is NOT decreased.
+     *
+     * @throws InsufficientAllowanceError if signer has insufficient allowance
+     * @throws InsufficientBalanceError if `from` has insufficient balance
+     * @throws ValidationError if inputs are invalid or would cause overflow
+     */
+    transferFrom(signer: TusdtSigner, from: AccountId, to: AccountId, value: Balance, options?: TxOptions): Promise<TxResult>;
+    /**
+     * Safe approval that mitigates the ERC20 approve front-running attack.
+     *
+     * If the current allowance > 0 and newValue > 0, this first sets the
+     * allowance to 0, then sets it to the desired value.
+     *
+     * @throws ValidationError if inputs are invalid
+     */
+    safeApprove(signer: TusdtSigner, spender: AccountId, newValue: Balance, options?: TxOptions): Promise<TxResult>;
+    /**
+     * Subscribe to all Transfer events emitted by this contract.
+     * Includes mints (from=null), burns (to=null), and regular transfers.
+     *
+     * @param options - Optional. Pass `onError` to receive errors instead of silent skipping.
+     * @returns A function to unsubscribe from the event stream.
+     */
+    onTransfer(callback: (event: TransferEvent) => void, options?: EventSubscriptionOptions): Promise<Unsubscribe>;
+    /**
+     * Subscribe to all Approval events emitted by this contract.
+     *
+     * @param options - Optional. Pass `onError` to receive errors instead of silent skipping.
+     * @returns A function to unsubscribe from the event stream.
+     */
+    onApproval(callback: (event: ApprovalEvent) => void, options?: EventSubscriptionOptions): Promise<Unsubscribe>;
+    /**
+     * Subscribe to Transfer events where a specific account is the sender.
+     *
+     * @param account - SS58 address of the sender to filter for
+     * @param options - Optional. Pass `onError` to receive errors instead of silent skipping.
+     * @returns A function to unsubscribe from the event stream.
+     */
+    onTransferFrom(account: AccountId, callback: (event: TransferEvent) => void, options?: EventSubscriptionOptions): Promise<Unsubscribe>;
+    /**
+     * Subscribe to Transfer events where a specific account is the recipient.
+     *
+     * @param account - SS58 address of the recipient to filter for
+     * @param options - Optional. Pass `onError` to receive errors instead of silent skipping.
+     * @returns A function to unsubscribe from the event stream.
+     */
+    onTransferTo(account: AccountId, callback: (event: TransferEvent) => void, options?: EventSubscriptionOptions): Promise<Unsubscribe>;
+    /**
+     * Subscribe to all Transfer events on finalized blocks.
+     *
+     * Finalized blocks are immutable (no reorg risk), making this suitable for
+     * payment detection and reconciliation. Events include block number and
+     * event index within the block.
+     *
+     * For a full production payment listener with reconnection, deduplication,
+     * and address filtering, use `TusdtPaymentListener` from `tusdt-sdk/server`.
+     *
+     * @param options - Optional. Pass `onError` to receive errors instead of silent skipping.
+     * @returns A function to unsubscribe from the event stream.
+     */
+    onFinalizedTransfer(callback: (event: FinalizedTransferEvent) => void, options?: WatchFinalizedOptions): Promise<Unsubscribe>;
+    /**
+     * Subscribe to Transfer events to a specific account on finalized blocks.
+     *
+     * @param account - SS58 address of the recipient to filter for
+     * @param options - Optional. Pass `onError` to receive errors instead of silent skipping.
+     * @returns A function to unsubscribe from the event stream.
+     */
+    onFinalizedTransferTo(account: AccountId, callback: (event: FinalizedTransferEvent) => void, options?: WatchFinalizedOptions): Promise<Unsubscribe>;
+}
+//# sourceMappingURL=tusdt-contract.d.ts.map

package/dist/contract/tusdt-contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tusdt-contract.d.ts","sourceRoot":"","sources":["../../src/contract/tusdt-contract.ts"],"names":[],"mappings":"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"}

package/dist/core/constants.d.ts

@@ -0,0 +1,10 @@
+/** u64 maximum value: 2^64 - 1 */
+export declare const U64_MAX: bigint;
+/** Zero balance constant */
+export declare const ZERO_BALANCE: bigint;
+/**
+ * 32 zero bytes as hex string.
+ * Used as defaultCaller for read-only contract queries when no specific caller is needed.
+ */
+export declare const ZERO_ADDRESS: string;
+//# sourceMappingURL=constants.d.ts.map

package/dist/core/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../src/core/constants.ts"],"names":[],"mappings":"AAAA,kCAAkC;AAClC,eAAO,MAAM,OAAO,EAAE,MAAoC,CAAC;AAE3D,4BAA4B;AAC5B,eAAO,MAAM,YAAY,EAAE,MAAW,CAAC;AAEvC;;;GAGG;AACH,eAAO,MAAM,YAAY,EAAE,MAA+B,CAAC"}

package/dist/core/errors.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Base error class for all TUSDT SDK errors.
+ */
+export declare class TusdtSdkError extends Error {
+    constructor(message: string, options?: ErrorOptions);
+}
+/**
+ * Client-side input validation failure.
+ * Thrown before any RPC call when inputs are invalid.
+ */
+export declare class ValidationError extends TusdtSdkError {
+    constructor(message: string);
+}
+/**
+ * Base error for contract-returned errors.
+ * The contract rejected the call with a typed error variant.
+ */
+export declare class ContractError extends TusdtSdkError {
+    readonly contractErrorType: string;
+    constructor(message: string, contractErrorType: string);
+}
+/**
+ * Contract returned InsufficientBalance (error index 0).
+ * The sender does not have enough tokens for the transfer.
+ */
+export declare class InsufficientBalanceError extends ContractError {
+    constructor(message?: string);
+}
+/**
+ * Contract returned InsufficientAllowance (error index 1).
+ * The spender does not have enough allowance for the transferFrom.
+ */
+export declare class InsufficientAllowanceError extends ContractError {
+    constructor(message?: string);
+}
+/**
+ * Contract returned NotController (error index 2).
+ * Only the controller can perform mint/burn operations.
+ */
+export declare class NotControllerError extends ContractError {
+    constructor(message?: string);
+}
+/**
+ * Pallet-level dispatch failure during dry-run.
+ * The transaction would fail at the runtime level (e.g., OutOfGas, contract trap).
+ */
+export declare class DryRunError extends TusdtSdkError {
+    readonly dispatchError: unknown;
+    constructor(message: string, dispatchError?: unknown);
+}
+/**
+ * On-chain extrinsic failure after submission.
+ * The transaction was included in a block but failed during execution.
+ */
+export declare class DispatchError extends TusdtSdkError {
+    readonly dispatchError: unknown;
+    constructor(message: string, dispatchError?: unknown);
+}
+/**
+ * WebSocket/RPC connection failure.
+ */
+export declare class ConnectionError extends TusdtSdkError {
+    constructor(message: string);
+}
+/**
+ * Transaction was not included within the expected time.
+ */
+export declare class TimeoutError extends TusdtSdkError {
+    constructor(message: string);
+}
+/**
+ * Maps a Dedot contract error variant to the corresponding typed SDK error.
+ *
+ * The TUSDT ERC20 contract defines three error variants:
+ * - InsufficientBalance (index 0)
+ * - InsufficientAllowance (index 1)
+ * - NotController (index 2)
+ *
+ * Dedot's generated types produce these as a string union:
+ * `TusdtErc20TusdtError = 'InsufficientBalance' | 'InsufficientAllowance' | 'NotController'`
+ *
+ * The error may also arrive as an object with a `type` property in some contexts.
+ */
+export declare function mapContractError(error: unknown): ContractError;
+//# sourceMappingURL=errors.d.ts.map

package/dist/core/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/core/errors.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,qBAAa,aAAc,SAAQ,KAAK;gBAC1B,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY;CAIpD;AAED;;;GAGG;AACH,qBAAa,eAAgB,SAAQ,aAAa;gBACpC,OAAO,EAAE,MAAM;CAI5B;AAED;;;GAGG;AACH,qBAAa,aAAc,SAAQ,aAAa;IAC9C,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;gBAEvB,OAAO,EAAE,MAAM,EAAE,iBAAiB,EAAE,MAAM;CAKvD;AAED;;;GAGG;AACH,qBAAa,wBAAyB,SAAQ,aAAa;gBAC7C,OAAO,CAAC,EAAE,MAAM;CAO7B;AAED;;;GAGG;AACH,qBAAa,0BAA2B,SAAQ,aAAa;gBAC/C,OAAO,CAAC,EAAE,MAAM;CAO7B;AAED;;;GAGG;AACH,qBAAa,kBAAmB,SAAQ,aAAa;gBACvC,OAAO,CAAC,EAAE,MAAM;CAO7B;AAED;;;GAGG;AACH,qBAAa,WAAY,SAAQ,aAAa;IAC5C,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;gBAEpB,OAAO,EAAE,MAAM,EAAE,aAAa,CAAC,EAAE,OAAO;CAKrD;AAED;;;GAGG;AACH,qBAAa,aAAc,SAAQ,aAAa;IAC9C,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;gBAEpB,OAAO,EAAE,MAAM,EAAE,aAAa,CAAC,EAAE,OAAO;CAKrD;AAED;;GAEG;AACH,qBAAa,eAAgB,SAAQ,aAAa;gBACpC,OAAO,EAAE,MAAM;CAI5B;AAED;;GAEG;AACH,qBAAa,YAAa,SAAQ,aAAa;gBACjC,OAAO,EAAE,MAAM;CAI5B;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,aAAa,CAoC9D"}

package/dist/core/types.d.ts

@@ -0,0 +1,97 @@
+/** u64 token balance, always represented as bigint */
+export type Balance = bigint;
+/** SS58-encoded Substrate account address */
+export type AccountId = string;
+/** Finality level for transaction waiting */
+export type WaitFor = 'bestChainBlockIncluded' | 'finalized';
+/** Options for state-changing transactions */
+export interface TxOptions {
+    /** Finality level to wait for. Default: 'bestChainBlockIncluded' */
+    waitFor?: WaitFor;
+}
+/** Decoded Transfer event from the TUSDT ERC20 contract */
+export interface TransferEvent {
+    /** Sender address, or null for mint events */
+    from: AccountId | null;
+    /** Recipient address, or null for burn events */
+    to: AccountId | null;
+    /** Amount transferred (bigint, u64) */
+    value: Balance;
+    /** Block hash where the event occurred */
+    blockHash: string;
+}
+/**
+ * Transfer event from a finalized block.
+ * Extends TransferEvent with block number and event position.
+ * Used by finalized-block watchers and TusdtPaymentListener.
+ */
+export interface FinalizedTransferEvent extends TransferEvent {
+    /** Block number where the event occurred (finalized) */
+    blockNumber: number;
+    /** Index among Transfer events from this contract in the block */
+    txIndex?: number;
+}
+/** Decoded Approval event from the TUSDT ERC20 contract */
+export interface ApprovalEvent {
+    /** Token owner who granted the allowance */
+    owner: AccountId;
+    /** Spender who received the allowance */
+    spender: AccountId;
+    /** Approved amount (bigint, u64) */
+    value: Balance;
+    /** Block hash where the event occurred */
+    blockHash: string;
+}
+/** Gas estimation from dry-run */
+export interface QueryGasEstimate {
+    refTime: bigint;
+    proofSize: bigint;
+}
+/** Result of a successful state-changing transaction */
+export interface TxResult {
+    /** Block hash where the tx was included */
+    blockHash: string;
+    /** Transaction hash */
+    txHash: string;
+    /** Gas consumed estimate from dry-run */
+    gasEstimate: QueryGasEstimate;
+    /** Decoded Transfer events from this tx */
+    transfers: TransferEvent[];
+    /** Decoded Approval events from this tx */
+    approvals: ApprovalEvent[];
+}
+/** Unsubscribe function returned by event subscriptions */
+export type Unsubscribe = () => void;
+/** Options for event subscription functions */
+export interface EventSubscriptionOptions {
+    /** Called when an error occurs during block event processing */
+    onError?: (error: Error) => void;
+}
+/**
+ * Signer type accepted by the SDK.
+ *
+ * Supports two patterns that Dedot natively accepts:
+ * 1. IKeyringPair from @polkadot/keyring (backend/testing) - has `address` and `sign` method
+ * 2. Injected wallet signer (browser) - has `address` and nested `signer` object
+ *
+ * Dedot's contract.tx.signAndSend() dispatches based on the shape:
+ * - signAndSend(keyringPair) for IKeyringPair
+ * - signAndSend(address, { signer }) for injected signers
+ */
+export type TusdtSigner = KeyringPairSigner | InjectedWalletSigner;
+/** Backend signer using a keyring pair (has `sign` method directly on the object) */
+export interface KeyringPairSigner {
+    readonly address: string;
+    sign(data: Uint8Array): Uint8Array;
+    /** Keyring pairs have additional properties; this is the minimal interface */
+    [key: string]: unknown;
+}
+/** Browser-injected wallet signer */
+export interface InjectedWalletSigner {
+    readonly address: string;
+    readonly signer: {
+        signPayload: (payload: unknown) => Promise<unknown>;
+        signRaw?: (raw: unknown) => Promise<unknown>;
+    };
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/core/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/core/types.ts"],"names":[],"mappings":"AAAA,sDAAsD;AACtD,MAAM,MAAM,OAAO,GAAG,MAAM,CAAC;AAE7B,6CAA6C;AAC7C,MAAM,MAAM,SAAS,GAAG,MAAM,CAAC;AAE/B,6CAA6C;AAC7C,MAAM,MAAM,OAAO,GAAG,wBAAwB,GAAG,WAAW,CAAC;AAE7D,8CAA8C;AAC9C,MAAM,WAAW,SAAS;IACxB,oEAAoE;IACpE,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,2DAA2D;AAC3D,MAAM,WAAW,aAAa;IAC5B,8CAA8C;IAC9C,IAAI,EAAE,SAAS,GAAG,IAAI,CAAC;IACvB,iDAAiD;IACjD,EAAE,EAAE,SAAS,GAAG,IAAI,CAAC;IACrB,uCAAuC;IACvC,KAAK,EAAE,OAAO,CAAC;IACf,0CAA0C;IAC1C,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;GAIG;AACH,MAAM,WAAW,sBAAuB,SAAQ,aAAa;IAC3D,wDAAwD;IACxD,WAAW,EAAE,MAAM,CAAC;IACpB,kEAAkE;IAClE,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,2DAA2D;AAC3D,MAAM,WAAW,aAAa;IAC5B,4CAA4C;IAC5C,KAAK,EAAE,SAAS,CAAC;IACjB,yCAAyC;IACzC,OAAO,EAAE,SAAS,CAAC;IACnB,oCAAoC;IACpC,KAAK,EAAE,OAAO,CAAC;IACf,0CAA0C;IAC1C,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,kCAAkC;AAClC,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,wDAAwD;AACxD,MAAM,WAAW,QAAQ;IACvB,2CAA2C;IAC3C,SAAS,EAAE,MAAM,CAAC;IAClB,uBAAuB;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,yCAAyC;IACzC,WAAW,EAAE,gBAAgB,CAAC;IAC9B,2CAA2C;IAC3C,SAAS,EAAE,aAAa,EAAE,CAAC;IAC3B,2CAA2C;IAC3C,SAAS,EAAE,aAAa,EAAE,CAAC;CAC5B;AAED,2DAA2D;AAC3D,MAAM,MAAM,WAAW,GAAG,MAAM,IAAI,CAAC;AAErC,+CAA+C;AAC/C,MAAM,WAAW,wBAAwB;IACvC,gEAAgE;IAChE,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;CAClC;AAED;;;;;;;;;;GAUG;AACH,MAAM,MAAM,WAAW,GACnB,iBAAiB,GACjB,oBAAoB,CAAC;AAEzB,qFAAqF;AACrF,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,IAAI,CAAC,IAAI,EAAE,UAAU,GAAG,UAAU,CAAC;IACnC,8EAA8E;IAC9E,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,qCAAqC;AACrC,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE;QACf,WAAW,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;QACpD,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;KAC9C,CAAC;CACH"}

package/dist/core/validation.d.ts

@@ -0,0 +1,30 @@
+import type { TusdtSigner } from './types.js';
+/**
+ * Validates that a value is a valid u64 balance.
+ * Throws ValidationError if not bigint, negative, or exceeds u64 max.
+ */
+export declare function validateBalance(value: bigint): void;
+/**
+ * Validates that an address string is well-formed.
+ * Performs lightweight format checks. Full SS58 validation happens
+ * at the Dedot/runtime level when encoding parameters.
+ */
+export declare function validateAddress(address: string): void;
+/**
+ * Validates that adding transferAmount to recipientBalance does not overflow u64.
+ * This is a critical pre-flight check because the contract panics on overflow
+ * (consuming all gas with an opaque error).
+ */
+export declare function validateOverflowSafe(recipientBalance: bigint, transferAmount: bigint): void;
+/**
+ * Type guard: checks whether a signer is a KeyringPair (has a `sign` method).
+ * This distinguishes backend KeyringPair signers from injected wallet signers.
+ */
+export declare function isKeyringPair(signer: TusdtSigner): signer is TusdtSigner & {
+    sign: (data: Uint8Array) => Uint8Array;
+};
+/**
+ * Extracts the SS58 address from either signer type.
+ */
+export declare function getSignerAddress(signer: TusdtSigner): string;
+//# sourceMappingURL=validation.d.ts.map

package/dist/core/validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../../src/core/validation.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C;;;GAGG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAcnD;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAYrD;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAClC,gBAAgB,EAAE,MAAM,EACxB,cAAc,EAAE,MAAM,GACrB,IAAI,CAMN;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,WAAW,GAClB,MAAM,IAAI,WAAW,GAAG;IAAE,IAAI,EAAE,CAAC,IAAI,EAAE,UAAU,KAAK,UAAU,CAAA;CAAE,CAQpE;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM,CAE5D"}

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+export { TusdtContract } from './contract/tusdt-contract.js';
+export type { TusdtContractOptions, SubstrateClient } from './contract/tusdt-contract.js';
+export type { AccountId, Balance, TusdtSigner, KeyringPairSigner, InjectedWalletSigner, TxOptions, TxResult, TransferEvent, ApprovalEvent, FinalizedTransferEvent, QueryGasEstimate, Unsubscribe, WaitFor, EventSubscriptionOptions, } from './core/types.js';
+export { TusdtSdkError, ValidationError, ContractError, InsufficientBalanceError, InsufficientAllowanceError, NotControllerError, DryRunError, DispatchError, ConnectionError, TimeoutError, mapContractError, } from './core/errors.js';
+export { U64_MAX, ZERO_BALANCE } from './core/constants.js';
+export { queryController, queryTotalSupply, queryBalanceOf, queryAllowance, } from './contract/queries.js';
+export { executeTransfer, executeApprove, executeTransferFrom, } from './contract/transactions.js';
+export { safeApprove } from './contract/helpers.js';
+export { watchFinalizedTransfers, watchFinalizedTransfersTo } from './contract/finalized-events.js';
+export type { WatchFinalizedOptions } from './contract/finalized-events.js';
+export { subscribeTransfer, subscribeApproval, subscribeTransferFrom, subscribeTransferTo, } from './contract/events.js';
+export { validateBalance, validateAddress, validateOverflowSafe, isKeyringPair, getSignerAddress, } from './core/validation.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAC7D,YAAY,EAAE,oBAAoB,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAG1F,YAAY,EACV,SAAS,EACT,OAAO,EACP,WAAW,EACX,iBAAiB,EACjB,oBAAoB,EACpB,SAAS,EACT,QAAQ,EACR,aAAa,EACb,aAAa,EACb,sBAAsB,EACtB,gBAAgB,EAChB,WAAW,EACX,OAAO,EACP,wBAAwB,GACzB,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EACL,aAAa,EACb,eAAe,EACf,aAAa,EACb,wBAAwB,EACxB,0BAA0B,EAC1B,kBAAkB,EAClB,WAAW,EACX,aAAa,EACb,eAAe,EACf,YAAY,EACZ,gBAAgB,GACjB,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAG5D,OAAO,EACL,eAAe,EACf,gBAAgB,EAChB,cAAc,EACd,cAAc,GACf,MAAM,uBAAuB,CAAC;AAG/B,OAAO,EACL,eAAe,EACf,cAAc,EACd,mBAAmB,GACpB,MAAM,4BAA4B,CAAC;AAGpC,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAGpD,OAAO,EAAE,uBAAuB,EAAE,yBAAyB,EAAE,MAAM,gCAAgC,CAAC;AACpG,YAAY,EAAE,qBAAqB,EAAE,MAAM,gCAAgC,CAAC;AAG5E,OAAO,EACL,iBAAiB,EACjB,iBAAiB,EACjB,qBAAqB,EACrB,mBAAmB,GACpB,MAAM,sBAAsB,CAAC;AAG9B,OAAO,EACL,eAAe,EACf,eAAe,EACf,oBAAoB,EACpB,aAAa,EACb,gBAAgB,GACjB,MAAM,sBAAsB,CAAC"}

package/dist/index.js

@@ -0,0 +1,3 @@
+export { ConnectionError, ContractError, DispatchError, DryRunError, InsufficientAllowanceError, InsufficientBalanceError, NotControllerError, TimeoutError, TusdtContract, TusdtSdkError, U64_MAX, ValidationError, ZERO_BALANCE, executeApprove, executeTransfer, executeTransferFrom, getSignerAddress, isKeyringPair, mapContractError, queryAllowance, queryBalanceOf, queryController, queryTotalSupply, safeApprove, subscribeApproval, subscribeTransfer, subscribeTransferFrom, subscribeTransferTo, validateAddress, validateBalance, validateOverflowSafe, watchFinalizedTransfers, watchFinalizedTransfersTo } from './chunk-5HS7VSOA.js';
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js"}

package/dist/server.d.ts

@@ -0,0 +1,19 @@
+export * from './index.js';
+export { TusdtPaymentListener } from './contract/payment-listener.js';
+export type { PaymentListenerConfig, ReconnectConfig } from './contract/payment-listener.js';
+/**
+ * Create an IKeyringPair signer from a secret URI (e.g., "//Alice", "//Bob").
+ *
+ * This is a convenience helper for backend and testing environments.
+ * Uses dynamic imports to avoid hard errors when @polkadot/keyring is not installed.
+ *
+ * Requires peer dependencies:
+ * - @polkadot/keyring
+ * - @polkadot/util-crypto
+ *
+ * @param suri - Secret URI (e.g., "//Alice", "//Bob", or a mnemonic)
+ * @param type - Key type. Default: 'sr25519'
+ * @returns An IKeyringPair that can be passed as a TusdtSigner
+ */
+export declare function createSigner(suri: string, type?: 'sr25519' | 'ed25519'): Promise<import('./core/types.js').KeyringPairSigner>;
+//# sourceMappingURL=server.d.ts.map

package/dist/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAEA,cAAc,YAAY,CAAC;AAG3B,OAAO,EAAE,oBAAoB,EAAE,MAAM,gCAAgC,CAAC;AACtE,YAAY,EAAE,qBAAqB,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC;AAE7F;;;;;;;;;;;;;GAaG;AACH,wBAAsB,YAAY,CAChC,IAAI,EAAE,MAAM,EACZ,IAAI,GAAE,SAAS,GAAG,SAAqB,GACtC,OAAO,CAAC,OAAO,iBAAiB,EAAE,iBAAiB,CAAC,CAMtD"}