celo-org / txtypes

💡 Explainer and demo for transaction types on Celo

Transaction types on Celo

This repo contains an explainer on transaction types supported on Celo and a demo to make specific transactions.

IMPORTANT This repo is for educational purposes only. The information provided here may be inaccurate. Please don’t rely on it exclusively to implement low-level client libraries.

Summary

Celo has support for all Ethereum transaction types (i.e. "100% Ethereum compatibility") and a single Celo transaction type.

Actively supported on Celo

Chain	Transaction type	#	Specification	Recommended	Support	Comment
	Dynamic fee transaction v2	123	CIP-64	✅	Active 🟢	Supports paying gas in custom fee currencies
	Dynamic fee transaction	2	EIP-1559 (CIP-42)	✅	Active 🟢	Typical Ethereum transaction
	Access list transaction	1	EIP-2930 (CIP-35)	❌	Active 🟢	Does not support dynamically changing base fee per gas
	Legacy transaction	0	Ethereum Yellow Paper (CIP-35)	❌	Active 🟢	Does not support dynamically changing base fee per gas

Scheduled for deprecation on Celo

Chain	Transaction type	#	Specification	Recommended	Support	Comment
	Dynamic fee transaction	124	CIP-42	❌	Security 🟠	Deprecation warning published in Gingerbread hard fork
	Legacy transaction	0	Celo Mainnet launch (Blockchain client v1.0.0)	❌	Security 🟠	Deprecation warning published in Gingerbread hard fork

The stages of support are:

• Active support 🟢: the transaction type is supported and recommended for use.
• Security support 🟠: the transaction type is supported but not recommended for use because it might be deprecated in the future.
• Deprecated 🔴: the transaction type is not supported and not recommended for use.

Client library support

Legend:

• = support for the recommended Ethereum transaction type (2)
• = support for the recommended Celo transaction type (123)
• ✅ = available
• ❌ = not available

Client library	Language		since		since	Comment
viem	TS/JS	✅		✅	>1.19.5	---
ethers	TS/JS	✅		❌		Discussion with maintainer. Currently only supported via @celo-tools/celo-ethers-wrapper
@celo-tools/celo-ethers-wrapper	TS/JS	✅		✅	>2.0.0	---
web3	TS/JS	✅		❌		Currently only supported via @celo/contractkit
@celo/contractkit	TS/JS	✅		✅	>5.0.0	---
Web3j	Java	✅		❌		---
rust-ethers	Rust	✅		❌		---
brownie	Python	✅		❌		---

Background

Legacy transactions

Ethereum originally had one format for transactions (now called "legacy transactions"). A legacy transaction contains the following transaction parameters: nonce, gasPrice, gasLimit, recipient, amount, data, and chaindId.

To produce a valid "legacy transaction":

1. the transaction parameters are RLP-encoded:

   RLP([nonce, gasprice, gaslimit, recipient, amount, data, chaindId, 0, 0])
   

2. the RLP-encoded transaction is hashed (using Keccak256).

3. the hash is signed with a private key using the ECDSA algorithm, which generates the v, r, and s signature parameters.

4. the transaction and signature parameters above are RLP-encoded to produce a valid signed transaction:

   RLP([nonce, gasprice, gaslimit, recipient, amount, data, v, r, s])
   

A valid signed transaction can then be submitted on-chain, and its raw parameters can be parsed by RLP-decoding the transaction.

Typed transactions

Over time, the Ethereum community has sought to add new types of transactions such as dynamic fee transactions (EIP-1559: Fee market change for ETH 1.0 chain) or optional access list transactions (EIP-2930: Optional access lists) to supported new desired behaviors on the network.

To allow new transactions to be supported without breaking support with the legacy transaction format, the concept of typed transactions was proposed in EIP-2718: Typed Transaction Envelope, which introduces a new high-level transaction format that is used to implement all future transaction types.

Distinguishing between legacy and typed transactions

Whereas a valid "legacy transaction" is simply an RLP-encoded list of transaction parameters, a valid "typed transactions" is an arbitrary byte array prepended with a transaction type, where:

• a transaction type, is a number between 0 (0x00) and 127 (0x7f) representing the type of the transaction, and

• a transaction payload, is arbitrary byte data that encodes raw transaction parameters in compliance with the specified transaction type.

To distinguish between legacy transactions and typed transactions at the client level, the EIP designers observed that the first byte of a legacy transaction would never be in the range [0, 0x7f] (or [0, 127]), and instead always be in the range [0xc0, 0xfe] (or [192, 254]).

With that observation, transactions can be decoded with the following heuristic:

• read the first byte of a transaction
• if it's bigger than 0x7f (127), then it's a legacy transaction. To decode it, you must read all bytes (including the first byte just read) and interpret them as a legacy transaction.
• else, if it's smaller or equal to 0x7f (127), then it's a typed transaction. To decode it you must read the remaining bytes (excluding the first byte just read) and interpret them according to the specified transaction type.

Every transaction type is defined in an EIP, which specifies how to encode as well as decode transaction payloads. This means that a typed transaction can only be interpreted with knowledge of its transaction type and a relevant decoder.

List of transaction types on Celo

Legacy transaction (0)

NOTE This transaction type is 100% compatible with Ethereum and has no Celo-specific parameters.

