Skip to content

Celo tx refactor #1980

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 6 commits into from
Jul 24, 2025
Merged

Celo tx refactor #1980

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
4272134
Update overview.md: remove warning and outdated information
lvpeschke Jul 24, 2025
4e22807
Update transaction-types.mdx: correct title casing and remove outdate…
lvpeschke Jul 24, 2025
9c64331
Update transaction documentation: remove outdated warnings and improv…
lvpeschke Jul 24, 2025
e45e521
Merge branch 'main' into lvpeschke/l2-tx
lvpeschke Jul 24, 2025
9be9d3e
Fix typos
lvpeschke Jul 24, 2025
fa260b8
Merge branch 'main' into lvpeschke/l2-tx
lvpeschke Jul 24, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 4 additions & 8 deletions docs/what-is-celo/using-celo/protocol/transaction/overview.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,22 +5,18 @@ description: Introduction to transactions on Celo.

# Transactions on Celo

Introduction to transactions on Celo.
In Celo's transition to a Layer 2 (L2) solution, several key changes have been proposed to the network's tokenomics, particularly concerning gas pricing and transaction fee allocation.

---

## Gas Pricing

:::info

This section is a work in progress and based on the ["The Great Celo Halvening - Proposed Tokenomics in the Era of Celo L2"](https://forum.celo.org/t/the-great-celo-halvening-proposed-tokenomics-in-the-era-of-celo-l2/9701/1). Please check the [forum](https://forum.celo.org/) for the latest information.
:::

In Celo's transition to a Layer 2 (L2) solution, several key changes have been proposed to the network's tokenomics, particularly concerning gas pricing and transaction fee allocation.

## Gas Pricing Mechanism

Celo employs a gas pricing model based on **EIP-1559**, which dynamically adjusts the base fee to manage network demand. This mechanism ensures that gas prices respond to network congestion, increasing during high demand periods and decreasing when demand is low. The protocol sets a **base fee floor** to prevent the base fee from falling below a certain threshold, safeguarding the network against spam transactions and uncontrolled state growth.
Celo employs a gas pricing model based on **EIP-1559**, which dynamically adjusts the base fee to manage network demand. This mechanism ensures that gas prices respond to network congestion, increasing during high demand periods and decreasing when demand is low. The protocol sets a **base fee floor** to prevent the base fee from falling below a certain threshold, safeguarding the network against spam transactions and uncontrolled state growth.

## Fee Abstraction

Expand All @@ -42,10 +38,10 @@ With the shift to L2, the allocation of transaction fees has been restructured t

- **Sequencer and Batcher Operations**: Supporting the infrastructure that orders and batches transactions on the network.

- **Revenue Sharing with the OP-Stack**: Complying with the Superchain Ecosystem requirements, which involve sharing revenue with the OP-Stack.
- **Revenue Sharing with the OP-Stack**: Complying with the Superchain Ecosystem requirements, which involve sharing revenue with the OP-Stack.

This reallocation ensures that transaction fees are utilized effectively to maintain network sustainability and operational efficiency in the L2 environment.

## Conclusion

Celo's transition to L2 introduces significant changes to gas pricing and transaction fee allocation, aligning with the network's goals of sustainability, user accessibility, and robust operational support. These adjustments are designed to enhance the overall efficiency and resilience of the Celo ecosystem.
Celo's transition to L2 introduces significant changes to gas pricing and transaction fee allocation, aligning with the network's goals of sustainability, user accessibility, and robust operational support. These adjustments are designed to enhance the overall efficiency and resilience of the Celo ecosystem.
57 changes: 21 additions & 36 deletions docs/what-is-celo/using-celo/protocol/transaction/transaction-types.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
---
title: Transaction types on Celo
title: Transaction Types on Celo
description: This page contains an explainer on transaction types supported on Celo and a demo to make specific transactions.
---

Expand All @@ -8,37 +8,22 @@ import TabItem from "@theme/TabItem";

This page 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.

:::warning
As of block height 31,056,500 (March 26, 2025, 3:00 AM UTC), Celo is no longer a standalone Layer 1 blockchain—it is now an Ethereum Layer 2!
Some documentation may be outdated as updates are in progress. If you encounter issues, please [file a bug report](https://github.com/celo-org/docs/issues/new/choose).

For the most up-to-date information, refer to our [Celo L2 documentation](https://docs.celo.org/cel2).
:::
---

## Summary

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

### Actively supported on Celo
### Actively Supported on Celo

| Chain | Transaction type | # | Specification | Recommended | Support | Comment |
| ----------------------------------------------------------------------- | -------------------------- | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | --------- | -------------------------------------------------------- |
| <img width="20" src="/img/doc-images/transaction-types/Celo.jpg" /> | Dynamic fee transaction v2 | `123` | [CIP-64](https://github.com/celo-org/celo-proposals/blob/master/CIPs/cip-0064.md) | ✅ | Active 🟢 | Supports paying gas in custom fee currencies |
| <img width="20" src="/img/doc-images/transaction-types/Ethereum.png" /> | Set code transaction | `4` | [EIP-7702](https://eips.ethereum.org/EIPS/eip-7702) | Available since the Isthmus hardfork |
| <img width="20" src="/img/doc-images/transaction-types/Ethereum.png" /> | Dynamic fee transaction | `2` | [EIP-1559](https://eips.ethereum.org/EIPS/eip-1559) ([CIP-42](https://github.com/celo-org/celo-proposals/blob/master/CIPs/cip-0042.md)) | ✅ | Active 🟢 | Typical Ethereum transaction |
| <img width="20" src="/img/doc-images/transaction-types/Ethereum.png" /> | Access list transaction | `1` | [EIP-2930](https://eips.ethereum.org/EIPS/eip-2930) ([CIP-35](https://github.com/celo-org/celo-proposals/blob/master/CIPs/cip-0035.md)) | ❌ | Active 🟢 | Does not support dynamically changing _base fee_ per gas |
| <img width="20" src="/img/doc-images/transaction-types/Ethereum.png" /> | Legacy transaction | `0` | [Ethereum Yellow Paper](https://ethereum.github.io/yellowpaper/paper.pdf) ([CIP-35](https://github.com/celo-org/celo-proposals/blob/master/CIPs/cip-0035.md)) | ❌ | Active 🟢 | Does not support dynamically changing _base fee_ per gas |

### Scheduled for support on Celo

| Chain | Transaction type | # | Specification | Comment |
| ----------------------------------------------------------------------- | -------------------- | --- | --------------------------------------------------- | ----------------------------------------------------------------------- |
| <img width="20" src="/img/doc-images/transaction-types/Ethereum.png" /> | Set code transaction | `4` | [EIP-7702](https://eips.ethereum.org/EIPS/eip-7702) | Available from the [Isthmus](/cel2/notices/isthmus-upgrade.md) hardfork |

### Deprecated on Celo

| Chain | Transaction type | # | Specification | 　 Support | Comment |
Expand All @@ -53,7 +38,7 @@ The stages of support are:
because it might be deprecated in the future.
- **Deprecated** 🔴: the transaction type is not supported and not recommended for use.

### Client library support
### Client Library Support

Legend:

Expand All @@ -79,7 +64,7 @@ Legend:

## Background

### Legacy transactions
### Legacy Transactions

Ethereum originally had one format for transactions (now called "legacy transactions").
A legacy transaction contains the following transaction parameters:
Expand Down Expand Up @@ -108,7 +93,7 @@ To produce a valid "legacy transaction":
A valid signed transaction can then be submitted on-chain, and its raw parameters can be
parsed by RLP-decoding the transaction.

### Typed transactions
### Typed Transactions

Over time, the Ethereum community has sought to add new types of transactions
such as dynamic fee transactions
Expand All @@ -122,7 +107,7 @@ legacy transaction format, the concept of **typed transactions** was proposed in
[EIP-2718: Typed Transaction Envelope](https://eips.ethereum.org/EIPS/eip-2718), which introduces
a new high-level transaction format that is used to implement all future transaction types.

### Distinguishing between legacy and typed transactions
### 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
Expand Down Expand Up @@ -152,9 +137,9 @@ Every transaction type is defined in an EIP, which specifies how to _encode_ as
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
## List of Transaction Types on Celo

### <img width="12" src="/img/doc-images/transaction-types/Ethereum.png" /> Legacy transaction (`0`)
### <img width="12" src="/img/doc-images/transaction-types/Ethereum.png" /> Legacy Transaction (`0`)

:::note
This transaction type is 100% compatible with Ethereum and has no Celo-specific parameters.
Expand All @@ -177,7 +162,7 @@ they are commonly referred to as "type 0" transactions.
on [May 19, 2021](https://blog.celo.org/donut-hardfork-is-live-on-celo-585e2e294dcb)
as specified in [CIP-35: Support for Ethereum-compatible transactions](https://github.com/celo-org/celo-proposals/blob/master/CIPs/cip-0035.md).

### <img width="12" src="/img/doc-images/transaction-types/Ethereum.png" /> Access list transaction (`1`)
### <img width="12" src="/img/doc-images/transaction-types/Ethereum.png" /> Access List Transaction (`1`)

:::note
This transaction type is 100% compatible with Ethereum and has no Celo-specific parameters.
Expand All @@ -198,7 +183,7 @@ This transaction type is 100% compatible with Ethereum and has no Celo-specific
on [May 19, 2021](https://blog.celo.org/donut-hardfork-is-live-on-celo-585e2e294dcb)
as specified in [CIP-35: Support for Ethereum-compatible transactions](https://github.com/celo-org/celo-proposals/blob/master/CIPs/cip-0035.md).

### <img width="12" src="/img/doc-images/transaction-types/Ethereum.png" /> Dynamic fee transaction (`2`)
### <img width="12" src="/img/doc-images/transaction-types/Ethereum.png" /> Dynamic Fee Transaction (`2`)

:::note
This transaction type is 100% compatible with Ethereum and has no Celo-specific parameters.
Expand All @@ -219,7 +204,7 @@ This transaction type is 100% compatible with Ethereum and has no Celo-specific
on [Mar 8, 2022](https://blog.celo.org/brewing-the-espresso-hardfork-92a696af1a17) as specified
in [CIP-42: Modification to EIP-1559](https://github.com/celo-org/celo-proposals/blob/master/CIPs/cip-0042.md)

### <img width="12" src="/img/doc-images/transaction-types/Ethereum.png" /> Set code transaction (`4`)
### <img width="12" src="/img/doc-images/transaction-types/Ethereum.png" /> Set Code Transaction (`4`)

:::note
This transaction type is 100% compatible with Ethereum and has no Celo-specific parameters.
Expand All @@ -238,7 +223,7 @@ This transaction type is 100% compatible with Ethereum and has no Celo-specific
- It is scheduled for support on Celo during the
[Celo Isthmus](/cel2/notices/isthmus-upgrade.md) hardfork.

### <img width="14" src="/img/doc-images/transaction-types/Celo.jpg" /> Legacy transaction (`0`)
### <img width="14" src="/img/doc-images/transaction-types/Celo.jpg" /> Legacy Transaction (`0`)

:::danger
This transaction type is no longer supported following the migration to Celo L2.
Expand All @@ -259,7 +244,7 @@ parameters: `feecurrency`, `gatewayfeerecipient`, and `gatewayfee`.
[Apr 22, 2020](https://dune.com/queries/3106924/5185945) as specified in
[Blockchain client v1.0.0](https://github.com/celo-org/celo-blockchain/tree/celo-v1.0.0).

### <img width="14" src="/img/doc-images/transaction-types/Celo.jpg" /> Dynamic fee transaction (`124`)
### <img width="14" src="/img/doc-images/transaction-types/Celo.jpg" /> Dynamic Fee Transaction (`124`)

:::danger
This transaction type is no longer supported following the migration to Celo L2.
Expand All @@ -286,7 +271,7 @@ parameters: `feecurrency`, `gatewayfeerecipient`, and `gatewayfee`.
on [Mar 8, 2022](https://blog.celo.org/brewing-the-espresso-hardfork-92a696af1a17) as specified
in [CIP-42: Modification to EIP-1559](https://github.com/celo-org/celo-proposals/blob/master/CIPs/cip-0042.md).

### <img width="14" src="/img/doc-images/transaction-types/Celo.jpg" /> Dynamic fee transaction v2 (`123`)
### <img width="14" src="/img/doc-images/transaction-types/Celo.jpg" /> Dynamic Fee Transaction v2 (`123`)

:::warning
This transaction is not compatible with Ethereum and has one Celo-specific
Expand Down Expand Up @@ -358,7 +343,7 @@ const walletClient = createWalletClient({

</Tabs>

### Function to print Transaction receipt
### Function to Print Transaction Receipt

<Tabs>

Expand Down Expand Up @@ -403,7 +388,7 @@ const walletClient = createWalletClient({

</Tabs>

### Code to send Transaction Type (0)
### Code to Send Transaction Type (0)

<Tabs>

Expand Down Expand Up @@ -436,7 +421,7 @@ const walletClient = createWalletClient({

</Tabs>

### Code to send Transaction Type (2)
### Code to Send Transaction Type (2)

<Tabs>

Expand Down Expand Up @@ -470,7 +455,7 @@ const walletClient = createWalletClient({

</Tabs>

### Code to send Transaction Type (123)
### Code to Send Transaction Type (123)

<Tabs>

Expand Down
29 changes: 11 additions & 18 deletions docs/what-is-celo/using-celo/protocol/transaction/tx-comment-encryption.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,40 +7,33 @@ description: Overview of encrypted payment comments and its technical details re

In this section, you will find detailed information about the various transaction types supported on Celo, including encrypted payment comments and their technical details, as well as insights into gas pricing and fee abstraction.

:::warning
As of block height 31,056,500 (March 26, 2025, 3:00 AM UTC), Celo is no longer a standalone Layer 1 blockchain—it is now an Ethereum Layer 2!
Some documentation may be outdated as updates are in progress. If you encounter issues, please [file a bug report](https://github.com/celo-org/docs/issues/new/choose).

For the most up-to-date information, refer to our [Celo L2 documentation](https://docs.celo.org/cel2).
:::

---

### Introduction to Comment Encryption
## Introduction to Comment Encryption

As part of Celo's identity protocol, a public encryption key is stored along with a user's address in the `Accounts` contract.

Both the address key pair and the encryption key pair are derived from the backup phrase. When sending a transaction the encryption key of the recipient is retrieved when getting his or her address. The comment is then encrypted using a 128 bit hybrid encryption scheme \(ECDH on secp256k1 with AES-128-CTR\). This system ensures that comments can only be read by the sending and receiving parties and that messages will be recovered when restoring a wallet from its backup phrase.

### Comment Encryption Technical Details
## Comment Encryption Technical Details

A 128 bit randomly generated session key, sk, is generated and used to symmetrically encrypt the comment. sk is asymmetrically encrypted to the sender and to the recipient.

‌`Encrypted = ECIES(sk, to=pubSelf) | ECIES(sk, to=pubOther) | AES(ke=sk, km=sk, comment)`

#### ‌Symmetric Encryption \(AES-128-CTR\)
### ‌Symmetric Encryption \(AES-128-CTR\)

- Takes encryption key, ke, and MAC key, km, and the data to encrypt, plaintext
- Cipher: AES-128-CTR using a randomly generated iv
- Authenticate iv \| ciphertext using HMAC with SHA-256 and km
- Return iv \| ciphertext \| mac

#### Asymmetric Encryption \(ECIES\)
### Asymmetric Encryption \(ECIES\)

1. Takes data to encrypt, plaintext, and the public key of the recipient, pubKeyTo
2. Generate an ephemeral keypair, ephemPubKey and ephemPrivKey
3. Derive 32 bytes of key material, k, from ECDH between ephemPrivKey and pubKeyTousing ConcatKDF \(specified as NIST 800-56C Rev 1 One Step KDF\) with SHA-256 for H\(x\)
4. The encryption key, ke, is the first 128 bits of k
5. The MAC key, km, is SHA-256 of the second 128 bits of k
6. Encrypt the plaintext symmetrically with AES-128-CTR using ke, km, and a random iv
7. Return ephemPubKey \| AES-128-CTR-HMAC\(ke, km, plaintext\) where the public key needs to be uncompressed \(current limitation with decrypt\).
1. Takes data to encrypt, plaintext, and the public key of the recipient, pubKeyTo
2. Generate an ephemeral keypair, ephemPubKey and ephemPrivKey
3. Derive 32 bytes of key material, k, from ECDH between ephemPrivKey and pubKeyTousing ConcatKDF \(specified as NIST 800-56C Rev 1 One Step KDF\) with SHA-256 for H\(x\)
4. The encryption key, ke, is the first 128 bits of k
5. The MAC key, km, is SHA-256 of the second 128 bits of k
6. Encrypt the plaintext symmetrically with AES-128-CTR using ke, km, and a random iv
7. Return ephemPubKey \| AES-128-CTR-HMAC\(ke, km, plaintext\) where the public key needs to be uncompressed \(current limitation with decrypt\).