@t402/ton 2.0.0

package/dist/esm/index.mjs

@@ -0,0 +1,108 @@
+import {
+  ExactTonScheme
+} from "./chunk-ZCMWKFVA.mjs";
+import {
+  JETTON_REGISTRY,
+  USDT_ADDRESSES,
+  getDefaultJetton,
+  getJettonByAddress,
+  getJettonConfig,
+  getNetworkJettons,
+  getNetworksForJetton,
+  getSupportedNetworks,
+  getUsdtNetworks,
+  isNetworkSupported
+} from "./chunk-RST5PY7E.mjs";
+import {
+  DEFAULT_FORWARD_TON,
+  DEFAULT_JETTON_TRANSFER_TON,
+  DEFAULT_VALIDITY_DURATION,
+  JETTON_BURN_OP,
+  JETTON_INTERNAL_TRANSFER_OP,
+  JETTON_TRANSFER_NOTIFICATION_OP,
+  JETTON_TRANSFER_OP,
+  MAX_JETTON_TRANSFER_TON,
+  MIN_JETTON_TRANSFER_TON,
+  NETWORK_ENDPOINTS,
+  NETWORK_V4_ENDPOINTS,
+  SCHEME_EXACT,
+  TON_MAINNET_CAIP2,
+  TON_MAINNET_ENDPOINT,
+  TON_MAINNET_V4_ENDPOINT,
+  TON_NETWORKS,
+  TON_TESTNET_CAIP2,
+  TON_TESTNET_ENDPOINT,
+  TON_TESTNET_V4_ENDPOINT,
+  addressesEqual,
+  buildJettonTransferBody,
+  convertFromJettonAmount,
+  convertToJettonAmount,
+  estimateJettonTransferGas,
+  formatAddress,
+  generateQueryId,
+  getEndpoint,
+  isTonNetwork,
+  normalizeNetwork,
+  parseJettonTransferBody,
+  parseTonAddress,
+  validateTonAddress
+} from "./chunk-6LOUEHJT.mjs";
+
+// src/signer.ts
+function toClientTonSigner(signer) {
+  return signer;
+}
+function toFacilitatorTonSigner(client) {
+  return {
+    ...client,
+    getAddresses: () => [client.address]
+  };
+}
+export {
+  DEFAULT_FORWARD_TON,
+  DEFAULT_JETTON_TRANSFER_TON,
+  DEFAULT_VALIDITY_DURATION,
+  ExactTonScheme,
+  JETTON_BURN_OP,
+  JETTON_INTERNAL_TRANSFER_OP,
+  JETTON_REGISTRY,
+  JETTON_TRANSFER_NOTIFICATION_OP,
+  JETTON_TRANSFER_OP,
+  MAX_JETTON_TRANSFER_TON,
+  MIN_JETTON_TRANSFER_TON,
+  NETWORK_ENDPOINTS,
+  NETWORK_V4_ENDPOINTS,
+  SCHEME_EXACT,
+  TON_MAINNET_CAIP2,
+  TON_MAINNET_ENDPOINT,
+  TON_MAINNET_V4_ENDPOINT,
+  TON_NETWORKS,
+  TON_TESTNET_CAIP2,
+  TON_TESTNET_ENDPOINT,
+  TON_TESTNET_V4_ENDPOINT,
+  USDT_ADDRESSES,
+  addressesEqual,
+  buildJettonTransferBody,
+  convertFromJettonAmount,
+  convertToJettonAmount,
+  estimateJettonTransferGas,
+  formatAddress,
+  generateQueryId,
+  getDefaultJetton,
+  getEndpoint,
+  getJettonByAddress,
+  getJettonConfig,
+  getNetworkJettons,
+  getNetworksForJetton,
+  getSupportedNetworks,
+  getUsdtNetworks,
+  isNetworkSupported,
+  isTonNetwork,
+  normalizeNetwork,
+  parseJettonTransferBody,
+  parseTonAddress,
+  toClientTonSigner,
+  toFacilitatorTonSigner,
+  validateTonAddress
+};
+//# sourceMappingURL=index.mjs.map

