Transactions V2

CPN supports two versions of onchain transactions: V1 and an optional upgrade, V2 — enabling secure and compliant stablecoin settlement across Ethereum and Polygon. Both deliver the same core payment capabilities but differ in how gas fees, signing, and orchestration are managed.

Payment settlement contract and Permit2

Transactions V2 uses a payment settlement smart contract that allows you to send verified payments to the BFI that are authorized by you, an attester (CPN), and (optionally) the BFI. The contract ensures that the transaction is accurate and correct, and can serve as proof of payment after the transaction has settled.

Unlike Transactions V1, which uses EIP-3009 for token approvals, the payment settlement contract uses the Permit2 contract, Uniswap's universal token approval system. Permit2 makes integrations more straightforward by using gasless, offchain signatures for token transfers. Permit2 permits are signature-based, time-bound, and single-use.

The payment settlement smart contract uses Permit2 to execute funds transfer from your wallet to the recipient wallet in a single contract execution. In practice, this means that you sign an EIP-712 typed-data message of the PermitWitnessTransferFrom method call to allow the payment settlement smart contract to transfer USDC out of your wallet and into the recipient wallet.

{
  "types": {
    "EIP712Domain": [
      {
        "name": "name",
        "type": "string"
      },
      {
        "name": "chainId",
        "type": "uint256"
      },
      {
        "name": "verifyingContract",
        "type": "address"
      }
    ],
    "PermitWitnessTransferFrom": [
      { "name": "permitted", "type": "TokenPermissions" },
      { "name": "spender", "type": "address" },
      { "name": "nonce", "type": "uint256" },
      { "name": "deadline", "type": "uint256" },
      { "name": "witness", "type": "PaymentIntent" }
    ],
    "TokenPermissions": [
      { "name": "token", "type": "address" },
      { "name": "amount", "type": "uint256" }
    ],
    "PaymentIntent": [
      { "name": "from", "type": "address" },
      { "name": "to", "type": "address" },
      { "name": "value", "type": "uint256" },
      { "name": "validAfter", "type": "uint256" },
      { "name": "validBefore", "type": "uint256" },
      { "name": "nonce", "type": "bytes32" },
      { "name": "beneficiary", "type": "address" },
      { "name": "maxFee", "type": "uint256" },
      { "name": "requirePayeeSign", "type": "bool" },
      { "name": "attester", "type": "address" }
    ]
  },
  "domain": {
    "name": "Permit2",
    "chainId": 11155111,
    "verifyingContract": "PERMIT2_ADDRESS"
  },
  "message": {
    "permitted": {
      "token": "0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238",
      "amount": "100050000"
    },
    "spender": "CPN_SMART_CONTRACT_ADDRESS",
    "nonce": "0",
    "deadline": "1234567890",
    "witness": {
      "from": "OFI_PAYER_ADDRESS",
      "to": "BFI_PAYEE_ADDRESS",
      "value": "100000000",
      "validAfter": "0",
      "validBefore": "1234567890",
      "nonce": "ONCHAIN_PAYMENT_REF",
      "beneficiary": "CIRCLE_BENEFICIARY_ADDRESS",
      "maxFee": "50000",
      "requirePayeeSign": false,
      "attester": "CPN_WALLET_ADDRESS"
    }
  },
  "primaryType": "PermitWitnessTransferFrom"
}

Permit2 allowance

The use of Permit2 requires you to grant an allowance of USDC to the Permit2 contract ahead of the payment. This allowance grants the Permit2 contract permission to transfer USDC from your wallet in a CPN settlement. When you sign a CPN transaction, that transaction allows the payment settlement contract to consume the USDC allowance previously granted to Permit2.

The allowance amount can be set to a specific value based on the expected payment volume or to the maximum uint256 value for unlimited transfers. The allowance is the foundational authorization that makes the entire CPN payment settlement system possible through Permit2's signature-based transfer mechanism.

Transactions V2 provides gas abstraction which removes the requirement for you to pay native tokens for gas fees during transaction broadcast. This provides a lower-complexity operational model for you by eliminating the need to acquire and maintain a native token balance in your wallet.

When a Transaction V2 quote is created, the fees field includes a fixed gas fee denoted in USDC. This gas fee is valid as long as the payment remains active. During transaction settlement, the payment settlement smart contract withdraws the fee amount from your wallet and distributes it to the beneficiary.

The transaction fee you pay is fixed regardless of fluctuations of the native blockchain gas fee levels. CPN ensures that the transaction gets broadcast accurately and on time. This removes the need for manual acceleration and monitoring by delegating it to CPN.