@t402/polkadot 2.3.0

package/src/tokens.ts

@@ -0,0 +1,111 @@
+/**
+ * Polkadot Asset Hub Token Registry
+ *
+ * On Polkadot Asset Hub, tokens are identified by Asset IDs.
+ * USDT is Asset ID 1984, created by Tether.
+ */
+
+import {
+  POLKADOT_ASSET_HUB_CAIP2,
+  KUSAMA_ASSET_HUB_CAIP2,
+  WESTEND_ASSET_HUB_CAIP2,
+} from "./constants.js";
+
+/**
+ * Token configuration for Polkadot Asset Hub
+ */
+export interface TokenConfig {
+  /** Asset ID on Asset Hub */
+  readonly assetId: number;
+  /** Token symbol */
+  readonly symbol: string;
+  /** Token name */
+  readonly name: string;
+  /** Decimal places */
+  readonly decimals: number;
+  /** Issuer (creator of the asset) */
+  readonly issuer?: string;
+}
+
+/**
+ * USDT on Polkadot Asset Hub
+ * Asset ID: 1984
+ * Decimals: 6
+ */
+export const USDT_POLKADOT: TokenConfig = {
+  assetId: 1984,
+  symbol: "USDT",
+  name: "Tether USD",
+  decimals: 6,
+  issuer: "Tether",
+};
+
+/**
+ * USDT on Kusama Asset Hub
+ * Asset ID: 1984 (same as Polkadot)
+ */
+export const USDT_KUSAMA: TokenConfig = {
+  assetId: 1984,
+  symbol: "USDT",
+  name: "Tether USD",
+  decimals: 6,
+  issuer: "Tether",
+};
+
+/**
+ * Test USDT on Westend Asset Hub (testnet)
+ */
+export const USDT_WESTEND: TokenConfig = {
+  assetId: 1984,
+  symbol: "USDT",
+  name: "Test Tether USD",
+  decimals: 6,
+};
+
+/**
+ * Network-specific token registries
+ */
+export const TOKEN_REGISTRY: Record<string, Record<string, TokenConfig>> = {
+  [POLKADOT_ASSET_HUB_CAIP2]: {
+    USDT: USDT_POLKADOT,
+  },
+  [KUSAMA_ASSET_HUB_CAIP2]: {
+    USDT: USDT_KUSAMA,
+  },
+  [WESTEND_ASSET_HUB_CAIP2]: {
+    USDT: USDT_WESTEND,
+  },
+};
+
+/**
+ * Default tokens per network
+ */
+export const DEFAULT_TOKENS: Record<string, TokenConfig> = {
+  [POLKADOT_ASSET_HUB_CAIP2]: USDT_POLKADOT,
+  [KUSAMA_ASSET_HUB_CAIP2]: USDT_KUSAMA,
+  [WESTEND_ASSET_HUB_CAIP2]: USDT_WESTEND,
+};
+
+/**
+ * Get token configuration by network and symbol
+ */
+export function getTokenConfig(
+  network: string,
+  symbol: string = "USDT",
+): TokenConfig | undefined {
+  return TOKEN_REGISTRY[network]?.[symbol];
+}
+
+/**
+ * Get the default token for a network
+ */
+export function getDefaultToken(network: string): TokenConfig | undefined {
+  return DEFAULT_TOKENS[network];
+}
+
+/**
+ * Get asset ID for a token on a network
+ */
+export function getAssetId(network: string, symbol: string = "USDT"): number | undefined {
+  return getTokenConfig(network, symbol)?.assetId;
+}

package/src/types.ts

@@ -0,0 +1,151 @@
+/**
+ * Polkadot Asset Hub T402 Types
+ */
+
+import type { Network } from "@t402/core/types";
+
+/**
+ * Payment payload for exact-direct scheme on Polkadot
+ */
+export 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
+ */
+export 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
+ */
+export interface PolkadotEvent {
+  /** Module name */
+  module: string;
+  /** Event name */
+  name: string;
+  /** Event data */
+  data: Record<string, unknown>;
+}
+
+/**
+ * Parsed asset transfer from extrinsic
+ */
+export 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
+ */
+export 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
+ */
+export 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
+ */
+export interface PolkadotServerConfig {
+  /** Custom RPC URL */
+  rpcUrl?: string;
+  /** Custom indexer URL */
+  indexerUrl?: string;
+  /** Facilitator addresses per network */
+  facilitatorAddresses?: Record<string, string>;
+}
+
+/**
+ * Configuration for Polkadot facilitator
+ */
+export interface PolkadotFacilitatorConfig {
+  /** Maximum age of extrinsic to accept (in seconds) */
+  maxExtrinsicAge?: number;
+  /** Duration to cache used extrinsic hashes */
+  usedExtrinsicCacheDuration?: number;
+}

package/src/utils.ts