package/dist/esm/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/signer.ts"],"sourcesContent":["/**\n * TON Signer Interfaces\n *\n * Defines the signer interfaces for t402 client and facilitator operations.\n * These interfaces abstract away the specific wallet implementation,\n * allowing integration with various TON wallets and signing mechanisms.\n */\n\nimport type { Address, Cell, SendMode } from \"@ton/core\";\nimport type { VerifyMessageResult, TransactionConfirmation } from \"./types.js\";\n\n/**\n * Parameters for signing a TON internal message\n */\nexport type SignMessageParams = {\n  /** Destination address (typically Jetton wallet contract) */\n  to: Address;\n  /** Amount of TON to attach (for gas) in nanoTON */\n  value: bigint;\n  /** Message body (Jetton transfer cell) */\n  body: Cell;\n  /** Send mode flags (optional, defaults to PAY_GAS_SEPARATELY) */\n  sendMode?: SendMode;\n  /** Bounce flag (optional, defaults to true) */\n  bounce?: boolean;\n  /** Message validity timeout in seconds (optional) */\n  timeout?: number;\n};\n\n/**\n * ClientTonSigner - Used by t402 clients to sign Jetton transfer messages\n *\n * This interface represents a TON wallet that can:\n * - Sign internal messages for Jetton transfers\n * - Query its own seqno (sequence number)\n *\n * Implementations may include:\n * - WalletContractV4 with private key\n * - TonConnect wallet adapter\n * - Hardware wallet integration\n */\nexport type ClientTonSigner = {\n  /** The wallet address */\n  readonly address: Address;\n\n  /**\n   * Sign an internal message for Jetton transfer\n   * Returns the complete signed external message ready for broadcast\n   *\n   * @param params - Message parameters\n   * @returns Signed external message as Cell (BOC)\n   */\n  signMessage(params: SignMessageParams): Promise<Cell>;\n\n  /**\n   * Get current seqno for the wallet\n   * Used for replay protection\n   *\n   * @returns Current sequence number\n   */\n  getSeqno(): Promise<number>;\n};\n\n/**\n * Parameters for verifying a signed message\n */\nexport type VerifyMessageParams = {\n  /** The signed BOC from client (base64) */\n  signedBoc: string;\n  /** Expected sender address */\n  expectedFrom: string;\n  /** Expected Jetton transfer details */\n  expectedTransfer: {\n    /** Expected Jetton amount */\n    jettonAmount: bigint;\n    /** Expected destination address */\n    destination: string;\n    /** Jetton master address */\n    jettonMaster: string;\n  };\n};\n\n/**\n * Parameters for waiting on transaction confirmation\n */\nexport type WaitForTransactionParams = {\n  /** Address to monitor */\n  address: string;\n  /** Expected seqno after transaction */\n  seqno: number;\n  /** Timeout in milliseconds (optional) */\n  timeout?: number;\n};\n\n/**\n * FacilitatorTonSigner - Used by t402 facilitators to verify and settle payments\n *\n * This interface combines RPC capabilities with signing abilities:\n * - Query Jetton balances and wallet addresses\n * - Verify signed messages\n * - Broadcast transactions\n * - Wait for confirmations\n */\nexport type FacilitatorTonSigner = {\n  /**\n   * Get all addresses this facilitator can use for signing\n   * Enables dynamic address selection for load balancing\n   */\n  getAddresses(): readonly string[];\n\n  /**\n   * Query Jetton balance for an owner\n   *\n   * @param params - Owner and Jetton master addresses\n   * @returns Balance in smallest units\n   */\n  getJettonBalance(params: { ownerAddress: string; jettonMasterAddress: string }): Promise<bigint>;\n\n  /**\n   * Get Jetton wallet address for an owner\n   * Derives the associated Jetton wallet contract address\n   *\n   * @param params - Owner and Jetton master addresses\n   * @returns Jetton wallet address\n   */\n  getJettonWalletAddress(params: {\n    ownerAddress: string;\n    jettonMasterAddress: string;\n  }): Promise<string>;\n\n  /**\n   * Verify a signed message matches expected parameters\n   * Validates the BOC structure and transfer details\n   *\n   * @param params - Verification parameters\n   * @returns Verification result\n   */\n  verifyMessage(params: VerifyMessageParams): Promise<VerifyMessageResult>;\n\n  /**\n   * Send a pre-signed external message to the network\n   *\n   * @param signedBoc - Base64 encoded signed BOC\n   * @returns Transaction hash or identifier\n   */\n  sendExternalMessage(signedBoc: string): Promise<string>;\n\n  /**\n   * Wait for transaction confirmation\n   *\n   * @param params - Transaction monitoring parameters\n   * @returns Confirmation result\n   */\n  waitForTransaction(params: WaitForTransactionParams): Promise<TransactionConfirmation>;\n\n  /**\n   * Get current seqno for an address\n   *\n   * @param address - Wallet address to query\n   * @returns Current seqno\n   */\n  getSeqno(address: string): Promise<number>;\n\n  /**\n   * Check if a wallet is deployed (active)\n   *\n   * @param address - Address to check\n   * @returns true if deployed\n   */\n  isDeployed(address: string): Promise<boolean>;\n};\n\n/**\n * Converts a TON wallet to a ClientTonSigner\n * Identity function for type compatibility\n *\n * @param signer - The signer to convert\n * @returns The same signer with ClientTonSigner type\n */\nexport function toClientTonSigner(signer: ClientTonSigner): ClientTonSigner {\n  return signer;\n}\n\n/**\n * Creates a FacilitatorTonSigner from a single-address facilitator\n * Wraps the single address in a getAddresses() function for compatibility\n *\n * @param client - Facilitator client with single address\n * @returns FacilitatorTonSigner with getAddresses() support\n */\nexport function toFacilitatorTonSigner(\n  client: Omit<FacilitatorTonSigner, \"getAddresses\"> & { address: string },\n): FacilitatorTonSigner {\n  return {\n    ...client,\n    getAddresses: () => [client.address],\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAmLO,SAAS,kBAAkB,QAA0C;AAC1E,SAAO;AACT;AASO,SAAS,uBACd,QACsB;AACtB,SAAO;AAAA,IACL,GAAG;AAAA,IACH,cAAc,MAAM,CAAC,OAAO,OAAO;AAAA,EACrC;AACF;","names":[]}

