@t402/tezos 2.3.0

package/dist/types-DQMtUOa_.d.ts

@@ -0,0 +1,125 @@
+import { Network } from '@t402/core/types';
+
+/**
+ * Tezos mechanism types
+ */
+
+/**
+ * Exact-direct payment payload for Tezos
+ */
+type ExactDirectTezosPayload = {
+    /** Operation hash (o...) */
+    opHash: string;
+    /** Sender address (tz1/tz2/tz3...) */
+    from: string;
+    /** Recipient address */
+    to: string;
+    /** Amount in smallest units */
+    amount: string;
+    /** FA2 contract address (KT1...) */
+    contractAddress: string;
+    /** Token ID within the FA2 contract */
+    tokenId: number;
+};
+/**
+ * Tezos signer interface for client-side operations
+ */
+interface TezosSigner {
+    /** Get the signer's address */
+    getAddress(): Promise<string>;
+    /**
+     * Execute an FA2 transfer
+     * @param contractAddress FA2 contract address
+     * @param tokenId Token ID
+     * @param to Recipient address
+     * @param amount Amount to transfer
+     * @returns Operation hash
+     */
+    transfer(contractAddress: string, tokenId: number, to: string, amount: bigint): Promise<string>;
+    /**
+     * Get token balance
+     * @param contractAddress FA2 contract address
+     * @param tokenId Token ID
+     * @param address Address to check (optional, defaults to signer address)
+     * @returns Balance in smallest units
+     */
+    getBalance(contractAddress: string, tokenId: number, address?: string): Promise<bigint>;
+}
+/**
+ * Tezos signer interface for facilitator operations
+ */
+interface FacilitatorTezosSigner {
+    /** Get facilitator addresses for a network */
+    getAddresses(network: Network): string[];
+    /**
+     * Query an operation by hash
+     * @param opHash Operation hash
+     * @returns Operation result or null if not found
+     */
+    queryOperation(opHash: string): Promise<TezosOperationResult | null>;
+    /**
+     * Get token balance for an address
+     * @param contractAddress FA2 contract address
+     * @param tokenId Token ID
+     * @param address Address to check
+     * @returns Balance as string
+     */
+    getBalance(contractAddress: string, tokenId: number, address: string): Promise<string>;
+}
+/**
+ * Tezos operation result from indexer
+ */
+interface TezosOperationResult {
+    /** Operation hash */
+    hash: string;
+    /** Block level */
+    level: number;
+    /** Timestamp */
+    timestamp: string;
+    /** Status: applied, failed, backtracked, skipped */
+    status: "applied" | "failed" | "backtracked" | "skipped";
+    /** Sender address */
+    sender: {
+        address: string;
+    };
+    /** Target contract (for contract calls) */
+    target?: {
+        address: string;
+    };
+    /** Entrypoint called */
+    entrypoint?: string;
+    /** Parameter value */
+    parameter?: unknown;
+    /** Amount transferred (in mutez for XTZ) */
+    amount?: number;
+    /** Errors if failed */
+    errors?: Array<{
+        type: string;
+        message?: string;
+    }>;
+}
+/**
+ * FA2 transfer parameter structure
+ */
+interface FA2TransferParam {
+    from_: string;
+    txs: Array<{
+        to_: string;
+        token_id: number;
+        amount: string;
+    }>;
+}
+/**
+ * Check if a string is a valid Tezos address
+ */
+declare function isValidTezosAddress(address: string): boolean;
+/**
+ * Check if a string is a valid Tezos operation hash
+ */
+declare function isValidOperationHash(opHash: string): boolean;
+/**
+ * Check if a network is a Tezos network
+ */
+declare function isTezosNetwork(network: string): boolean;
+
+export { type ExactDirectTezosPayload as E, type FacilitatorTezosSigner as F, type TezosSigner as T, type TezosOperationResult as a, type FA2TransferParam as b, isValidOperationHash as c, isTezosNetwork as d, isValidTezosAddress as i };

package/package.json

