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.
Celo has support for all Ethereum transaction types (i.e. "100% Ethereum compatibility") and a single Celo transaction type.
| Chain | Transaction type | # | Specification | Recommended | Support | Comment |
|---|---|---|---|---|---|---|
 |
Dynamic fee transaction | 123 |
CIP-64 | ✅ | Active 🟢 | Supports paying gas in custom fee currencies |
 |
Dynamic fee transaction | 2 |
EIP-1559 | ✅ | 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 |
| Chain | Transaction type | # | Specification | Recommended | Support | Comment |
|---|---|---|---|---|---|---|
|
Dynamic fee transaction | 124 |
CIP-42 | ❌ | Sunset 🔴 | Deprecation warning published in Gingerbread hard fork |
|
Legacy transaction | 0 |
Celo Mainnet launch (Blockchain client v1.0.0) | ❌ | Sunset 🔴 | 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.
- Sunset 🔴: the transaction type was supported in the past but will fail now.
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 v1 |
TS/JS | ✅ | ❌ | Only supported via@celo/contractkit |
||
web3 v4 |
TS/JS | ✅ | ❌ | Use @celo/web3-plugin-transaction-types | ||
@celo/contractkit |
TS/JS | ✅ | ✅ | >5.0.0 | --- | |
Web3j |
Java | ✅ | ❌ | --- | ||
rust-ethers |
Rust | ✅ | ❌ | --- | ||
brownie |
Python | ✅ | ❌ | --- |
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":
-
the transaction parameters are RLP-encoded:
RLP([nonce, gasprice, gaslimit, recipient, amount, data, chaindId, 0, 0]) -
the RLP-encoded transaction is hashed (using Keccak256).
-
the hash is signed with a private key using the ECDSA algorithm, which generates the
v,r, andssignature parameters. -
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.
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.
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.
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.
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.
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
NOTE This transaction is not compatible with Ethereum and has three Celo-specific parameters:
feecurrency,gatewayfeerecipient, andgatewayfee.
Warning This transaction type has been sunset. 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.
NOTE This transaction is not compatible with Ethereum and has three Celo-specific parameters:
feecurrency,gatewayfeerecipient, andgatewayfee.
Warning This transaction type has been sunset. Do not use. 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.
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
- 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
yarn install
# or
npm installCreate a .env file in the root directory of the project:
cp .env.example .envPaste the private key of an account that has CELO and cUSD on Alfajores into the .env file.
yarn demo
# or
npm demo$ 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.