package/dist/esm/signer-CFiw2DST.d.mts

@@ -0,0 +1,277 @@
+import { Address, Cell, SendMode } from '@ton/core';
+
+/**
+ * TON Payment Payload Types
+ *
+ * Defines the payload structure for TON Jetton payments in the t402 protocol.
+ * Uses BOC (Bag of Cells) format for message serialization.
+ */
+/**
+ * TON payment payload for the exact scheme (V2)
+ * Contains a pre-signed external message for Jetton transfer
+ */
+type ExactTonPayloadV2 = {
+    /**
+     * Base64 encoded signed external message (BOC format)
+     * Contains the complete Jetton transfer message ready for broadcast
+     * The message is signed by the client's wallet private key
+     */
+    signedBoc: string;
+    /**
+     * Transfer authorization metadata
+     * Provides human-readable and verifiable parameters
+     */
+    authorization: {
+        /**
+         * Sender wallet address (friendly format, bounceable)
+         * This is the TON wallet address that will send the Jetton transfer
+         */
+        from: string;
+        /**
+         * Recipient wallet address (friendly format)
+         * Final destination for the Jetton tokens
+         */
+        to: string;
+        /**
+         * Jetton master contract address
+         * Identifies which Jetton token is being transferred
+         */
+        jettonMaster: string;
+        /**
+         * Jetton amount in smallest units (e.g., 1000000 for 1 USDT with 6 decimals)
+         */
+        jettonAmount: string;
+        /**
+         * TON amount attached for gas (in nanoTON)
+         * Required to pay for the internal message execution
+         */
+        tonAmount: string;
+        /**
+         * Unix timestamp (seconds) after which the authorization expires
+         * Message will be rejected by the network after this time
+         */
+        validUntil: number;
+        /**
+         * Wallet sequence number at time of signing
+         * Prevents replay attacks - each seqno can only be used once
+         */
+        seqno: number;
+        /**
+         * Query ID for the Jetton transfer
+         * Used for message correlation and deduplication
+         */
+        queryId: string;
+    };
+};
+/**
+ * Alias for the current payload version
+ */
+type ExactTonPayload = ExactTonPayloadV2;
+/**
+ * Result of message verification
+ */
+type VerifyMessageResult = {
+    /** Whether the message is valid */
+    valid: boolean;
+    /** Reason for invalidity (if applicable) */
+    reason?: string;
+    /** Extracted transfer parameters */
+    transfer?: {
+        from: string;
+        to: string;
+        jettonAmount: bigint;
+        queryId: bigint;
+    };
+};
+/**
+ * Transaction confirmation result
+ */
+type TransactionConfirmation = {
+    /** Whether the transaction was confirmed */
+    success: boolean;
+    /** Logical time of the transaction */
+    lt?: bigint;
+    /** Transaction hash */
+    hash?: string;
+    /** Error message if failed */
+    error?: string;
+};
+
+/**
+ * TON Signer Interfaces
+ *
+ * Defines the signer interfaces for t402 client and facilitator operations.
+ * These interfaces abstract away the specific wallet implementation,
+ * allowing integration with various TON wallets and signing mechanisms.
+ */
+
+/**
+ * Parameters for signing a TON internal message
+ */
+type SignMessageParams = {
+    /** Destination address (typically Jetton wallet contract) */
+    to: Address;
+    /** Amount of TON to attach (for gas) in nanoTON */
+    value: bigint;
+    /** Message body (Jetton transfer cell) */
+    body: Cell;
+    /** Send mode flags (optional, defaults to PAY_GAS_SEPARATELY) */
+    sendMode?: SendMode;
+    /** Bounce flag (optional, defaults to true) */
+    bounce?: boolean;
+    /** Message validity timeout in seconds (optional) */
+    timeout?: number;
+};
+/**
+ * ClientTonSigner - Used by t402 clients to sign Jetton transfer messages
+ *
+ * This interface represents a TON wallet that can:
+ * - Sign internal messages for Jetton transfers
+ * - Query its own seqno (sequence number)
+ *
+ * Implementations may include:
+ * - WalletContractV4 with private key
+ * - TonConnect wallet adapter
+ * - Hardware wallet integration
+ */
+type ClientTonSigner = {
+    /** The wallet address */
+    readonly address: Address;
+    /**
+     * Sign an internal message for Jetton transfer
+     * Returns the complete signed external message ready for broadcast
+     *
+     * @param params - Message parameters
+     * @returns Signed external message as Cell (BOC)
+     */
+    signMessage(params: SignMessageParams): Promise<Cell>;
+    /**
+     * Get current seqno for the wallet
+     * Used for replay protection
+     *
+     * @returns Current sequence number
+     */
+    getSeqno(): Promise<number>;
+};
+/**
+ * Parameters for verifying a signed message
+ */
+type VerifyMessageParams = {
+    /** The signed BOC from client (base64) */
+    signedBoc: string;
+    /** Expected sender address */
+    expectedFrom: string;
+    /** Expected Jetton transfer details */
+    expectedTransfer: {
+        /** Expected Jetton amount */
+        jettonAmount: bigint;
+        /** Expected destination address */
+        destination: string;
+        /** Jetton master address */
+        jettonMaster: string;
+    };
+};
+/**
+ * Parameters for waiting on transaction confirmation
+ */
+type WaitForTransactionParams = {
+    /** Address to monitor */
+    address: string;
+    /** Expected seqno after transaction */
+    seqno: number;
+    /** Timeout in milliseconds (optional) */
+    timeout?: number;
+};
+/**
+ * FacilitatorTonSigner - Used by t402 facilitators to verify and settle payments
+ *
+ * This interface combines RPC capabilities with signing abilities:
+ * - Query Jetton balances and wallet addresses
+ * - Verify signed messages
+ * - Broadcast transactions
+ * - Wait for confirmations
+ */
+type FacilitatorTonSigner = {
+    /**
+     * Get all addresses this facilitator can use for signing
+     * Enables dynamic address selection for load balancing
+     */
+    getAddresses(): readonly string[];
+    /**
+     * Query Jetton balance for an owner
+     *
+     * @param params - Owner and Jetton master addresses
+     * @returns Balance in smallest units
+     */
+    getJettonBalance(params: {
+        ownerAddress: string;
+        jettonMasterAddress: string;
+    }): Promise<bigint>;
+    /**
+     * Get Jetton wallet address for an owner
+     * Derives the associated Jetton wallet contract address
+     *
+     * @param params - Owner and Jetton master addresses
+     * @returns Jetton wallet address
+     */
+    getJettonWalletAddress(params: {
+        ownerAddress: string;
+        jettonMasterAddress: string;
+    }): Promise<string>;
+    /**
+     * Verify a signed message matches expected parameters
+     * Validates the BOC structure and transfer details
+     *
+     * @param params - Verification parameters
+     * @returns Verification result
+     */
+    verifyMessage(params: VerifyMessageParams): Promise<VerifyMessageResult>;
+    /**
+     * Send a pre-signed external message to the network
+     *
+     * @param signedBoc - Base64 encoded signed BOC
+     * @returns Transaction hash or identifier
+     */
+    sendExternalMessage(signedBoc: string): Promise<string>;
+    /**
+     * Wait for transaction confirmation
+     *
+     * @param params - Transaction monitoring parameters
+     * @returns Confirmation result
+     */
+    waitForTransaction(params: WaitForTransactionParams): Promise<TransactionConfirmation>;
+    /**
+     * Get current seqno for an address
+     *
+     * @param address - Wallet address to query
+     * @returns Current seqno
+     */
+    getSeqno(address: string): Promise<number>;
+    /**
+     * Check if a wallet is deployed (active)
+     *
+     * @param address - Address to check
+     * @returns true if deployed
+     */
+    isDeployed(address: string): Promise<boolean>;
+};
+/**
+ * Converts a TON wallet to a ClientTonSigner
+ * Identity function for type compatibility
+ *
+ * @param signer - The signer to convert
+ * @returns The same signer with ClientTonSigner type
+ */
+declare function toClientTonSigner(signer: ClientTonSigner): ClientTonSigner;
+/**
+ * Creates a FacilitatorTonSigner from a single-address facilitator
+ * Wraps the single address in a getAddresses() function for compatibility
+ *
+ * @param client - Facilitator client with single address
+ * @returns FacilitatorTonSigner with getAddresses() support
+ */
+declare function toFacilitatorTonSigner(client: Omit<FacilitatorTonSigner, "getAddresses"> & {
+    address: string;
+}): FacilitatorTonSigner;
+
+export { type ClientTonSigner as C, type ExactTonPayloadV2 as E, type FacilitatorTonSigner as F, type SignMessageParams as S, type TransactionConfirmation as T, type VerifyMessageParams as V, type WaitForTransactionParams as W, toFacilitatorTonSigner as a, type ExactTonPayload as b, type VerifyMessageResult as c, toClientTonSigner as t };