Although legacy transactions are never formally prepended with the 0x00 transaction type, they are commonly referred to as "type 0" transactions.

• This transaction is defined as follows:

  RLP([nonce, gasprice, gaslimit, recipient, amount, data, v, r, s])
  

• It was introduced on Ethereum during Mainnet launch on Jul 30, 2015 as specified in the Ethereum Yellow Paper.

• It was introduced on Celo during the Celo Donut hard fork on May 19, 2021 as specified in CIP-35: Support for Ethereum-compatible transactions.

Access list transaction (1)

NOTE This transaction type is 100% compatible with Ethereum and has no Celo-specific parameters.

• This transaction is defined as follows:

  0x01 || RLP([chainId, nonce, gasPrice, gasLimit, to, value, data, accessList, signatureYParity, signatureR, signatureS])
  

• It was introduced on Ethereum during the Ethereum Berlin hard fork on Apr, 15 2021 as specified in EIP-2930: Optional access lists.

• It was introduced on Celo during the Celo Donut hard fork on May 19, 2021 as specified in CIP-35: Support for Ethereum-compatible transactions.

Dynamic fee transaction (2)

NOTE This transaction type is 100% compatible with Ethereum and has no Celo-specific parameters.

• This transaction is defined as follows:

  0x02 || RLP([chainId, nonce, maxPriorityFeePerGas, maxFeePerGas, gasLimit, to, value, data, accessList, signatureYParity, signatureR, signatureS])
  

• It was introduced on Ethereum during the Ethereum London hard fork on Aug, 5 2021 as specified in EIP-1559: Fee market change for ETH 1.0 chain.

• It was introduced on Celo during the Celo Espresso hard fork on Mar 8, 2022 as specified in CIP-42: Modification to EIP-1559

Legacy transaction (0)

NOTE This transaction is not compatible with Ethereum and has three Celo-specific parameters: feecurrency, gatewayfeerecipient, and gatewayfee.

Warning This transaction type is scheduled for deprecation. A deprecation warning was published in the Gingerbread hard fork on Sep 26, 2023.

• This transaction is defined as follows:

  RLP([nonce, gasprice, gaslimit, feecurrency, gatewayfeerecipient, gatewayfee, recipient, amount, data, v, r, s])
  

• It was introduced on Celo during Mainnet launch on Apr 22, 2020 as specified in Blockchain client v1.0.0.

Dynamic fee transaction (124)

NOTE This transaction is not compatible with Ethereum and has three Celo-specific parameters: feecurrency, gatewayfeerecipient, and gatewayfee.

Warning This transaction type is scheduled for deprecation. A deprecation warning was published in the Gingerbread hard fork on Sep 26, 2023.

• This transaction is defined as follows:

  0x7c || RLP([chain_id, nonce, max_priority_fee_per_gas, max_fee_per_gas, gas_limit, feecurrency, gatewayfeerecipient, gatewayfee, destination, amount, data, access_list, v, r, s])
  

• It was introduced on Celo during the Celo Espresso hard fork on Mar 8, 2022 as specified in CIP-42: Modification to EIP-1559.

Dynamic fee transaction v2 (123)

NOTE This transaction is not compatible with Ethereum and has one Celo-specific parameter: feecurrency.

• This transaction is defined as follows:

  0x7b || RLP([chainId, nonce, maxPriorityFeePerGas, maxFeePerGas, gasLimit, to, value, data, accessList, feeCurrency, v, r, s])
  

• It was introduced on Celo during the Celo Gingerbread hard fork on Sep 26, 2023 as specified in CIP-64: New Transaction Type: Celo Dynamic Fee v2

Demo usage

Requirements

• Celo account with 1 CELO and 1 cUSD on Alfajores (you can get free testnet tokens from faucet.celo.org)
• Node.js v18.14.2

Install dependencies

yarn install
# or
npm install

Set up environment variables

Create a .env file in the root directory of the project:

cp .env.example .env

Paste the private key of an account that has CELO and cUSD on Alfajores into the .env file.

Run the demo

yarn demo
# or
npm demo

Expected output

$ yarn demo

Initiating legacy transaction...
Transaction details: {
  type: 'legacy',
  status: 'success',
  transactionHash: '0xbf2c54cecdd4bee52967cab05286caeb2d7202d2d4cea3578e18aee9dad5af11',
  from: '0x303c22e6ef01cba9d03259248863836cb91336d5',
  to: '0x70997970c51812dc3a010c7d01b50e0d17dc79c8'
} 

Initiating dynamic fee (EIP-1559) transaction...
Transaction details: {
  type: 'eip1559',
  status: 'success',
  transactionHash: '0x63dc4d839df23a38392d74bc8876b2a1ddfe874d800d44647a476ecd2c3f4945',
  from: '0x303c22e6ef01cba9d03259248863836cb91336d5',
  to: '0x70997970c51812dc3a010c7d01b50e0d17dc79c8'
} 

Initiating custom fee currency transaction...
Transaction details: {
  type: '0x7b',
  status: 'success',
  transactionHash: '0x7d22baea5d23a8b10fa6a2b5ad49b66113f9258bd5c5ac3914f67a521fc5fc2b',
  from: '0x303c22e6ef01cba9d03259248863836cb91336d5',
  to: '0x70997970c51812dc3a010c7d01b50e0d17dc79c8'
} 

✨  Done in 23.28s.