@t402/polkadot 2.3.0

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

@@ -0,0 +1,315 @@
+/**
+ * Polkadot Exact-Direct Facilitator Scheme
+ *
+ * Verifies that a Polkadot asset transfer was executed correctly
+ * by querying the Subscan indexer.
+ */
+
+import type {
+  Network,
+  PaymentPayload,
+  PaymentRequirements,
+  SchemeNetworkFacilitator,
+  SettleResponse,
+  VerifyResponse,
+} from "@t402/core/types";
+import { POLKADOT_CAIP2_NAMESPACE, SCHEME_EXACT_DIRECT, getNetworkConfig } from "../../constants.js";
+import { getDefaultToken } from "../../tokens.js";
+import type {
+  ExactDirectPolkadotPayload,
+  FacilitatorPolkadotSigner,
+  PolkadotFacilitatorConfig,
+} from "../../types.js";
+import {
+  buildExtrinsicId,
+  compareAddresses,
+  extractAssetTransfer,
+  extractAssetTransferFromEvents,
+  isValidBlockHash,
+  isValidExtrinsicHash,
+} from "../../utils.js";
+
+// Default configuration
+const DEFAULT_MAX_EXTRINSIC_AGE = 3600; // 1 hour
+const DEFAULT_CACHE_DURATION = 24 * 60 * 60 * 1000; // 24 hours in ms
+
+/**
+ * Exact-direct facilitator scheme for Polkadot Asset Hub
+ */
+export class ExactDirectPolkadotFacilitator implements SchemeNetworkFacilitator {
+  readonly scheme = SCHEME_EXACT_DIRECT;
+  readonly caipFamily = `${POLKADOT_CAIP2_NAMESPACE}:*`;
+
+  private readonly signer: FacilitatorPolkadotSigner;
+  private readonly config: Required<PolkadotFacilitatorConfig>;
+  private readonly usedExtrinsics = new Map<string, number>();
+
+  constructor(
+    signer: FacilitatorPolkadotSigner,
+    config: PolkadotFacilitatorConfig = {},
+  ) {
+    this.signer = signer;
+    this.config = {
+      maxExtrinsicAge: config.maxExtrinsicAge ?? DEFAULT_MAX_EXTRINSIC_AGE,
+      usedExtrinsicCacheDuration:
+        config.usedExtrinsicCacheDuration ?? DEFAULT_CACHE_DURATION,
+    };
+
+    // Start cleanup interval
+    this.startCleanupInterval();
+  }
+
+  /**
+   * Get extra data for payment requirements
+   */
+  getExtra(network: Network): Record<string, unknown> | undefined {
+    const config = getNetworkConfig(network);
+    if (!config) return undefined;
+
+    const token = getDefaultToken(network);
+    return {
+      assetId: token?.assetId,
+      assetSymbol: token?.symbol,
+      assetDecimals: token?.decimals,
+      networkName: config.name,
+    };
+  }
+
+  /**
+   * Get facilitator signer addresses for a network
+   */
+  getSigners(network: Network): string[] {
+    return this.signer.getAddresses(network);
+  }
+
+  /**
+   * Verify a payment payload
+   */
+  async verify(
+    payload: PaymentPayload,
+    requirements: PaymentRequirements,
+  ): Promise<VerifyResponse> {
+    const network = requirements.network;
+
+    // Validate scheme
+    if (payload.accepted.scheme !== SCHEME_EXACT_DIRECT) {
+      return {
+        isValid: false,
+        invalidReason: `invalid_scheme: expected ${SCHEME_EXACT_DIRECT}, got ${payload.accepted.scheme}`,
+      };
+    }
+
+    // Validate network
+    if (payload.accepted.network !== network) {
+      return {
+        isValid: false,
+        invalidReason: `network_mismatch: expected ${network}, got ${payload.accepted.network}`,
+      };
+    }
+
+    // Parse payload
+    const polkadotPayload = payload.payload as unknown as ExactDirectPolkadotPayload;
+
+    // Validate required fields
+    if (!polkadotPayload.extrinsicHash && !polkadotPayload.blockHash) {
+      return {
+        isValid: false,
+        invalidReason: "missing_extrinsic_identifier: need extrinsicHash or blockHash",
+      };
+    }
+
+    // Validate extrinsic hash format if provided
+    if (polkadotPayload.extrinsicHash && !isValidExtrinsicHash(polkadotPayload.extrinsicHash)) {
+      return {
+        isValid: false,
+        invalidReason: "invalid_extrinsic_hash_format",
+      };
+    }
+
+    // Validate block hash format if provided
+    if (polkadotPayload.blockHash && !isValidBlockHash(polkadotPayload.blockHash)) {
+      return {
+        isValid: false,
+        invalidReason: "invalid_block_hash_format",
+      };
+    }
+
+    if (!polkadotPayload.from) {
+      return {
+        isValid: false,
+        invalidReason: "missing_from_address",
+      };
+    }
+
+    // Build unique identifier for replay protection
+    const extrinsicId = polkadotPayload.extrinsicHash ||
+      buildExtrinsicId(polkadotPayload.blockHash, polkadotPayload.extrinsicIndex);
+
+    // Check for replay attack
+    if (this.isExtrinsicUsed(extrinsicId)) {
+      return {
+        isValid: false,
+        invalidReason: "extrinsic_already_used",
+        payer: polkadotPayload.from,
+      };
+    }
+
+    // Query extrinsic
+    const extrinsicResult = await this.signer.queryExtrinsic(
+      polkadotPayload.extrinsicHash,
+      polkadotPayload.blockHash,
+      polkadotPayload.extrinsicIndex,
+    );
+
+    if (!extrinsicResult) {
+      return {
+        isValid: false,
+        invalidReason: "extrinsic_not_found",
+        payer: polkadotPayload.from,
+      };
+    }
+
+    // Verify extrinsic was successful
+    if (!extrinsicResult.success) {
+      return {
+        isValid: false,
+        invalidReason: "extrinsic_failed",
+        payer: polkadotPayload.from,
+      };
+    }
+
+    // Check extrinsic age
+    if (this.config.maxExtrinsicAge > 0) {
+      const extrinsicTime = new Date(extrinsicResult.timestamp).getTime();
+      const age = (Date.now() - extrinsicTime) / 1000;
+      if (age > this.config.maxExtrinsicAge) {
+        return {
+          isValid: false,
+          invalidReason: `extrinsic_too_old: ${Math.round(age)} seconds`,
+          payer: polkadotPayload.from,
+        };
+      }
+    }
+
+    // Extract transfer details
+    const transfer =
+      extractAssetTransfer(extrinsicResult) ||
+      extractAssetTransferFromEvents(extrinsicResult);
+
+    if (!transfer) {
+      return {
+        isValid: false,
+        invalidReason: "not_asset_transfer",
+        payer: polkadotPayload.from,
+      };
+    }
+
+    // Verify asset ID
+    const expectedAssetId = (requirements.extra?.assetId as number) ?? polkadotPayload.assetId;
+    if (transfer.assetId !== expectedAssetId) {
+      return {
+        isValid: false,
+        invalidReason: `asset_mismatch: expected ${expectedAssetId}, got ${transfer.assetId}`,
+        payer: polkadotPayload.from,
+      };
+    }
+
+    // Verify recipient
+    if (!compareAddresses(transfer.to, requirements.payTo)) {
+      return {
+        isValid: false,
+        invalidReason: `recipient_mismatch: expected ${requirements.payTo}, got ${transfer.to}`,
+        payer: polkadotPayload.from,
+      };
+    }
+
+    // Verify amount
+    const txAmount = BigInt(transfer.amount);
+    const requiredAmount = BigInt(requirements.amount);
+    if (txAmount < requiredAmount) {
+      return {
+        isValid: false,
+        invalidReason: `insufficient_amount: expected ${requirements.amount}, got ${transfer.amount}`,
+        payer: polkadotPayload.from,
+      };
+    }
+
+    // Mark extrinsic as used
+    this.markExtrinsicUsed(extrinsicId);
+
+    return {
+      isValid: true,
+      payer: polkadotPayload.from,
+    };
+  }
+
+  /**
+   * Settle a payment (for exact-direct, the transfer is already complete)
+   */
+  async settle(
+    payload: PaymentPayload,
+    requirements: PaymentRequirements,
+  ): Promise<SettleResponse> {
+    // Verify first
+    const verifyResult = await this.verify(payload, requirements);
+
+    if (!verifyResult.isValid) {
+      return {
+        success: false,
+        errorReason: verifyResult.invalidReason || "verification_failed",
+        payer: verifyResult.payer,
+        transaction: "",
+        network: requirements.network,
+      };
+    }
+
+    const polkadotPayload = payload.payload as unknown as ExactDirectPolkadotPayload;
+
+    // For exact-direct, settlement is already complete
+    return {
+      success: true,
+      transaction: polkadotPayload.extrinsicHash ||
+        buildExtrinsicId(polkadotPayload.blockHash, polkadotPayload.extrinsicIndex),
+      network: requirements.network,
+      payer: verifyResult.payer,
+    };
+  }
+
+  /**
+   * Check if an extrinsic has been used
+   */
+  private isExtrinsicUsed(extrinsicId: string): boolean {
+    return this.usedExtrinsics.has(extrinsicId);
+  }
+
+  /**
+   * Mark an extrinsic as used
+   */
+  private markExtrinsicUsed(extrinsicId: string): void {
+    this.usedExtrinsics.set(extrinsicId, Date.now());
+  }
+
+  /**
+   * Start the cleanup interval for used extrinsics cache
+   */
+  private startCleanupInterval(): void {
+    setInterval(() => {
+      const cutoff = Date.now() - this.config.usedExtrinsicCacheDuration;
+      for (const [extrinsicId, timestamp] of this.usedExtrinsics) {
+        if (timestamp < cutoff) {
+          this.usedExtrinsics.delete(extrinsicId);
+        }
+      }
+    }, 60 * 60 * 1000); // Run every hour
+  }
+}
+
+/**
+ * Create an exact-direct facilitator for Polkadot
+ */
+export function createExactDirectPolkadotFacilitator(
+  signer: FacilitatorPolkadotSigner,
+  config: PolkadotFacilitatorConfig = {},
+): ExactDirectPolkadotFacilitator {
+  return new ExactDirectPolkadotFacilitator(signer, config);
+}

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

