@t402/polkadot 2.3.0

package/dist/types-Dbjfcz2Y.d.cts

@@ -0,0 +1,135 @@
+import { Network } from '@t402/core/types';
+
+/**
+ * Polkadot Asset Hub T402 Types
+ */
+
+/**
+ * Payment payload for exact-direct scheme on Polkadot
+ */
+type ExactDirectPolkadotPayload = {
+    /** Extrinsic hash (block hash + extrinsic index) */
+    extrinsicHash: string;
+    /** Block hash containing the extrinsic */
+    blockHash: string;
+    /** Extrinsic index within the block */
+    extrinsicIndex: number;
+    /** Sender address (SS58 format) */
+    from: string;
+    /** Recipient address (SS58 format) */
+    to: string;
+    /** Amount in smallest unit (with decimals) */
+    amount: string;
+    /** Asset ID */
+    assetId: number;
+};
+/**
+ * Result of a Polkadot extrinsic query
+ */
+interface PolkadotExtrinsicResult {
+    /** Extrinsic hash */
+    extrinsicHash: string;
+    /** Block hash */
+    blockHash: string;
+    /** Block number */
+    blockNumber: number;
+    /** Extrinsic index */
+    extrinsicIndex: number;
+    /** Timestamp (ISO 8601) */
+    timestamp: string;
+    /** Signer address */
+    signer: string;
+    /** Success status */
+    success: boolean;
+    /** Module name (e.g., "assets") */
+    module: string;
+    /** Call name (e.g., "transfer") */
+    call: string;
+    /** Call arguments */
+    args: Record<string, unknown>;
+    /** Events emitted by the extrinsic */
+    events: PolkadotEvent[];
+}
+/**
+ * Polkadot event structure
+ */
+interface PolkadotEvent {
+    /** Module name */
+    module: string;
+    /** Event name */
+    name: string;
+    /** Event data */
+    data: Record<string, unknown>;
+}
+/**
+ * Parsed asset transfer from extrinsic
+ */
+interface ParsedAssetTransfer {
+    /** Asset ID */
+    assetId: number;
+    /** Sender address */
+    from: string;
+    /** Recipient address */
+    to: string;
+    /** Amount transferred */
+    amount: string;
+    /** Whether the transfer was successful */
+    success: boolean;
+}
+/**
+ * Signer interface for Polkadot facilitator
+ */
+interface FacilitatorPolkadotSigner {
+    /**
+     * Get the facilitator's addresses for a network
+     */
+    getAddresses(network: Network): string[];
+    /**
+     * Query an extrinsic by hash
+     */
+    queryExtrinsic(extrinsicHash: string, blockHash?: string, extrinsicIndex?: number): Promise<PolkadotExtrinsicResult | null>;
+    /**
+     * Get balance of an asset for an address
+     */
+    getBalance(assetId: number, address: string): Promise<string>;
+}
+/**
+ * Client signer interface for signing transactions
+ */
+interface ClientPolkadotSigner {
+    /**
+     * Get the signer's address
+     */
+    getAddress(): Promise<string>;
+    /**
+     * Sign and submit an asset transfer
+     * Returns the extrinsic hash, block hash, and extrinsic index
+     */
+    transferAsset(assetId: number, to: string, amount: string): Promise<{
+        extrinsicHash: string;
+        blockHash: string;
+        extrinsicIndex: number;
+    }>;
+}
+/**
+ * Configuration for Polkadot server
+ */
+interface PolkadotServerConfig {
+    /** Custom RPC URL */
+    rpcUrl?: string;
+    /** Custom indexer URL */
+    indexerUrl?: string;
+    /** Facilitator addresses per network */
+    facilitatorAddresses?: Record<string, string>;
+}
+/**
+ * Configuration for Polkadot facilitator
+ */
+interface PolkadotFacilitatorConfig {
+    /** Maximum age of extrinsic to accept (in seconds) */
+    maxExtrinsicAge?: number;
+    /** Duration to cache used extrinsic hashes */
+    usedExtrinsicCacheDuration?: number;
+}
+
+export type { ClientPolkadotSigner as C, ExactDirectPolkadotPayload as E, FacilitatorPolkadotSigner as F, PolkadotExtrinsicResult as P, ParsedAssetTransfer as a, PolkadotEvent as b, PolkadotServerConfig as c, PolkadotFacilitatorConfig as d };

