@t402/tezos 2.3.0

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

@@ -0,0 +1,311 @@
+/**
+ * Tezos Exact-Direct Facilitator Scheme
+ *
+ * Verifies FA2 transfer operations and manages replay protection.
+ */
+
+import type {
+  SchemeNetworkFacilitator,
+  PaymentPayload,
+  PaymentRequirements,
+  VerifyResponse,
+  SettleResponse,
+  Network,
+} from "@t402/core/types";
+import { SCHEME_EXACT_DIRECT, TEZOS_CAIP2_NAMESPACE } from "../../constants.js";
+import type {
+  FacilitatorTezosSigner,
+  ExactDirectTezosPayload,
+} from "../../types.js";
+import { isValidOperationHash, isTezosNetwork } from "../../types.js";
+import {
+  compareAddresses,
+  extractFA2TransferDetails,
+} from "../../utils.js";
+import { getDefaultToken } from "../../tokens.js";
+
+/**
+ * Configuration for ExactDirectTezosFacilitator
+ */
+export interface ExactDirectTezosFacilitatorConfig {
+  /**
+   * Maximum age of operation in seconds (default: 3600 = 1 hour)
+   */
+  maxOperationAge?: number;
+
+  /**
+   * Duration to cache used operation hashes (in milliseconds)
+   */
+  usedOpCacheDuration?: number;
+}
+
+/**
+ * Tezos Exact-Direct Facilitator
+ *
+ * Implements the facilitator-side verification and settlement.
+ * For exact-direct, settlement is a no-op since client already executed.
+ */
+export class ExactDirectTezosFacilitator implements SchemeNetworkFacilitator {
+  readonly scheme = SCHEME_EXACT_DIRECT;
+  readonly caipFamily = `${TEZOS_CAIP2_NAMESPACE}:*`;
+
+  private readonly config: Required<ExactDirectTezosFacilitatorConfig>;
+  private usedOps: Map<string, number> = new Map();
+
+  constructor(
+    private readonly signer: FacilitatorTezosSigner,
+    config?: ExactDirectTezosFacilitatorConfig,
+  ) {
+    this.config = {
+      maxOperationAge: config?.maxOperationAge ?? 3600,
+      usedOpCacheDuration: config?.usedOpCacheDuration ?? 24 * 60 * 60 * 1000, // 24 hours
+    };
+
+    // Start cleanup interval
+    this.startCleanupInterval();
+  }
+
+  /**
+   * Get extra data for a supported kind
+   */
+  getExtra(network: Network): Record<string, unknown> | undefined {
+    const token = getDefaultToken(network);
+    if (!token) {
+      return undefined;
+    }
+    return {
+      assetSymbol: token.symbol,
+      assetDecimals: token.decimals,
+    };
+  }
+
+  /**
+   * 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> {
+    // Validate scheme
+    if (payload.accepted.scheme !== SCHEME_EXACT_DIRECT) {
+      return {
+        isValid: false,
+        invalidReason: "invalid_scheme",
+      };
+    }
+
+    // Validate network
+    if (!isTezosNetwork(payload.accepted.network)) {
+      return {
+        isValid: false,
+        invalidReason: "invalid_network",
+      };
+    }
+
+    // Extract Tezos-specific payload
+    const tezosPayload = payload.payload as ExactDirectTezosPayload;
+
+    // Validate operation hash format
+    if (!isValidOperationHash(tezosPayload.opHash)) {
+      return {
+        isValid: false,
+        invalidReason: "invalid_operation_hash_format",
+      };
+    }
+
+    // Check for replay attack
+    if (this.isOpUsed(tezosPayload.opHash)) {
+      return {
+        isValid: false,
+        invalidReason: "operation_already_used",
+        payer: tezosPayload.from,
+      };
+    }
+
+    try {
+      // Query operation
+      const op = await this.signer.queryOperation(tezosPayload.opHash);
+      if (!op) {
+        return {
+          isValid: false,
+          invalidReason: "operation_not_found",
+          payer: tezosPayload.from,
+        };
+      }
+
+      // Verify operation was successful
+      if (op.status !== "applied") {
+        return {
+          isValid: false,
+          invalidReason: `operation_not_applied: status is ${op.status}`,
+          payer: tezosPayload.from,
+        };
+      }
+
+      // Check operation age
+      if (this.config.maxOperationAge > 0) {
+        const opTimestamp = new Date(op.timestamp).getTime() / 1000;
+        const now = Date.now() / 1000;
+        const age = now - opTimestamp;
+        if (age > this.config.maxOperationAge) {
+          return {
+            isValid: false,
+            invalidReason: `operation_too_old: ${Math.round(age)} seconds`,
+            payer: tezosPayload.from,
+          };
+        }
+      }
+
+      // Verify it's a transfer to the correct contract
+      if (op.target?.address !== tezosPayload.contractAddress) {
+        return {
+          isValid: false,
+          invalidReason: `contract_mismatch: expected ${tezosPayload.contractAddress}, got ${op.target?.address}`,
+          payer: tezosPayload.from,
+        };
+      }
+
+      // Verify entrypoint
+      if (op.entrypoint !== "transfer") {
+        return {
+          isValid: false,
+          invalidReason: `entrypoint_mismatch: expected transfer, got ${op.entrypoint}`,
+          payer: tezosPayload.from,
+        };
+      }
+
+      // Extract transfer details from parameter
+      const transferDetails = extractFA2TransferDetails(op.parameter);
+      if (!transferDetails) {
+        return {
+          isValid: false,
+          invalidReason: "could_not_extract_transfer_details",
+          payer: tezosPayload.from,
+        };
+      }
+
+      // Verify sender
+      if (!compareAddresses(transferDetails.from, op.sender.address)) {
+        return {
+          isValid: false,
+          invalidReason: `sender_mismatch: parameter says ${transferDetails.from}, but sender is ${op.sender.address}`,
+          payer: tezosPayload.from,
+        };
+      }
+
+      // Verify recipient
+      if (!compareAddresses(transferDetails.to, requirements.payTo)) {
+        return {
+          isValid: false,
+          invalidReason: `recipient_mismatch: expected ${requirements.payTo}, got ${transferDetails.to}`,
+          payer: tezosPayload.from,
+        };
+      }
+
+      // Verify token ID
+      if (transferDetails.tokenId !== tezosPayload.tokenId) {
+        return {
+          isValid: false,
+          invalidReason: `token_id_mismatch: expected ${tezosPayload.tokenId}, got ${transferDetails.tokenId}`,
+          payer: tezosPayload.from,
+        };
+      }
+
+      // Verify amount
+      const expectedAmount = BigInt(requirements.amount);
+      const actualAmount = BigInt(transferDetails.amount);
+      if (actualAmount < expectedAmount) {
+        return {
+          isValid: false,
+          invalidReason: `insufficient_amount: expected ${expectedAmount}, got ${actualAmount}`,
+          payer: tezosPayload.from,
+        };
+      }
+
+      // Mark operation as used
+      this.markOpUsed(tezosPayload.opHash);
+
+      return {
+        isValid: true,
+        payer: transferDetails.from,
+      };
+    } catch (error) {
+      return {
+        isValid: false,
+        invalidReason: `verification_error: ${error instanceof Error ? error.message : String(error)}`,
+        payer: tezosPayload.from,
+      };
+    }
+  }
+
+  /**
+   * Settle a payment (no-op for exact-direct since client already executed)
+   */
+  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 tezosPayload = payload.payload as ExactDirectTezosPayload;
+
+    // For exact-direct, settlement is already complete
+    return {
+      success: true,
+      transaction: tezosPayload.opHash,
+      network: requirements.network,
+      payer: tezosPayload.from,
+    };
+  }
+
+  /**
+   * Check if an operation has been used
+   */
+  private isOpUsed(opHash: string): boolean {
+    return this.usedOps.has(opHash);
+  }
+
+  /**
+   * Mark an operation as used
+   */
+  private markOpUsed(opHash: string): void {
+    this.usedOps.set(opHash, Date.now());
+  }
+
+  /**
+   * Start the cleanup interval for used operations
+   */
+  private startCleanupInterval(): void {
+    setInterval(
+      () => {
+        const cutoff = Date.now() - this.config.usedOpCacheDuration;
+        for (const [opHash, usedAt] of this.usedOps.entries()) {
+          if (usedAt < cutoff) {
+            this.usedOps.delete(opHash);
+          }
+        }
+      },
+      60 * 60 * 1000,
+    ); // Cleanup every hour
+  }
+}
+
+export default ExactDirectTezosFacilitator;

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

