Coinbase Commerce Onchain Payment Protocol deep dive

Overview

Coinbase Commerce launched in 2018 and has grown to serve thousands of merchants worldwide and process billions of dollars in onchain payments. In the 5 years since launch, amazing new crypto innovations have come online allowing us to make major leaps forward to improve onchain Commerce for merchants and payers. 

Harnessing these new technologies, Commerce launched a major upgrade to address the largest merchant concerns around operational complexity (manual payment resolutions when payments are fat-fingered) and financial risk (from crypto volatility) that made it hard to accept crypto at scale. We’ve implemented the following:

• Reducing crypto volatility:  Merchants can now opt for automatic conversions to USDC, where the swapping occurs onchain via a decentralized exchange (DEX). Before a merchant receives funds, the payer's currency is exchanged for USDC, the Commerce fee is deducted from the total, and the remaining amount is deposited into the merchant’s chosen wallet. Swapping the payer’s currency on a DEX removes slippage during volatile periods, as the transaction will be executed instantly at the desired conversion rate or reversed immediately if the rate changes, allowing the payer to retry the transaction if needed.

• Payer token support: By transitioning to an onchain model, we harnessed smart contracts to facilitate the seamless swapping and transfer of tokens from payer to merchant. This change expanded the range of supported currencies from 13 to hundreds - all while ensuring settlements in USDC.

• Compliance: We understand the importance of compliance. With each Commerce version, we've enabled merchants to accept funds from KYC-verified users through Coinbase retail accounts. The Onchain Payment Protocol uses Coinbase’s internal systems to screen wallets against banned address list and OFAC sanctions, ensuring a secure environment.

How the protocol operates The core components of the Onchain Payment Protocol are Operators, TransferIntents, and the Transfers.sol smart contract. Let's explore each of these elements in detail.

What is an Operator and why are they important?

Operators act as gatekeepers and stewards of the protocol, facilitating the signing of TransferIntents and approving or denying users' access to the protocol. They can set their own fees for facilitating fund transfers from payer to merchant. Coinbase Commerce, for instance, operates as a registered Operator, providing merchants with added confidence. Operators are incentivized by fees and play a crucial role in safeguarding against malicious activity. Later, we discuss the steps one can take to become an Operator.

TransferIntents

TransferIntents serve as signed collections of transaction information, created and signed by Operators of the protocol. They are structs (akin to JavaScript objects) that encompass essential details for a transaction like the recipient, recipient amount, fees, refund destination (payer address), and others.

TransferIntents undergo two key phases: creation, hashing, and signing by an Operator, followed by providing them to payers as calldata for the Transfers.sol contract. The contract, in turn, verifies the intent's validity using a modifier called validIntent, ensuring it was signed by the Operator and aligns with the recipient field.

Transfers.sol contract

Transfers.sol is a solidity-based smart contract deployed across three networks – Base, Ethereum, and Polygon. This contract is responsible for orchestrating the fund movement from customers to merchants and consists of functions that will be called based on the merchant and customer currency preferences. Before funds are exchanged between a customer and merchant, the Transfers.sol contract first validates the Transfer Intent sent by the customer. It does so by verifying that the Operator is registered on the contract and whether the signature matches the expected hash. This verification is made possible through a cryptographic recover method on the signature.

Flexible Settlement

The Transfers.sol contract plays a pivotal role in empowering users of the Onchain Payment Protocol to engage in flexible payment and settlement processes. Flexible settlement, in this context, refers to the ability for merchants to easily add new settlement addresses or manage existing ones within their merchant dashboard settings. Any modifications to the settlement address take immediate effect upon the successful completion of a two-factor verification process.

For flexible payments, the protocol leverages Uniswap’s Permit2 token approval system and Universal Router to provide a smooth, low-cost, and consistent payment experience for users. On EVM chains, setting an allowance results in a state change thus requiring gas. Signatures on the other hand do not require gas. Permit2 allows users to bypass setting allowances by releasing tokens to a permissioned spender through a one-time signature. Much like smart order routers used in exchanges like Prime, the Universal Router optimizes trades based on the venues it communicates with. In tandem, the Permit2 and Universal Router allow for users to include a Permit2 signature with their transaction that is redeemed by the Universal Router to carry out the token swap. 

To achieve this flexibility, the Transfers contract has several methods that invoke Permit2 and Uniswap’s V3 router to transfer funds from a sender to a recipient, depending on the types of tokens being transacted. 

Become an operator

To become an Operator of the protocol, you’ll need to follow several key steps. First, Initiate your operator status by calling the contract method `registerOperator` (or `registerOperatorWithFeeDestination`). Next, create a TransferIntent object with the appropriate properties. These details define the nature of the transaction you’ll be facilitating. With the TransferIntent defined, generate a signature for a specific subset of its contents. This signature, created through an EIP-712 signature, is based on the hashed data from the provided fields. This ensures that the payer, who initiates the transaction, is the responsible party for the payment.

Lastly, provide the signed TransferIntent to the customer. Commerce handles this via our front-end client, which is designed to work with Coinbase Commerce as an Operator. When deciding to become an Operator please do this carefully. Specifically, prospective Operators must design their front-end and backend to select themselves as the Operator for a given TransferIntent, check the payer/merchant against banned address lists, and gracefully handle a user's payment.

The Onchain Payment Protocol offers a seamless and efficient solution for merchants and their customers, enabling them to transact with hundreds of cryptocurrencies while enjoying the benefits of flexible payment and settlement options. With familiar onchain user experiences and a commitment to simplifying the payment process, we're excited about the future of crypto payments. Stay tuned for more updates as we continue to evolve and empower users in the world of decentralized commerce.