@@ -0,0 +1,9 @@
+export {
+  ExactDirectPolkadotServer,
+  createExactDirectPolkadotServer,
+} from "./scheme.js";
+
+export {
+  registerExactDirectPolkadotServer,
+  type PolkadotServerRegistrationConfig,
+} from "./register.js";

package/src/exact-direct/server/register.ts

@@ -0,0 +1,57 @@
+/**
+ * Registration function for Polkadot exact-direct server
+ */
+
+import { t402ResourceServer } from "@t402/core/server";
+import type { Network } from "@t402/core/types";
+import { POLKADOT_CAIP2_NAMESPACE } from "../../constants.js";
+import { ExactDirectPolkadotServer, type ExactDirectPolkadotServerConfig } from "./scheme.js";
+
+/**
+ * Configuration for registering Polkadot server schemes
+ */
+export interface PolkadotServerRegistrationConfig extends ExactDirectPolkadotServerConfig {
+  /**
+   * Optional specific networks to register
+   * If not provided, registers wildcard support (polkadot:*)
+   */
+  networks?: Network[];
+}
+
+/**
+ * Registers Polkadot exact-direct payment scheme to a t402ResourceServer instance.
+ *
+ * @param server - The t402ResourceServer instance to register schemes to
+ * @param config - Configuration for Polkadot server registration
+ * @returns The server instance for chaining
+ *
+ * @example
+ * ```typescript
+ * import { registerExactDirectPolkadotServer } from "@t402/polkadot/exact-direct/server";
+ * import { t402ResourceServer } from "@t402/core/server";
+ *
+ * const server = new t402ResourceServer();
+ * registerExactDirectPolkadotServer(server, {
+ *   networks: ["polkadot:68d56f15f85d3136970ec16946040bc1"]
+ * });
+ * ```
+ */
+export function registerExactDirectPolkadotServer(
+  server: t402ResourceServer,
+  config: PolkadotServerRegistrationConfig = {},
+): t402ResourceServer {
+  const scheme = new ExactDirectPolkadotServer(config);
+
+  // Register scheme
+  if (config.networks && config.networks.length > 0) {
+    // Register specific networks
+    config.networks.forEach((network) => {
+      server.register(network, scheme);
+    });
+  } else {
+    // Register wildcard for all Polkadot networks
+    server.register(`${POLKADOT_CAIP2_NAMESPACE}:*`, scheme);
+  }
+
+  return server;
+}

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