package/package.json

@@ -0,0 +1,99 @@
+{
+  "name": "@t402/ton",
+  "version": "2.0.0",
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/cjs/index.d.ts",
+  "keywords": [
+    "t402",
+    "payment",
+    "protocol",
+    "ton",
+    "blockchain",
+    "jetton"
+  ],
+  "license": "Apache-2.0",
+  "author": "T402 Team",
+  "repository": "https://github.com/t402-io/t402",
+  "description": "t402 Payment Protocol TON Implementation",
+  "devDependencies": {
+    "@eslint/js": "^9.24.0",
+    "@types/node": "^22.13.4",
+    "@typescript-eslint/eslint-plugin": "^8.29.1",
+    "@typescript-eslint/parser": "^8.29.1",
+    "eslint": "^9.24.0",
+    "eslint-plugin-import": "^2.31.0",
+    "eslint-plugin-jsdoc": "^50.6.9",
+    "eslint-plugin-prettier": "^5.2.6",
+    "prettier": "3.5.2",
+    "tsup": "^8.4.0",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.3",
+    "vite": "^6.2.6",
+    "vite-tsconfig-paths": "^5.1.4",
+    "vitest": "^3.0.5"
+  },
+  "dependencies": {
+    "@ton/core": "^0.62.0",
+    "@ton/ton": "^15.0.0",
+    "@ton/crypto": "^3.2.0",
+    "@t402/core": "2.0.0"
+  },
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/esm/index.d.mts",
+        "default": "./dist/esm/index.mjs"
+      },
+      "require": {
+        "types": "./dist/cjs/index.d.ts",
+        "default": "./dist/cjs/index.js"
+      }
+    },
+    "./exact/client": {
+      "import": {
+        "types": "./dist/esm/exact/client/index.d.mts",
+        "default": "./dist/esm/exact/client/index.mjs"
+      },
+      "require": {
+        "types": "./dist/cjs/exact/client/index.d.ts",
+        "default": "./dist/cjs/exact/client/index.js"
+      }
+    },
+    "./exact/server": {
+      "import": {
+        "types": "./dist/esm/exact/server/index.d.mts",
+        "default": "./dist/esm/exact/server/index.mjs"
+      },
+      "require": {
+        "types": "./dist/cjs/exact/server/index.d.ts",
+        "default": "./dist/cjs/exact/server/index.js"
+      }
+    },
+    "./exact/facilitator": {
+      "import": {
+        "types": "./dist/esm/exact/facilitator/index.d.mts",
+        "default": "./dist/esm/exact/facilitator/index.mjs"
+      },
+      "require": {
+        "types": "./dist/cjs/exact/facilitator/index.d.ts",
+        "default": "./dist/cjs/exact/facilitator/index.js"
+      }
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "start": "tsx --env-file=.env index.ts",
+    "build": "tsup",
+    "test": "vitest run",
+    "test:integration": "vitest run --config vitest.integration.config.ts",
+    "test:watch": "vitest",
+    "watch": "tsc --watch",
+    "format": "prettier -c .prettierrc --write \"**/*.{ts,js,cjs,json,md}\"",
+    "format:check": "prettier -c .prettierrc --check \"**/*.{ts,js,cjs,json,md}\"",
+    "lint": "eslint . --ext .ts --fix",
+    "lint:check": "eslint . --ext .ts"
+  }
+}