CCTP on Stellar

import { StrKey } from "@stellar/stellar-sdk";

/**
 * Validates that the input is a Stellar contract address (C…) and decodes it
 * to a 0x-prefixed bytes32 hex string suitable for EVM contract calls.
 *
 * @param strkey - Stellar contract address (C…)
 * @returns 0x-prefixed 64-character hex string
 * @throws If the input is not a valid contract address
 */
function contractStrkeyToBytes32(strkey: string): `0x${string}` {
  if (!StrKey.isValidContract(strkey)) {
    throw new Error(`Invalid contract strkey: ${strkey}`);
  }
  return `0x${Buffer.from(StrKey.decodeContract(strkey)).toString("hex")}`;
}

/**
 * Builds the hookData buffer for a CCTP Forwarder burn message.
 *
 * Hook data layout:
 *   bytes  0–23: reserved (zeroed)
 *   bytes 24–27: hook data version (u32 BE, currently 0)
 *   bytes 28–31: forward_recipient byte length (u32 BE)
 *   bytes 32+  : forward_recipient (UTF-8 encoded Stellar strkey)
 *
 * @param forwardRecipientStrkey - Stellar strkey of the final token recipient (C…, G…, or M…)
 * @returns Hook data as a 0x-prefixed hex string
 */
function buildCctpForwarderHookData(
  forwardRecipientStrkey: string,
): `0x${string}` {
  const isValid =
    StrKey.isValidEd25519PublicKey(forwardRecipientStrkey) ||
    StrKey.isValidContract(forwardRecipientStrkey) ||
    StrKey.isValidMed25519PublicKey(forwardRecipientStrkey);
  if (!isValid) {
    throw new Error(
      `Invalid forward recipient: ${forwardRecipientStrkey} (expected G..., C..., or M... address)`,
    );
  }

  const recipientBytes = Buffer.from(forwardRecipientStrkey, "utf8");
  const hookData = Buffer.alloc(32 + recipientBytes.length);
  hookData.writeUInt32BE(0, 24); // hook version = 0
  hookData.writeUInt32BE(recipientBytes.length, 28); // recipient byte length
  recipientBytes.copy(hookData, 32); // recipient strkey as UTF-8
  return `0x${hookData.toString("hex")}`;
}

interface DepositForBurnWithHookParams {
  amount: bigint;
  destinationDomain: number;
  mintRecipient: `0x${string}`;
  burnToken: `0x${string}`;
  destinationCaller: `0x${string}`;
  maxFee: bigint;
  minFinalityThreshold: number;
  hookData: `0x${string}`;
}

/**
 * Prepares all arguments for an EVM `depositForBurnWithHook` call targeting
 * Stellar via the CCTP Forwarder. Converts Stellar strkeys to 0x-prefixed
 * bytes32 hex strings and encodes the hook data.
 *
 * @param amount - Token amount to burn (in EVM token decimals)
 * @param cctpForwarderStrkey - Stellar strkey of the CCTP Forwarder contract (C…), used as mintRecipient and destinationCaller
 * @param burnToken - EVM address of the token to burn
 * @param maxFee - Maximum fee for the burn
 * @param minFinalityThreshold - Minimum finality threshold (1000 = fast, 2000 = standard)
 * @param forwardRecipientStrkey - Stellar strkey of the final token recipient (C…, G…, or M…), encoded in hookData
 */
function prepareEvmDepositForBurnWithHookToStellar(
  amount: bigint,
  cctpForwarderStrkey: string,
  burnToken: `0x${string}`,
  maxFee: bigint,
  minFinalityThreshold: number,
  forwardRecipientStrkey: string,
): DepositForBurnWithHookParams {
  const cctpForwarderHex = contractStrkeyToBytes32(cctpForwarderStrkey);
  const hookData = buildCctpForwarderHookData(forwardRecipientStrkey);

  return {
    amount,
    destinationDomain: 27,
    mintRecipient: cctpForwarderHex,
    burnToken,
    destinationCaller: cctpForwarderHex,
    maxFee,
    minFinalityThreshold,
    hookData,
  };
}

{
  "messages": [
    {
      "message": "0x...",
      "eventNonce": "0",
      "attestation": "0x...",
      "cctpVersion": 2,
      "status": "complete",
      "decodedMessage": {
        "sourceDomain": "0",
        "destinationDomain": "27",
        "nonce": "0x0000000000000000000000000000000000000000000000000000000000000000",
        "sender": null,
        "recipient": null,
        "destinationCaller": null,
        "minFinalityThreshold": "1000",
        "finalityThresholdExecuted": "2000",
        "messageBody": "0x...",
        "decodedMessageBody": {
          "burnToken": null,
          "mintRecipient": null,
          "amount": "1000000",
          "messageSender": null,
          "maxFee": "0",
          "feeExecuted": "0",
          "expirationBlock": "0",
          "hookData": null
        }
      }
    }
  ]
}