@@ -0,0 +1,216 @@
+/**
+ * Polkadot Exact-Direct Server Scheme
+ *
+ * Handles price parsing and payment requirement enhancement for
+ * Polkadot Asset Hub payments using the exact-direct scheme.
+ */
+
+import type {
+  SchemeNetworkServer,
+  PaymentRequirements,
+  Price,
+  AssetAmount,
+  Network,
+  MoneyParser,
+} from "@t402/core/types";
+import { SCHEME_EXACT_DIRECT, isPolkadotNetwork } from "../../constants.js";
+import { getDefaultToken, getTokenConfig, TOKEN_REGISTRY } from "../../tokens.js";
+import { parseAmount } from "../../utils.js";
+
+/**
+ * Configuration for ExactDirectPolkadotServer
+ */
+export interface ExactDirectPolkadotServerConfig {
+  /** Preferred token symbol (e.g., "USDT"). Defaults to network's default token. */
+  preferredToken?: string;
+}
+
+/**
+ * Polkadot Exact-Direct Server
+ *
+ * Implements the server-side price parsing and payment requirements enhancement.
+ */
+export class ExactDirectPolkadotServer implements SchemeNetworkServer {
+  readonly scheme = SCHEME_EXACT_DIRECT;
+  private moneyParsers: MoneyParser[] = [];
+  private config: ExactDirectPolkadotServerConfig;
+
+  constructor(config: ExactDirectPolkadotServerConfig = {}) {
+    this.config = config;
+  }
+
+  /**
+   * Register a custom money parser in the parser chain.
+   */
+  registerMoneyParser(parser: MoneyParser): ExactDirectPolkadotServer {
+    this.moneyParsers.push(parser);
+    return this;
+  }
+
+  /**
+   * Parse price into Polkadot-specific amount
+   */
+  async parsePrice(price: Price, network: Network): Promise<AssetAmount> {
+    // Validate network
+    if (!isPolkadotNetwork(network)) {
+      throw new Error(`Invalid Polkadot network: ${network}`);
+    }
+
+    // If already an AssetAmount, return it directly
+    if (typeof price === "object" && price !== null && "amount" in price) {
+      if (!price.asset) {
+        throw new Error(`Asset must be specified for AssetAmount on network ${network}`);
+      }
+      return {
+        amount: price.amount,
+        asset: price.asset,
+        extra: price.extra || {},
+      };
+    }
+
+    // Parse Money to decimal number
+    const amount = this.parseMoneyToDecimal(price);
+
+    // Try each custom money parser in order
+    for (const parser of this.moneyParsers) {
+      const result = await parser(amount, network);
+      if (result !== null) {
+        return result;
+      }
+    }
+
+    // All custom parsers returned null, use default conversion
+    return this.defaultMoneyConversion(amount, network);
+  }
+
+  /**
+   * Enhance payment requirements with Polkadot-specific details
+   */
+  async enhancePaymentRequirements(
+    paymentRequirements: PaymentRequirements,
+    supportedKind: {
+      t402Version: number;
+      scheme: string;
+      network: Network;
+      extra?: Record<string, unknown>;
+    },
+    facilitatorExtensions: string[],
+  ): Promise<PaymentRequirements> {
+    // Mark unused parameters
+    void facilitatorExtensions;
+
+    // Start with existing extra fields
+    const extra = { ...paymentRequirements.extra };
+
+    // Add any facilitator-provided extra fields
+    if (supportedKind.extra?.assetId) {
+      extra.assetId = supportedKind.extra.assetId;
+    }
+    if (supportedKind.extra?.assetSymbol) {
+      extra.assetSymbol = supportedKind.extra.assetSymbol;
+    }
+    if (supportedKind.extra?.assetDecimals) {
+      extra.assetDecimals = supportedKind.extra.assetDecimals;
+    }
+    if (supportedKind.extra?.networkName) {
+      extra.networkName = supportedKind.extra.networkName;
+    }
+
+    return {
+      ...paymentRequirements,
+      extra,
+    };
+  }
+
+  /**
+   * Parse Money (string | number) to a decimal number.
+   */
+  private parseMoneyToDecimal(money: string | number): number {
+    if (typeof money === "number") {
+      return money;
+    }
+
+    // Remove $ sign and whitespace, then parse
+    const cleanMoney = money.replace(/^\$/, "").trim();
+    const amount = parseFloat(cleanMoney);
+
+    if (isNaN(amount)) {
+      throw new Error(`Invalid money format: ${money}`);
+    }
+
+    return amount;
+  }
+
+  /**
+   * Default money conversion implementation.
+   */
+  private defaultMoneyConversion(amount: number, network: Network): AssetAmount {
+    const token = this.getDefaultAsset(network);
+
+    // Convert decimal amount to token amount
+    const tokenAmount = parseAmount(amount.toString(), token.decimals);
+
+    return {
+      amount: tokenAmount.toString(),
+      asset: this.createAssetIdentifier(network, token.assetId),
+      extra: {
+        symbol: token.symbol,
+        name: token.name,
+        decimals: token.decimals,
+        assetId: token.assetId,
+      },
+    };
+  }
+
+  /**
+   * Create a CAIP-19 asset identifier for Polkadot assets
+   */
+  private createAssetIdentifier(
+    network: Network,
+    assetId: number,
+  ): string {
+    return `${network}/asset:${assetId}`;
+  }
+
+  /**
+   * Get the default asset info for a network.
+   */
+  private getDefaultAsset(
+    network: Network,
+  ): { assetId: number; symbol: string; name: string; decimals: number } {
+    // If a preferred token is configured, try to use it
+    if (this.config.preferredToken) {
+      const preferred = getTokenConfig(network, this.config.preferredToken);
+      if (preferred) return preferred;
+    }
+
+    // Use the network's default token
+    const defaultToken = getDefaultToken(network);
+    if (defaultToken) return defaultToken;
+
+    throw new Error(`No tokens configured for network ${network}`);
+  }
+
+  /**
+   * Get all supported networks
+   */
+  static getSupportedNetworks(): string[] {
+    return Object.keys(TOKEN_REGISTRY);
+  }
+
+  /**
+   * Check if a network is supported
+   */
+  static isNetworkSupported(network: string): boolean {
+    return network in TOKEN_REGISTRY;
+  }
+}
+
+/**
+ * Create an exact-direct server for Polkadot
+ */
+export function createExactDirectPolkadotServer(
+  config: ExactDirectPolkadotServerConfig = {},
+): ExactDirectPolkadotServer {
+  return new ExactDirectPolkadotServer(config);
+}