@@ -0,0 +1,13 @@
+/**
+ * Tezos Exact-Direct Server
+ */
+
+export {
+  ExactDirectTezosServer,
+  type ExactDirectTezosServerConfig,
+} from "./scheme.js";
+
+export {
+  registerExactDirectTezosServer,
+  type TezosServerConfig,
+} from "./register.js";

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

@@ -0,0 +1,64 @@
+/**
+ * Registration function for Tezos Exact-Direct server
+ */
+
+import { t402ResourceServer } from "@t402/core/server";
+import type { Network } from "@t402/core/types";
+import {
+  ExactDirectTezosServer,
+  type ExactDirectTezosServerConfig,
+} from "./scheme.js";
+
+/**
+ * Configuration options for registering Tezos schemes to a t402ResourceServer
+ */
+export interface TezosServerConfig {
+  /**
+   * Optional specific networks to register
+   * If not provided, registers wildcard support (tezos:*)
+   */
+  networks?: Network[];
+
+  /**
+   * Optional scheme configuration
+   */
+  schemeConfig?: ExactDirectTezosServerConfig;
+}
+
+/**
+ * Registers Tezos exact-direct payment scheme to a t402ResourceServer instance.
+ *
+ * @param server - The t402ResourceServer instance to register schemes to
+ * @param config - Configuration for Tezos server registration
+ * @returns The server instance for chaining
+ *
+ * @example
+ * ```typescript
+ * import { registerExactDirectTezosServer } from "@t402/tezos/exact-direct/server";
+ * import { t402ResourceServer } from "@t402/core/server";
+ *
+ * const server = new t402ResourceServer();
+ * registerExactDirectTezosServer(server, {
+ *   networks: ["tezos:NetXdQprcVkpaWU"]
+ * });
+ * ```
+ */
+export function registerExactDirectTezosServer(
+  server: t402ResourceServer,
+  config: TezosServerConfig = {},
+): t402ResourceServer {
+  const scheme = new ExactDirectTezosServer(config.schemeConfig);
+
+  // 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 Tezos networks
+    server.register("tezos:*", scheme);
+  }
+
+  return server;
+}

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