@@ -0,0 +1,100 @@
+{
+  "name": "@t402/tezos",
+  "version": "2.3.0",
+  "description": "Tezos (FA2) mechanism for T402 payment protocol",
+  "type": "module",
+  "main": "./dist/cjs/index.js",
+  "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.ts",
+        "default": "./dist/cjs/index.js"
+      }
+    },
+    "./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.ts",
+        "default": "./dist/cjs/exact-direct/client/index.js"
+      }
+    },
+    "./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.ts",
+        "default": "./dist/cjs/exact-direct/server/index.js"
+      }
+    },
+    "./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.ts",
+        "default": "./dist/cjs/exact-direct/facilitator/index.js"
+      }
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "dependencies": {
+    "@t402/core": "2.3.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.21",
+    "tsup": "^8.5.0",
+    "typescript": "^5.8.3",
+    "vitest": "^3.2.4"
+  },
+  "peerDependencies": {
+    "@taquito/taquito": "^19.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@taquito/taquito": {
+      "optional": true
+    }
+  },
+  "keywords": [
+    "t402",
+    "tezos",
+    "fa2",
+    "tzip-12",
+    "usdt",
+    "payment",
+    "blockchain"
+  ],
+  "author": "T402",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/t402-io/t402.git",
+    "directory": "typescript/packages/mechanisms/tezos"
+  },
+  "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",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  }
+}

package/src/constants.ts

@@ -0,0 +1,53 @@
+/**
+ * Tezos mechanism constants
+ */
+
+// Scheme identifiers
+export const SCHEME_EXACT_DIRECT = "exact-direct";
+
+// CAIP-2 namespace
+export const TEZOS_CAIP2_NAMESPACE = "tezos";
+
+// CAIP-2 network identifiers (derived from genesis block hash)
+export const TEZOS_MAINNET_CAIP2 = "tezos:NetXdQprcVkpaWU";
+export const TEZOS_GHOSTNET_CAIP2 = "tezos:NetXnHfVqm9iesp";
+
+// Default RPC endpoints
+export const DEFAULT_MAINNET_RPC = "https://mainnet.api.tez.ie";
+export const DEFAULT_GHOSTNET_RPC = "https://ghostnet.tezos.marigold.dev";
+
+// Default indexer API endpoints (TzKT)
+export const DEFAULT_MAINNET_INDEXER = "https://api.tzkt.io";
+export const DEFAULT_GHOSTNET_INDEXER = "https://api.ghostnet.tzkt.io";
+
+// FA2 token standard (TZIP-12)
+export const FA2_TRANSFER_ENTRYPOINT = "transfer";
+export const FA2_BALANCE_OF_ENTRYPOINT = "balance_of";
+export const FA2_UPDATE_OPERATORS_ENTRYPOINT = "update_operators";
+
+// Supported networks
+export const SUPPORTED_NETWORKS = [
+  TEZOS_MAINNET_CAIP2,
+  TEZOS_GHOSTNET_CAIP2,
+] as const;
+
+// Network configurations
+export const NETWORK_CONFIGS: Record<
+  string,
+  {
+    name: string;
+    rpcUrl: string;
+    indexerUrl: string;
+  }
+> = {
+  [TEZOS_MAINNET_CAIP2]: {
+    name: "Tezos Mainnet",
+    rpcUrl: DEFAULT_MAINNET_RPC,
+    indexerUrl: DEFAULT_MAINNET_INDEXER,
+  },
+  [TEZOS_GHOSTNET_CAIP2]: {
+    name: "Tezos Ghostnet",
+    rpcUrl: DEFAULT_GHOSTNET_RPC,
+    indexerUrl: DEFAULT_GHOSTNET_INDEXER,
+  },
+};

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

@@ -0,0 +1,13 @@
+/**
+ * Tezos Exact-Direct Client
+ */
+
+export {
+  ExactDirectTezosClient,
+  type ExactDirectTezosClientConfig,
+} from "./scheme.js";
+
+export {
+  registerExactDirectTezosClient,
+  type TezosClientConfig,
+} from "./register.js";

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

@@ -0,0 +1,71 @@
+/**
+ * Registration function for Tezos Exact-Direct client
+ */
+
+import { t402Client } from "@t402/core/client";
+import type { Network } from "@t402/core/types";
+import type { TezosSigner } from "../../types.js";
+import {
+  ExactDirectTezosClient,
+  type ExactDirectTezosClientConfig,
+} from "./scheme.js";
+
+/**
+ * Configuration options for registering Tezos schemes to a t402Client
+ */
+export interface TezosClientConfig {
+  /**
+   * The Tezos signer for payment operations
+   */
+  signer: TezosSigner;
+
+  /**
+   * Optional specific networks to register
+   * If not provided, registers wildcard support (tezos:*)
+   */
+  networks?: Network[];
+
+  /**
+   * Optional scheme configuration
+   */
+  schemeConfig?: ExactDirectTezosClientConfig;
+}
+
+/**
+ * Registers Tezos exact-direct payment scheme to a t402Client instance.
+ *
+ * @param client - The t402Client instance to register schemes to
+ * @param config - Configuration for Tezos client registration
+ * @returns The client instance for chaining
+ *
+ * @example
+ * ```typescript
+ * import { registerExactDirectTezosClient } from "@t402/tezos/exact-direct/client";
+ * import { t402Client } from "@t402/core/client";
+ *
+ * const client = new t402Client();
+ * registerExactDirectTezosClient(client, {
+ *   signer: myTezosSigner,
+ *   networks: ["tezos:NetXdQprcVkpaWU"]
+ * });
+ * ```
+ */
+export function registerExactDirectTezosClient(
+  client: t402Client,
+  config: TezosClientConfig,
+): t402Client {
+  const scheme = new ExactDirectTezosClient(config.signer, config.schemeConfig);
+
+  // Register scheme
+  if (config.networks && config.networks.length > 0) {
+    // Register specific networks
+    config.networks.forEach((network) => {
+      client.register(network, scheme);
+    });
+  } else {
+    // Register wildcard for all Tezos networks
+    client.register("tezos:*", scheme);
+  }
+
+  return client;
+}

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