@@ -0,0 +1,176 @@
+/**
+ * Polkadot Asset Hub Utility Functions
+ */
+
+import type { PolkadotExtrinsicResult, ParsedAssetTransfer } from "./types.js";
+
+/**
+ * Validate a Polkadot SS58 address format
+ * SS58 addresses are base58-encoded with a checksum
+ */
+export function isValidAddress(address: string): boolean {
+  if (!address || typeof address !== "string") {
+    return false;
+  }
+
+  // SS58 addresses typically start with 1 (Polkadot), or have other prefixes
+  // Length is typically 47-48 characters for Polkadot addresses
+  // For a simple validation, check base58 characters and length
+  const base58Regex = /^[1-9A-HJ-NP-Za-km-z]{45,50}$/;
+  return base58Regex.test(address);
+}
+
+/**
+ * Validate an extrinsic hash format
+ * Extrinsic hashes are 32-byte hex strings prefixed with 0x
+ */
+export function isValidExtrinsicHash(hash: string): boolean {
+  if (!hash || typeof hash !== "string") {
+    return false;
+  }
+  return /^0x[a-fA-F0-9]{64}$/.test(hash);
+}
+
+/**
+ * Validate a block hash format
+ */
+export function isValidBlockHash(hash: string): boolean {
+  return isValidExtrinsicHash(hash); // Same format
+}
+
+/**
+ * Compare two SS58 addresses (case-sensitive)
+ */
+export function compareAddresses(addr1: string, addr2: string): boolean {
+  return addr1 === addr2;
+}
+
+/**
+ * Format an amount with decimals for display
+ */
+export function formatAmount(amount: string, decimals: number): string {
+  const amountBigInt = BigInt(amount);
+  const divisor = BigInt(10 ** decimals);
+  const wholePart = amountBigInt / divisor;
+  const fractionalPart = amountBigInt % divisor;
+
+  if (fractionalPart === 0n) {
+    return wholePart.toString();
+  }
+
+  const fractionalStr = fractionalPart.toString().padStart(decimals, "0");
+  const trimmedFractional = fractionalStr.replace(/0+$/, "");
+  return `${wholePart}.${trimmedFractional}`;
+}
+
+/**
+ * Parse an amount string to the smallest unit (with decimals applied)
+ */
+export function parseAmount(amount: string, decimals: number): string {
+  const parts = amount.split(".");
+  const wholePart = parts[0] || "0";
+  const fractionalPart = (parts[1] || "").padEnd(decimals, "0").slice(0, decimals);
+  return BigInt(wholePart + fractionalPart).toString();
+}
+
+/**
+ * Extract asset transfer details from an extrinsic result
+ */
+export function extractAssetTransfer(
+  result: PolkadotExtrinsicResult,
+): ParsedAssetTransfer | null {
+  if (!result.success) {
+    return null;
+  }
+
+  // Check if this is an assets.transfer or assets.transferKeepAlive call
+  if (result.module !== "assets") {
+    return null;
+  }
+
+  if (result.call !== "transfer" && result.call !== "transferKeepAlive") {
+    return null;
+  }
+
+  // Extract transfer details from args
+  const assetId = result.args.id as number | undefined;
+  const to = result.args.target as string | undefined;
+  const amount = result.args.amount as string | undefined;
+
+  if (assetId === undefined || !to || !amount) {
+    return null;
+  }
+
+  return {
+    assetId,
+    from: result.signer,
+    to,
+    amount: amount.toString(),
+    success: true,
+  };
+}
+
+/**
+ * Extract asset transfer from events (alternative method)
+ */
+export function extractAssetTransferFromEvents(
+  result: PolkadotExtrinsicResult,
+): ParsedAssetTransfer | null {
+  if (!result.success) {
+    return null;
+  }
+
+  // Look for assets.Transferred event
+  const transferEvent = result.events.find(
+    (e) => e.module === "assets" && e.name === "Transferred",
+  );
+
+  if (!transferEvent) {
+    return null;
+  }
+
+  const assetId = transferEvent.data.assetId as number | undefined;
+  const from = transferEvent.data.from as string | undefined;
+  const to = transferEvent.data.to as string | undefined;
+  const amount = transferEvent.data.amount as string | undefined;
+
+  if (assetId === undefined || !from || !to || !amount) {
+    return null;
+  }
+
+  return {
+    assetId,
+    from,
+    to,
+    amount: amount.toString(),
+    success: true,
+  };
+}
+
+/**
+ * Build a unique extrinsic identifier from block hash and index
+ */
+export function buildExtrinsicId(blockHash: string, extrinsicIndex: number): string {
+  return `${blockHash}-${extrinsicIndex}`;
+}
+
+/**
+ * Parse an extrinsic identifier back to components
+ */
+export function parseExtrinsicId(
+  extrinsicId: string,
+): { blockHash: string; extrinsicIndex: number } | null {
+  const lastDashIndex = extrinsicId.lastIndexOf("-");
+  if (lastDashIndex === -1) {
+    return null;
+  }
+
+  const blockHash = extrinsicId.slice(0, lastDashIndex);
+  const extrinsicIndex = parseInt(extrinsicId.slice(lastDashIndex + 1), 10);
+
+  if (!isValidBlockHash(blockHash) || isNaN(extrinsicIndex)) {
+    return null;
+  }
+
+  return { blockHash, extrinsicIndex };
+}