@@ -0,0 +1,205 @@
+/**
+ * Tezos Exact-Direct Server Scheme
+ *
+ * Handles price parsing and payment requirement enhancement for
+ * Tezos FA2 payments using the exact-direct scheme.
+ */
+
+import type {
+  SchemeNetworkServer,
+  PaymentRequirements,
+  Price,
+  AssetAmount,
+  Network,
+  MoneyParser,
+} from "@t402/core/types";
+import { SCHEME_EXACT_DIRECT } from "../../constants.js";
+import { getTokenBySymbol, getDefaultToken, TOKEN_REGISTRY } from "../../tokens.js";
+import { parseAmount } from "../../utils.js";
+import { isTezosNetwork } from "../../types.js";
+
+/**
+ * Configuration for ExactDirectTezosServer
+ */
+export interface ExactDirectTezosServerConfig {
+  /** Preferred token symbol (e.g., "USDt"). Defaults to network's default token. */
+  preferredToken?: string;
+}
+
+/**
+ * Tezos Exact-Direct Server
+ *
+ * Implements the server-side price parsing and payment requirements enhancement.
+ */
+export class ExactDirectTezosServer implements SchemeNetworkServer {
+  readonly scheme = SCHEME_EXACT_DIRECT;
+  private moneyParsers: MoneyParser[] = [];
+  private config: ExactDirectTezosServerConfig;
+
+  constructor(config: ExactDirectTezosServerConfig = {}) {
+    this.config = config;
+  }
+
+  /**
+   * Register a custom money parser in the parser chain.
+   */
+  registerMoneyParser(parser: MoneyParser): ExactDirectTezosServer {
+    this.moneyParsers.push(parser);
+    return this;
+  }
+
+  /**
+   * Parse price into Tezos-specific amount
+   */
+  async parsePrice(price: Price, network: Network): Promise<AssetAmount> {
+    // Validate network
+    if (!isTezosNetwork(network)) {
+      throw new Error(`Invalid Tezos 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 Tezos-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?.assetSymbol) {
+      extra.assetSymbol = supportedKind.extra.assetSymbol;
+    }
+    if (supportedKind.extra?.assetDecimals) {
+      extra.assetDecimals = supportedKind.extra.assetDecimals;
+    }
+
+    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.contractAddress, token.tokenId),
+      extra: {
+        symbol: token.symbol,
+        name: token.name,
+        decimals: token.decimals,
+        tokenId: token.tokenId,
+      },
+    };
+  }
+
+  /**
+   * Create a CAIP-19 asset identifier for Tezos FA2
+   */
+  private createAssetIdentifier(
+    network: Network,
+    contractAddress: string,
+    tokenId: number,
+  ): string {
+    return `${network}/fa2:${contractAddress}/${tokenId}`;
+  }
+
+  /**
+   * Get the default asset info for a network.
+   */
+  private getDefaultAsset(
+    network: Network,
+  ): { contractAddress: string; tokenId: number; symbol: string; name: string; decimals: number } {
+    // If a preferred token is configured, try to use it
+    if (this.config.preferredToken) {
+      const preferred = getTokenBySymbol(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;
+  }
+}
+
+export default ExactDirectTezosServer;

package/src/index.ts

@@ -0,0 +1,32 @@
+/**
+ * @t402/tezos - Tezos (FA2) mechanism for T402 payment protocol
+ *
+ * This package provides client, server, and facilitator implementations
+ * for processing USDT payments on Tezos using the FA2 token standard (TZIP-12).
+ *
+ * @example
+ * ```typescript
+ * // Client usage
+ * import { registerExactDirectTezosClient } from "@t402/tezos/exact-direct/client";
+ *
+ * // Server usage
+ * import { registerExactDirectTezosServer } from "@t402/tezos/exact-direct/server";
+ *
+ * // Facilitator usage
+ * import { registerExactDirectTezosFacilitator } from "@t402/tezos/exact-direct/facilitator";
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+// Constants
+export * from "./constants.js";
+
+// Types
+export * from "./types.js";
+
+// Tokens
+export * from "./tokens.js";
+
+// Utilities
+export * from "./utils.js";

package/src/tokens.ts

@@ -0,0 +1,86 @@
+/**
+ * Tezos token registry
+ */
+
+import { TEZOS_MAINNET_CAIP2, TEZOS_GHOSTNET_CAIP2 } from "./constants.js";
+
+/**
+ * Token configuration for Tezos FA2 tokens
+ */
+export interface TokenConfig {
+  /** FA2 contract address (KT1...) */
+  contractAddress: string;
+  /** Token ID within the FA2 contract */
+  tokenId: number;
+  /** Token symbol */
+  symbol: string;
+  /** Token name */
+  name: string;
+  /** Token decimals */
+  decimals: number;
+}
+
+/**
+ * USDT on Tezos Mainnet
+ */
+export const USDT_MAINNET: TokenConfig = {
+  contractAddress: "KT1XnTn74bUtxHfDtBmm2bGZAQfhPbvKWR8o",
+  tokenId: 0,
+  symbol: "USDt",
+  name: "Tether USD",
+  decimals: 6,
+};
+
+/**
+ * Token registry by network
+ */
+export const TOKEN_REGISTRY: Record<string, TokenConfig[]> = {
+  [TEZOS_MAINNET_CAIP2]: [USDT_MAINNET],
+  [TEZOS_GHOSTNET_CAIP2]: [],
+};
+
+/**
+ * Default token for each network
+ */
+export const DEFAULT_TOKENS: Record<string, TokenConfig | undefined> = {
+  [TEZOS_MAINNET_CAIP2]: USDT_MAINNET,
+  [TEZOS_GHOSTNET_CAIP2]: undefined,
+};
+
+/**
+ * Get token by symbol for a network
+ */
+export function getTokenBySymbol(
+  network: string,
+  symbol: string,
+): TokenConfig | undefined {
+  const tokens = TOKEN_REGISTRY[network];
+  if (!tokens) return undefined;
+  return tokens.find(
+    (t) => t.symbol.toLowerCase() === symbol.toLowerCase(),
+  );
+}
+
+/**
+ * Get token by contract address and token ID
+ */
+export function getTokenByContract(
+  network: string,
+  contractAddress: string,
+  tokenId: number,
+): TokenConfig | undefined {
+  const tokens = TOKEN_REGISTRY[network];
+  if (!tokens) return undefined;
+  return tokens.find(
+    (t) =>
+      t.contractAddress.toLowerCase() === contractAddress.toLowerCase() &&
+      t.tokenId === tokenId,
+  );
+}
+
+/**
+ * Get default token for a network
+ */
+export function getDefaultToken(network: string): TokenConfig | undefined {
+  return DEFAULT_TOKENS[network];
+}