package/dist/types-Dbjfcz2Y.d.ts

@@ -0,0 +1,135 @@
+import { Network } from '@t402/core/types';
+
+/**
+ * Polkadot Asset Hub T402 Types
+ */
+
+/**
+ * Payment payload for exact-direct scheme on Polkadot
+ */
+type ExactDirectPolkadotPayload = {
+    /** Extrinsic hash (block hash + extrinsic index) */
+    extrinsicHash: string;
+    /** Block hash containing the extrinsic */
+    blockHash: string;
+    /** Extrinsic index within the block */
+    extrinsicIndex: number;
+    /** Sender address (SS58 format) */
+    from: string;
+    /** Recipient address (SS58 format) */
+    to: string;
+    /** Amount in smallest unit (with decimals) */
+    amount: string;
+    /** Asset ID */
+    assetId: number;
+};
+/**
+ * Result of a Polkadot extrinsic query
+ */
+interface PolkadotExtrinsicResult {
+    /** Extrinsic hash */
+    extrinsicHash: string;
+    /** Block hash */
+    blockHash: string;
+    /** Block number */
+    blockNumber: number;
+    /** Extrinsic index */
+    extrinsicIndex: number;
+    /** Timestamp (ISO 8601) */
+    timestamp: string;
+    /** Signer address */
+    signer: string;
+    /** Success status */
+    success: boolean;
+    /** Module name (e.g., "assets") */
+    module: string;
+    /** Call name (e.g., "transfer") */
+    call: string;
+    /** Call arguments */
+    args: Record<string, unknown>;
+    /** Events emitted by the extrinsic */
+    events: PolkadotEvent[];
+}
+/**
+ * Polkadot event structure
+ */
+interface PolkadotEvent {
+    /** Module name */
+    module: string;
+    /** Event name */
+    name: string;
+    /** Event data */
+    data: Record<string, unknown>;
+}
+/**
+ * Parsed asset transfer from extrinsic
+ */
+interface ParsedAssetTransfer {
+    /** Asset ID */
+    assetId: number;
+    /** Sender address */
+    from: string;
+    /** Recipient address */
+    to: string;
+    /** Amount transferred */
+    amount: string;
+    /** Whether the transfer was successful */
+    success: boolean;
+}
+/**
+ * Signer interface for Polkadot facilitator
+ */
+interface FacilitatorPolkadotSigner {
+    /**
+     * Get the facilitator's addresses for a network
+     */
+    getAddresses(network: Network): string[];
+    /**
+     * Query an extrinsic by hash
+     */
+    queryExtrinsic(extrinsicHash: string, blockHash?: string, extrinsicIndex?: number): Promise<PolkadotExtrinsicResult | null>;
+    /**
+     * Get balance of an asset for an address
+     */
+    getBalance(assetId: number, address: string): Promise<string>;
+}
+/**
+ * Client signer interface for signing transactions
+ */
+interface ClientPolkadotSigner {
+    /**
+     * Get the signer's address
+     */
+    getAddress(): Promise<string>;
+    /**
+     * Sign and submit an asset transfer
+     * Returns the extrinsic hash, block hash, and extrinsic index
+     */
+    transferAsset(assetId: number, to: string, amount: string): Promise<{
+        extrinsicHash: string;
+        blockHash: string;
+        extrinsicIndex: number;
+    }>;
+}
+/**
+ * Configuration for Polkadot server
+ */
+interface PolkadotServerConfig {
+    /** Custom RPC URL */
+    rpcUrl?: string;
+    /** Custom indexer URL */
+    indexerUrl?: string;
+    /** Facilitator addresses per network */
+    facilitatorAddresses?: Record<string, string>;
+}
+/**
+ * Configuration for Polkadot facilitator
+ */
+interface PolkadotFacilitatorConfig {
+    /** Maximum age of extrinsic to accept (in seconds) */
+    maxExtrinsicAge?: number;
+    /** Duration to cache used extrinsic hashes */
+    usedExtrinsicCacheDuration?: number;
+}
+
+export type { ClientPolkadotSigner as C, ExactDirectPolkadotPayload as E, FacilitatorPolkadotSigner as F, PolkadotExtrinsicResult as P, ParsedAssetTransfer as a, PolkadotEvent as b, PolkadotServerConfig as c, PolkadotFacilitatorConfig as d };