package/src/index.ts

@@ -0,0 +1,84 @@
+/**
+ * @t402/polkadot - Polkadot Asset Hub mechanism for T402
+ *
+ * This package provides support for USDT payments on Polkadot Asset Hub
+ * using the exact-direct scheme.
+ *
+ * @example
+ * ```typescript
+ * // Client usage
+ * import { createExactDirectPolkadotClient } from '@t402/polkadot/exact-direct/client';
+ *
+ * const client = createExactDirectPolkadotClient({
+ *   signer: myPolkadotSigner,
+ * });
+ *
+ * // Server usage
+ * import { registerExactDirectPolkadotServer } from '@t402/polkadot/exact-direct/server';
+ *
+ * registerExactDirectPolkadotServer(server);
+ *
+ * // Facilitator usage
+ * import { createExactDirectPolkadotFacilitator } from '@t402/polkadot/exact-direct/facilitator';
+ *
+ * const facilitator = createExactDirectPolkadotFacilitator(signer);
+ * ```
+ */
+
+// Re-export constants
+export {
+  POLKADOT_CAIP2_NAMESPACE,
+  POLKADOT_ASSET_HUB_CAIP2,
+  KUSAMA_ASSET_HUB_CAIP2,
+  WESTEND_ASSET_HUB_CAIP2,
+  SCHEME_EXACT_DIRECT,
+  DEFAULT_POLKADOT_INDEXER,
+  DEFAULT_KUSAMA_INDEXER,
+  DEFAULT_WESTEND_INDEXER,
+  DEFAULT_POLKADOT_RPC,
+  DEFAULT_KUSAMA_RPC,
+  DEFAULT_WESTEND_RPC,
+  POLKADOT_NETWORKS,
+  getNetworkConfig,
+  isPolkadotNetwork,
+  type PolkadotNetworkConfig,
+} from "./constants.js";
+
+// Re-export token registry
+export {
+  USDT_POLKADOT,
+  USDT_KUSAMA,
+  USDT_WESTEND,
+  TOKEN_REGISTRY,
+  DEFAULT_TOKENS,
+  getTokenConfig,
+  getDefaultToken,
+  getAssetId,
+  type TokenConfig,
+} from "./tokens.js";
+
+// Re-export types
+export type {
+  ExactDirectPolkadotPayload,
+  PolkadotExtrinsicResult,
+  PolkadotEvent,
+  ParsedAssetTransfer,
+  FacilitatorPolkadotSigner,
+  ClientPolkadotSigner,
+  PolkadotServerConfig,
+  PolkadotFacilitatorConfig,
+} from "./types.js";
+
+// Re-export utilities
+export {
+  isValidAddress,
+  isValidExtrinsicHash,
+  isValidBlockHash,
+  compareAddresses,
+  formatAmount,
+  parseAmount,
+  extractAssetTransfer,
+  extractAssetTransferFromEvents,
+  buildExtrinsicId,
+  parseExtrinsicId,
+} from "./utils.js";