@@ -0,0 +1,177 @@
+/**
+ * Tezos Exact-Direct Client Scheme
+ *
+ * The client executes the FA2 transfer directly and provides
+ * the operation hash as proof of payment.
+ */
+
+import type {
+  SchemeNetworkClient,
+  PaymentPayload,
+  PaymentRequirements,
+} from "@t402/core/types";
+import { SCHEME_EXACT_DIRECT, TEZOS_CAIP2_NAMESPACE } from "../../constants.js";
+import type { TezosSigner, ExactDirectTezosPayload } from "../../types.js";
+import { isValidTezosAddress } from "../../types.js";
+import { getTokenBySymbol } from "../../tokens.js";
+import { compareAddresses } from "../../utils.js";
+
+/**
+ * Configuration for ExactDirectTezosClient
+ */
+export interface ExactDirectTezosClientConfig {
+  /**
+   * Whether to verify the operation was successful before returning
+   * @default true
+   */
+  verifyOperation?: boolean;
+}
+
+/**
+ * Tezos Exact-Direct Client
+ *
+ * Implements the client-side payment flow where the client:
+ * 1. Receives payment requirements
+ * 2. Executes the FA2 transfer operation
+ * 3. Returns operation hash as proof
+ */
+export class ExactDirectTezosClient implements SchemeNetworkClient {
+  readonly scheme = SCHEME_EXACT_DIRECT;
+
+  constructor(
+    private readonly signer: TezosSigner,
+    config: ExactDirectTezosClientConfig = {},
+  ) {
+    // Config reserved for future use
+    void config;
+  }
+
+  /**
+   * Create a payment payload by executing the transfer
+   */
+  async createPaymentPayload(
+    t402Version: number,
+    paymentRequirements: PaymentRequirements,
+  ): Promise<Pick<PaymentPayload, "t402Version" | "payload">> {
+    // Validate requirements
+    this.validateRequirements(paymentRequirements);
+
+    // Get sender address
+    const from = await this.signer.getAddress();
+
+    // Parse asset to get contract address and token ID
+    const assetInfo = this.parseAssetIdentifier(paymentRequirements.asset);
+    if (!assetInfo) {
+      throw new Error(`Invalid asset identifier: ${paymentRequirements.asset}`);
+    }
+
+    // Get amount
+    const amount = BigInt(paymentRequirements.amount);
+
+    // Check balance
+    const balance = await this.signer.getBalance(
+      assetInfo.contractAddress,
+      assetInfo.tokenId,
+    );
+    if (balance < amount) {
+      throw new Error(
+        `Insufficient balance: have ${balance}, need ${amount}`,
+      );
+    }
+
+    // Execute transfer
+    const opHash = await this.signer.transfer(
+      assetInfo.contractAddress,
+      assetInfo.tokenId,
+      paymentRequirements.payTo,
+      amount,
+    );
+
+    // Create payload
+    const payload: ExactDirectTezosPayload = {
+      opHash,
+      from,
+      to: paymentRequirements.payTo,
+      amount: paymentRequirements.amount,
+      contractAddress: assetInfo.contractAddress,
+      tokenId: assetInfo.tokenId,
+    };
+
+    return {
+      t402Version,
+      payload,
+    };
+  }
+
+  /**
+   * Parse CAIP-19 asset identifier for Tezos FA2
+   * Format: tezos:{chainRef}/fa2:{contractAddress}/{tokenId}
+   */
+  private parseAssetIdentifier(
+    asset: string,
+  ): { contractAddress: string; tokenId: number } | null {
+    // Try parsing CAIP-19 format
+    const caipMatch = asset.match(/^tezos:[^/]+\/fa2:([^/]+)\/(\d+)$/);
+    if (caipMatch) {
+      return {
+        contractAddress: caipMatch[1],
+        tokenId: parseInt(caipMatch[2], 10),
+      };
+    }
+
+    // Try simple format: contractAddress/tokenId or just contractAddress (default tokenId 0)
+    const simpleMatch = asset.match(/^(KT1[a-zA-Z0-9]+)(?:\/(\d+))?$/);
+    if (simpleMatch) {
+      return {
+        contractAddress: simpleMatch[1],
+        tokenId: simpleMatch[2] ? parseInt(simpleMatch[2], 10) : 0,
+      };
+    }
+
+    return null;
+  }
+
+  /**
+   * 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(`${TEZOS_CAIP2_NAMESPACE}:`)) {
+      throw new Error(`Invalid network: ${requirements.network}`);
+    }
+
+    // Check payTo address
+    if (!isValidTezosAddress(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}`);
+    }
+
+    // Check asset
+    const assetInfo = this.parseAssetIdentifier(requirements.asset);
+    if (!assetInfo) {
+      throw new Error(`Invalid asset: ${requirements.asset}`);
+    }
+
+    // Verify token is supported (warn for unknown tokens)
+    const tokenConfig = getTokenBySymbol(requirements.network, "USDt");
+    if (tokenConfig && !compareAddresses(tokenConfig.contractAddress, assetInfo.contractAddress)) {
+      console.warn(
+        `Using non-standard token: ${assetInfo.contractAddress}`,
+      );
+    }
+  }
+}
+
+export default ExactDirectTezosClient;

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

@@ -0,0 +1,13 @@
+/**
+ * Tezos Exact-Direct Facilitator
+ */
+
+export {
+  ExactDirectTezosFacilitator,
+  type ExactDirectTezosFacilitatorConfig,
+} from "./scheme.js";
+
+export {
+  registerExactDirectTezosFacilitator,
+  type TezosFacilitatorConfig,
+} from "./register.js";

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

@@ -0,0 +1,74 @@
+/**
+ * Registration function for Tezos Exact-Direct facilitator
+ */
+
+import { t402Facilitator } from "@t402/core/facilitator";
+import type { Network } from "@t402/core/types";
+import type { FacilitatorTezosSigner } from "../../types.js";
+import {
+  ExactDirectTezosFacilitator,
+  type ExactDirectTezosFacilitatorConfig,
+} from "./scheme.js";
+
+/**
+ * Configuration options for registering Tezos schemes to a t402Facilitator
+ */
+export interface TezosFacilitatorConfig {
+  /**
+   * The Tezos signer for facilitator operations (verify and settle)
+   */
+  signer: FacilitatorTezosSigner;
+
+  /**
+   * Optional specific networks to register
+   * If not provided, registers wildcard support (tezos:*)
+   */
+  networks?: Network[];
+
+  /**
+   * Optional scheme configuration
+   */
+  schemeConfig?: ExactDirectTezosFacilitatorConfig;
+}
+
+/**
+ * Registers Tezos exact-direct payment schemes to a t402Facilitator instance.
+ *
+ * @param facilitator - The t402Facilitator instance to register schemes to
+ * @param config - Configuration for Tezos facilitator registration
+ * @returns The facilitator instance for chaining
+ *
+ * @example
+ * ```typescript
+ * import { registerExactDirectTezosFacilitator } from "@t402/tezos/exact-direct/facilitator";
+ * import { t402Facilitator } from "@t402/core/facilitator";
+ *
+ * const facilitator = new t402Facilitator();
+ * registerExactDirectTezosFacilitator(facilitator, {
+ *   signer: myTezosSigner,
+ *   networks: ["tezos:NetXdQprcVkpaWU"]
+ * });
+ * ```
+ */
+export function registerExactDirectTezosFacilitator(
+  facilitator: t402Facilitator,
+  config: TezosFacilitatorConfig,
+): t402Facilitator {
+  const scheme = new ExactDirectTezosFacilitator(
+    config.signer,
+    config.schemeConfig,
+  );
+
+  // Register scheme
+  if (config.networks && config.networks.length > 0) {
+    // Register specific networks
+    config.networks.forEach((network) => {
+      facilitator.register(network, scheme);
+    });
+  } else {
+    // Register wildcard for all Tezos networks
+    facilitator.register("tezos:*", scheme);
+  }
+
+  return facilitator;
+}