package/package.json

@@ -0,0 +1,103 @@
+{
+  "name": "@t402/polkadot",
+  "version": "2.3.0",
+  "description": "T402 Polkadot Asset Hub mechanism - USDT payments on Polkadot",
+  "type": "module",
+  "main": "./dist/cjs/index.cjs",
+  "module": "./dist/esm/index.mjs",
+  "types": "./dist/esm/index.d.mts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/esm/index.d.mts",
+        "default": "./dist/esm/index.mjs"
+      },
+      "require": {
+        "types": "./dist/cjs/index.d.cts",
+        "default": "./dist/cjs/index.cjs"
+      }
+    },
+    "./exact-direct/client": {
+      "import": {
+        "types": "./dist/esm/exact-direct/client/index.d.mts",
+        "default": "./dist/esm/exact-direct/client/index.mjs"
+      },
+      "require": {
+        "types": "./dist/cjs/exact-direct/client/index.d.cts",
+        "default": "./dist/cjs/exact-direct/client/index.cjs"
+      }
+    },
+    "./exact-direct/server": {
+      "import": {
+        "types": "./dist/esm/exact-direct/server/index.d.mts",
+        "default": "./dist/esm/exact-direct/server/index.mjs"
+      },
+      "require": {
+        "types": "./dist/cjs/exact-direct/server/index.d.cts",
+        "default": "./dist/cjs/exact-direct/server/index.cjs"
+      }
+    },
+    "./exact-direct/facilitator": {
+      "import": {
+        "types": "./dist/esm/exact-direct/facilitator/index.d.mts",
+        "default": "./dist/esm/exact-direct/facilitator/index.mjs"
+      },
+      "require": {
+        "types": "./dist/cjs/exact-direct/facilitator/index.d.cts",
+        "default": "./dist/cjs/exact-direct/facilitator/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "dependencies": {
+    "@t402/core": "2.3.0"
+  },
+  "peerDependencies": {
+    "@polkadot/api": ">=12.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@polkadot/api": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@polkadot/api": "^14.0.0",
+    "@types/node": "^22.0.0",
+    "@vitest/coverage-v8": "^3.2.4",
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2",
+    "vitest": "^3.2.4"
+  },
+  "keywords": [
+    "t402",
+    "polkadot",
+    "asset-hub",
+    "usdt",
+    "payments",
+    "cryptocurrency",
+    "web3"
+  ],
+  "author": "T402 Team",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/t402-io/t402.git",
+    "directory": "typescript/packages/mechanisms/polkadot"
+  },
+  "bugs": {
+    "url": "https://github.com/t402-io/t402/issues"
+  },
+  "homepage": "https://t402.io",
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  }
+}

package/src/constants.ts

@@ -0,0 +1,87 @@
+/**
+ * Polkadot Asset Hub T402 Constants
+ *
+ * Polkadot Asset Hub (formerly Statemint) is a common-good parachain
+ * that hosts assets like USDT on the Polkadot network.
+ */
+
+// CAIP-2 namespace for Polkadot
+export const POLKADOT_CAIP2_NAMESPACE = "polkadot";
+
+// CAIP-2 network identifiers (first 32 chars of genesis hash)
+// Polkadot Asset Hub (Parachain ID: 1000)
+export const POLKADOT_ASSET_HUB_CAIP2 = "polkadot:68d56f15f85d3136970ec16946040bc1";
+
+// Kusama Asset Hub (Parachain ID: 1000 on Kusama)
+export const KUSAMA_ASSET_HUB_CAIP2 = "polkadot:48239ef607d7928874027a43a67689209727dfb3d3dc5e5b03a39bdc2eda771a";
+
+// Westend Asset Hub (Testnet)
+export const WESTEND_ASSET_HUB_CAIP2 = "polkadot:e143f23803ac50e8f6f8e62695d1ce9e";
+
+// Scheme identifier
+export const SCHEME_EXACT_DIRECT = "exact-direct";
+
+// Default indexers (Subscan API)
+export const DEFAULT_POLKADOT_INDEXER = "https://assethub-polkadot.api.subscan.io";
+export const DEFAULT_KUSAMA_INDEXER = "https://assethub-kusama.api.subscan.io";
+export const DEFAULT_WESTEND_INDEXER = "https://assethub-westend.api.subscan.io";
+
+// Default RPC endpoints
+export const DEFAULT_POLKADOT_RPC = "wss://polkadot-asset-hub-rpc.polkadot.io";
+export const DEFAULT_KUSAMA_RPC = "wss://kusama-asset-hub-rpc.polkadot.io";
+export const DEFAULT_WESTEND_RPC = "wss://westend-asset-hub-rpc.polkadot.io";
+
+// Network configurations
+export interface PolkadotNetworkConfig {
+  readonly name: string;
+  readonly caip2: string;
+  readonly rpcUrl: string;
+  readonly indexerUrl: string;
+  readonly genesisHash: string;
+  readonly ss58Prefix: number;
+  readonly isTestnet: boolean;
+}
+
+export const POLKADOT_NETWORKS: Record<string, PolkadotNetworkConfig> = {
+  [POLKADOT_ASSET_HUB_CAIP2]: {
+    name: "Polkadot Asset Hub",
+    caip2: POLKADOT_ASSET_HUB_CAIP2,
+    rpcUrl: DEFAULT_POLKADOT_RPC,
+    indexerUrl: DEFAULT_POLKADOT_INDEXER,
+    genesisHash: "0x68d56f15f85d3136970ec16946040bc1752654e906147f7e43e9d539d7c3de2f",
+    ss58Prefix: 0, // Polkadot
+    isTestnet: false,
+  },
+  [KUSAMA_ASSET_HUB_CAIP2]: {
+    name: "Kusama Asset Hub",
+    caip2: KUSAMA_ASSET_HUB_CAIP2,
+    rpcUrl: DEFAULT_KUSAMA_RPC,
+    indexerUrl: DEFAULT_KUSAMA_INDEXER,
+    genesisHash: "0x48239ef607d7928874027a43a67689209727dfb3d3dc5e5b03a39bdc2eda771a",
+    ss58Prefix: 2, // Kusama
+    isTestnet: false,
+  },
+  [WESTEND_ASSET_HUB_CAIP2]: {
+    name: "Westend Asset Hub",
+    caip2: WESTEND_ASSET_HUB_CAIP2,
+    rpcUrl: DEFAULT_WESTEND_RPC,
+    indexerUrl: DEFAULT_WESTEND_INDEXER,
+    genesisHash: "0xe143f23803ac50e8f6f8e62695d1ce9e4e1d68aa36c1cd2cfd15340213f3423e",
+    ss58Prefix: 42, // Generic Substrate
+    isTestnet: true,
+  },
+};
+
+/**
+ * Get network configuration by CAIP-2 identifier
+ */
+export function getNetworkConfig(network: string): PolkadotNetworkConfig | undefined {
+  return POLKADOT_NETWORKS[network];
+}
+
+/**
+ * Check if a network identifier is a Polkadot network
+ */
+export function isPolkadotNetwork(network: string): boolean {
+  return network.startsWith(`${POLKADOT_CAIP2_NAMESPACE}:`);
+}

package/src/exact-direct/client/index.ts

@@ -0,0 +1,5 @@
+export {
+  ExactDirectPolkadotClient,
+  createExactDirectPolkadotClient,
+  type ExactDirectPolkadotClientConfig,
+} from "./scheme.js";

package/src/exact-direct/client/scheme.ts

@@ -0,0 +1,117 @@
+/**
+ * Polkadot Exact-Direct Client Scheme
+ *
+ * In the exact-direct scheme, the client executes the asset transfer directly
+ * and provides the extrinsic hash as proof of payment.
+ */
+
+import type {
+  PaymentPayload,
+  PaymentRequirements,
+  SchemeNetworkClient,
+} from "@t402/core/types";
+import type { ClientPolkadotSigner, ExactDirectPolkadotPayload } from "../../types.js";
+import { SCHEME_EXACT_DIRECT, POLKADOT_CAIP2_NAMESPACE } from "../../constants.js";
+import { getAssetId } from "../../tokens.js";
+import { isValidAddress } from "../../utils.js";
+
+/**
+ * Configuration for the exact-direct client
+ */
+export interface ExactDirectPolkadotClientConfig {
+  /** Signer for executing transactions */
+  signer: ClientPolkadotSigner;
+}
+
+/**
+ * Exact-direct client scheme for Polkadot Asset Hub
+ */
+export class ExactDirectPolkadotClient implements SchemeNetworkClient {
+  readonly scheme = SCHEME_EXACT_DIRECT;
+  private readonly signer: ClientPolkadotSigner;
+
+  constructor(config: ExactDirectPolkadotClientConfig) {
+    this.signer = config.signer;
+  }
+
+  /**
+   * Create a payment payload by executing the transfer
+   */
+  async createPaymentPayload(
+    t402Version: number,
+    requirements: PaymentRequirements,
+  ): Promise<Pick<PaymentPayload, "t402Version" | "payload">> {
+    // Validate requirements
+    this.validateRequirements(requirements);
+
+    const { network, amount, payTo, extra } = requirements;
+
+    // Get asset ID from extra or use default USDT
+    const symbol = (extra?.assetSymbol as string) || "USDT";
+    const assetId = (extra?.assetId as number) ?? getAssetId(network, symbol);
+
+    if (assetId === undefined) {
+      throw new Error(`Unknown asset ${symbol} on network ${network}`);
+    }
+
+    // Get sender address
+    const from = await this.signer.getAddress();
+
+    // Execute the transfer
+    const { extrinsicHash, blockHash, extrinsicIndex } =
+      await this.signer.transferAsset(assetId, payTo, amount);
+
+    // Build the payload
+    const polkadotPayload: ExactDirectPolkadotPayload = {
+      extrinsicHash,
+      blockHash,
+      extrinsicIndex,
+      from,
+      to: payTo,
+      amount,
+      assetId,
+    };
+
+    return {
+      t402Version,
+      payload: polkadotPayload,
+    };
+  }
+
+  /**
+   * Validate payment requirements
+   */
+  private validateRequirements(requirements: PaymentRequirements): void {
+    // Check scheme
+    if (requirements.scheme !== SCHEME_EXACT_DIRECT) {
+      throw new Error(
+        `Invalid scheme: expected ${SCHEME_EXACT_DIRECT}, got ${requirements.scheme}`,
+      );
+    }
+
+    // Check network
+    if (!requirements.network.startsWith(`${POLKADOT_CAIP2_NAMESPACE}:`)) {
+      throw new Error(`Invalid network: ${requirements.network}`);
+    }
+
+    // Check payTo address
+    if (!isValidAddress(requirements.payTo)) {
+      throw new Error(`Invalid payTo address: ${requirements.payTo}`);
+    }
+
+    // Check amount
+    const amount = BigInt(requirements.amount);
+    if (amount <= 0n) {
+      throw new Error(`Invalid amount: ${requirements.amount}`);
+    }
+  }
+}
+
+/**
+ * Create an exact-direct client for Polkadot
+ */
+export function createExactDirectPolkadotClient(
+  config: ExactDirectPolkadotClientConfig,
+): ExactDirectPolkadotClient {
+  return new ExactDirectPolkadotClient(config);
+}

package/src/exact-direct/facilitator/index.ts

@@ -0,0 +1,4 @@
+export {
+  ExactDirectPolkadotFacilitator,
+  createExactDirectPolkadotFacilitator,
+} from "./scheme.js";