From 529aab4c820e23c5c24a7ca40289d5866cea4f57 Mon Sep 17 00:00:00 2001 From: Paul Lange Date: Mon, 24 Aug 2026 16:57:55 +0200 Subject: [PATCH 1/7] docs: add Legacy-tab successor pages (celo-l1, staking group, metadata, bridge guides, operator FAQ) --- docs.json | 29 +++- .../bridging-celo-from-ethereum.mdx | 155 ++++++++++++++++++ .../withdrawing-celo-to-ethereum.mdx | 153 +++++++++++++++++ home/celo-l1.mdx | 58 +++++++ home/protocol/metadata.mdx | 63 +++++++ home/protocol/staking/index.mdx | 36 ++++ .../staking/key-management/detailed.mdx | 97 +++++++++++ .../staking/key-management/key-rotation.mdx | 49 ++++++ .../staking/key-management/summary.mdx | 35 ++++ home/protocol/staking/locked-celo.mdx | 74 +++++++++ home/protocol/staking/validator-elections.mdx | 64 ++++++++ home/protocol/staking/validator-groups.mdx | 72 ++++++++ home/protocol/staking/voting.mdx | 93 +++++++++++ infra-partners/operators/faq.mdx | 101 ++++++++++++ 14 files changed, 1076 insertions(+), 3 deletions(-) create mode 100644 home/bridged-tokens/bridging-celo-from-ethereum.mdx create mode 100644 home/bridged-tokens/withdrawing-celo-to-ethereum.mdx create mode 100644 home/celo-l1.mdx create mode 100644 home/protocol/metadata.mdx create mode 100644 home/protocol/staking/index.mdx create mode 100644 home/protocol/staking/key-management/detailed.mdx create mode 100644 home/protocol/staking/key-management/key-rotation.mdx create mode 100644 home/protocol/staking/key-management/summary.mdx create mode 100644 home/protocol/staking/locked-celo.mdx create mode 100644 home/protocol/staking/validator-elections.mdx create mode 100644 home/protocol/staking/validator-groups.mdx create mode 100644 home/protocol/staking/voting.mdx create mode 100644 infra-partners/operators/faq.mdx diff --git a/docs.json b/docs.json index 1c7808df7..bc1a8a195 100644 --- a/docs.json +++ b/docs.json @@ -46,6 +46,7 @@ "pages": [ "home/index", "home/history", + "home/celo-l1", "home/wallets", "home/exchanges", "home/gas-fees", @@ -54,7 +55,9 @@ "group": "Bridging", "pages": [ "home/bridged-tokens/bridges", - "home/bridged-tokens/native-ETH-bridging" + "home/bridged-tokens/native-ETH-bridging", + "home/bridged-tokens/bridging-celo-from-ethereum", + "home/bridged-tokens/withdrawing-celo-to-ethereum" ] } ] @@ -66,7 +69,8 @@ "home/protocol/security-council", "home/protocol/celo-token", "home/protocol/escrow", - "home/protocol/challengers" + "home/protocol/challengers", + "home/protocol/metadata" ] }, { @@ -89,6 +93,24 @@ "home/protocol/transactions/transaction-types" ] }, + { + "group": "Staking", + "pages": [ + "home/protocol/staking/index", + "home/protocol/staking/locked-celo", + "home/protocol/staking/validator-elections", + "home/protocol/staking/validator-groups", + "home/protocol/staking/voting", + { + "group": "Key Management", + "pages": [ + "home/protocol/staking/key-management/summary", + "home/protocol/staking/key-management/detailed", + "home/protocol/staking/key-management/key-rotation" + ] + } + ] + }, { "group": "Epoch Rewards", "pages": [ @@ -421,7 +443,8 @@ "pages": [ "infra-partners/operators/overview", "infra-partners/operators/architecture", - "infra-partners/operators/run-node" + "infra-partners/operators/run-node", + "infra-partners/operators/faq" ] }, { diff --git a/home/bridged-tokens/bridging-celo-from-ethereum.mdx b/home/bridged-tokens/bridging-celo-from-ethereum.mdx new file mode 100644 index 000000000..fe8602523 --- /dev/null +++ b/home/bridged-tokens/bridging-celo-from-ethereum.mdx @@ -0,0 +1,155 @@ +--- +title: Bridging CELO from Ethereum +description: Programmatically bridge CELO from Ethereum to Celo through the native OptimismPortal bridge using the viem OP Stack +--- + +This guide is for developers who want to bridge CELO from Ethereum to Celo programmatically with the [viem OP Stack](https://viem.sh/op-stack). CELO is an ERC-20 token on Ethereum, so unlike a stock OP Stack chain the deposit goes through `depositERC20Transaction` rather than a plain value deposit. If you just want to bridge with a UI, use [Superbridge](/home/bridged-tokens/bridges). + +The example below runs against the testnets, bridging CELO from Ethereum Sepolia to Celo Sepolia. + +## Steps to bridge CELO + +Before transferring tokens, you must authorize the `OptimismPortalProxy` contract to spend CELO on your behalf. Without this approval, the bridging transaction cannot proceed. + +Call the [`depositERC20Transaction`](https://viem.sh/op-stack/actions/depositTransaction#deposittransaction) function on the `OptimismPortalProxy` contract on Ethereum Sepolia. This function moves CELO tokens from your account to Celo Sepolia. + +## Code example + +The following example demonstrates how to configure a file with all the details you need for interacting with Celo Sepolia. + + + + + ```js index.js + import { createWalletClient, createPublicClient, http, parseEther } from "viem"; + import { privateKeyToAccount } from "viem/accounts"; + import { celoSepolia, sepolia } from "viem/chains"; + import { getL2TransactionHashes, publicActionsL2 } from "viem/op-stack"; + + // Ethereum Sepolia (11155111), CELO token (CeloTokenProxy), 18 decimals + const CELOL1 = "0x3c7011fd5e6aed460caa4985cf8d8caba435b092"; + + // Ethereum Sepolia (11155111), portal for Celo Sepolia + // https://docs.celo.org/tooling/contracts/l1-contracts + const OptimismPortalProxy = "0x44ae3d41a335a7d05eb533029917aad35662dcc2"; + + const account = privateKeyToAccount( + "...", + ); + + export const walletClientL1 = createWalletClient({ + account, + chain: sepolia, + transport: http(), + }); + + export const publicClientL1 = createPublicClient({ + account, + chain: sepolia, + transport: http(), + }); + + export const publicClientL2 = createPublicClient({ + chain: celoSepolia, + transport: http(), + }).extend(publicActionsL2()); + + async function main() { + // Approve OptimismPortal to pull CELO on Sepolia + const approve = await walletClientL1.writeContract({ + address: CELOL1, + abi: [ + { + inputs: [ + { name: "spender", type: "address" }, + { name: "amount", type: "uint256" }, + ], + name: "approve", + type: "function", + }, + ], + functionName: "approve", + args: [OptimismPortalProxy, parseEther("0.0001")], + }); + + console.log(`Approval TX Hash: ${approve}`); + + let approveReceipt = await publicClientL1.waitForTransactionReceipt({ + hash: approve, + }); + console.log(`Approve Transaction Receipt: ${approveReceipt}`); + + // Call depositERC20Transaction on OptimismPortal + const deposit = await walletClientL1.writeContract({ + address: OptimismPortalProxy, + abi: [ + { + inputs: [ + { + name: "_to", + type: "address", + }, + { + name: "mint", + type: "uint256", + }, + { + name: "_value", + type: "uint256", + }, + { + name: "_gasLimit", + type: "uint64", + }, + { + name: "_isCreation", + type: "bool", + }, + { + name: "_data", + type: "bytes", + }, + ], + name: "depositERC20Transaction", + type: "function", + }, + ], + functionName: "depositERC20Transaction", + args: [ + account.address, // Account where you want to receive CELO on L2 + parseEther("0.0001"), // Amount you are transferring to the Portal + parseEther("0.0001"), // Amount you want on L2 + 100_000, // Amount of L2 gas to purchase by burning gas on L1. + false, // Whether the transaction is a contract creation + "", // Data to trigger the recipient with + ], + }); + + console.log(`Deposit Transaction: ${deposit}`); + + + let depositReceipt = await publicClientL1.waitForTransactionReceipt({ + hash: deposit, + }); + console.log(`Deposit Transaction Receipt: ${depositReceipt}`); + + // Get the L2 transaction hash from the L1 transaction receipt. + const [l2Hash] = getL2TransactionHashes(depositReceipt); + + // Wait for the L2 transaction to be processed. + const l2Receipt = await publicClientL2.waitForTransactionReceipt({ + hash: l2Hash, + }); + + console.log(`L2Receipt: ${l2Receipt}`); + } + + main(); + ``` + + +## Related + +- [Withdrawing CELO to Ethereum](/home/bridged-tokens/withdrawing-celo-to-ethereum) - the reverse direction, through the three-step withdrawal flow +- [Bridges](/home/bridged-tokens/bridges) - bridge UIs, including Superbridge for mainnet +- [L1 contracts](/tooling/contracts/l1-contracts) - the portal and token addresses for mainnet and Celo Sepolia diff --git a/home/bridged-tokens/withdrawing-celo-to-ethereum.mdx b/home/bridged-tokens/withdrawing-celo-to-ethereum.mdx new file mode 100644 index 000000000..1e6fd3c77 --- /dev/null +++ b/home/bridged-tokens/withdrawing-celo-to-ethereum.mdx @@ -0,0 +1,153 @@ +--- +title: Withdrawing CELO to Ethereum +description: Programmatically withdraw CELO from Celo back to Ethereum through the native bridge using the viem OP Stack +--- + +This guide is for developers who want to withdraw CELO from Celo back to Ethereum programmatically with the [viem OP Stack](https://viem.sh/op-stack). If you just want to bridge with a UI, use [Superbridge](/home/bridged-tokens/bridges). + +The example below runs against the testnets, withdrawing CELO from Celo Sepolia to Ethereum Sepolia. + +## Steps to withdraw CELO + +Withdrawals require the user to submit three transactions: + +1. [Withdrawal initiating a transaction](https://viem.sh/op-stack/actions/initiateWithdrawal), which the user submits on L2. +2. [Withdrawal proving transaction](https://viem.sh/op-stack/actions/proveWithdrawal), which the user submits on L1 to prove that the withdrawal is legitimate. +3. [Withdrawal finalizing transaction](https://viem.sh/op-stack/actions/finalizeWithdrawal), which the user submits on L1 after the fault challenge period has passed, to actually run the transaction on L1. + +## Code example + +The following example demonstrates how to configure a file with all the details you need for interacting with Celo Sepolia. + + + ```js index.js + import { + createPublicClient, + createWalletClient, + http, + parseEther, + } from "viem"; + import { privateKeyToAccount } from "viem/accounts"; + import { celoSepolia, sepolia } from "viem/chains"; + import { + publicActionsL1, + walletActionsL2, + walletActionsL1, + publicActionsL2, + } from "viem/op-stack"; + + const account = privateKeyToAccount( + "[PRIVATE_KEY]", + ); + + const value = parseEther("0.0001"); // Amount to Withdraw + + export const publicClientL1 = createPublicClient({ + chain: sepolia, + transport: http(), + }).extend(publicActionsL1()); + + export const publicClientL2 = createPublicClient({ + chain: celoSepolia, + transport: http(), + }).extend(publicActionsL2()); + + export const walletClientL1 = createWalletClient({ + chain: sepolia, + transport: http(), + account, + }).extend(walletActionsL1()); + + export const walletClientL2 = createWalletClient({ + chain: celoSepolia, + transport: http(), + account, + }).extend(walletActionsL2()); + + export default async function main() { + console.log("Building Initiate Withdrawal..."); + const args = await publicClientL1.buildInitiateWithdrawal({ + account, + to: account.address, // Receive on the same address on L1. + value, + }); + + console.log("Initiaiting Withdrawal..."); + const hash = await walletClientL2.initiateWithdrawal(args); + + const initiateWithdrawalReceipt = await publicClientL2.waitForTransactionReceipt({ + hash + }); + console.log(`Withdrawal Initiated: ${initiateWithdrawalReceipt}`); + + /** + * The below step can take upto 2 hours! + * + * Hence, you may want to use viem's `getTimeToProve`. + * + * https://viem.sh/op-stack/actions/getTimeToProve + * + * Store the wait time in a database + * and let the user know to come back later. + * + * */ + console.log("Waiting to prove..."); + const { output, withdrawal } = await publicClientL1.waitToProve({ + receipt: initiateWithdrawalReceipt, + targetChain: walletClientL2.chain, + }); + + console.log("Building Prove Withdrawal..."); + const proveArgs = await publicClientL2.buildProveWithdrawal({ + output, + withdrawal, + }); + + console.log("Proving Withdrawal..."); + const proveHash = await walletClientL1.proveWithdrawal(proveArgs); + + const proveReceipt = await publicClientL1.waitForTransactionReceipt({ + hash: proveHash, + }); + console.log(`Withdrawal Proved: ${proveReceipt}`); + + /** + * The below step can take a few minutes, ideally 2 minutes. + * + * Hence, you may want to use viem's `getTimeToFinalize`. + * + * https://viem.sh/op-stack/actions/getTimeToFinalize + * + * Store the wait time in a database + * and let the user know to come back later. + * + * + */ + console.log("Waiting To Finalize..."); + await publicClientL1.waitToFinalize({ + targetChain: walletClientL2.chain, + withdrawalHash: withdrawal.withdrawalHash, + }); + + console.log("Finalizing Withdrawal..."); + const finalizeWithdrawalHash = await walletClientL1.finalizeWithdrawal({ + targetChain: walletClientL2.chain, + withdrawal, + }); + + const finalizeWithdrawalReceipt = await publicClientL1.waitForTransactionReceipt({ + hash: finalizeWithdrawalHash, + }); + console.log(`Withdrawal Finalized: ${finalizeWithdrawalReceipt}`) + } + + + ``` + + + +## Related + +- [Bridging CELO from Ethereum](/home/bridged-tokens/bridging-celo-from-ethereum) - the deposit direction +- [Bridges](/home/bridged-tokens/bridges) - bridge UIs, including Superbridge for mainnet +- [L1 contracts](/tooling/contracts/l1-contracts) - the portal and token addresses for mainnet and Celo Sepolia diff --git a/home/celo-l1.mdx b/home/celo-l1.mdx new file mode 100644 index 000000000..371b3fea4 --- /dev/null +++ b/home/celo-l1.mdx @@ -0,0 +1,58 @@ +--- +title: "About Celo L1" +sidebarTitle: "Celo L1" +description: What the Celo Layer 1 blockchain was, how it worked, and what changed when Celo became an Ethereum Layer 2 in March 2025 +--- + +This page is a historical reference for anyone who wants to understand Celo's original Layer 1 blockchain, or who followed a link to a page about a mechanism that no longer exists. Celo ran as an independent L1 from April 2020 until March 2025, when it completed its migration to an Ethereum Layer 2 at block 31,056,500. + +Celo launched in 2020 as a mobile-first Layer 1 blockchain designed to advance global financial inclusion through smartphone-accessible crypto payments and phone number-based addressing. Built on proof-of-stake consensus with a commitment to carbon neutrality, the L1 featured fast, low-cost transactions and native stablecoins like cUSD that powered a growing DeFi ecosystem. + +## The L1 architecture + +Celo L1 was a full-stack design. The `celo-blockchain` client, a fork of go-ethereum, replaced Proof-of-Work with a Byzantine Fault Tolerant (BFT) proof-of-stake consensus run by an elected set of validators. Most machines on the network ran as full nodes, serving light clients on user devices and forwarding their transactions in exchange for fees. The Celo Core Contracts, upgradeable through on-chain governance, implemented the platform's features in smart contracts: stable currencies, identity attestations, validator elections and staking, and governance itself. + +## What changed in the migration + +The table below summarizes the technical changes involved in transitioning from Celo's Layer 1 to Layer 2: + +| **Aspect** | **Layer 1** | **Layer 2** | +|----------------------|---------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------| +| **Architecture** | Single service, providing execution, consensus, and data availability. | Multiple services built on the op-stack with separate execution, data availability, and settlement layers. | +| **Bridging** | Third-party bridges connecting to various chains. | Additional native bridge with Ethereum alongside existing third-party bridges. | +| **CELO Token** | Lived on the Celo L1. | Lives on Ethereum; CELO on L2 represents CELO bridged from Ethereum. | +| **Blocks** | 5s long, 50M gas. | 1s long, 30M gas. | +| **Extra Fields** | — | Withdrawals & withdrawalsRoot, blobGasUsed & excessBlobGas, parentBeaconBlockRoot. | +| **Removed Fields** | — | Randomness, epochSnarkData. | +| **Validator Duties**| Operated the consensus protocol. | Validators temporarily operate community RPC nodes. | +| **Validator Rewards**| Distributed at epoch blocks. | Distributed periodically via smart contract execution. | +| **Sequencing** | Determined by the output of consensus, run by validators. | Initially handled by a centralized sequencer with plans for decentralized sequencing later. | +| **Precompiles** | — | All Celo precompiles removed except for the transfer precompile which supports token duality. | +| **EIP1559** | Governable implementation on-chain. | Upgraded implementation with modified parameters across networks. | +| **Hardforks** | — | Cel2 hardfork for transition to L2 alongside other op-stack hardforks. | +| **Transactions** | — | Deprecated transactions include Type 0 with feeCurrency field and Type 124. | +| **Finality** | One block finality, instantaneous once block is produced. | Finality depends on trust in sequencer, batcher, proposer, and eigenDA, or ultimately on Ethereum. | + +## Retired mechanisms + +These L1 mechanisms were decommissioned before or during the L2 migration and no longer exist on Celo: + +- **BFT consensus, validator proxies, and slashing** — validators no longer produce blocks; a sequencer orders transactions, and the old validator node operations (proxies, consensus key ceremonies, downtime slashing) ended with the L1. +- **On-chain randomness** — the `Random` contract was removed; contracts use the `PREVRANDAO` opcode instead. See [Deactivated Random Contract](/specs/l2-migration#deactivated-random-contract). +- **Granda Mento** — the mechanism for exchanging large amounts of CELO for stable tokens through approved exchange proposals ([CIP 38](https://github.com/celo-org/celo-proposals/blob/master/CIPs/cip-0038.md)) was decommissioned. +- **The on-chain stability algorithm (CP-DOTO) and stability fees** — the constant-product mechanism that minted and burned stable assets against the reserve became [Mento](https://www.mento.org/), which now operates as its own protocol; the demurrage-style stability fee on stable-token balances was disabled and removed from the protocol. +- **Komenci and meta-transaction wallets** — the fee-less onboarding flow used by the original Celo Wallet was discontinued. +- **The `celo-blockchain` client** — the L1 client (docker image `us.gcr.io/celo-org/geth`) stopped syncing new blocks at the migration. To serve pre-migration state, run a [Historical RPC Service](/infra-partners/operators/archive-node). + +## Resources + +| Resource | Link | +|---|---| +| Celo whitepapers | [celo.org/papers](https://celo.org/papers) | +| L2 migration changes in the specs | [/specs/l2-migration](/specs/l2-migration) | + +## Related + +- [Our History](/home/history) - the timeline of Celo's evolution from L1 to L2 +- [Staking](/home/protocol/staking/index) - locked CELO, validator elections, and voting, which continue on L2 +- [Node operators](/infra-partners/operators/overview) - running Celo L2 nodes today diff --git a/home/protocol/metadata.mdx b/home/protocol/metadata.mdx new file mode 100644 index 000000000..ca89a6452 --- /dev/null +++ b/home/protocol/metadata.mdx @@ -0,0 +1,63 @@ +--- +title: "Metadata and Claims" +sidebarTitle: "Metadata" +description: Connect a Celo account with off-chain identities and URLs through signed metadata files registered on the Accounts contract +--- + +This page is for validators, group operators, and tool builders who want to attach verifiable off-chain information to a Celo account. The Celo protocol's **metadata and claims** feature makes it possible to connect on-chain with off-chain identities. + +## Use cases + +- Tools want to present public metadata supplied by a validator or validator group as part of a list of candidate groups, or a list of current elected validators. +- Community RPC providers register their public RPC URL as a claim; see [Registering the Node URL](/contribute-to-celo/community-rpc-nodes/registering-as-rpc-node#registering-the-node-url). +- Governance Explorer UIs may want to present public metadata about the creators of governance proposals. + +Furthermore, these tools may want to include user chosen information such as names or profile pictures that would be expensive to store on-chain. For this purpose, the Celo protocol supports **metadata** that allows accounts to make both verifiable as well as non-verifiable claims. The design is described in [CIP3](https://github.com/celo-org/CIPs/pull/4). + +On the `Accounts` smart contract, any account can register a URL under which their metadata file is available. The metadata file contains an unordered list of claims, signed by the account. + +## Types of claim + +The following types of claim are supported: + +- **Name Claim** - An account can claim a human-readable name. This claim is not verifiable. + +- **Keybase User Claim** - Accounts can make claims on [Keybase](https://keybase.io) usernames. This claim is verifiable by signing a message with the account and hosting it on the publicly accessible path of the Keybase file system. + +- **Domain Claim** - Accounts can make claims on domain names. This claim is verifiable by signing a message with the account and embedding it in a [TXT record](https://wikipedia.org/wiki/TXT_record). + +- **RPC URL Claim** - Community RPC providers claim the public HTTPS URL their node serves. See [Registering a community RPC provider](/contribute-to-celo/community-rpc-nodes/registering-as-rpc-node#registering-the-node-url). + +## Handling metadata + +You can interact with metadata files through the [CLI](/tooling/libraries-sdks/cli/account). Most commands require an RPC node to make view calls, and to modify metadata files, you'll need the relevant account to be unlocked to sign the files. + +You can create an empty metadata file with: + +```bash +celocli account:create-metadata ./metadata.json --from $ACCOUNT_ADDRESS +``` + +You can display the claims in your file and their status with: + +```bash +celocli account:show-metadata ./metadata.json +``` + +Once you are satisfied with your claims, you can upload your file to your own web site or a site that will host the file (for example, [https://gist.github.com](https://gist.github.com)) and then register it with the `Accounts` smart contract by running: + +```bash +celocli account:register-metadata --url $METADATA_URL --from $ACCOUNT_ADDRESS +``` + +Then, anyone can lookup your claims and verify them by running: + +```bash +celocli account:get-metadata $ACCOUNT_ADDRESS +``` + +## Related + +- [Registering a community RPC provider](/contribute-to-celo/community-rpc-nodes/registering-as-rpc-node) - the RPC URL claim in the registration flow +- [Validator groups](/home/protocol/staking/validator-groups) - why groups publish identity claims +- [celocli account commands](/tooling/libraries-sdks/cli/account) - the full command reference diff --git a/home/protocol/staking/index.mdx b/home/protocol/staking/index.mdx new file mode 100644 index 000000000..a66a809a2 --- /dev/null +++ b/home/protocol/staking/index.mdx @@ -0,0 +1,36 @@ +--- +title: "Staking" +description: Lock CELO to vote in validator elections and governance, back a community RPC provider, and earn epoch rewards +--- + +This section is for CELO holders who want to stake, and for operators who manage a validator group or community RPC node. Locked CELO powers three things at once: votes in validator elections, votes on [governance proposals](/home/protocol/governance/overview), and the stake behind registered validators and groups. + + +**Terminology** + +The term "validator" is used in the code and corresponding explanation due to historical reasons, but refers to the community RPC providers. + + + + + How locking works, the unlocking period, and the lock-vote-activate flow + + + How the election selects the active set each epoch, and how voting caps work + + + The intermediaries between voters and validators, membership, and the group commission + + + How to choose a group and where to browse candidates + + + Account roles and authorized signers for staking safely + + + +## Related + +- [How community RPC elections work](/contribute-to-celo/community-rpc-nodes/how-it-works) - the role elections play after the L2 migration +- [Epoch rewards](/home/protocol/epoch-rewards/index) - what voters and providers earn each epoch +- [About Celo L1](/home/celo-l1) - the proof-of-stake consensus these mechanisms originally secured diff --git a/home/protocol/staking/key-management/detailed.mdx b/home/protocol/staking/key-management/detailed.mdx new file mode 100644 index 000000000..5edd5575f --- /dev/null +++ b/home/protocol/staking/key-management/detailed.mdx @@ -0,0 +1,97 @@ +--- +title: "Detailed Role Descriptions" +sidebarTitle: "Detailed Roles" +description: Each Celo account role in detail, with the celocli commands to designate accounts and authorize signers +--- + +This page is for CELO holders and node operators setting up staking keys. It describes each account role and shows how to designate an account as playing that role. + +## Celo Accounts + +Any private key generated for use in the Celo protocol has a corresponding address. The account address is the last 20 bytes of the hash of the corresponding public key, just as in Ethereum. Celo account keys can be used to sign and send transactions on the Celo network. + +Celo Accounts can be designated as Locked CELO Accounts or authorized as signer keys on behalf of a Locked CELO Account by sending special transactions using [celocli](/cli/). Note that Celo accounts that have not been designated as Locked CELO Accounts or authorized signers may not be able to send certain transactions related to staking. + +## Locked CELO Accounts + +[Locked CELO](/home/protocol/staking/locked-celo) Account keys have the highest level of privilege in the Celo protocol. These keys can be used to lock and unlock CELO in order to be used in staking. Furthermore, Locked CELO Account keys can be used to authorize other keys to sign transactions and messages on behalf of the Locked CELO Account. + +In _most_ cases, the Locked CELO Account key has all the privileges as any authorized signers. For example, if a voter signer is authorized, a user can place votes on behalf of the Locked CELO Account with both the authorized vote signer _and_ the Locked CELO Account. + +Because of the significant privileges afforded to the Locked CELO Account, it is best to store this key securely and access it as infrequently as is possible. Authorizing other signers is one way to minimize how frequently you need to access your Locked CELO Account key. The Locked CELO Account key will only be used to send transactions and **can be stored on a Ledger hardware wallet.** + +### Creating a Locked CELO Account + +A Celo account may be designated as a Locked CELO Account by running the following command: + +```bash +# Designate the Celo account as a Locked CELO Account +celocli account:register --from $ADDRESS_TO_DESIGNATE --useLedger + +# Confirm the address was designated as a Locked CELO Account +celocli account:show $ADDRESS_TO_DESIGNATE +``` + +Note that [ReleaseGold](/home/manage/release-gold) beneficiary keys are considered vanilla Celo accounts with respect to staking, and that the `ReleaseGold` contract address is what ultimately gets designated as a Locked CELO Account. + +## Authorized Vote Signers + +Any Locked CELO Account may optionally authorize a Celo account as a vote signer. Authorized vote signers can vote for validator groups and for on-chain governance proposals on behalf of the Locked CELO Account. + +Note that the vote signer must first generate a "proof-of-possession" indicating that signer's willingness to be authorized on behalf of the Locked CELO Account. + +Authorized vote signers can only be used to send voting transactions and **can be stored on a Ledger hardware wallet**. + +### Authorizing a Vote Signer + +A Celo account may be authorized as a vote signer on behalf of a Locked CELO Account by running the following commands: + +```bash +# Create a proof-of-possession. Note that the signer private key must be available. +celocli account:proof-of-possession --account $LOCKED_GOLD_ACCOUNT --signer $SIGNER_TO_AUTHORIZE --useLedger + +# Authorize the vote signer. Note that the Locked Gold Account private key must be available. +celocli account:authorize --from $LOCKED_GOLD_ACCOUNT --role vote --signer $SIGNER_TO_AUTHORIZE --signature $SIGNER_PROOF_OF_POSSESSION --useLedger + +# Confirm that the vote signer was authorized +celocli account:show $LOCKED_GOLD_ACCOUNT + +# You can also look up account info via the authorized signer +celocli account:show $SIGNER_TO_AUTHORIZE +``` + +## Authorized Validator Signers + +Any Locked CELO Account may optionally authorize a Celo account as a validator signer. Authorized validator signers can be used to register and manage a validator or validator group on behalf of the Locked CELO Account. + +An authorized validator signer key that will be used to register a validator group can be used to send group management transactions (e.g. register, add member A, queue commission update to 0.25, etc.). An authorized validator signer key that will be used to register a validator can be used to send validator management transactions (e.g. register, affiliate with group A, etc.). These keys send only transactions and **can be stored on a Ledger hardware wallet.** + +Note that the validator signer must first generate a "proof-of-possession" indicating the signer's willingness to be authorized on behalf of the Locked CELO Account. + + +On the Celo L1, the validator signer key was also used to sign consensus messages, together with a BLS signer key derived from it. Consensus signing ended with the L2 migration; see [About Celo L1](/home/celo-l1). + + +### Authorizing a Validator Signer + +A Celo account may be authorized as a validator signer on behalf of a Locked CELO Account by running the following commands: + +```bash +# Create a proof-of-possession. Note that the signer private key must be available. +celocli account:proof-of-possession --account $LOCKED_GOLD_ACCOUNT --signer $SIGNER_TO_AUTHORIZE + +# Authorize the validator signer. Note that the Locked CELO Account private key must be available. +celocli account:authorize --from $LOCKED_GOLD_ACCOUNT --role validator --signer $SIGNER_TO_AUTHORIZE --signature $SIGNER_PROOF_OF_POSSESSION --useLedger + +# Confirm that the validator signer was authorized +celocli account:show $LOCKED_GOLD_ACCOUNT + +# You can also look up account info via the authorized signer +celocli account:show $SIGNER_TO_AUTHORIZE +``` + +## Related + +- [Key management summary](/home/protocol/staking/key-management/summary) - the roles at a glance +- [Key rotation](/home/protocol/staking/key-management/key-rotation) - replacing an authorized signer safely +- [Registering a community RPC provider](/contribute-to-celo/community-rpc-nodes/registering-as-rpc-node) - these commands in the full registration flow diff --git a/home/protocol/staking/key-management/key-rotation.mdx b/home/protocol/staking/key-management/key-rotation.mdx new file mode 100644 index 000000000..9db21064c --- /dev/null +++ b/home/protocol/staking/key-management/key-rotation.mdx @@ -0,0 +1,49 @@ +--- +title: "Signer Key Rotation" +sidebarTitle: "Key Rotation" +description: Replace an authorized signer key with a new one without touching the Locked CELO account key +--- + +This page is for operators and CELO holders who need to replace an authorized signer key. As detailed in [the Celo account roles description page](/home/protocol/staking/key-management/detailed), Locked CELO accounts can authorize separate signer keys for roles such as voting or validator management. This way, if an authorized signer key is lost or compromised, the Locked CELO account can authorize a new signer to replace the old one, without risking the key that custodies funds. This prevents losing an authorized signer key from becoming a catastrophic event. In fact, it is recommended as an operational best practice to regularly rotate keys to limit the impact of keys being silently compromised. + +## Rotate a signer key + +Authorizing a new signer for a role overwrites the old signer for that role. The new signer must first produce a proof-of-possession, and the key being replaced must never have been used as an authorized signer or Locked CELO Account before. + +```bash +# With $SIGNER_TO_AUTHORIZE as the new signer: + +# Create a proof-of-possession. Note that the new signer private key must be available. +celocli account:proof-of-possession --account $VALIDATOR_ACCOUNT_ADDRESS --signer $SIGNER_TO_AUTHORIZE +``` + +If `VALIDATOR_ACCOUNT_ADDRESS` corresponds to a key you possess: + +```bash +# From a node with access to the key for VALIDATOR_ACCOUNT_ADDRESS +celocli account:authorize --from $VALIDATOR_ACCOUNT_ADDRESS --role validator --signer $SIGNER_TO_AUTHORIZE --signature 0x$SIGNER_PROOF_OF_POSSESSION +``` + +If `VALIDATOR_ACCOUNT_ADDRESS` is a `ReleaseGold` contract: + +```bash +# From a node with access to the beneficiary key of VALIDATOR_ACCOUNT_ADDRESS +celocli releasecelo:authorize --contract $VALIDATOR_ACCOUNT_ADDRESS --role validator --signer $SIGNER_TO_AUTHORIZE --signature 0x$SIGNER_PROOF_OF_POSSESSION +``` + +The same flow applies to vote signers with `--role vote`. + +Confirm the rotation: + +```bash +celocli account:show $VALIDATOR_ACCOUNT_ADDRESS +``` + + +A newly authorized signer takes effect for validator elections at the next epoch. A deauthorized signer cannot be reauthorized later, so never reuse old signer keys. + + +## Related + +- [Detailed role descriptions](/home/protocol/staking/key-management/detailed) - the authorize commands per role +- [Key management summary](/home/protocol/staking/key-management/summary) - which key can be stored where diff --git a/home/protocol/staking/key-management/summary.mdx b/home/protocol/staking/key-management/summary.mdx new file mode 100644 index 000000000..311260ad5 --- /dev/null +++ b/home/protocol/staking/key-management/summary.mdx @@ -0,0 +1,35 @@ +--- +title: "Key Management" +sidebarTitle: "Summary" +description: The account roles and authorized signer keys used for locking CELO, voting, and managing validators on Celo +--- + +This page is for CELO holders and node operators who manage staking keys. The Celo protocol was designed with the understanding that there is often an inherent tradeoff between the convenience of accessing a private key and the security with which that private key can be custodied. In general Celo is unopinionated about how keys are custodied, but also allows users to authorize private keys with specific, limited privileges. This allows users to custody each private key according to its sensitivity (i.e. what is the impact of this key being lost or stolen?) and usage patterns (i.e. how often and under which circumstances will this key need to be accessed). + +## Summary + +The table below outlines a summary of the various account roles in the Celo protocol. Note that these roles are often _mutually exclusive_. An account that has been designated as one role can often not be used for a different purpose. Also note that under the hood, all of these accounts are based on secp256k1 ECDSA private keys. The different account roles are simply a concept encoded into the Celo staking smart contracts, specifically [Accounts.sol](https://github.com/celo-org/celo-monorepo/blob/master/packages/protocol/contracts/common/Accounts.sol). + +For more details on a specific key type, please see the [detailed role descriptions](/home/protocol/staking/key-management/detailed). + +| Role | Description | Ledger compatible | +| ----------------------------------- | ------------------------------------------------------------------------------------------------ | ----------------- | +| Celo Account | An account used to send transactions in the Celo protocol | Yes | +| Locked CELO Account | Used to lock and unlock CELO and authorize signers | Yes | +| Authorized vote signer | Can vote on behalf of a Locked CELO Account | Yes | +| Authorized validator (group) signer | Can register and manage a validator group on behalf of a Locked CELO Account | Yes | +| Authorized validator signer | Can register and manage a validator on behalf of a Locked CELO Account | Yes | + + +Two further signer roles exist in `Accounts.sol` but had duties that ended with the Celo L1: the validator BLS signer (consensus block signing) and the attestation signer (the retired Attestation Service). See [About Celo L1](/home/celo-l1). + + + +A Locked CELO Account may have at most one authorized signer of each type at any time. Once a signer is authorized, the only way to deauthorize that signer is to authorize a new signer that has never previously been used as an authorized signer or Locked CELO Account. It follows then that a newly deauthorized signer cannot be reauthorized. + + +## Related + +- [Detailed role descriptions](/home/protocol/staking/key-management/detailed) - each role with the commands to designate it +- [Key rotation](/home/protocol/staking/key-management/key-rotation) - replacing an authorized signer safely +- [Registering a community RPC provider](/contribute-to-celo/community-rpc-nodes/registering-as-rpc-node) - the keys in use during registration diff --git a/home/protocol/staking/locked-celo.mdx b/home/protocol/staking/locked-celo.mdx new file mode 100644 index 000000000..80d43bb1d --- /dev/null +++ b/home/protocol/staking/locked-celo.mdx @@ -0,0 +1,74 @@ +--- +title: "Locked CELO" +description: Lock CELO to vote in validator elections and governance while keeping the same balance available for staking +--- + +This page is for CELO holders who want to participate in validator elections and on-chain governance. To take part, you first lock CELO; the same locked balance can vote and stake concurrently. + + +**Terminology** + +This page references "Locked Gold". The native asset of Celo was called Celo Gold (cGLD), but is now called CELO. Many references have been updated, but code and smart contract references may still mention Gold as it is more difficult to reliably and securely update the protocol code. + + +## Validator election participation + +To participate in validator elections, users must first make a transfer of CELO to the `LockedGold` smart contract. + +## Concurrent use of Locked CELO + +Locking up CELO guarantees that the same asset is not used more than once in the same vote. However every unit of Locked CELO can be deployed in several ways at once. Using an amount for voting for a validator does not preclude that same amount also being used to vote for a governance proposal, or as a stake at the same time. Users do not need to choose whether to have to move funds from validator elections in order to vote on a governance proposal. + +## Unlocking period + +Celo implements an **unlocking period**, a delay of 3 days after making a request to unlock Locked CELO before it can be recovered from the escrow. + +This value balances two concerns. First, it is long enough that an election will have taken place since the request to unlock, so that those units of CELO will no longer have any impact on which validators are managing the network. This deters an attacker from manipulations in the form of borrowing funds to purchase CELO, then using it to elect malicious validators, since they will not be able to return the borrowed funds until after the attack, when presumably it would have been detected and the borrowed funds’ value have fallen. + +Second, the unlocking period is short enough that it does not represent a significant liquidity risk for most users. This limits the attractiveness to users of exchanges creating secondary markets in Locked CELO and thereby pooling voting power. + +## Locking and voting flow + + +![](https://storage.googleapis.com/celo-website/docs/locked-gold-flow.jpg) + + +The flow is as follows: + +- An account calls `lock`, transferring an amount of CELO from their balance to the `LockedGold` smart contract. This increments the account's 'non-voting' balance by the same amount. + +- Then the account calls `vote`, passing in an amount and the address of the group to vote for. This decrements the account's 'non-voting' balance and increments the 'pending' balance associated with that group by the same amount. This counts immediately towards electing validators. Note that the vote may be rejected if it would mean that the account would be voting for more than 3 distinct groups, or that the [voting cap](/home/protocol/staking/validator-elections#group-voting-caps) for the group would be exceeded. + +- At the end of the current epoch (approximately every 24 hours), the protocol first delivers [epoch rewards](/home/protocol/epoch-rewards/index) to validators, groups and voters based on the current epoch (pending votes do not count for these purposes), and then runs an [election](/home/protocol/staking/validator-elections) to select the active validator set for the following epoch. + +- The pending vote continues to contribute towards electing validators until it is changed, but the account must call `activate` (in a subsequent epoch to the one in which the vote was made) to convert the pending vote to one that earns rewards. + +- At the end of that epoch, if the group for which the vote was made had elected one or more validators in the prior election, then the activated vote is eligible for [Locked CELO rewards](/home/protocol/epoch-rewards/index). These are applied to the pool of activated votes for the group. This means that activated voting Locked CELO automatically compounds, with the rewards increasing the account's votes for the same group, thereby increasing future rewards, benefitting participants who have elected to continuously participate in governance. + +- The account may subsequently choose to `unvote` a specific amount of voting Locked CELO from a group, up to the total balance that the account has accrued there. Due to rewards, this Locked CELO amount may be higher than the original value passed to `vote`. + +- This Locked CELO immediately becomes non-voting, receives no further Epoch Rewards, and can be re-used to vote for a different group. + +- The account may choose to `unlock` an amount of Locked CELO at any time, provided that it is inactive: this means it is non-voting in Validator Elections, the `deregistrationPeriod` has elapsed if the amount has been used as a validator or validator group stake, and not active in any [Governance proposals](/home/protocol/governance/overview). Once an unlocking period of 3 days has passed, the account can call `withdraw` to have the `LockedGold` contract transfer them that amount. + +Votes persist between epochs, and the same vote is applied to each election unless and until it is changed. Vote withdrawal, vote changes, and additional CELO being used to vote have no effect on the validator set until the election finalizes at the end of the epoch. + +## Vote delegation + +[Contract Release 10](https://github.com/celo-org/celo-monorepo/issues/10375) introduced vote delegation, which allows the governance participant to delegate their voting power. + + +Validators and Validator groups cannot delegate. + + +The governance participants who cannot actively participate to vote on governance proposals in the Celo ecosystem can now delegate their votes to utilize the dormant votes. + +Currently, participants can only delegate to 10 other delegatees. + +Participants can follow the steps [here](/home/protocol/governance/voting-in-governance#vote-delegation) to perform delegation using CeloCLI. + +## Related + +- [Validator elections](/home/protocol/staking/validator-elections) - how locked votes translate into the active set +- [Voting for validator groups](/home/protocol/staking/voting) - choosing a group to vote for +- [Key management](/home/protocol/staking/key-management/summary) - authorizing a vote signer so the locking key stays cold diff --git a/home/protocol/staking/validator-elections.mdx b/home/protocol/staking/validator-elections.mdx new file mode 100644 index 000000000..532ec6c43 --- /dev/null +++ b/home/protocol/staking/validator-elections.mdx @@ -0,0 +1,64 @@ +--- +title: "Validator Elections" +description: How Celo elects the active validator set each epoch from locked CELO votes, and how group voting caps protect the election +--- + +This page is for CELO holders and operators who want to understand how the active validator set is chosen. Elections run at the end of every epoch, approximately every 24 hours. + + +**Terminology** + +The term "validator" is used in the code and corresponding explanation due to historical reasons, but refers to the community RPC providers. + + +## Updating the active validator set + +The active validator set is updated by running an election at the conclusion of each epoch, after [epoch rewards](/home/protocol/epoch-rewards/index) are processed. Epoch processing is implemented in the [`EpochManager` contract](https://github.com/celo-org/celo-monorepo/blob/master/packages/protocol/contracts-0.8/common/EpochManager.sol) and triggered through permissionless function calls. + +### Group voting caps + +One way to consider the security of a proof-of-stake system is the marginal cost of getting a malicious validator elected. In a steady state, assuming the Celo community set the incentives appropriately, a full complement of validators is likely to be elected, which means the attack cost is the cost of acquiring sufficient CELO to receive more votes than the currently elected validator with fewest votes, and thereby supplant it. + +### Goal of validator elections + +The objective of Celo’s validator elections differs from real-world elections: they aim to translate voter preferences into representation while promoting decentralization and creating a moat around existing, well-performing elected validators. Two design choices influence this: a limit on the maximum number of member validator that a group can list, and a **voting cap** on the number of votes that any one group can receive. + +### Handling excess votes + +Since voting for a group can cause only the group’s member validators to get elected, and no more, votes in excess of the number needed to achieve that are unproductive in the sense that they do not raise the number of votes needed to get the least-voted-for validator elected. This would translate into a lower cost for a malicious actor to acquire enough CELO to supplant that validator. This is particularly true because the protocol limits the maximum number of members in a group, to promote decentralization. + +### Per-group vote cap + +The Celo protocol addresses this by enforcing a per-group vote cap. This cap is set to be the number of votes that would be needed to elect all of its validators, plus one more validator. The cap is enforced at the point of voting: a user can only cast a vote for a group if it currently has fewer votes than this cap. An account holder may not set or increase the amount of gold they have voting for a particular validator group `j`, if it already has at least `[(group_members_j + 1) / min(total_group_members, max_validators)]` of the total Locked Gold. + +### Adding new validators + +If a group adds a new validator, or the total amount of voting Locked Gold increases, the group’s cap rises and new votes are permitted. If a group removes a validator or a validator chooses to leave, or the total amount of voting Locked Gold falls, then the group’s cap falls: if it has more votes than this new cap, then new votes are no longer permitted, but all existing votes continue to be counted. + +The Celo protocol allows an account to divide its vote between up to ten groups, since there may be cases where the vote cap prevents an account allocating its entire vote to its first choice group. + +## Running the election + + +![](https://storage.googleapis.com/celo-website/docs/election.jpg) + + +The `Election` contract is called during epoch processing to select the validators for the following epoch. The contract maintains a sorted list of the Locked Gold voting (either pending or activated) for each Validator Group. The [D’Hondt method](https://wikipedia.org/wiki/D'Hondt_method), a closed party list form of proportional representation, is applied to iteratively select validators from the Validator Groups with the greatest associated vote balances. + +### Filtering groups + +The list of groups is first filtered to remove those that have not achieved a certain fraction of the votes of the total voting Locked Gold. + +### Assigning seats + +Then, in the first iteration, the algorithm assigns the first seat to the group that has at least one member and with the most votes. Thereafter, it assigns the seat to the group that would ‘pay’, if its next validator were elected, the highest vote averaged over its candidates that have been selected so far plus the one under consideration. + +### Number of active validators + +There is a minimum target and a maximum cap on the number of active validators that may be selected. If the minimum target is not reached, the election aborts and no change is made to the validator set this epoch. + +## Related + +- [Locked CELO](/home/protocol/staking/locked-celo) - the lock-vote-activate flow behind every ballot +- [Validator groups](/home/protocol/staking/validator-groups) - the entities the votes are cast for +- [How community RPC elections work](/contribute-to-celo/community-rpc-nodes/how-it-works) - what winning the election means after the L2 migration diff --git a/home/protocol/staking/validator-groups.mdx b/home/protocol/staking/validator-groups.mdx new file mode 100644 index 000000000..2bf3d8803 --- /dev/null +++ b/home/protocol/staking/validator-groups.mdx @@ -0,0 +1,72 @@ +--- +title: "Validator Groups" +description: How validator groups mediate between voters and validators, and how membership, commission, and voting caps work +--- + +This page is for CELO holders choosing where to vote and for operators running a group. Celo's staking mechanism introduces **Validator Groups** as intermediaries between voters and validators. + + +**Terminology** + +The term "validator" is used in the code and corresponding explanation due to historical reasons, but refers to the community RPC providers. + + +## What is a validator group? + +A validator group has **members**, an ordered list of candidate validators. There is a fixed limit to the number of members that a group may have. + +## Why use a validator group? + +Validator groups can help mitigate the information disparity between voters and validators. It is anticipated that groups might emerge that do not necessarily operate validators themselves but attract votes for their reputation for ensuring their associated validators have known real-world identities, have high uptime, are well maintained and regularly audited. Since every validator needs to be accepted by a single group to stand for election, that group will be more able to build up long-term judgements on their validators’ operational practices and security setups than each of the numerous CELO holders that might vote for it would. + +## Fielding multiple validators + +Equally, a number of organizations may want to attempt to field multiple validators under their own control, or be able to interchange the specific machines or keys under which they validate in the case of hardware or connectivity failure. By switching out validators in the list, groups can accomplish this without users having to change their votes. + +## Validator group limits + +Validator groups can have no more than a small, fixed maximum number of validators -- currently 5 in Mainnet. This means an organization wanting to get more validators elected than this maximum has the added challenge of managing multiple group identities and reputations simultaneously. This further promotes decentralization and strengthens operational security, making it more likely that the validator set will be composed of nodes operated in different fashions by independent individuals and organizations. + +## Registration + +Any account that has at least the minimum stake requirement in Locked Gold, whether voting or non-voting, can register an empty validator group. If a validating key is specified it may be used for this registration. + +## Deregistration + +The account that creates a validator group is able to deregister that group if it has no members. + +While an account has a registered validator group, or for up to a `deregistrationPeriod` after it is deregistered, attempts to `unlock` the account's amount of Locked Gold will fail if they would cause the remaining amount to fall below the minimum stake requirement. + +## Group share + +Validator groups are compensated by taking a share (the 'Group Share') of the [validator rewards](/home/protocol/epoch-rewards/index) from any of its member validators that are elected during an epoch. This value is set at registration time and can be changed later. + +## Changing group members + +The account owner controls the list of validators in their group and can at any time add, remove, or re-order validators. + +For a validator to be added to a group, several conditions must hold: the number of members in the group must be less than the maximum; the Locked Gold balance of the group's account must be sufficient (the stake is per-member validator); and the validator must first have set its affiliation to the group. + +This means that while a group can unilaterally remove a validator, and a validator can unilaterally leave by changing its affiliation, both parties have to agree before a validator can become a member of a group. + +## Votes and voting cap + +Validator Groups can receive votes from Locked Gold up to a [voting cap](/home/protocol/staking/validator-elections#group-voting-caps). This value is set to be the number of votes that would be needed to elect all of its validators, plus one more validator. The cap is enforced at the point of voting: a user can only cast a vote for a group if it currently has fewer votes than this cap. + +## Penalties + +A penalty factor, initially `1.0`, is also tracked for each validator group. This value may be reduced as a penalty for misbehavior of the validator in the group. It affects the future rewards of the group, its validators, and Locked Gold holders receiving rewards for voting for the group. See [Penalties](/contribute-to-celo/community-rpc-nodes/penalties) for the conditions that apply to community RPC providers. + +## Metadata + +Both validators and validator groups can use [account metadata](/home/protocol/metadata) to provide unverified metadata (such as name and organizational affiliation) as well as claims that can be verified off-chain for control of third-party accounts and domain names. + +## Dissolving of a validator group + +There is a 180 day unlocking period for Celo locked when creating a validator group. + +## Related + +- [Validator elections](/home/protocol/staking/validator-elections) - how groups turn votes into elected validators +- [Voting for validator groups](/home/protocol/staking/voting) - what voters look for in a group +- [Registering a community RPC provider](/contribute-to-celo/community-rpc-nodes/registering-as-rpc-node) - the operator-side registration flow, including the group commission diff --git a/home/protocol/staking/voting.mdx b/home/protocol/staking/voting.mdx new file mode 100644 index 000000000..337c5e0d2 --- /dev/null +++ b/home/protocol/staking/voting.mdx @@ -0,0 +1,93 @@ +--- +title: "Voting for Validator Groups" +description: How to choose a validator group to vote for with locked CELO, and where to browse candidate groups +--- + +This page is for CELO holders deciding where to place their validator-election votes. Selecting organizations that operate well-run infrastructure is essential for Celo's long-term success, and voters make that decision by locking CELO and voting for validator groups. + + +**Terminology** + +The term "validator" is used in the code and corresponding explanation due to historical reasons, but refers to the community RPC providers. + + +## What are validators? + +Validators historically produced blocks on the Celo L1; after the L2 migration they [serve the network as community RPC providers](/contribute-to-celo/community-rpc-nodes/community-rpc-node). The Celo community decides who fills this role by locking CELO and voting for [Validator Groups](/home/protocol/staking/validator-groups), intermediaries that sit between voters and Validators. Every Validator Group has an ordered list of up to 5 candidate Validators. Some organizations may operate a group with their own Validators in it; some may operate a group to which they have added Validators run by others. + + +If you would like to keep up-to-date with all the news happening in the Celo community, including validation, node operation and governance, please sign up to our [Celo Signal mailing list here](https://share.hsforms.com/1Qrhush1vSA2WIamd_yL4ow53n4j). + +You can add the [Celo Signal public calendar](https://calendar.google.com/calendar/u/0/embed?src=c_9su6ich1uhmetr4ob3sij6kaqs@group.calendar.google.com) as well which has relevant dates. + + +## Validator elections + +[Validator elections](/home/protocol/staking/validator-elections) are held every epoch (approximately once per day). At each epoch, every elected Validator must be re-elected to continue. Validators are selected [in proportion](/home/protocol/staking/validator-elections#running-the-election) to votes received for each Validator Group. + +If you hold CELO, or are a beneficiary of a [`ReleaseGold` contract](/home/manage/release-gold) that allows voting, you can vote for Validator Groups. A single account can split their LockedGold balance to have outstanding votes for up to 10 groups. + +CELO that you lock and use to vote for a group that elects one or more Validators receives [epoch rewards](/home/protocol/epoch-rewards/index) every epoch (approximately every day). + +Unlike a number of Proof of Stake protocols, **CELO used for voting is never at risk**. The actions of the Validator Groups or Validators you vote for can cause you to receive lower or higher rewards, but the CELO you locked will always be available to be unlocked in the future. [Penalties](/contribute-to-celo/community-rpc-nodes/penalties) in the Celo protocol apply only to Validators and Validator Groups. + +## Choosing a validator group + +As a CELO holder, you have the opportunity to impact the Celo network by voting for Validator Groups. It is crucial that voters choose groups that contribute to both the technical health of the network, as well as the community. Some factors to consider when deciding which Validator Group to vote for include: + +### Technical + +- **Proven identity:** Validators and groups can supply [verifiable DNS claims](/home/protocol/metadata). You can use these to securely identify that the same entity has access both to the account of a Validator or group and the supplied DNS records. + +- **Can receive votes**: Validator Groups can receive votes up to a certain [voting cap](/home/protocol/staking/validator-elections#group-voting-caps). You cannot vote for groups with a balance that would put it beyond its cap. + +- **Will get elected**: CELO holders only receive voter rewards during an epoch if their CELO is used to vote for a Validator Group that elects at least one Validator during that epoch. Put another way, your vote does not contribute to the network or earning you rewards if your group does not receive enough other votes to elect at least one Validator. + +- **Reliable**: Voter rewards depend on the performance of the elected Validators in the group for which the vote was made. Nodes that fail to meet their obligations are subject to [penalties](/contribute-to-celo/community-rpc-nodes/penalties), which also reduce the rewards of the group's voters. + +- **No recent penalties:** When Validators and groups register, their Locked CELO becomes "staked", in that it is subject to penalties for conduct that could seriously adversely affect the health of the network. Voters' Locked CELO is never at risk, but voter rewards are affected by penalties applied to the group or its Validators. + +### Community + +- **Promotes the Celo mission**: Celo's mission is to [build a monetary system that creates the conditions of prosperity for all](https://medium.com/celoorg/an-introductory-guide-to-celo-b185c62d3067). Consider Validator Groups that further this mission through their own activities or initiatives around financial inclusion, education and sustainability. + +- **Broadens Diversity**: The Celo community aims to be inclusive to the largest number of contributors, with the most varied and diverse backgrounds possible. Support that diversity by considering what new perspectives and strengths the teams you support offer. As well as the backgrounds and experiences of the team, consider that the network security and availability is improved by Validators operating at different network locations, on different platforms, and with different toolchains. + +- **Contributes to Celo:** Support Validator Groups that strengthen the Celo developer community, for example through building or operating services for the Celo ecosystem, participating actively in on-chain governance, and answering questions and supporting others, on [Discord](https://chat.celo.org) or the [Forum](https://forum.celo.org). + +## The Celo Foundation voting policy + +As described above, there are many criteria to consider when deciding which group to vote for. While it is highly recommended that all CELO holders do their independent research when deciding which group to vote for, another option is to vote for Validator Groups that have received votes from the Celo Foundation. + +The Celo Foundation follows a validator group voting policy when voting with the CELO that it holds. This policy has been developed by the Foundation board and technical advisors with the express goal of promoting the long-term security and decentralization of the network. Validator Groups have an opportunity to apply for Foundation votes every 3 months, and a new cohort is selected based on past performance and contributions. + +You can find the [full set of Validator Groups currently receiving votes, and their addresses linked here](https://docs.google.com/spreadsheets/d/1ltVNkQfXW3lIZxXU52R3IXeD6w21oacWFVb3a-FYRBY/edit?usp=sharing). + +## Validator explorers + +The Celo ecosystem includes a number of great services for browsing registered Validator Groups and Validators. + + +**Warning**: Exercise caution in relying on Validator-supplied names to determine their real-world identity. Malicious participants may attempt to impersonate other Validators in order to attract votes. + +Validators and groups can also supply [verifiable DNS claims](/home/protocol/metadata), and validator explorers display these. You can use these to securely identify that the same entity has access both to the account of a Validator or group and the supplied DNS records. + + +### [Celo Mondo Validator Explorer](https://mondo.celo.org/) ([cLabs](https://clabs.co)) + +The Celo Mondo "Staking" tab displays information for Mainnet Validators. + +### [Celovote Scores](https://celovote.com/scores) (WOTrust | celovote.com) + +Celovote shows a ranking of Validator groups based on their estimated annual rate of return (ARR). +The estimate is calculated based on past performance. + +### [Vido](https://vido.atalma.io/celo/block-map) ([Atalma](https://www.atalma.io/)) + +Vido is a node monitoring suite for Celo with subscribable metrics to get alerted if your node stops performing. + +## Related + +- [Locked CELO](/home/protocol/staking/locked-celo) - the lock-vote-activate flow for casting these votes +- [Validator groups](/home/protocol/staking/validator-groups) - how groups work and how they are compensated +- [Key management](/home/protocol/staking/key-management/summary) - authorizing a vote signer so votes never expose the locking key diff --git a/infra-partners/operators/faq.mdx b/infra-partners/operators/faq.mdx new file mode 100644 index 000000000..a8581cf72 --- /dev/null +++ b/infra-partners/operators/faq.mdx @@ -0,0 +1,101 @@ +--- +title: Cel2 FAQ +description: Answers to common questions about running nodes and using Celo after the L2 migration +--- + +This FAQ is for node operators and developers with questions about Celo since the migration to an Ethereum L2. + +## Mainnet + + + + +A couple of issues could be causing this. + +* If you are running multiple instances of op-node, make sure to check that they each have a unique and persisted private key at `--p2p.priv.path` +* Ensure that your node is accessible to other nodes, check the __Configure P2P for external network access__ section under [Running a full node](/infra-partners/operators/run-node#running-a-full-node) + + + + +See the guides for [running a node](/infra-partners/operators/run-node) or the guide on [how to migrate an L1 node](/infra-partners/operators/migrate-node). + + + + +Yes. This is part of [running a node](/infra-partners/operators/run-node). +If you're using the [Docker Compose Setup](https://github.com/celo-org/celo-l2-node-docker-compose), it's included. + + + + +All balances have been carried over to the L2, unchanged. + + + + +There is no change and it continues to work in the same way as before. + + + + +Yes, same as with Ethereum. + + + + +Have a look at the [changes from L1 to L2 in the specs](/specs/l2-migration#changes-for-json-rpc-users). + + + + +Validators are becoming [Community RPC providers](/contribute-to-celo/community-rpc-nodes/community-rpc-node). + + + + +There are multiple options. + +* Install [Celo CLI](/cli/index) at version 6.1.0 or later. Then run: `celocli network:community-rpc-nodes`. +* [Vido Node Explorer](https://dev.vido.atalma.io/celo/rpc) +* [Celo Community RPC Gateway](https://celo-community.org/) + + + + +[Governance](/home/protocol/governance/overview) remains a pillar of the Celo blockchain. The Validator Hotfix process has been adapted, see [Updated Governance Hotfix](/specs/l2-migration#updated-governance-hotfix) for the changes. + + + + +* CELO token duality? Supported, see [Token Duality](/specs/token-duality). +* Fee currencies? Supported, see [Fee Abstraction](/specs/fee-abstraction). +* Epoch rewards? Epochs now work differently, but rewards stay, see [Epochs and Rewards](/specs/smart-contract-updates-from-l1#epochs-and-rewards). + + + + +See the [Celo L2 Specification](/specs) for how Celo differs from a stock OP Stack chain, including block time, the native token, fee currencies, and finality. + + + + +See [Transaction fees in the specs](/specs/transaction-fees): the L1 fee is always zero, and L1 costs are covered through the base fee floor. + + + + +The block period is 1 second. + + + + +The gas limit per block is 30 million, so the maximum throughput is 30M gas/s. + + + + +See [L1 -> L2 Migration Changes](/specs/l2-migration) in the spec for the details, and [About Celo L1](/home/celo-l1) for the mechanisms that were retired. + + + From 6fcba0e134d2180eafd9d93f83ef26109054afe0 Mon Sep 17 00:00:00 2001 From: Paul Lange Date: Mon, 24 Aug 2026 17:12:31 +0200 Subject: [PATCH 2/7] docs: delete legacy/, remove Legacy tab, re-point 109 redirects, add 60 legacy redirects --- docs.json | 602 ++++++++++-------- home/protocol/celo-token.mdx | 1 + home/protocol/epoch-rewards/index.mdx | 2 +- infra-partners/operators/migrate-node.mdx | 9 + legacy/faq.mdx | 100 --- legacy/l1-architecture.mdx | 69 -- legacy/node/run-mainnet.mdx | 123 ---- legacy/overview.mdx | 39 -- legacy/protocol/consensus/index.mdx | 25 - legacy/protocol/consensus/locating-nodes.mdx | 36 -- .../consensus/validator-set-differences.mdx | 16 - legacy/protocol/contracts/add-contract.mdx | 28 - .../identity/encrypted-cloud-backup.mdx | 114 ---- legacy/protocol/identity/index.mdx | 54 -- legacy/protocol/identity/metadata.mdx | 70 -- .../odis-domain-sequential-delay-domain.mdx | 15 - legacy/protocol/identity/odis-domain.mdx | 51 -- .../identity/odis-use-case-key-hardening.mdx | 43 -- .../odis-use-case-phone-number-privacy.mdx | 41 -- legacy/protocol/identity/odis.mdx | 116 ---- legacy/protocol/identity/privacy-research.mdx | 17 - .../identity/smart-contract-accounts.mdx | 84 --- legacy/protocol/pos/becoming-a-validator.mdx | 15 - .../pos/epoch-rewards-locked-gold.mdx | 43 -- .../protocol/pos/epoch-rewards-validator.mdx | 67 -- legacy/protocol/pos/epoch-rewards.mdx | 50 -- legacy/protocol/pos/index.mdx | 65 -- legacy/protocol/pos/locked-gold.mdx | 75 --- legacy/protocol/pos/penalties.mdx | 48 -- legacy/protocol/pos/validator-elections.mdx | 59 -- legacy/protocol/pos/validator-groups.mdx | 67 -- legacy/protocol/randomness.mdx | 55 -- .../stability/adding-stable-assets.mdx | 89 --- legacy/protocol/stability/doto.mdx | 60 -- legacy/protocol/stability/granda-mento.mdx | 56 -- legacy/protocol/stability/index.mdx | 36 -- legacy/protocol/stability/oracles.mdx | 31 - legacy/protocol/stability/stability-fees.mdx | 63 -- .../transaction/erc20-transaction-fees.mdx | 83 --- legacy/protocol/transaction/escrow.mdx | 32 - legacy/protocol/transaction/gas-pricing.mdx | 42 -- legacy/protocol/transaction/index.mdx | 23 - .../protocol/transaction/native-currency.mdx | 26 - .../transaction/transaction-types.mdx | 471 -------------- .../transaction/tx-comment-encryption.mdx | 45 -- .../guides/bridging-celo-from-l1-to-l2.mdx | 144 ----- .../guides/withdrawing-celo-from-l2-to-l1.mdx | 145 ----- legacy/transition/optimism/op-l2.mdx | 47 -- legacy/transition/whats-changed/l1-l2.mdx | 102 --- legacy/transition/whats-changed/overview.mdx | 11 - .../celo-foundation-voting-policy.mdx | 162 ----- legacy/validator/devops-best-practices.mdx | 35 - legacy/validator/index.mdx | 43 -- legacy/validator/key-management/detailed.mdx | 162 ----- .../validator/key-management/key-rotation.mdx | 70 -- legacy/validator/key-management/summary.mdx | 37 -- legacy/validator/monitoring.mdx | 156 ----- legacy/validator/node-upgrade.mdx | 169 ----- legacy/validator/proxy.mdx | 34 - legacy/validator/run/mainnet.mdx | 25 - legacy/validator/security.mdx | 32 - legacy/validator/troubleshooting-faq.mdx | 59 -- legacy/validator/validator-explorer.mdx | 109 ---- legacy/validator/voting.mdx | 96 --- specs/l2-migration.mdx | 4 + 65 files changed, 365 insertions(+), 4533 deletions(-) delete mode 100644 legacy/faq.mdx delete mode 100644 legacy/l1-architecture.mdx delete mode 100644 legacy/node/run-mainnet.mdx delete mode 100644 legacy/overview.mdx delete mode 100644 legacy/protocol/consensus/index.mdx delete mode 100644 legacy/protocol/consensus/locating-nodes.mdx delete mode 100644 legacy/protocol/consensus/validator-set-differences.mdx delete mode 100644 legacy/protocol/contracts/add-contract.mdx delete mode 100644 legacy/protocol/identity/encrypted-cloud-backup.mdx delete mode 100644 legacy/protocol/identity/index.mdx delete mode 100644 legacy/protocol/identity/metadata.mdx delete mode 100644 legacy/protocol/identity/odis-domain-sequential-delay-domain.mdx delete mode 100644 legacy/protocol/identity/odis-domain.mdx delete mode 100644 legacy/protocol/identity/odis-use-case-key-hardening.mdx delete mode 100644 legacy/protocol/identity/odis-use-case-phone-number-privacy.mdx delete mode 100644 legacy/protocol/identity/odis.mdx delete mode 100644 legacy/protocol/identity/privacy-research.mdx delete mode 100644 legacy/protocol/identity/smart-contract-accounts.mdx delete mode 100644 legacy/protocol/pos/becoming-a-validator.mdx delete mode 100644 legacy/protocol/pos/epoch-rewards-locked-gold.mdx delete mode 100644 legacy/protocol/pos/epoch-rewards-validator.mdx delete mode 100644 legacy/protocol/pos/epoch-rewards.mdx delete mode 100644 legacy/protocol/pos/index.mdx delete mode 100644 legacy/protocol/pos/locked-gold.mdx delete mode 100644 legacy/protocol/pos/penalties.mdx delete mode 100644 legacy/protocol/pos/validator-elections.mdx delete mode 100644 legacy/protocol/pos/validator-groups.mdx delete mode 100644 legacy/protocol/randomness.mdx delete mode 100644 legacy/protocol/stability/adding-stable-assets.mdx delete mode 100644 legacy/protocol/stability/doto.mdx delete mode 100644 legacy/protocol/stability/granda-mento.mdx delete mode 100644 legacy/protocol/stability/index.mdx delete mode 100644 legacy/protocol/stability/oracles.mdx delete mode 100644 legacy/protocol/stability/stability-fees.mdx delete mode 100644 legacy/protocol/transaction/erc20-transaction-fees.mdx delete mode 100644 legacy/protocol/transaction/escrow.mdx delete mode 100644 legacy/protocol/transaction/gas-pricing.mdx delete mode 100644 legacy/protocol/transaction/index.mdx delete mode 100644 legacy/protocol/transaction/native-currency.mdx delete mode 100644 legacy/protocol/transaction/transaction-types.mdx delete mode 100644 legacy/protocol/transaction/tx-comment-encryption.mdx delete mode 100644 legacy/transition/guides/bridging-celo-from-l1-to-l2.mdx delete mode 100644 legacy/transition/guides/withdrawing-celo-from-l2-to-l1.mdx delete mode 100644 legacy/transition/optimism/op-l2.mdx delete mode 100644 legacy/transition/whats-changed/l1-l2.mdx delete mode 100644 legacy/transition/whats-changed/overview.mdx delete mode 100644 legacy/validator/celo-foundation-voting-policy.mdx delete mode 100644 legacy/validator/devops-best-practices.mdx delete mode 100644 legacy/validator/index.mdx delete mode 100644 legacy/validator/key-management/detailed.mdx delete mode 100644 legacy/validator/key-management/key-rotation.mdx delete mode 100644 legacy/validator/key-management/summary.mdx delete mode 100644 legacy/validator/monitoring.mdx delete mode 100644 legacy/validator/node-upgrade.mdx delete mode 100644 legacy/validator/proxy.mdx delete mode 100644 legacy/validator/run/mainnet.mdx delete mode 100644 legacy/validator/security.mdx delete mode 100644 legacy/validator/troubleshooting-faq.mdx delete mode 100644 legacy/validator/validator-explorer.mdx delete mode 100644 legacy/validator/voting.mdx diff --git a/docs.json b/docs.json index bc1a8a195..3710eca7e 100644 --- a/docs.json +++ b/docs.json @@ -508,148 +508,6 @@ ] } ] - }, - { - "tab": "Legacy", - "groups": [ - { - "group": "Overview", - "pages": [ - "legacy/overview", - "legacy/l1-architecture", - "legacy/faq" - ] - }, - { - "group": "Transition From L1 to L2", - "pages": [ - "legacy/transition/whats-changed/overview", - "legacy/transition/whats-changed/l1-l2", - "legacy/transition/optimism/op-l2", - "legacy/transition/guides/bridging-celo-from-l1-to-l2", - "legacy/transition/guides/withdrawing-celo-from-l2-to-l1" - ] - }, - { - "group": "Protocol", - "pages": [ - { - "group": "Proof-of-Stake", - "pages": [ - "legacy/protocol/pos/index", - "legacy/protocol/pos/validator-groups", - "legacy/protocol/pos/locked-gold", - "legacy/protocol/pos/validator-elections", - { - "group": "Epoch Rewards", - "pages": [ - "legacy/protocol/pos/epoch-rewards", - "legacy/protocol/pos/epoch-rewards-validator", - "legacy/protocol/pos/epoch-rewards-locked-gold" - ] - }, - "legacy/protocol/pos/penalties" - ] - }, - { - "group": "Consensus", - "pages": [ - "legacy/protocol/consensus/index", - "legacy/protocol/consensus/validator-set-differences", - "legacy/protocol/consensus/locating-nodes" - ] - }, - { - "group": "Transactions", - "pages": [ - "legacy/protocol/transaction/index", - "legacy/protocol/transaction/native-currency", - "legacy/protocol/transaction/erc20-transaction-fees", - "legacy/protocol/transaction/gas-pricing", - "legacy/protocol/transaction/escrow", - "legacy/protocol/transaction/tx-comment-encryption", - "legacy/protocol/transaction/transaction-types" - ] - }, - { - "group": "Stability", - "pages": [ - "legacy/protocol/stability/index", - "legacy/protocol/stability/doto", - "legacy/protocol/stability/granda-mento", - "legacy/protocol/stability/oracles", - "legacy/protocol/stability/stability-fees", - "legacy/protocol/stability/adding-stable-assets" - ] - }, - { - "group": "Identity", - "pages": [ - "legacy/protocol/identity/index", - "legacy/protocol/identity/metadata", - "legacy/protocol/identity/smart-contract-accounts", - "legacy/protocol/identity/encrypted-cloud-backup", - "legacy/protocol/identity/privacy-research", - { - "group": "ODIS", - "pages": [ - { - "group": "Use Cases", - "pages": [ - "legacy/protocol/identity/odis-use-case-phone-number-privacy", - "legacy/protocol/identity/odis-use-case-key-hardening" - ] - }, - { - "group": "Domains", - "pages": [ - "legacy/protocol/identity/odis-domain", - "legacy/protocol/identity/odis-domain-sequential-delay-domain" - ] - } - ] - } - ] - }, - "legacy/protocol/randomness", - { - "group": "Contracts", - "pages": ["legacy/protocol/contracts/add-contract"] - } - ] - }, - { - "group": "Nodes", - "pages": ["legacy/node/run-mainnet"] - }, - { - "group": "Validator", - "pages": [ - "legacy/validator/index", - "legacy/validator/voting", - { - "group": "Run a Validator", - "pages": ["legacy/validator/run/mainnet"] - }, - { - "group": "Key Management", - "pages": [ - "legacy/validator/key-management/summary", - "legacy/validator/key-management/detailed", - "legacy/validator/key-management/key-rotation" - ] - }, - "legacy/validator/security", - "legacy/validator/monitoring", - "legacy/validator/devops-best-practices", - "legacy/validator/node-upgrade", - "legacy/validator/proxy", - "legacy/validator/validator-explorer", - "legacy/validator/celo-foundation-voting-policy", - "legacy/validator/troubleshooting-faq" - ] - } - ] } ], "global": { @@ -681,7 +539,7 @@ }, { "anchor": "FAQs", - "href": "https://docs.celo.org/legacy/faq", + "href": "https://docs.celo.org/infra-partners/operators/faq", "icon": "square-question" } ] @@ -839,7 +697,7 @@ }, { "source": "/celo-codebase/protocol/consensus/locating-nodes", - "destination": "/legacy/protocol/consensus/locating-nodes" + "destination": "/home/celo-l1" }, { "source": "/celo-codebase/protocol/consensus/ultralight-sync", @@ -847,47 +705,47 @@ }, { "source": "/celo-codebase/protocol/consensus/validator-set-differences", - "destination": "/legacy/protocol/consensus/validator-set-differences" + "destination": "/home/celo-l1" }, { "source": "/celo-codebase/protocol/identity", - "destination": "/legacy/protocol/identity" + "destination": "/build-on-celo/build-on-socialconnect" }, { "source": "/celo-codebase/protocol/identity/encrypted-cloud-backup", - "destination": "/legacy/protocol/identity/encrypted-cloud-backup" + "destination": "/build-on-celo/build-on-socialconnect" }, { "source": "/celo-codebase/protocol/identity/index", - "destination": "/legacy/protocol/identity" + "destination": "/build-on-celo/build-on-socialconnect" }, { "source": "/celo-codebase/protocol/identity/metadata", - "destination": "/legacy/protocol/identity/metadata" + "destination": "/home/protocol/metadata" }, { "source": "/celo-codebase/protocol/identity/phone-number-privacy", - "destination": "/legacy/protocol/identity/odis-use-case-phone-number-privacy" + "destination": "/build-on-celo/build-on-socialconnect" }, { "source": "/celo-codebase/protocol/identity/privacy-research", - "destination": "/legacy/protocol/identity/privacy-research" + "destination": "/home/celo-l1" }, { "source": "/celo-codebase/protocol/identity/randomness", - "destination": "/legacy/protocol/randomness" + "destination": "/specs/l2-migration#deactivated-random-contract" }, { "source": "/celo-codebase/protocol/identity/smart-contract-accounts", - "destination": "/legacy/protocol/identity/smart-contract-accounts" + "destination": "/home/celo-l1" }, { "source": "/celo-codebase/protocol/identity/valora-accounts", - "destination": "/legacy/protocol/identity/smart-contract-accounts" + "destination": "/home/celo-l1" }, { "source": "/celo-codebase/protocol/identity#using-the-mapping-for-payment", - "destination": "/legacy/protocol/identity" + "destination": "/build-on-celo/build-on-socialconnect" }, { "source": "/celo-codebase/protocol/index", @@ -895,31 +753,31 @@ }, { "source": "/celo-codebase/protocol/odis", - "destination": "/legacy/protocol/identity/odis" + "destination": "/build-on-celo/build-on-socialconnect" }, { "source": "/celo-codebase/protocol/odis/domains", - "destination": "/legacy/protocol/identity/odis" + "destination": "/build-on-celo/build-on-socialconnect" }, { "source": "/celo-codebase/protocol/odis/domains/index", - "destination": "/legacy/protocol/identity/odis-domain" + "destination": "/build-on-celo/build-on-socialconnect" }, { "source": "/celo-codebase/protocol/odis/domains/sequential-delay-domain", - "destination": "/legacy/protocol/identity/odis-domain-sequential-delay-domain" + "destination": "/build-on-celo/build-on-socialconnect" }, { "source": "/celo-codebase/protocol/odis/index", - "destination": "/legacy/protocol/identity/odis" + "destination": "/build-on-celo/build-on-socialconnect" }, { "source": "/celo-codebase/protocol/odis/use-cases/key-hardening", - "destination": "/legacy/protocol/identity/odis-use-case-key-hardening" + "destination": "/build-on-celo/build-on-socialconnect" }, { "source": "/celo-codebase/protocol/odis/use-cases/phone-number-privacy", - "destination": "/legacy/protocol/identity/odis-use-case-phone-number-privacy" + "destination": "/build-on-celo/build-on-socialconnect" }, { "source": "/celo-codebase/protocol/optics", @@ -939,15 +797,15 @@ }, { "source": "/celo-codebase/protocol/plumo", - "destination": "/legacy/overview" + "destination": "/home/celo-l1" }, { "source": "/celo-codebase/protocol/proof-of-stake", - "destination": "/legacy/protocol/pos" + "destination": "/home/protocol/staking/index" }, { "source": "/celo-codebase/protocol/proof-of-stake/becoming-a-validator", - "destination": "/legacy/protocol/pos/becoming-a-validator" + "destination": "/contribute-to-celo/community-rpc-nodes/registering-as-rpc-node" }, { "source": "/celo-codebase/protocol/proof-of-stake/carbon-offsetting-fund", @@ -959,7 +817,7 @@ }, { "source": "/celo-codebase/protocol/proof-of-stake/epoch-rewards", - "destination": "/legacy/protocol/pos/epoch-rewards" + "destination": "/home/protocol/epoch-rewards/index" }, { "source": "/celo-codebase/protocol/proof-of-stake/epoch-rewards/carbon-offsetting-fund", @@ -975,51 +833,51 @@ }, { "source": "/celo-codebase/protocol/proof-of-stake/epoch-rewards/locked-gold-rewards", - "destination": "/legacy/protocol/pos/epoch-rewards-locked-gold" + "destination": "/home/protocol/epoch-rewards/index" }, { "source": "/celo-codebase/protocol/proof-of-stake/epoch-rewards/locked-gold-rewards#introduction-to-locked-celo-rewards", - "destination": "/legacy/protocol/pos/epoch-rewards-locked-gold" + "destination": "/home/protocol/epoch-rewards/index" }, { "source": "/celo-codebase/protocol/proof-of-stake/epoch-rewards/validator-rewards", - "destination": "/legacy/protocol/pos/epoch-rewards-validator" + "destination": "/home/protocol/epoch-rewards/index" }, { "source": "/celo-codebase/protocol/proof-of-stake/epoch-rewards/validator-rewards#:~:text=Calculating%20Uptime%20Score,validators%20committing%20the%20previous%20block.", - "destination": "/legacy/protocol/pos/epoch-rewards-validator" + "destination": "/home/protocol/epoch-rewards/index" }, { "source": "/celo-codebase/protocol/proof-of-stake/epoch-rewards/validator-rewards#calculating-uptime-score", - "destination": "/legacy/protocol/pos/epoch-rewards-validator" + "destination": "/home/protocol/epoch-rewards/index" }, { "source": "/celo-codebase/protocol/proof-of-stake/index", - "destination": "/legacy/protocol/pos" + "destination": "/home/protocol/staking/index" }, { "source": "/celo-codebase/protocol/proof-of-stake/locked-gold", - "destination": "/legacy/protocol/pos/locked-gold" + "destination": "/home/protocol/staking/locked-celo" }, { "source": "/celo-codebase/protocol/proof-of-stake/locked-gold-rewards", - "destination": "/legacy/protocol/pos/epoch-rewards-locked-gold" + "destination": "/home/protocol/epoch-rewards/index" }, { "source": "/celo-codebase/protocol/proof-of-stake/penalties", - "destination": "/legacy/protocol/pos/penalties" + "destination": "/contribute-to-celo/community-rpc-nodes/penalties" }, { "source": "/celo-codebase/protocol/proof-of-stake/validator-elections", - "destination": "/legacy/protocol/pos/validator-elections" + "destination": "/home/protocol/staking/validator-elections" }, { "source": "/celo-codebase/protocol/proof-of-stake/validator-groups", - "destination": "/legacy/protocol/pos/validator-groups" + "destination": "/home/protocol/staking/validator-groups" }, { "source": "/celo-codebase/protocol/proof-of-stake/validator-rewards", - "destination": "/legacy/protocol/pos/epoch-rewards-validator" + "destination": "/home/protocol/epoch-rewards/index" }, { "source": "/celo-codebase/protocol/release-gold", @@ -1027,39 +885,39 @@ }, { "source": "/celo-codebase/protocol/stability", - "destination": "/legacy/protocol/stability" + "destination": "/build-on-celo/build-with-local-stablecoin" }, { "source": "/celo-codebase/protocol/stability/adding_stable_assets", - "destination": "/legacy/protocol/stability/adding-stable-assets" + "destination": "/build-on-celo/build-with-local-stablecoin" }, { "source": "/celo-codebase/protocol/stability/doto", - "destination": "/legacy/protocol/stability/doto" + "destination": "/build-on-celo/build-with-local-stablecoin" }, { "source": "/celo-codebase/protocol/stability/granda-mento", - "destination": "/legacy/protocol/stability/granda-mento" + "destination": "/home/celo-l1" }, { "source": "/celo-codebase/protocol/stability/index", - "destination": "/legacy/protocol/stability" + "destination": "/build-on-celo/build-with-local-stablecoin" }, { "source": "/celo-codebase/protocol/stability/oracles", - "destination": "/legacy/protocol/stability/oracles" + "destination": "/tooling/oracles/index" }, { "source": "/celo-codebase/protocol/stability/stability-fees", - "destination": "/legacy/protocol/stability/stability-fees" + "destination": "/home/celo-l1" }, { "source": "/celo-codebase/protocol/stability#stability-of-celos-stablecoin-protocol", - "destination": "/legacy/protocol/stability" + "destination": "/build-on-celo/build-with-local-stablecoin" }, { "source": "/celo-codebase/protocol/transactions/erc20-transaction-fees", - "destination": "/legacy/protocol/transaction/erc20-transaction-fees" + "destination": "/build-on-celo/fee-abstraction/overview" }, { "source": "/celo-codebase/protocol/transactions/escrow", @@ -1067,7 +925,7 @@ }, { "source": "/celo-codebase/protocol/transactions/gas-pricing", - "destination": "/legacy/protocol/transaction/gas-pricing" + "destination": "/specs/transaction-fees" }, { "source": "/celo-codebase/protocol/transactions/index", @@ -1075,7 +933,7 @@ }, { "source": "/celo-codebase/protocol/transactions/native-currency", - "destination": "/legacy/protocol/transaction/native-currency" + "destination": "/home/protocol/celo-token" }, { "source": "/celo-codebase/protocol/transactions/tx-comment-encryption", @@ -1131,7 +989,7 @@ }, { "source": "/celo-gold-holder-guide/voting-validators", - "destination": "/legacy/validator/voting" + "destination": "/home/protocol/staking/voting" }, { "source": "/celo-holder-guide/celo-exchange-bot", @@ -1187,7 +1045,7 @@ }, { "source": "/celo-holder-guide/voting-validators", - "destination": "/legacy/validator/voting" + "destination": "/home/protocol/staking/voting" }, { "source": "/celo-owner-guide/celo-exchange-bot", @@ -1219,7 +1077,7 @@ }, { "source": "/celo-owner-guide/quick-start#vote-for-a-validator-group", - "destination": "/legacy/validator/voting" + "destination": "/home/protocol/staking/voting" }, { "source": "/celo-owner-guide/release-gold", @@ -1231,7 +1089,7 @@ }, { "source": "/celo-owner-guide/voting-validators", - "destination": "/legacy/validator/voting" + "destination": "/home/protocol/staking/voting" }, { "source": "/celo-sdk", @@ -1463,7 +1321,7 @@ }, { "source": "/blog/2022/05/11/Plumo%20-%20An%20Ultralight%20Blockchain%20Client%20on%20Celo", - "destination": "/legacy/overview" + "destination": "/home/celo-l1" }, { "source": "/blog/2022/05/19/3%20Simple%20Steps%20to%20Get%20Started%20with%20Valora%20on%20Celo", @@ -1995,7 +1853,7 @@ }, { "source": "/getting-started/baklava-testnet/running-a-validator-in-baklava", - "destination": "/legacy/validator" + "destination": "/contribute-to-celo/community-rpc-nodes/community-rpc-node" }, { "source": "/getting-started/choosing-a-network", @@ -2067,7 +1925,7 @@ }, { "source": "/getting-started/validator-troubleshooting-faq", - "destination": "/legacy/validator" + "destination": "/contribute-to-celo/community-rpc-nodes/community-rpc-node" }, { "source": "/getting-started/wallets", @@ -2175,7 +2033,7 @@ }, { "source": "/network/baklava/run-validator", - "destination": "/legacy/validator" + "destination": "/contribute-to-celo/community-rpc-nodes/community-rpc-node" }, { "source": "/network/mainnet/run-full-node", @@ -2183,7 +2041,7 @@ }, { "source": "/network/mainnet/run-validator", - "destination": "/legacy/validator" + "destination": "/contribute-to-celo/community-rpc-nodes/community-rpc-node" }, { "source": "/network/node/run-alfajores", @@ -2219,7 +2077,7 @@ }, { "source": "/protocol/consensus/locating-nodes", - "destination": "/legacy/protocol/consensus/locating-nodes" + "destination": "/home/celo-l1" }, { "source": "/protocol/consensus/ultralight-sync", @@ -2227,11 +2085,11 @@ }, { "source": "/protocol/consensus/validator-set-differences", - "destination": "/legacy/protocol/consensus/validator-set-differences" + "destination": "/home/celo-l1" }, { "source": "/protocol/contracts/add-contract", - "destination": "/legacy/protocol/contracts/add-contract" + "destination": "/contribute-to-celo/contributors/code-contributors" }, { "source": "/protocol/cross-chain-messaging", @@ -2275,7 +2133,7 @@ }, { "source": "/protocol/pos/epoch-rewards", - "destination": "/legacy/protocol/pos/epoch-rewards" + "destination": "/home/protocol/epoch-rewards/index" }, { "source": "/protocol/pos/epoch-rewards-carbon-offsetting-fund", @@ -2287,43 +2145,43 @@ }, { "source": "/protocol/pos/epoch-rewards-locked-gold", - "destination": "/legacy/protocol/pos/epoch-rewards-locked-gold" + "destination": "/home/protocol/epoch-rewards/index" }, { "source": "/protocol/pos/epoch-rewards-validator", - "destination": "/legacy/protocol/pos/epoch-rewards-validator" + "destination": "/home/protocol/epoch-rewards/index" }, { "source": "/protocol/pos/index", - "destination": "/legacy/protocol/pos" + "destination": "/home/protocol/staking/index" }, { "source": "/protocol/pos/locked-gold", - "destination": "/legacy/protocol/pos/locked-gold" + "destination": "/home/protocol/staking/locked-celo" }, { "source": "/protocol/pos/penalties", - "destination": "/legacy/protocol/pos/penalties" + "destination": "/contribute-to-celo/community-rpc-nodes/penalties" }, { "source": "/protocol/pos/validator-elections", - "destination": "/legacy/protocol/pos/validator-elections" + "destination": "/home/protocol/staking/validator-elections" }, { "source": "/protocol/pos/validator-groups", - "destination": "/legacy/protocol/pos/validator-groups" + "destination": "/home/protocol/staking/validator-groups" }, { "source": "/protocol/pos/validator-rewards", - "destination": "/legacy/protocol/pos/epoch-rewards-validator" + "destination": "/home/protocol/epoch-rewards/index" }, { "source": "/protocol/proof-of-stake", - "destination": "/legacy/protocol/pos" + "destination": "/home/protocol/staking/index" }, { "source": "/protocol/randomness", - "destination": "/legacy/protocol/randomness" + "destination": "/specs/l2-migration#deactivated-random-contract" }, { "source": "/protocol/socialconnect", @@ -2331,7 +2189,7 @@ }, { "source": "/protocol/stability", - "destination": "/legacy/protocol/stability" + "destination": "/build-on-celo/build-with-local-stablecoin" }, { "source": "/protocol/transaction/erc20-transaction-fees", @@ -2407,11 +2265,11 @@ }, { "source": "/validator-guide/attestation-service", - "destination": "/legacy/validator" + "destination": "/contribute-to-celo/community-rpc-nodes/community-rpc-node" }, { "source": "/validator-guide/celo-foundation-voting-policy", - "destination": "/legacy/validator/celo-foundation-voting-policy" + "destination": "/home/protocol/staking/voting" }, { "source": "/validator-guide/celo-signal", @@ -2419,55 +2277,55 @@ }, { "source": "/validator-guide/devops-best-practices", - "destination": "/legacy/validator/devops-best-practices" + "destination": "/home/celo-l1" }, { "source": "/validator-guide/key-management/detailed", - "destination": "/legacy/validator/key-management/detailed" + "destination": "/home/protocol/staking/key-management/detailed" }, { "source": "/validator-guide/key-management/key-rotation", - "destination": "/legacy/validator/key-management/key-rotation" + "destination": "/home/protocol/staking/key-management/key-rotation" }, { "source": "/validator-guide/key-management/summary", - "destination": "/legacy/validator/key-management/summary" + "destination": "/home/protocol/staking/key-management/summary" }, { "source": "/validator-guide/monitoring", - "destination": "/legacy/validator/monitoring" + "destination": "/home/celo-l1" }, { "source": "/validator-guide/node-upgrades", - "destination": "/legacy/validator/node-upgrade" + "destination": "/home/celo-l1" }, { "source": "/validator-guide/overview", - "destination": "/legacy/validator" + "destination": "/contribute-to-celo/community-rpc-nodes/community-rpc-node" }, { "source": "/validator-guide/proxy", - "destination": "/legacy/validator/proxy" + "destination": "/home/celo-l1" }, { "source": "/validator-guide/securing-nodes-and-services", - "destination": "/legacy/validator/security" + "destination": "/home/celo-l1" }, { "source": "/validator-guide/summary/key-rotation", - "destination": "/legacy/validator/key-management/key-rotation" + "destination": "/home/protocol/staking/key-management/key-rotation" }, { "source": "/validator-guide/validator-explorer", - "destination": "/legacy/validator/validator-explorer" + "destination": "/home/protocol/staking/voting#validator-explorers" }, { "source": "/validator/attestation", - "destination": "/legacy/validator" + "destination": "/contribute-to-celo/community-rpc-nodes/community-rpc-node" }, { "source": "/validator/celo-foundation-voting-policy", - "destination": "/legacy/validator/celo-foundation-voting-policy" + "destination": "/home/protocol/staking/voting" }, { "source": "/validator/celo-signal", @@ -2475,59 +2333,59 @@ }, { "source": "/validator/devops-best-practices", - "destination": "/legacy/validator/devops-best-practices" + "destination": "/home/celo-l1" }, { "source": "/validator/key-management/detailed", - "destination": "/legacy/validator/key-management/detailed" + "destination": "/home/protocol/staking/key-management/detailed" }, { "source": "/validator/key-management/key-rotation", - "destination": "/legacy/validator/key-management/key-rotation" + "destination": "/home/protocol/staking/key-management/key-rotation" }, { "source": "/validator/key-management/summary", - "destination": "/legacy/validator/key-management/summary" + "destination": "/home/protocol/staking/key-management/summary" }, { "source": "/validator/monitoring", - "destination": "/legacy/validator/monitoring" + "destination": "/home/celo-l1" }, { "source": "/validator/node-upgrade", - "destination": "/legacy/validator/node-upgrade" + "destination": "/home/celo-l1" }, { "source": "/validator/proxy", - "destination": "/legacy/validator/proxy" + "destination": "/home/celo-l1" }, { "source": "/validator/run/alfajores", - "destination": "/legacy/validator/run/mainnet" + "destination": "/contribute-to-celo/community-rpc-nodes/community-rpc-node" }, { "source": "/validator/run/baklava", - "destination": "/legacy/validator/run/mainnet" + "destination": "/contribute-to-celo/community-rpc-nodes/community-rpc-node" }, { "source": "/validator/run/celo-devnet", - "destination": "/legacy/validator/run/mainnet" + "destination": "/contribute-to-celo/community-rpc-nodes/community-rpc-node" }, { "source": "/validator/run/celo-testnet", - "destination": "/legacy/validator/run/mainnet" + "destination": "/contribute-to-celo/community-rpc-nodes/community-rpc-node" }, { "source": "/validator/run/mainnet", - "destination": "/legacy/validator/run/mainnet" + "destination": "/contribute-to-celo/community-rpc-nodes/community-rpc-node" }, { "source": "/validator/security", - "destination": "/legacy/validator/security" + "destination": "/home/celo-l1" }, { "source": "/validator/troubleshooting-faq", - "destination": "/legacy/validator/troubleshooting-faq" + "destination": "/contribute-to-celo/community-rpc-nodes/validator-rpc-faq" }, { "source": "/what-is-celo/about-celo-l1/protocol", @@ -2823,7 +2681,7 @@ }, { "source": "/what-is-celo/about-celo-l1/:slug*", - "destination": "/legacy/:slug*" + "destination": "/home/celo-l1" }, { "source": "/cli", @@ -2927,15 +2785,15 @@ }, { "source": "/cel2/faq", - "destination": "/legacy/faq" + "destination": "/infra-partners/operators/faq" }, { "source": "/cel2/guides/bridging-celo-from-l1-to-l2", - "destination": "/legacy/transition/guides/bridging-celo-from-l1-to-l2" + "destination": "/home/bridged-tokens/bridging-celo-from-ethereum" }, { "source": "/cel2/guides/withdrawing-celo-from-l2-to-l1", - "destination": "/legacy/transition/guides/withdrawing-celo-from-l2-to-l1" + "destination": "/home/bridged-tokens/withdrawing-celo-to-ethereum" }, { "source": "/cel2/notices/celo-sepolia-launch", @@ -3027,23 +2885,23 @@ }, { "source": "/cel2/whats-changed/l1-l2", - "destination": "/legacy/transition/whats-changed/l1-l2" + "destination": "/specs/l2-migration" }, { "source": "/cel2/whats-changed/op-l2", - "destination": "/legacy/transition/optimism/op-l2" + "destination": "/specs/l2-migration" }, { "source": "/cel2/whats-changed/overview", - "destination": "/legacy/transition/whats-changed/overview" + "destination": "/home/celo-l1" }, { "source": "/cel2", - "destination": "/legacy/overview" + "destination": "/home/celo-l1" }, { "source": "/learn/add-gas-currency", - "destination": "/legacy/protocol/transaction/erc20-transaction-fees" + "destination": "/build-on-celo/fee-abstraction/overview" }, { "source": "/learn/CELO-coin-summary", @@ -3099,7 +2957,7 @@ }, { "source": "/learn/celo-whitepapers", - "destination": "/legacy/overview" + "destination": "/home/celo-l1" }, { "source": "/learn/developer-onboarding", @@ -3276,6 +3134,246 @@ { "source": "/community/developer-events", "destination": "/contribute-to-celo/builders" + }, + { + "source": "/legacy/faq", + "destination": "/infra-partners/operators/faq" + }, + { + "source": "/legacy/transition/guides/bridging-celo-from-l1-to-l2", + "destination": "/home/bridged-tokens/bridging-celo-from-ethereum" + }, + { + "source": "/legacy/transition/guides/withdrawing-celo-from-l2-to-l1", + "destination": "/home/bridged-tokens/withdrawing-celo-to-ethereum" + }, + { + "source": "/legacy/protocol/pos/index", + "destination": "/home/protocol/staking/index" + }, + { + "source": "/legacy/protocol/pos/locked-gold", + "destination": "/home/protocol/staking/locked-celo" + }, + { + "source": "/legacy/protocol/pos/validator-elections", + "destination": "/home/protocol/staking/validator-elections" + }, + { + "source": "/legacy/protocol/pos/validator-groups", + "destination": "/home/protocol/staking/validator-groups" + }, + { + "source": "/legacy/validator/voting", + "destination": "/home/protocol/staking/voting" + }, + { + "source": "/legacy/validator/key-management/summary", + "destination": "/home/protocol/staking/key-management/summary" + }, + { + "source": "/legacy/validator/key-management/detailed", + "destination": "/home/protocol/staking/key-management/detailed" + }, + { + "source": "/legacy/validator/key-management/key-rotation", + "destination": "/home/protocol/staking/key-management/key-rotation" + }, + { + "source": "/legacy/protocol/identity/metadata", + "destination": "/home/protocol/metadata" + }, + { + "source": "/legacy/overview", + "destination": "/home/celo-l1" + }, + { + "source": "/legacy/l1-architecture", + "destination": "/home/celo-l1" + }, + { + "source": "/legacy/protocol/transaction/index", + "destination": "/home/protocol/transactions/overview" + }, + { + "source": "/legacy/protocol/transaction/native-currency", + "destination": "/home/protocol/celo-token" + }, + { + "source": "/legacy/protocol/transaction/erc20-transaction-fees", + "destination": "/build-on-celo/fee-abstraction/overview" + }, + { + "source": "/legacy/protocol/transaction/gas-pricing", + "destination": "/specs/transaction-fees" + }, + { + "source": "/legacy/protocol/transaction/escrow", + "destination": "/home/protocol/escrow" + }, + { + "source": "/legacy/protocol/transaction/transaction-types", + "destination": "/home/protocol/transactions/transaction-types" + }, + { + "source": "/legacy/protocol/transaction/tx-comment-encryption", + "destination": "/home/protocol/transactions/tx-comment-encryption" + }, + { + "source": "/legacy/protocol/stability/index", + "destination": "/build-on-celo/build-with-local-stablecoin" + }, + { + "source": "/legacy/protocol/stability/adding-stable-assets", + "destination": "/build-on-celo/build-with-local-stablecoin" + }, + { + "source": "/legacy/protocol/stability/stability-fees", + "destination": "/home/celo-l1" + }, + { + "source": "/legacy/protocol/stability/oracles", + "destination": "/tooling/oracles/index" + }, + { + "source": "/legacy/protocol/stability/doto", + "destination": "/build-on-celo/build-with-local-stablecoin" + }, + { + "source": "/legacy/protocol/stability/granda-mento", + "destination": "/home/celo-l1" + }, + { + "source": "/legacy/protocol/identity/index", + "destination": "/build-on-celo/build-on-socialconnect" + }, + { + "source": "/legacy/protocol/identity/odis", + "destination": "/build-on-celo/build-on-socialconnect" + }, + { + "source": "/legacy/protocol/identity/odis-domain", + "destination": "/build-on-celo/build-on-socialconnect" + }, + { + "source": "/legacy/protocol/identity/odis-domain-sequential-delay-domain", + "destination": "/build-on-celo/build-on-socialconnect" + }, + { + "source": "/legacy/protocol/identity/odis-use-case-phone-number-privacy", + "destination": "/build-on-celo/build-on-socialconnect" + }, + { + "source": "/legacy/protocol/identity/odis-use-case-key-hardening", + "destination": "/build-on-celo/build-on-socialconnect" + }, + { + "source": "/legacy/protocol/identity/encrypted-cloud-backup", + "destination": "/build-on-celo/build-on-socialconnect" + }, + { + "source": "/legacy/protocol/identity/smart-contract-accounts", + "destination": "/home/celo-l1" + }, + { + "source": "/legacy/protocol/identity/privacy-research", + "destination": "/home/celo-l1" + }, + { + "source": "/legacy/protocol/pos/epoch-rewards", + "destination": "/home/protocol/epoch-rewards/index" + }, + { + "source": "/legacy/protocol/pos/epoch-rewards-validator", + "destination": "/home/protocol/epoch-rewards/index" + }, + { + "source": "/legacy/protocol/pos/epoch-rewards-locked-gold", + "destination": "/home/protocol/epoch-rewards/index" + }, + { + "source": "/legacy/protocol/pos/penalties", + "destination": "/contribute-to-celo/community-rpc-nodes/penalties" + }, + { + "source": "/legacy/protocol/pos/becoming-a-validator", + "destination": "/contribute-to-celo/community-rpc-nodes/registering-as-rpc-node" + }, + { + "source": "/legacy/protocol/consensus/index", + "destination": "/home/celo-l1" + }, + { + "source": "/legacy/protocol/consensus/validator-set-differences", + "destination": "/home/celo-l1" + }, + { + "source": "/legacy/protocol/consensus/locating-nodes", + "destination": "/home/celo-l1" + }, + { + "source": "/legacy/protocol/randomness", + "destination": "/specs/l2-migration#deactivated-random-contract" + }, + { + "source": "/legacy/protocol/contracts/add-contract", + "destination": "/contribute-to-celo/contributors/code-contributors" + }, + { + "source": "/legacy/node/run-mainnet", + "destination": "/infra-partners/operators/archive-node" + }, + { + "source": "/legacy/validator/index", + "destination": "/contribute-to-celo/community-rpc-nodes/community-rpc-node" + }, + { + "source": "/legacy/validator/run/mainnet", + "destination": "/contribute-to-celo/community-rpc-nodes/community-rpc-node" + }, + { + "source": "/legacy/validator/security", + "destination": "/home/celo-l1" + }, + { + "source": "/legacy/validator/monitoring", + "destination": "/home/celo-l1" + }, + { + "source": "/legacy/validator/devops-best-practices", + "destination": "/home/celo-l1" + }, + { + "source": "/legacy/validator/node-upgrade", + "destination": "/home/celo-l1" + }, + { + "source": "/legacy/validator/proxy", + "destination": "/home/celo-l1" + }, + { + "source": "/legacy/validator/troubleshooting-faq", + "destination": "/contribute-to-celo/community-rpc-nodes/validator-rpc-faq" + }, + { + "source": "/legacy/validator/validator-explorer", + "destination": "/home/protocol/staking/voting#validator-explorers" + }, + { + "source": "/legacy/validator/celo-foundation-voting-policy", + "destination": "/home/protocol/staking/voting" + }, + { + "source": "/legacy/transition/whats-changed/overview", + "destination": "/home/celo-l1" + }, + { + "source": "/legacy/transition/whats-changed/l1-l2", + "destination": "/specs/l2-migration" + }, + { + "source": "/legacy/transition/optimism/op-l2", + "destination": "/specs/l2-migration" } ], "footer": { diff --git a/home/protocol/celo-token.mdx b/home/protocol/celo-token.mdx index d196e165f..a15a55da2 100644 --- a/home/protocol/celo-token.mdx +++ b/home/protocol/celo-token.mdx @@ -40,6 +40,7 @@ Regardless of the transfer method, CELO tokens **reflect in both the native acco - The `transfer` and `transferFrom` functions do **not** modify contract storage. - Instead, these functions **initiate a native transfer**. - Since Ethereum does not support native transfers from smart contracts, **Celo introduces a transfer precompile** to handle this. This precompile can only be called by the CELO token. +- The address of the CELO ERC-20 contract can be looked up via the Registry smart contract, under the `GoldToken` identifier. --- diff --git a/home/protocol/epoch-rewards/index.mdx b/home/protocol/epoch-rewards/index.mdx index 5387c6e6d..9ef5e636e 100644 --- a/home/protocol/epoch-rewards/index.mdx +++ b/home/protocol/epoch-rewards/index.mdx @@ -32,7 +32,7 @@ A total of **400 million CELO** will be released through epoch rewards over time ****Migration from L1 to L2**** -For details on how epoch rewards worked when Celo was a Layer 1 blockchain, see [the historical epoch rewards section](/legacy/protocol/pos/epoch-rewards). +For details on how epoch rewards worked when Celo was a Layer 1 blockchain, see [About Celo L1](/home/celo-l1). For technical changes since the L1 to L2 migration, refer to the [official specs](/specs/smart-contract-updates-from-l1#epochs-and-rewards). diff --git a/infra-partners/operators/migrate-node.mdx b/infra-partners/operators/migrate-node.mdx index ed0984b1b..becaf059c 100644 --- a/infra-partners/operators/migrate-node.mdx +++ b/infra-partners/operators/migrate-node.mdx @@ -278,3 +278,12 @@ If needed, you can also run the `check-db` script on its own as follows. ``` This command takes in an optional `--fail-fast` flag that will make it exit at the first gap detected like it does when run via [celo-l2-node-docker-compose](https://github.com/celo-org/celo-l2-node-docker-compose). If the `--fail-fast` flag is not provided then the script will collect all the gaps it finds and print them out at the end. + +### Extracting a Key from the Old Geth Keystore + +The old geth keystore API is not supported anymore, but you can extract your private key by using [cast](https://book.getfoundry.sh/cast/)'s `decrypt-keystore` command. +Just give it the path to your keystore and the name of your key, e.g. + +```bash +cast wallet decrypt-keystore -k validator-00/keystore/ testkey +``` diff --git a/legacy/faq.mdx b/legacy/faq.mdx deleted file mode 100644 index 9959d7f25..000000000 --- a/legacy/faq.mdx +++ /dev/null @@ -1,100 +0,0 @@ ---- -title: Cel2 FAQ -og:description: Frequently Asked Questions about Cel2 ---- - -## Mainnet - - - - -A couple of issues could be causing this. - -* If you are running multiple instances of op-node, make sure to check that they each have a unique and persisted private key at `--p2p.priv.path` -* Ensure that your node is accessible to other nodes, check the __Configure P2P for external network access__ section under [Running a full node](/infra-partners/operators/run-node#running-a-full-node) - - - - -See the guides for [running a node](/infra-partners/operators/run-node) or the guide on [how to migrate an L1 node](/infra-partners/operators/migrate-node). - - - - -Yes. This is part of [running a node](/infra-partners/operators/run-node). -If you're using the [Docker Compose Setup](https://github.com/celo-org/celo-l2-node-docker-compose), it's included. - - - - -All balances have been carried over to the L2, unchanged. - - - - -There is no change and it continues to work in the same way as before. - - - - -Yes, same as with Ethereum. - - - - -Have a look at the [changes from L1 to L2 in the specs](/specs/l2-migration#changes-for-json-rpc-users). - - - - -Validators are becoming [Community RPC providers](/contribute-to-celo/community-rpc-nodes/community-rpc-node). - - - - -There are multiple options. - -* Install [Celo CLI](/cli/index) at version 6.1.0 or later. Then run: `celocli network:community-rpc-nodes`. -* [Vido Node Explorer](https://dev.vido.atalma.io/celo/rpc) -* [Celo Community RPC Gateway](https://celo-community.org/) - - - - -[Governance](/home/protocol/governance/overview) remains a pillar of the Celo blockchain. The Validator Hotfix process has been adapted, see [Updated Governance Hotfix](/specs/l2-migration#updated-governance-hotfix) for the changes. - - - - -* CELO token duality? Supported, see [Token Duality](/specs/token-duality). -* Fee currencies? Supported, see [Fee Abstraction](/specs/fee-abstraction). -* Epoch rewards? Epochs now work differently, but rewards stay, see [Epochs and Rewards](/specs/smart-contract-updates-from-l1#epochs-and-rewards). - - - - -See [What's Changed Optimism -> Celo L2](/legacy/transition/optimism/op-l2). -Also see [Celo L2 Specification](/specs) for greater detail. - - - - -See [What's changed section covering L1 fees](/legacy/transition/optimism/op-l2#l1-fees). - - - - -The block period is 1 second. - - - - -The gas limit per block is 30 million, so the maximum throughput is 30M gas/s. - - - - -See [What's Changed Celo L1 -> L2](/legacy/transition/whats-changed/l1-l2) and [L1 -> L2 Migration Changes](/specs/l2-migration) in the spec for greater detail. - - - diff --git a/legacy/l1-architecture.mdx b/legacy/l1-architecture.mdx deleted file mode 100644 index 8945e5ac5..000000000 --- a/legacy/l1-architecture.mdx +++ /dev/null @@ -1,69 +0,0 @@ ---- -title: Architecture -og:description: Overview of the Celo Stack including it's blockchain, core contracts, and applications. -sidebarTitle: "L1 Architecture" ---- - -Overview of the Celo Stack including it's blockchain, core contracts, and applications. - - -This page describes the historical Celo Layer 1 blockchain. It is useful for understanding Celo’s history, but does not reflect the current state of the network. As of block height 31,056,500 (March 26, 2025, 3:00 AM UTC), Celo has transitioned to an Ethereum Layer 2. - - ---- - -## Introduction to the Celo Stack - -Celo is oriented around providing the simplest possible experience for end-users, who may have no familiarity with cryptocurrencies and may be using low-cost devices with limited connectivity. - -## A Full-Stack Approach - -To achieve this, Celo takes a full-stack approach, where each layer of the stack is designed with the end-user in mind while considering other stakeholders (e.g. operators of nodes in the network) involved in enabling the end-user experience. - - -![Celo full-stack architecture diagram showing three layers: Applications layer at top with Celo Wallet and other dApps, Celo Protocol layer in middle containing Core Contracts and Blockchain, and underlying infrastructure with validators, full nodes, and light clients](https://storage.googleapis.com/celo-website/docs/full-stack-diagram.jpg) - - -## Celo Blockchain - -An open cryptographic protocol that allows applications to make transactions with and run smart contracts in a secure and decentralized fashion. The Celo blockchain code has shared ancestry with[ Ethereum](https://www.ethereum.org/) and maintains full EVM compatibility for smart contracts. However, it uses a[ Byzantine Fault Tolerant](http://pmg.csail.mit.edu/papers/osdi99.pdf) (BFT) consensus mechanism (Proof-of-Stake) rather than Proof-of-Work and has different block format, transaction format, client synchronization protocols, and gas payment and pricing mechanisms. - -## Celo Core Contracts - -A set of smart contracts running on the Celo blockchain that comprise much of the logic of the platform features including ERC-20 stable currencies, identity attestations, proof-of-stake, and governance. These smart contracts are upgradeable and managed by the decentralized governance process. - -## Applications - -Applications for end users built on the Celo Platform. The Celo Wallet app, the first of an ecosystem of applications, allows end-users to manage accounts and make payments securely and simply by taking advantage of the innovations in the Celo Protocol. Applications take the form of external mobile or backend software: they interact with the Celo blockchain to issue transactions and invoke code that forms the Celo Core Contracts’ API. Third parties can also deploy custom smart contracts that their own applications can invoke, which in turn can leverage Celo Core Contracts. Applications may use centralized cloud services to provide some of their functionality: in the case of the Celo Wallet, push notifications, and a transaction activity feed. - -The Celo blockchain and Celo Core Contracts together comprise the Celo Protocol. - -## Celo Network Topology - -The topology of a Celo network consists of machines running the Celo blockchain software in several distinct configurations: - - -![Network topology diagram showing three types of nodes: Light Clients (represented by mobile phone icons) connecting to Full Nodes (computer server icons), which in turn connect to Validators (secure server icons). Arrows indicate the flow of communication between different node types in the Celo network hierarchy.](https://storage.googleapis.com/celo-website/docs/network.png) - - -## Validators - -Validators gather transactions received from other nodes and execute any associated smart contracts to form new blocks, then participate in a Byzantine Fault Tolerant (BFT) consensus protocol to advance the state of the network. Since BFT protocols can scale only to a few hundred participants and can tolerate at most a third of the participants acting maliciously, a proof-of-stake mechanism admits only a limited set of nodes to this role. - -## Full Nodes - -Most machines running the Celo blockchain software are either not configured to be, or not elected as, validators. Celo nodes do not do "mining" as in Proof-of-Work networks. Their primary role is to serve requests from light clients and forward their transactions, for which they receive the fees associated with those transactions. These payments create a ‘permissionless onramp’ for individuals in the community to earn currency. Full nodes maintain at least a partial history of the blockchain by transferring new blocks between themselves and can join or leave the network at any time. - -## Light Clients - -Applications including the Celo Wallet will also run on each user's device an instance of the Celo blockchain software operating as a ‘light client’. Light clients connect to full nodes to make requests for account and transaction data and to sign and submit new transactions, but they do not receive or retain the full state of the blockchain. - -## Celo Wallet - -The Celo Wallet application is a fully unmanaged wallet that allows users to self custody their funds using their own keys and accounts. All critical features such as sending transactions and checking balances can be done in a trustless manner using the peer-to-peer light client protocol. However, the wallet does use a few centralized cloud services to improve the user experience where possible, e.g.: - -- **Google Play Services:** to pre-load invitations in the app -- **Celo Wallet Notification Service:** sends device push notifications when a user receives a payment or requests for payment -- **Celo Wallet Blockchain API:** provides a GraphQL API to query transactions on the blockchain on a per-account basis, used to implement a user's activity feed. - -When end-users download the Celo Wallet from, for example, the Google Play Store, users are trusting both cLabs (or the entity that has made the application available in the Play Store) and Google to deliver a correct binary, and most users would feel that relying on these centralized services to provide this additional functionality is worthwhile. \ No newline at end of file diff --git a/legacy/node/run-mainnet.mdx b/legacy/node/run-mainnet.mdx deleted file mode 100644 index 33ec52646..000000000 --- a/legacy/node/run-mainnet.mdx +++ /dev/null @@ -1,123 +0,0 @@ ---- -title: "Run a Full Node" -sidebarTitle: "Mainnet Full Node" -og:description: How to run a full node on the Celo Mainnet Network using a prebuilt Docker image. ---- - -How to run on the Mainnet Network using a prebuilt Docker image. - - -This page describes the historical Celo Layer 1 blockchain. It is useful for understanding Celo’s history, but does not reflect the current state of the network. As of block height 31,056,500 (March 26, 2025, 3:00 AM UTC), Celo has transitioned to an Ethereum Layer 2. - - ---- - -Full nodes play a special purpose in the Celo ecosystem, acting as a bridge between the mobile wallets \(running as light clients\) and the validator nodes. - -## Prerequisites - -- **You have Docker installed.** If you don’t have it already, follow the instructions here: [Get Started with Docker](https://www.docker.com/get-started). It will involve creating or signing in with a Docker account, downloading a desktop app, and then launching the app to be able to use the Docker CLI. If you are running on a Linux server, follow the instructions for your distro [here](https://docs.docker.com/install/#server). You may be required to run Docker with `sudo` depending on your installation environment. - - -Code you'll see on this page is bash commands and their output. - -When you see text in angle brackets <>, replace them and the text inside with your own value of what it refers to. Don't include the <> in the command. - - -## Celo Networks - -First we are going to setup the environment variables required for the `mainnet` network. Run: - -```bash -export CELO_IMAGE=us.gcr.io/celo-org/geth:mainnet -``` - -## Pull the Celo Docker image - -We're going to use a Docker image containing the Celo node software in this tutorial. - -If you are re-running these instructions, the Celo Docker image may have been updated, and it's important to get the latest version. - -```bash -docker pull $CELO_IMAGE -``` - -## Set up a data directory - -First, create the directory that will store your node's configuration and its copy of the blockchain. This directory can be named anything you'd like, but here's a default you can use. The commands below create a directory and then navigate into it. The rest of the steps assume you are running the commands from inside this directory. - -```bash -mkdir celo-data-dir -cd celo-data-dir -``` - -## Create an account and get its address - -In this step, you'll create an account on the network. If you've already done this and have an account address, you can skip this and move on to configuring your node. - -Run the command to create a new account: - -```bash -docker run -v $PWD:/root/.celo --rm -it $CELO_IMAGE account new -``` - -It will prompt you for a passphrase, ask you to confirm it, and then will output your account address: `Public address of the key: ` - -Save this address to an environment variables, so that you can reference it below (don't include the braces): - -```bash -export CELO_ACCOUNT_ADDRESS= -``` - - -This environment variable will only persist while you have this terminal window open. If you want this environment variable to be available in the future, you can add it to your `~/.bash_profile` - - -## Start the node - -This command specifies the settings needed to run the node, and gets it started. - -```bash -docker run --name celo-fullnode -d --restart unless-stopped --stop-timeout 300 -p 127.0.0.1:8545:8545 -p 127.0.0.1:8546:8546 -p 30303:30303 -p 30303:30303/udp -v $PWD:/root/.celo $CELO_IMAGE --verbosity 3 --syncmode full --http --http.addr 0.0.0.0 --http.api eth,net,web3,debug,admin,personal --light.serve 90 --light.maxpeers 1000 --maxpeers 1100 --etherbase $CELO_ACCOUNT_ADDRESS --datadir /root/.celo -``` - -You'll start seeing some output. After a few minutes, you should see lines that look like this. This means your node has started syncing with the network and is receiving blocks. - -```text -INFO [07-16|14:04:24.924] Imported new chain segment blocks=139 txs=319 mgas=61.987 elapsed=8.085s mgasps=7.666 number=406 hash=9acf16…4fddc8 age=6h58m44s cache=1.51mB -INFO [07-16|14:04:32.928] Imported new chain segment blocks=303 txs=179 mgas=21.837 elapsed=8.004s mgasps=2.728 number=709 hash=8de06a…77bb92 age=6h33m37s cache=1.77mB -INFO [07-16|14:04:40.918] Imported new chain segment blocks=411 txs=0 mgas=0.000 elapsed=8.023s mgasps=0.000 number=1120 hash=3db22a…9fa95a age=5h59m30s cache=1.92mB -INFO [07-16|14:04:48.941] Imported new chain segment blocks=335 txs=0 mgas=0.000 elapsed=8.023s mgasps=0.000 number=1455 hash=7eb3f8…32ebf0 age=5h31m43s cache=2.09mB -INFO [07-16|14:04:56.944] Imported new chain segment blocks=472 txs=0 mgas=0.000 elapsed=8.003s mgasps=0.000 number=1927 hash=4f1010…1414c1 age=4h52m31s cache=2.34mB -``` - -You will have fully synced with the network once you have pulled the latest block number, which you can lookup by visiting the [Block Explorer](https://celo.blockscout.com/). - - -**Security**: The command line above includes the parameter `--http.addr 0.0.0.0` which makes the Celo Blockchain software listen for incoming RPC requests on all network adaptors. Exercise extreme caution in doing this when running outside Docker, as it means that any unlocked accounts and their funds may be accessed from other machines on the Internet. In the context of running a Docker container on your local machine, this together with the `docker -p` flags allows you to make RPC calls from outside the container, i.e from your local host, but not from outside your machine. Read more about [Docker Networking](https://docs.docker.com/network/network-tutorial-standalone/#use-user-defined-bridge-networks) here. - - -## Running an Archive Node - -If you would like to run an archive node for `celo-blockchain`, you can run the following command: - -```bash -docker run --name celo-fullnode -d --restart unless-stopped --stop-timeout 300 -p 127.0.0.1:8545:8545 -p 127.0.0.1:8546:8546 -p 30303:30303 -p 30303:30303/udp -v $PWD:/root/.celo $CELO_IMAGE --verbosity 3 --syncmode full --gcmode archive --txlookuplimit=0 --cache.preimages --http --http.addr 0.0.0.0 --http.api eth,net,web3,debug,admin,personal --light.serve 90 --light.maxpeers 1000 --maxpeers 1100 --etherbase $CELO_ACCOUNT_ADDRESS --datadir /root/.celo -``` - -We add the following flags: `--gcmode archive --txlookuplimit=0 --cache.preimages` - -In `celo-blockchain`, this is called gcmode which refers to the concept of garbage collection. Setting it to archive basically turns it off. - -## Command Line Interface - -Once the full node is running, it can serve the [Command Line Interface](/cli/) tool `celocli`. For example: - -```bash -$ npm install -g @celo/celocli -... -$ celocli node:synced -true -$ celocli account:new -... -``` \ No newline at end of file diff --git a/legacy/overview.mdx b/legacy/overview.mdx deleted file mode 100644 index 9119d17e4..000000000 --- a/legacy/overview.mdx +++ /dev/null @@ -1,39 +0,0 @@ ---- -title: "About Celo L1" -sidebarTitle: "About Celo L1" -og:description: Introduction to the Celo Layer 1 blockchain that ran from 2020 until the Layer 2 migration ---- - -Celo was launched in 2020 as a mobile-first Layer 1 blockchain designed to advance global financial inclusion through smartphone-accessible crypto payments and phone number-based addressing. Built on proof-of-stake consensus with a commitment to carbon neutrality, Celo's L1 featured fast, low-cost transactions and native stablecoins like cUSD that powered a vibrant DeFi ecosystem. - -In 2024, Celo began migrating from its Layer 1 architecture to become an Ethereum Layer 2 network built on the OP-Stack. This migration aimed to achieve greater scalability and interoperability while preserving Celo's core mission and complete transaction history. -The migration was completed in March 2025 at block 31,056,500. - - -This section documents the historical Celo Layer 1 blockchain before its completed migration to Layer 2 and does not reflect Celo's current L2 architecture. - - -### Technical Changes - -The table below summarizes the technical changes involved in transitioning from Celo's Layer 1 to Layer 2: - -| **Aspect** | **Layer 1** | **Layer 2** | -|----------------------|---------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------| -| **Architecture** | Single service, providing execution, consensus, and data availability. | Multiple services built on the op-stack with separate execution, data availability, and settlement layers. | -| **Bridging** | Third-party bridges connecting to various chains. | Additional native bridge with Ethereum alongside existing third-party bridges. | -| **CELO Token** | Lived on the Celo L1. | Lives on Ethereum; CELO on L2 represents CELO bridged from Ethereum. | -| **Blocks** | 5s long, 50M gas. | 1s long, 30M gas. | -| **Extra Fields** | — | Withdrawals & withdrawalsRoot, blobGasUsed & excessBlobGas, parentBeaconBlockRoot. | -| **Removed Fields** | — | Randomness, epochSnarkData. | -| **Validator Duties**| Operated the consensus protocol. | Validators will temporarily operate community RPC nodes. | -| **Validator Rewards**| Distributed at epoch blocks. | Distributed periodically via smart contract execution. | -| **Sequencing** | Determined by the output of consensus, run by validators. | Initially handled by a centralized sequencer with plans for decentralized sequencing later. | -| **Precompiles** | — | All Celo precompiles removed except for the transfer precompile which supports token duality. | -| **EIP1559** | Governable implementation on-chain. | Upgraded implementation with modified parameters across networks. | -| **Hardforks** | — | Cel2 hardfork for transition to L2 alongside other op-stack hardforks. | -| **Transactions** | — | Deprecated transactions include Type 0 with feeCurrency field and Type 124. | -| **Finality** | One block finality, instantaneous once block is produced. | Finality depends on trust in sequencer, batcher, proposer, and eigenDA, or ultimately on Ethereum. | - -For more detailed technical changes, see [Celo's L2 Migration Documentation](/specs/l2-migration). - -For the original research behind the Celo L1 design, see the [Celo whitepapers](https://celo.org/papers). \ No newline at end of file diff --git a/legacy/protocol/consensus/index.mdx b/legacy/protocol/consensus/index.mdx deleted file mode 100644 index 3ff4e8305..000000000 --- a/legacy/protocol/consensus/index.mdx +++ /dev/null @@ -1,25 +0,0 @@ ---- -title: "Consensus" -sidebarTitle: "Overview" -og:description: Overview of Celo's consensus protocol and network validators. ---- - -Overview of Celo's consensus protocol and network validators. - - -This page describes the historical Celo Layer 1 blockchain. It is useful for understanding Celo’s history, but does not reflect the current state of the network. As of block height 31,056,500 (March 26, 2025, 3:00 AM UTC), Celo has transitioned to an Ethereum Layer 2. - - ---- - -## Protocol - -Celo’s consensus protocol is based on an implementation called Istanbul, or IBFT. IBFT was developed by AMIS and [proposed](https://github.com/ethereum/EIPs/issues/650) as an extension to [go-ethereum](https://github.com/ethereum/go-ethereum) but never merged. Variants of IBFT exist in both the [Quorum](https://github.com/jpmorganchase/quorum) and [Pantheon](https://github.com/PegaSysEng/pantheon) clients. We’ve modified Istanbul to bring it up to date with the latest [go-ethereum](https://github.com/ethereum/go-ethereum) releases and we’re fixing [correctness and liveness issues](https://arxiv.org/abs/1901.07160) and improving its scalability and security. - -## Finality - -Blocks in IBFT protocol are final, which means that there are no forks and any valid block must be somewhere in the main chain. The only way to revert a block would be to utilise social coordination to get all participants to manually revert the block. - -## Validators - -Celo’s consensus protocol is performed by nodes that are selected as validators. There is a maximum cap on the number of active validators that can be changed by governance proposal, which is currently set at 110 validators. The active validator set is determined via the proof-of-stake process and is updated at the end of each epoch, a fixed period of approximately one day. \ No newline at end of file diff --git a/legacy/protocol/consensus/locating-nodes.mdx b/legacy/protocol/consensus/locating-nodes.mdx deleted file mode 100644 index bc7c4b0e6..000000000 --- a/legacy/protocol/consensus/locating-nodes.mdx +++ /dev/null @@ -1,36 +0,0 @@ ---- -title: Locating Nodes -og:description: How Celo nodes join the network, establish a connection, and communiate their IP address. ---- - -How Celo nodes join the network, establish a connection, and communiate their IP address. - - -This page describes the historical Celo Layer 1 blockchain. It is useful for understanding Celo’s history, but does not reflect the current state of the network. As of block height 31,056,500 (March 26, 2025, 3:00 AM UTC), Celo has transitioned to an Ethereum Layer 2. - - ---- - -## V4 Discovery Protocol - -All Celo nodes \(including our validators\) are using a variant of Ethereum's V4 discovery protocol to find other nodes within the network. Details of Ethereum's protocol can be found [here](https://github.com/ethereum/devp2p/blob/master/discv4.md). - -## Joining the Network - -When a node attempts to join the network, it will execute Celo's discovery protocol. - -It will first send a request to the bootnodes to retrieve a list of other nodes of the network. The bootnodes will then reply with that list, and then the joining node will then send additional requests to nodes in that list to find additional nodes in the network. The main difference in Celo's discovery protocol compared to Ethereum's is that it will require that the joining node's networkID be the same as the bootnodes' \(and the same as all other network's nodes\). - -Also, all of the messages in Celo's discovery protocol must be hashed with a special salt to be accepted by other nodes. The reason why these changes were made is so that each node within a network will only store information of other nodes that have the same networkID (to distinguish nodes from other networks) and the same special salt \(to distinguish nodes from other blockchains, such as Ethereum\). - -## Establishing a Connection - -Once a joining node finds other nodes, it will establish direct TCP connections to a subset of them. This will allow that node to sync it's blockchain and transactions. Validators will additionally attempt to establish TCP connections to the rest of the validators, so that it can send consensus messages directly to them, instead of via gossip. The reason that the validators do this is to minimize the latency of messages that are sent and received among the validators, and to ultimately help minimize block time. - -## Communicating IP Address - -The way that validators communicate their IP address to other validators is by periodically gossiping a subprotocol message that we call an _IstanbulAnnounce_ message. - -That message will contain `n` copies (where `n` is the total number of validators for the current epoch) of the sending validator's IP address where each copy is encrypted with the other validators' public key. Once a validator receives a gossiped _IstanbulAnnounce_ message, it will decrypt the encrypted IP address that was encrypted with its public key, and then establish a TCP connection to it. All consensus related messages will then sent via those direct TCP connections. - -When an epoch ends, a validator will establish new connections with any newly elected validator and disconnect from any removed validators. If the validator itself is removed from the new epoch's validator set, then it will disconnect with all the validators. \ No newline at end of file diff --git a/legacy/protocol/consensus/validator-set-differences.mdx b/legacy/protocol/consensus/validator-set-differences.mdx deleted file mode 100644 index de4a4cbd7..000000000 --- a/legacy/protocol/consensus/validator-set-differences.mdx +++ /dev/null @@ -1,16 +0,0 @@ ---- -title: Validator Set Differences -og:description: How validator sets are elected and managed with the Celo protocol. ---- - -How validator sets are elected and managed with the Celo protocol. - - -This page describes the historical Celo Layer 1 blockchain. It is useful for understanding Celo’s history, but does not reflect the current state of the network. As of block height 31,056,500 (March 26, 2025, 3:00 AM UTC), Celo has transitioned to an Ethereum Layer 2. - - ---- - -## Computing Set Differences - -The validator set for a given epoch is elected at the end of the last block of the previous epoch. The new validator set is written to the **extradata** field of the header for this block. As an optimization, the validator set is encoded as the difference between the new and previous validator sets. Nodes that join the network are able to compute the validator set for the current epoch by starting with the initial validator set \(encoded in the genesis block\) and iteratively applying these diffs. \ No newline at end of file diff --git a/legacy/protocol/contracts/add-contract.mdx b/legacy/protocol/contracts/add-contract.mdx deleted file mode 100644 index 2029ac236..000000000 --- a/legacy/protocol/contracts/add-contract.mdx +++ /dev/null @@ -1,28 +0,0 @@ ---- -title: Add a contract in celo-monorepo -og:description: How to set up Unit/Migration tests on Celo -sidebarTitle: "Add a Contract" ---- - - -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](/build#celo-l2-mainnet). - - -## Adding a contract in celo-monorepo - -Set up a unit/migration test suit for the contract you just created in celo-monorepo and a short guide to running it successfully on celo test net. We’ll be using `Accounts.sol` as an example. - -## After initial contract creation - -After the contract is created and it’s ready to be tested, run `yarn build` to trigger typechain which is essentially a TS wrapper for the contract. Keep in mind that everytime you change your contract you have to run `yarn build` once again. - -## Unit tests - -The test directory is organized the same way as the contracts directory so feel free to navigate to the parent folder of your currently created contract and create a corresponding(.ts) file for it. For example: `celo-monorepo/packages/protocol/contracts/common/Accounts.sol → celo-monorepo/packages/protocol/test/common/accounts.ts`. - - -Some build issues can be resolved by simply deleting the `build` and the `typechain` folder. Don’t forget to run `yarn build` once again. - diff --git a/legacy/protocol/identity/encrypted-cloud-backup.mdx b/legacy/protocol/identity/encrypted-cloud-backup.mdx deleted file mode 100644 index 1a8a5a990..000000000 --- a/legacy/protocol/identity/encrypted-cloud-backup.mdx +++ /dev/null @@ -1,114 +0,0 @@ ---- -title: PEAR 🍐 -og:description: PEAR, the pin/password encrypted account recovery protocol for backing up account keys ---- - -Pin/Password Encrypted Account Recovery. - ---- - -Secure and reliable account key backups are critical to the experience of non-custodial wallets, and Celo more generally. -Day-to-day, users store their account keys on their mobile device, but if they lose their phone, they need a way to recover access to their account. -Described in this document is a protocol for encrypted backups of a user's account keys in their cloud storage account. - -## Summary - -Using built-in support for iOS and Android, mobile apps can save data backups to Apple iCloud and Google Drive respectively. -When a user installs the wallet onto a new device, possibly after losing their old device, or reinstalls the app on the same device, it can check the user's Drive or iCloud account for account backup data. -If available, this data can be downloaded and used to initialize the application with the recovered account information. - -Access to the user's cloud storage requires logging in to their Google or Apple account. -This provides a measure of security as only the owner of the cloud storage account can see the data, but is not enough to confidently store the wallet's account key. -In order to provide additional security, the account key backup should be encrypted with a secret, namely a PIN or password, that the user has memorized or stored securely. -This way, the users account key backup is only accessible to someone who can access their cloud storage account _and_ knows their secret. - -Because user-chosen secrets, especially PINs, are susceptible to guessing, this secret must be [hardened]() before it can be used as an encryption key. -Using [ODIS](/legacy/protocol/identity/odis) for [key hardening](/legacy/protocol/identity/odis-use-case-key-hardening), this scheme derives an encryption key for the account key backup that is resistant to guessing attacks. - -With these core components, we can construct an account recovery system that allows users who remember their password or PIN, and maintain access to a cloud storage account, to quickly and reliably recover their account while providing solid security guarantees. - -Valora is currently working to implement encrypted account recovery, using the user's access PIN for encryption. - -### Similar protocols - -- [iCloud Keychain](https://support.apple.com/guide/security/secure-icloud-keychain-recovery-secdeb202947/web) uses 6-digit PIN, hardened by an HSM app, and encrypt iCloud Keychain backups. -- [Signal SVR](https://support.apple.com/guide/security/secure-icloud-keychain-recovery-secdeb202947/web) uses a 4-digit PIN or alphanumeric password, hardened by an Intel SGX app, to encrypt contacts and metadata. -- [Coinbase Wallet](https://blog.coinbase.com/backup-your-private-keys-on-google-drive-and-icloud-with-coinbase-wallet-3c3f3fdc86dc) uses a password encrypted cloud backup to store user account keys. It is unclear if any hardening is used. -- [WhatsApp E2E Encrypted Backups](https://engineering.fb.com/2021/09/10/security/whatsapp-e2ee-backups/) uses [OPAQUE](https://datatracker.ietf.org/doc/draft-irtf-cfrg-opaque/) to harden a password encrypted backup -- [MixIn Network TIP](https://github.com/MixinNetwork/tip) uses 6-digit PINs, hardened by a set of signers, to derive account keys - -## User experience - -Here we describe the user experience of the protocol as designed. -Wallets may alter this flow to suite the needs of their users. - -### Onboarding - -During onboarding on a supported device, after the PIN or password is set and the account key is created, the user should be informed about the account backup and given a chance opt-out of backup system for their account. -If they opt out, the rest of the setup should be skipped as they will not be using this account recovery system. - -On Android, when the user opts-in, they should be prompted to select a Google account that they would like to use to store the backup. -On iOS, the user need not be prompted as there is a single Apple account on the device and the permissions architecture allows access to application-specific iCloud data without prompting the user. - -In the background, the chosen PIN or password and a locally generated salt value should be used to query ODIS. -The resulting hardened key should be used to encrypt the BIP-39 account key mnemonic. -The encrypted mnemonic and metadata, including the salt, should be stored in the user's cloud storage. - -### Recovery - -During recovery, the application should determine if a backup is available in their cloud account. -On iOS, this can be done automatically. -On Android, the user may choose to restore from a cloud backup, at which point they should be prompted to choose their Google account. - -If a backup is available the user may select to restore from a cloud backup, at which point they should be asked for their PIN or password. -Given the PIN or password, the application should combine it with the salt value and query ODIS to retrieve the hardened key for decrypting the account key backup. -If successful, the user will be sent to the home screen. -If unsuccessful, the user will be given the option to try again or enter their mnemonic phrase instead. - -Users should, by requirement of security, be given a limited number of attempts to enter their PIN or password. -Attempts should be rate limited with a certain number of attempts available immediately (e.g. 3-5 attempts within the first 24 hours), and a limited number of additional attempts available after one or more waiting periods (e.g. up to 10-15 attempts over 3 days). -Once all attempts are exhausted, the backup will become unrecoverable and the user will only be able to recover their account if they have their mnemonic phrase written down. - -## Implementation - -Client support for the encrypted backup protocol described here is implemented in the [`@social-connect/encrypted-backup` package](https://github.com/celo-org/social-connect/tree/main/packages/encrypted-backup). - -Creating a backup file consists of a number of steps to derive the encryption key, and assemble the backup file. - -1. Generate a random nonce and hash it with the password or PIN input to get the initial key. -2. Generate a random fuse key and hash it with the initial key to get an updated key. - Encrypt this fuse key to the public key of the circuit breaker service and discard the plaintext fuse key. -3. Send the key as a blinded message to the ODIS to be hashed under a [password hardening domain](/legacy/protocol/identity/odis-use-case-key-hardening). - Use an authentication key derived from the backup nonce such that only a user with access to the backup can make queries to ODIS. - Hash the response from ODIS together with the key to generate the hardened key. -4. Encrypt the account mnemonic phrase with the hardened encryption key, and assemble it together with the nonce, ODIS domain information, encrypted fuse key, and environment metadata for ODIS and the circuit breaker. - -If the implementing service does not wish to include a circuit breaker, which is described in more detail below, step two can be skipped. - -The backup file created in this protocol can then be stored by the wallet that implements this protocol in some authenticated storage, such as iCloud or Google Drive. - -In order to open the backup and recover the users account mnemonic the encrypted backup file is first retrieved from authenticated storage, then the decryption key is derived in the following steps similar to the steps above. - -1. Hash the password or PIN input with the nonce in the backup to get the initial key. -2. Query the circuit breaker to unwrap the encrypted fuse key and hash it with the initial key to get an updated key. -3. Send the key as a blinded message to the ODIS to be hashed under the included [password hardening domain](/legacy/protocol/identity/odis-use-case-key-hardening). - Use an authentication key derived from the backup nonce. - Hash the response from ODIS together with the key to generate the hardened key. -4. Decrypt the backup data with the hardened decryption key and return it as the account mnemonic. - -### Circuit breaker - -In order to handle the event of an ODIS service compromise, this is protocol includes a recommended circuit breaker service. -A circuit breaker service is essentially an online decryption service with a well-known public key that can be taken offline if needed to prevent access to the decryption key. -By using a fuse key which is decrypted to the circuit breaker service, and therefore can only be accessed if the service is online, as a step to derive the encryption key for the backup, the circuit breaker service operator is able to disable decryption of backup files in case of an emergency to protect user funds. -In particular, if the ODIS key hardening service is discovered to be compromised, the circuit breaker operator will take their service offline, preventing backups using the circuit breaker from being opened. -This ensures that an attacker who has compromised ODIS cannot leverage their attack to forcibly open backups created with this function. - -### PIN Blocklist - -When using a 4 or 6 digit PIN code to encrypt a backup, there are a number of PINs that are far more common than common than others. -Sequences (123456), patterns (124578) and important dates (110989) are chosen most frequently. -Within 30 guesses, an attacker has a 5-9% chance of guessing a users first-choice PIN code, as suggested by [research into PIN security](https://this-pin-can-be-easily-guessed.github.io/). -In order to address this, it is highly recommended to block the most easily guessed PINs. -One way to do this is to block PINs that are most popular. -A suggested implementation, which is [implemented by the Valora wallet](https://github.com/valora-inc/wallet/blob/3940661c40d08e4c5db952bd0abeaabb0030fc7a/packages/mobile/src/pincode/authentication.ts#L56-L108), is to create a blocklist from the top 25k most frequently seen PINs in the HIBP Passwords dataset. diff --git a/legacy/protocol/identity/index.mdx b/legacy/protocol/identity/index.mdx deleted file mode 100644 index 9a3b82e6d..000000000 --- a/legacy/protocol/identity/index.mdx +++ /dev/null @@ -1,54 +0,0 @@ ---- -title: "Identity Overview" -sidebarTitle: "Overview" -og:description: How Celo maps wallet addresses to phone numbers to make financial tools more accessible to mobile phone users. ---- - -How Celo maps wallet addresses to phone numbers to make financial tools more accessible to mobile phone users. - ---- - - -Celo's Identity protocol has moved to [docs.self.xyz](https://docs.self.xyz/). - - -## Introduction to Identity on Celo - -Celo’s unique purpose is to make financial tools accessible to anyone with a mobile phone. One barrier for the usage of many other platforms is their required usage of 30+ hexadecimal-character-long strings as addresses. It’s like bank account numbers, but worse. Hard to remember, easy to mess up. They are so hard to use that the predominant way of exchanging addresses is usually via copy-paste over an existing messaging channel or via QR-codes in person. Both approaches are practically interactive protocols and thus do not cover many use cases in which people would like to transact. Celo offers an optional lightweight identity layer that starts with a decentralized mapping of phone numbers to wallet addresses, allowing users to transact with one another via the most common identity scheme everyone is familiar with: their address book. - - -![](https://storage.googleapis.com/celo-website/docs/attestations-flow.jpg) - - -### Adding their phone number to the mapping - -To allow Bob to find an address mapped to her phone number, Alice can use the decentralized attestations protocol to link an account address to her phone number. Alice starts by making a request to the `Attestations` contract; transferring a fee along with her request. After a brief waiting time of `4` blocks (20 seconds), the `Attestations` contract will use the `Random` contract to produce a random selection of validators, from the current elected set in the `Validators` contract, to issue the attestation challenges. - -As part of the expectation of validators, they run the attestation service whose endpoint they register in their [Metadata](/legacy/protocol/identity/metadata). After attestation issuers have been selected for their requests, Alice determine the validators' attestation service URLs from her [Metadata](/legacy/protocol/identity/metadata) and requests an attestation message to her phone number by sending a direct HTTPS request. In turn, the attestation service produces a signed secret message attesting to the ownership of the given phone number by the requesting account. The validator sends the message to Alice's phone number via SMS. Read more under [attestation service](#attestation-service). - -When Alice receives the text message, she can take that signed message to the `Attestations` contract, which can verify that the attestation came from the validator indeed. Upon a successful attestation, the validator can redeem for the attestation request fee to pay them for the cost of sending the SMS. In the end, we have recorded an attestation by the validator to a mapping of Alice’s phone number to her account address. - -### Using the mapping for payment - -Once Alice has completed attestations for their phone number/address, Bob, who has her phone number in his contact book, can see that Alice has an attested account address with her phone number. He can use that address to send funds to Alice, without her having to specifically communicate her address to Bob. - -The `Attestations` contract records all attestations of a phone number to any number of addresses. That for example could happen when a user loses their private key and wants to map a new wallet address. However, it could also happen through the collusion of a validator with Alice. Therefore, it is important that clients of the identity protocol highlight possible conflicting attestations. - -Some risk exists for attestations to be added without the permission of the "legitimate" owner of the phone number. One such risk is that the phone service provider or [SIM swap](https://wikipedia.org/wiki/SIM_swap_scam) attacker could take control of the phone number and complete a number of attestations. Another risk is that a sufficient number of Attestation Service providers may collude to complete fake attestations. Notably, completing malicious attestations does not lead to a loss of funds, as the private key is still the necessary and sufficient condition for transactions of an account. However, without proper care, future senders may be tricked into sending funds to the newly associated address. In general the number and age of attestations for an address should be taken into account to identify the valid owner of a phone number. - -There are additional measures we can take to further secure the integrity of the mapping’s usage. In the future we plan to provide reference implementations in the wallet for some of these. For example, we plan to detect remapping of wallet addresses. Many users are already accustomed to sending small amounts first and verifying the receipt of those funds before attempting to transfer larger amounts. - -### Preventing harvesting of phone numbers - -To protect user privacy by preventing mass harvesting of phone numbers, the Celo platform includes a service that obfuscates the information saved on the blockchain. The service is enabled by default for all Celo Wallet users. Details of its functionality and architecture are explained in [Phone Number Privacy](/legacy/protocol/identity/odis-use-case-phone-number-privacy) - -### Attestation service - -The attestation service is a simple Node.js service that validators run to send signed messages for attestations. It can be configured with SMS providers, as different providers have different characteristics like reliability, trustworthiness and performance in different regions. The attestation service currently supports [Twilio](https://www.twilio.com) and [Nexmo](https://nexmo.com). Celo should widen the number of supported providers over time. - - - {/* We have been experimenting with a SMS provider that we would like community feedback on. Instead of sending the SMS via conventional providers like Twilio, users of a `Rewards Mobile App` could register themselves with a `Verification Pool` and be made responsible for sending those text messages. It would allow users with cheap or leftover SMS capacity from their cell phone plan to effectively acquire a share of the attestation request fees. It would represent a unique on-ramp for users who do not have access to classic on-ramps like exchanges. Validators could configure their attestation service to use such a SMS provider which could in theory provide better inclusion and performance. */} - -### Future improvements to privacy - -Celo is committed to meet the privacy needs of its users. More details about areas for future research can be found in [Privacy Research](/legacy/protocol/identity/privacy-research) \ No newline at end of file diff --git a/legacy/protocol/identity/metadata.mdx b/legacy/protocol/identity/metadata.mdx deleted file mode 100644 index 452a55b4d..000000000 --- a/legacy/protocol/identity/metadata.mdx +++ /dev/null @@ -1,70 +0,0 @@ ---- -title: "Metadata and Claims" -sidebarTitle: "Celo Metadata and Claims" -og:description: How the Celo protocol's metadata and claims feature makes it possible to connect on-chain with off-chain identities. ---- - -How the Celo protocol's **metadata and claims** feature makes it possible to connect on-chain with off-chain identities. - ---- - -## Use Cases - -- Tools want to present public metadata supplied by a validator or validator group as part of a list of candidate groups, or a list of current elected validators. -- Governance Explorer UIs may want to present public metadata about the creators of governance proposals -- The Celo Foundation receives notice of a security vulnerability and wants to contact elected validators to facilitate them to make a decision on applying a patch. -- A DApp makes a request to the Celo Wallet for account information or to sign a transaction. The Celo Wallet should provide information about the DApp to allow the user to make a decision whether to sign the transaction or not. - -Furthermore, these tools may want to include user chosen information such as names or profile pictures that would be expensive to store on-chain. For this purpose, the Celo protocol supports **metadata** that allows accounts to make both verifiable as well as non-verifiable claims. The design is described in [CIP3](https://github.com/celo-org/CIPs/pull/4). - -On the `Accounts` smart contract, any account can register a URL under which their metadata file is available. The metadata file contains an unordered list of claims, signed by the account. - -## Types of Claim - -ContractKit currently supports the following types of claim: - -- **Name Claim** - An account can claim a human-readable name. This claim is not verifiable. - -- **Attestation Service URL Claim** - For the [lightweight identity layer](/legacy/protocol/identity), validators can make a claim under which their Attestation Service is reachable to provide attestations. This claim is not verifiable. - -- **Keybase User Claim** - Accounts can make claims on [Keybase](https://keybase.io) usernames. This claim is verifiable by signing a message with the account and hosting it on the publicly accessible path of the Keybase file system. - -- **Domain Claim** - Accounts can make claims on domain names. This claim is verifiable by signing a message with the account and embedding it in a [TXT record](https://wikipedia.org/wiki/TXT_record). - -In the future ContractKit may support other types of claim, including: - -- **X User Claim** - Accounts can make claims on [X](https://x.com/) usernames. This claim is verifiable by signing a message with the account and posting it as a tweet. Any client can verify the claim with a reference to the tweet in the claim. - -## Handling Metadata - -You can interact with metadata files easily through the [CLI](/cli/account), or in your own scripts, tools or DApps via [ContractKit](/developer/contractkit/). Most commands require a node being available under `http://localhost:8545` to make view calls, and to modify metadata files, you'll need the relevant account to be unlocked to sign the files. - -You can create an empty metadata file with: - -```bash -celocli account:create-metadata ./metadata.json --from $ACCOUNT_ADDRESS -``` - -You can add claims with various commands: - -```bash -celocli account:claim-attestation-service-url ./metadata.json --from $ACCOUNT_ADDRESS --url $ATTESTATION_SERVICE_URL -``` - -You can display the claims in your file and their status with: - -```bash -celocli account:show-metadata ./metadata.json -``` - -Once you are satisfied with your claims, you can upload your file to your own web site or a site that will host the file (for example, [https://gist.github.com](https://gist.github.com) and then register it with the `Accounts` smart contract by running: - -```bash -celocli account:register-metadata --url $METADATA_URL --from $ACCOUNT_ADDRESS -``` - -Then, anyone can lookup your claims and verify them by running: - -```bash -celocli account:get-metadata $ACCOUNT_ADDRESS -``` \ No newline at end of file diff --git a/legacy/protocol/identity/odis-domain-sequential-delay-domain.mdx b/legacy/protocol/identity/odis-domain-sequential-delay-domain.mdx deleted file mode 100644 index a02e81304..000000000 --- a/legacy/protocol/identity/odis-domain-sequential-delay-domain.mdx +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: Sequential Delay Domain -og:description: The Sequential Delay Domain, an ODIS Domain enforcing time-delayed rate limits on recovery attempts ---- - - - -The Sequential Delay Domains is an [ODIS Domain](/legacy/protocol/identity/odis-domain) supporting signature-authenticated rate limits defined as a series of time-delayed stages. -The motivating use case is allowing wallets to define how often users can attempt to recover their account via the scheme outlined in [Pin/Password Encrypted Account Recovery](/legacy/protocol/identity/encrypted-cloud-backup), but can be used in any other application that need an authenticated rate limit represented as a series of time delayed stages. - -## Specification - -A full specification of the Sequential Delay Domain is available in an extension to CIP-40. - -- [Sequential Delay Domain Specification](https://github.com/celo-org/celo-proposals/blob/master/CIPs/CIP-0040/sequentialDelayDomain.md) diff --git a/legacy/protocol/identity/odis-domain.mdx b/legacy/protocol/identity/odis-domain.mdx deleted file mode 100644 index 732d67e4d..000000000 --- a/legacy/protocol/identity/odis-domain.mdx +++ /dev/null @@ -1,51 +0,0 @@ ---- -title: ODIS Domains -sidebarTitle: Overview -og:description: ODIS Domains, the structured messages that define rate limits and access rules for a use case ---- - - - - -Domain API features described here are not deployed to Mainnet ODIS as of April 1, 2022. - - -In order to support use cases such as password hardening, and future applications, ODIS implements Domains. -A Domain instance is structured message sent to ODIS along with the secret blinded message. -Unlike the blinded message, the Domain instance is visible to the ODIS service and allows the client to specify context information about their request. -This context information is used to decide what rate limit and/or authentication should be applied to the request, and is combined into the result to ensure output is unique to the context. -The Domain instance and blinded message are both passed to the ODIS partially oblivious pseudorandom function (POPRF), which is a new construction extending upon the [OPRF function](/legacy/protocol/identity/odis) used in the [phone number privacy service](/legacy/protocol/identity/odis-use-case-phone-number-privacy). - -As an example, a Domain for hashing an account password might specify an application username of "vitalik.eth" (context) and a cap of 10 password attempts (rate-limiting parameter). -These would be combined with the user's password (blinded input) in the POPRF, which acts as a one-way function, to form the final output. -As a result the rate limiting parameters, in this case allowing a total of 10 queries, can be set to arbitrary values but are effectively binding once chosen. -This allows the parameters to be tuned to the needs of the individual user or application and prevents potential overlap of different use cases. - -Queries with distinct domain specifiers will receive uncorrelated output. -For example, output from ODIS with the phone number domain and message `18002738255` will be distinct from and unrelated to the output when requesting with a password domain and message `18002738255`. - -In order to make this scheme flexible, allowing for user-defined tuning of rate-limits and the introduction of new rate limiting and authorization rules in the future, domains are defined as serializeable structs. -New domain types, with associated rate-limiting rules, may be added in the future to meet the needs of new applications. - -## Specification - -A full specification of Domains and the related ODIS APIs is available in CIP-40. - -- [CIP-40](https://github.com/celo-org/celo-proposals/blob/master/CIPs/cip-0040.md) - -## Implemented Domains - -- [Sequential Delay Domain](/legacy/protocol/identity/odis-domain-sequential-delay-domain) - -## Creating a Domain Type - -The Domains interface is designed to be flexible to facilitate new applications for the ODIS POPRF function. -If you have an application that would benefit from a new Domain type and rate limiting ruleset, the first step is to open an extension to the CIP-40 standard. - -New Domain types are standardized through a lighter version of the [general CIP process](https://github.com/celo-org/celo-proposals/blob/master/CIPs/cip-0000.md). -Open a PR against the celo-org/celo-proposals repository to add a specification for your new domain to the [CIP-40 extensions folder](https://github.com/celo-org/celo-proposals/tree/master/CIPs/CIP-0040). -As an example for what you should include, take a look at the [specification](https://github.com/celo-org/celo-proposals/blob/master/CIPs/CIP-0040/sequentialDelayDomain.md) for the `SequentialDelayDomain`. -When it is ready for review, contact a [CIP editor](https://github.com/celo-org/celo-proposals/blob/master/CIPs/cip-0000.md#cip-editors) to help get reviews from the ODIS core development team. - -Implementing a new Domain type, which includes new rate limiting to be enforced by the ODIS operators, requires an upgrade to the ODIS server implementation. -Once the new domain type is standardized, this implementation can be written and deployed to the staging and production ODIS service operators. diff --git a/legacy/protocol/identity/odis-use-case-key-hardening.mdx b/legacy/protocol/identity/odis-use-case-key-hardening.mdx deleted file mode 100644 index aa528cd1c..000000000 --- a/legacy/protocol/identity/odis-use-case-key-hardening.mdx +++ /dev/null @@ -1,43 +0,0 @@ ---- -title: Key Hardening -og:description: How ODIS hardened passwords against offline cracking when deriving encryption keys ---- - -Passwords are useful primitive in a number of applications, allowing a user to authenticate themselves by knowing the secret information. -Unfortunately, effective offline password cracking techniques limit the use of passwords to derive encryption or authentication keys. -An attacker with access to a signature or encrypted file that used a password, or the hash of a password, as the key can make repeated guesses until they find the password. -Given advanced tools such as [`hashcat`](https://hashcat.net/hashcat/) and extensive experience, hackers are very good at guessing passwords. - -Rate-limited or expensive hashing can be used to make it much more difficult to crack a password. -Computationally expensive password hashing functions, such as PBKDF and scrypt, are commonly used for this purpose, but provide [limited protection](https://arxiv.org/abs/2006.05023) and are expensive to run on end-user devices. -ODIS implements hashing (i.e. PRF evaluation) with a rate limit controlled by the committee of ODIS operators, and can be used to harden a password into a stronger cryptographic key. -As long as this committee remains collectively honest and secure, an attacker cannot make more guesses at a users password than ODIS allows, making it extremely unlikely a good password will be broken. - -Using ODIS for key hardening allows passwords to be used in a number of applications, including to create [encrypted account backups](/legacy/protocol/identity/encrypted-cloud-backup) and as a factor in [smart contract account recovery](/legacy/protocol/identity/smart-contract-accounts). - -## Rate limiting - -Choosing an appropriately restrictive rate limit is crucial. -Using a rate limit that is too restrictive may cause users to become frustrated as their access is denied if they take too many tries to recall their password, and a rate limit that is too loose can allow an attacker a much better chance at guessing the users password. -The appropriate rate limit is related to how much entropy the user secret has. - -- A strong user password can tolerate a loose rate limit, allowing millions of attempts without significant chance of attacker success. -- An average user password can tolerate a moderate rate limit, allowing hundreds of attempts. -- A 4 or 6 digit PIN can tolerate tens of attempts before the attacker has a significant chance of success. - -Because the right rate limit is context specific, [Domains](/legacy/protocol/identity/odis-domain) can be configured to the needs of the user. -The [Sequential Delay Domain](/legacy/protocol/identity/odis-domain-sequential-delay-domain) is designed for the use case of PIN and password hashing, and can be used to allow for a fixed number of attempts over a configurable time period (e.g. 15 attempts over 3 days). -The Sequential Delay Domain additionally supports signature-based authentication to prevent quota from being consumed by any except the intended user. - -## Salting - -Even with the use of ODIS to prevent brute-force guessing of a password, it remains important to include a user-specific value in the hashing request as a salt to prevent [rainbow table attacks](https://wikipedia.org/wiki/Rainbow_table). -A salt can be included in the Domain parameter of the request to ODIS to ensure a rate limit is enforced specific to the user's context. -Using a random salt value is recommended, however a client identifier such as a username or [phone number hash](/legacy/protocol/identity/odis-use-case-phone-number-privacy) can also be used. - -## Password filtering - -In addition to using ODIS to harden passwords chosen by users, it is recommended that the application help the user choose a good password during onboarding. -Password filtering, blocking the user from setting a password which may be weak, can greatly improve the quality of a user's password and prevent it being broken by guessing the most common passwords (e.g. "password"). -[NIST 800-63](https://pages.nist.gov/800-63-3/sp800-63-3.html) recommends that passwords should be checked against a list of known compromised passwords, such as [HIBP Passwords](https://haveibeenpwned.com/Passwords). -Additional research has found other [practical techniques for increasing the strength of passwords chosen by users](https://www.andrew.cmu.edu/user/nicolasc/publications/Tan-CCS20.pdf). diff --git a/legacy/protocol/identity/odis-use-case-phone-number-privacy.mdx b/legacy/protocol/identity/odis-use-case-phone-number-privacy.mdx deleted file mode 100644 index cc9902214..000000000 --- a/legacy/protocol/identity/odis-use-case-phone-number-privacy.mdx +++ /dev/null @@ -1,41 +0,0 @@ ---- -title: Phone Number Privacy -og:description: How ODIS preserved the privacy of phone numbers mapped to Celo addresses ---- - - - -Celo's [identity protocol](/legacy/protocol/identity) allows users to associate their phone number with one or more addresses on the Celo blockchain. -This allows users to find each other on the Celo network using phone number instead of cumbersome hexadecimal addresses. -The Oblivious Decentralized Identifier Service (ODIS) was created to help preserve the privacy of phone numbers and addresses. - -- [ODIS](/legacy/protocol/identity/odis) - -## Understanding the problem - -When a user sends a payment to someone in their phone's address book, the mobile client must look up the identifier for that phone number on-chain to find the corresponding Celo blockchain address. -This address is needed in order to create a payment transaction, and the user may only know the phone number of the person they want to pay. -If cleartext phone numbers were used as identifiers directly on the Celo network, then anyone would be able to associate all phone numbers with blockchain accounts and balances (e.g. After searching for addresses with a high balance, they could look up the associated phone number to [phish](https://wikipedia.org/wiki/Phishing) the account owner). -If instead, the identifier was the hash of the recipient's phone number, attackers would still be able to associate phone numbers with accounts and balances via a [rainbow table attack](https://wikipedia.org/wiki/Rainbow_table). - -## The solution - -The basis of the solution is to derive a user's identifier from both their phone number and a secret pepper that is provided by the Oblivious Decentralized Identifier Service (ODIS). -In order to associate a phone number with a Celo blockchain address, the mobile wallet first queries ODIS for the pepper. -It then uses the pepper to compute the unique identifier that's used on-chain. - -Peppers produced by ODIS are cryptographically strong, and so cannot be guessed in a brute force or rainbow table attack. -ODIS imposes a rate limit controlling how many peppers any individual can request, and so prevents an attacker from scanning a large number of phone numbers in an attempt to compromise user privacy. - -### Pepper request rate limiting - -ODIS imposes a rate limit on requests for peppers in order to limit the feasibility of rainbow table attacks. -When ODIS receives a request for a pepper, it authenticates the request and ensures the requester has not exceeded their quota. -Since blockchain accounts and phone numbers are not naturally Sybil-resistant (i.e. individuals can have many accounts or phone numbers), ODIS bases request quota on the following factors: - -- Requester transaction history -- Requester phone number attestation count and success rate -- Requester account balance - -The requirements for these factors are configured to make it prohibitively expensive to scrape large quantities of phone numbers while still allowing typical user flows to remain unaffected. -In particular, it should be possible for a user to look up their contacts in order to send them payments. diff --git a/legacy/protocol/identity/odis.mdx b/legacy/protocol/identity/odis.mdx deleted file mode 100644 index 9732e5f62..000000000 --- a/legacy/protocol/identity/odis.mdx +++ /dev/null @@ -1,116 +0,0 @@ ---- -title: Oblivious Decentralized Identifier Service (ODIS) -sidebarTitle: Overview ---- - -The Oblivious Decentralized Identifier Service (ODIS) allows for privacy preserving [phone number mappings](/legacy/protocol/identity/odis-use-case-phone-number-privacy), [password hardening](/legacy/protocol/identity/odis-use-case-key-hardening), and other use cases by implementing a rate limited oblivious pseudorandom function (OPRF). -Essentially, it is a service that allows users to compute a limited number of hashes (i.e. PRF evaluations), without letting the service see the data being hashed. -Many useful applications are built on top of this primitive, such as privacy protected phone number mappings, password hardening, and [captchas for bot detection](https://privacypass.github.io/). - -## Distributed key generation - -For the sake of user privacy and security, no single party should have the ability to unilaterally compute the OPRF function. -To ensure this, ODIS was designed to be decentralized across a set of reputable participants. -Before ODIS was deployed, a set of operators participated in a Distributed Key Generation (DKG) ceremony to generate shared secret, with its pieces split between the operators. -Details of the DKG setup can be found [in the Celo Threshold BLS repository](https://github.com/celo-org/celo-threshold-bls-rs). - -Each ODIS node holds a share of the key which can be used to calculate a piece of the OPRF evaluation that will be sent to the user. -When enough of these pieces are combined, their combination can be used to derive the unique OPRF evaluation (i.e. hash). -The number of key holders ($$m$$) and threshold of signatures required ($$k$$) to construct a full evaluation are both configurable at the time of the DKG ceremony. - -### Production setup - -As of October 2021, ODIS operates with 7 signers and a threshold of 5 (i.e. $$m=7, k=5$$). -As a result, 5 of the 7 parties must cooperate in order to produce an output from the (P)OPRF function, and as long as at least 3 are honest and secure, no unauthorized requests will be served. - -{/* TODO(victor): Once the new set is in production, information about the 7 operators should be included here */} - -### Security properties - -The goal the distributed key generation is to make it harder for a hacker, or a corrupt ODIS operator, to compromise the security of ODIS. -In particular, if an attacker has control over any less then the threshold $$k$$ of keys, they cannot make an unauthorized computation (e.g. querying the pepper for a phone number without quota) of the OPRF function. -Additionally, as long as $$k$$ operators remain honest and have access to their keys, honest users will continue to be able to use the service even if $$m-k$$ corrupt operators are refusing their requests. - -For example, consider the phone number privacy protocol when there are 7 ODIS operators and the required threshold is 5. An attacker may compute the pepper for all phone numbers if 5 operators are compromised or corrupt. If 3 are corrupt or taken offline (e.g. by DDoS attack) then an attacker may prevent the rest of the operators from generating the pepper for users. - -In the case that a single key is compromised, user data will remain private and the service operational; however, it's important that we can detect and perform a key rotation before the number of keys compromised exceeds $$k$$ or $$m - k + 1$$ (whichever is lower). - -## Rotating keys - -If a key held by one of the operators is leaked, or if the operator becomes corrupt, a key rotation can allow the group to generate a new set of keys. Once the new keys are in place, operators can destroy their old keys, preventing any use from the compromised key. -Key rotation can also allow new ODIS operators to be added, by creating new keys for all the existing operators as well as the newly added operator. - -To rotate keys, a new DKG ceremony must be performed with at least $$k$$ of the $$m$$ original keys. -These newly generated keys will not be compatible with the old keys; however if $$k$$ of the old keys are used, an attacker may still reach the necessary threshold. -Therefore, it's extremely important that all of the old keys are destroyed after a successful key rotation. -This DKG ceremony also provides the opportunity to change the values for $$k$$ and $$m$$, adding or removing operators, or changing the threshold required to compute the OPRF. -Note that this process for key rotation does not change the public key the client uses to [verify](#verification) the results. - -## Blinding - -When a client queries ODIS to get an OPRF evaluation, the client first blinds the phone number locally using a secret one-time key. -This blinding process preserves the privacy of underlying message (e.g. a mobile number or password) such that ODIS nodes won't learn any of the user's sensitive information. -In addition to protecting the user's privacy, it reduces the risk of targeted censorship. -ODIS operators compute the OPRF against this hidden input value, and return a result which is also hidden from the operators. -After the application receives the response, it unblinds it to receive the final evaluation result. -Note that this blinding process provides privacy to the user _even_ if all of the ODIS operators were corrupted. -This blinding process is what makes the oblivious pseudo random function (OPRF) "oblivious". - -## Verification - -Query results from ODIS can be verified against the services public key, which is shared with users along with the client library. -By verifying the results, the client can be sure that the service computed the OPRF correctly and that no one could have intercepted and changed the result. - -## Combiner - -To facilitate the communication needed for the $$k$$ of $$m$$ OPRF evaluation, ODIS includes a combiner service which performs this orchestration for the convenience of wallets and other clients building on Celo. -Like the ODIS operators, the combiner only receives the blinded message and therefore it cannot learn anything about the user's sensitive information. -The combiner also verifies the response from each operator to ensure a corrupt operator cannot affect the resulting pepper. -Clients can additionally verify the response they get from the combiner to ensure the combiner could not have tampered with it. - -Anyone can run a combiner, for their own use or for the public. -Currently, cLabs operates one such combiner that may be used by any project building on Celo. - -## Rate limiting - -As part of its core function, ODIS enforces rate limits on user queries. -Rate limits depend on the application context in which ODIS is being used (e.g. the rate limit is much higher for deriving peppers for phone numbers than for hardening a 6-digit PIN) - -### Phone number privacy - -The original API, targeted for phone number privacy, enforces a rate limit based on the actions, balance, and verification status or the user on the Celo blockchain. -In order to measure the quota for a given requester, ODIS must check their on-chain account information. -To prove ownership over their account, the POST request contains an Authorization header with the signed message body. -When ODIS nodes receive the request, it authenticates the user by recovering the message signer from the header and comparing it to the value in the message body. - -### Domains - -In the newer domain separated API, the rate limit can depend on a variety of factors configured to each domain type. -More information about the domains API and the implemented domain types can be found in the respective pages. - -- [Domains](/legacy/protocol/identity/odis-domain) -- [Sequential Delay Domain](/legacy/protocol/identity/odis-domain-sequential-delay-domain) - -A full specification of the Domains API can be found in CIP-40. - -- [CIP-40](https://github.com/celo-org/celo-proposals/blob/master/CIPs/cip-0040.md) - -## Request flow diagram - - -![request flow diagram](https://storage.googleapis.com/celo-website/docs/ODIS-flow-diagram.svg) - - -## Architecture - - -![architecture diagram](https://storage.googleapis.com/celo-website/docs/ODIS-architecture-diagram.svg) - - -The hosted architecture is divided into two components, the combiner and the signers. -Currently the combiner is a cloud function and the signers are independent NodeJS servers run by the operators. -Both services leverage the [Celo Threshold BLS library](https://github.com/celo-org/celo-threshold-bls-rs) which has been compiled to [a Web Assembly module](https://github.com/celo-org/blind-threshold-bls-wasm). - -The combiner and signers maintain some minimal state in a SQL database, mainly related to quota tracking. - -For storage of the BLS signing key, the signers currently support three cloud-based keystores: Azure Key Vault, AWS Secret Manager, and Google Secret Manager. diff --git a/legacy/protocol/identity/privacy-research.mdx b/legacy/protocol/identity/privacy-research.mdx deleted file mode 100644 index c1bc14789..000000000 --- a/legacy/protocol/identity/privacy-research.mdx +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: "Future Privacy Research" -sidebarTitle: "Privacy Research" -og:description: Known privacy limitations of the Celo L1 identity protocol and the research planned to address them ---- - -Celo is committed to meet the privacy needs of its users. This section describes future plans for delivering on this commitment, while also sharing the current limitations of the Celo networks. - -### Privacy mode - -One downside to this identity protocol is that knowledge of a phone number can let anyone quickly determine the balance of the associated wallet, which of course may be unacceptable for many use cases. For these circumstances, the contract allows users to use the `Attestations` contract in privacy mode. In this mode, the user does not map their phone number to their wallet address, but to an account that is not meant to be the recipient of transfers. Through a registered encryption key on the user’s account on the contract, schemes can be derived to allow users to selectively reveal their true wallet addresses to authorized participants. - -{/* ### Transaction and Balance Privacy - -As with most public blockchains \(e.g. Bitcoin, Ethereum\), transactions and smart contracts calls on Celo are public for everyone to see. This means that if a user wants to map the hash of their phone number to their wallet address, people with knowledge of that user's phone number will be able to see their transactions and balances. - -To address this issue, the cLabs team, [Matterlabs](https://matterlabs.dev) and other esteemed zk-SNARK cryptographers and Celo community members are working to create a framework that makes it easy to create gas-efficient tokens that offer Zcash-like privacy, using a shared anonymity pool. Such an implementation could allow wallets to use the default identity mode easily without the risk that someone with your phone number could see your balance and transaction history. */} diff --git a/legacy/protocol/identity/smart-contract-accounts.mdx b/legacy/protocol/identity/smart-contract-accounts.mdx deleted file mode 100644 index 0269e806c..000000000 --- a/legacy/protocol/identity/smart-contract-accounts.mdx +++ /dev/null @@ -1,84 +0,0 @@ ---- -title: Smart Contract Accounts -og:description: Smart contract accounts on Celo L1 and the features they enabled beyond externally owned accounts ---- - -Smart contract accounts are used to enable features beyond what can be accomplished with an externally owned account (EOA) alone. -In this document, we'll describe some of the features and considerations associated with smart contract accounts in general, and the architecture used by the Valora wallet in particular as an example of how smart contract accounts can be used. - -EOAs are what most people think of when they imagine a blockchain wallet. -EOAs are comprised of an ECDSA public/private key pair from which the on-chain address is derived. -The account address is derived from the public key, and transactions are authorized by the private key. -In most wallets, the EOA is generated and stored on the user's mobile device and backed up via a BIP-39 mnemonic phrase. - -A smart contract account on the other hand is a smart contract that can be used to interact with other smart contracts on behalf of the owner. -Celo provides an open-source implementation of a smart contract account; the [meta-transaction wallet](https://github.com/celo-org/celo-monorepo/blob/master/packages/protocol/contracts/common/MetaTransactionWallet.sol) (MTW). -In general, ownership can be determined in arbitrary ways, but most commonly an EOA is designated as the owner and can authorize transactions my signing a meta-transaction containing the details of the authorized transaction. -This is how the meta-transaction wallet works. -In this case you can think of the smart contract account as the primary account, and the EOA as the controller of this account. - -## Benefits of a smart contract account - -### Separation of signer and payer - -When new users create a wallet, they start with an empty balance. -This makes it difficult for the new users to verify their phone number as they need to pay for both the Celo transactions and the Attestation Service fees ([see here for more details](/legacy/protocol/identity/)). -To make this experience more intuitive and frictionless for new users, cLabs operates an [onboarding service called Komenci](https://github.com/celo-org/komenci/) that pays for the transactions on behalf of the user. -It does this by first deploying a meta-transaction wallet contract and setting the wallet EOA address as the signer. -At this point, the EOA can sign transactions and submit them to Komenci. -Komenci will wrap the signed transaction into a meta-transaction, which it pays for and submits to the network. - -In general, smart contract accounts allow the someone other than the account owner to pay for the transaction fees required to submit a transaction to the blockchain, enabling a number of useful operations not otherwise possible. - -### Account recovery - -Smart contract accounts can also be useful if a user ever loses their phone and recovery phrase. -Unlike EOAs, smart contract accounts can support account recovery methods that do not rely solely on recovering the underlying keys. -The meta-transaction wallet implements [a function](https://github.com/celo-org/celo-monorepo/blob/master/packages/protocol/contracts/common/MetaTransactionWallet.sol#L101-L108) to assign another Celo address as the Guardian of the account. -This Guardian can be a simple backup key or a smart contract implementing social recovery, [KELP](https://eprint.iacr.org/2021/289), or another account recovery protocol. -With the authorization of the Guardian, the meta-transaction wallet will update the owner of the account to replace the lost key. -Any funds or privileges held by the meta-transaction wallet are then recovered to the user who can control the account using their new key. - -### Transaction batching - -With smart contract accounts, including the meta-transaction wallet, transactions can be batched together to execute atomically. -This makes for a better user experience, as transactions can be guaranteed to execute all together or entirely revert. -It can also prevent some cases where front-running would be possible by splitting the user's transactions. - -## Valora accounts - -Behind every Valora wallet are two types of accounts: an externally owned account (EOA) and a meta-transaction wallet. -Valora generates the EOA during onboarding, and has a meta-transaction wallet deployed for it by Komenci with the generated EOA as the signer. -Using this configuration, Valora users gain the benefits listed above, including having Valora pay for the transaction fees associated with onboarding. - -## Sending to a Valora wallet - -When performing a payment to a Valora wallet, it's important that the address that is receiving funds is the EOA, and not the MTW since funds in the MTW are not displayed or directly accessible to Valora users. -To look up a wallet using a phone number: - -1. Use ODIS to query the phone number pepper -2. Use the phone number pepper to get the on-chain identifier -3. Use the on-chain identifier to get the account address -4. Use the account address to get the wallet address (EOA) - -The first two steps are covered extensively in [this guide](/developer/contractkit/odis). - -To get the account address (step 3) you can use the [Attestation contract method `lookupAccountsForIdentifier`](https://github.com/celo-org/celo-monorepo/blob/e6fdaf798a662ffe2c12f9a74b28e0fa1c1f8101/packages/sdk/contractkit/src/wrappers/Attestations.ts#L472). - -To get the wallet address from the account (step 4) you can use the [Account contract method `getWalletAddress`](https://github.com/celo-org/celo-monorepo/blob/e6fdaf798a662ffe2c12f9a74b28e0fa1c1f8101/packages/sdk/contractkit/src/wrappers/Accounts.ts#L318). - -It may also be necessary to lookup the data encryption key (ex. [for comment encryption](/legacy/protocol/transaction/tx-comment-encryption)). This key can similarly be queried with the account by using the [Account contract method `getDataEncryptionKey`](https://github.com/celo-org/celo-monorepo/blob/e6fdaf798a662ffe2c12f9a74b28e0fa1c1f8101/packages/sdk/contractkit/src/wrappers/Accounts.ts#L310). - -You can view a working example of this all tied together in [the `celocli` command `identity:get-attestations`](https://github.com/celo-org/celo-monorepo/blob/master/packages/cli/src/commands/identity/get-attestations.ts). - -## Enabling Valora to interact with your dApp - -### Signatures - -Since all Valora users will have the use a meta-transaction wallet, it's important to keep in mind that transactions may originate from an EOA as well as a smart contract. -If your contract relies upon EIP-712 signed typed data, be sure to also support typed data originating from contracts. -This data can't be signed by the `msg.sender` since it's originating from a contract, but is implicitly authorized by originating from the contract. - -## Implementation - -The implementation of the meta-transaction wallet can be [found here](https://github.com/celo-org/celo-monorepo/blob/master/packages/protocol/contracts/common/MetaTransactionWallet.sol). diff --git a/legacy/protocol/pos/becoming-a-validator.mdx b/legacy/protocol/pos/becoming-a-validator.mdx deleted file mode 100644 index f496af3b8..000000000 --- a/legacy/protocol/pos/becoming-a-validator.mdx +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: "Becoming a Validator" ---- - - -This page describes the historical Celo Layer 1 blockchain. It is useful for understanding Celo’s history, but does not reflect the current state of the network. As of block height 31,056,500 (March 26, 2025, 3:00 AM UTC), Celo has transitioned to an Ethereum Layer 2. - - ---- - -To participate in the network, an operator must put up a slashable commitment of locked CELO, register as a validator, and join a validator group. A minimum stake of one CELO and a notice period of 60 days is required to be a validator in the Alfajores Testnet. - -Any account that meets the minimum stake and notice period requirements can register as a validator. By doing so, the locked funds on that account become ‘at risk’: a fraction of the stake can be slashed automatically for an evolving set of misbehaviors. In addition, the community can use governance proposals to slash funds, which avoids having to anticipate and encode in the protocol every possible misbehavior. As long as the CELO staked for a validator account is not slashed, it’s eligible to earn rewards like any other Locked Gold account. - -A validator joins a validator group by affiliating itself with it. However, to avoid untrusted or malicious validators joining a group, the validator group must accept the affiliation. Once done, the validator is added to the list of validators in the group. A validator can remove itself from a validator group at any time. Changes only take effect at the next subsequent election, so if the validator is currently participating in consensus, it’s expected to do so until the end of the epoch in which it deregisters itself. diff --git a/legacy/protocol/pos/epoch-rewards-locked-gold.mdx b/legacy/protocol/pos/epoch-rewards-locked-gold.mdx deleted file mode 100644 index 48367bbf6..000000000 --- a/legacy/protocol/pos/epoch-rewards-locked-gold.mdx +++ /dev/null @@ -1,43 +0,0 @@ ---- -title: "Locked CELO Rewards" -sidebarTitle: "Locked CELO Rewards" -og:description: How to earn locked CELO rewards and adjust the rate for voting participation, target schedule, and deductions. ---- - -How to earn locked CELO rewards and adjust the rate for voting participation, target schedule, and deductions. - - -This page describes the historical Celo Layer 1 blockchain. It is useful for understanding Celo’s history, but does not reflect the current state of the network. As of block height 31,056,500 (March 26, 2025, 3:00 AM UTC), Celo has transitioned to an Ethereum Layer 2. - - ---- - -## Introduction to Locked CELO Rewards - -Holders of Locked CELO that voted in the previous epoch for a group that elected one or more validators and have activated their votes are eligible for rewards. Rewards are added directly to the Locked CELO voting for that group, and re-applied as votes for that same group, so future rewards are compounded without the account holder needing to take any action. The voting process is described further [here](/home/protocol/epoch-rewards/index). - - -Rewards to Locked CELO are totally independent from validator and validator group rewards, and are not subject to the **group share**. - - - -![Flow diagram showing locked CELO rewards process](https://storage.googleapis.com/celo-website/docs/locked-gold-rewards.jpg) - - -## Adjusting the Reward Rate for Voting Participation - -The protocol has a target for the proportion of circulating CELO that is locked and used for voting. An on-target reward rate is determined and then adjusted at every epoch to increase or reduce the attractiveness of locking up additional supply. This aims to balance having sufficient liquidity for CELO, while making it more challenging to buy enough CELO to meaningfully influence the outcome of a validator election. - -The reward rate is adjusted as follows: - - -![Mathematical equation showing reward rate adjustment formula](https://storage.googleapis.com/celo-website/docs/voting_reward_rate_adjustment_equation.png) - - -where $$rr$$ is the reward rate or voting yield, $$vf$$ is the voting fraction calculated as locked CELO for voting divided by circulating CELO supply, and $$af$$ is the adjustment factor. If the voting participation is below the target at the end of an epoch, the on-target reward rate is increased; if the voting participation is above the target at the end of an epoch, the reward is decreased. - -## Adjusting the Reward Rate for Target Schedule and Deductions - -Adjusting the on-target reward rate to account for under- or over-spending against the target schedule gives a baseline reward, essentially the percentage increase for a unit of Locked CELO voting for a group eligible for rewards. - -The reward for activated Locked CELO voting for a given group is determined as follows. First, if the group elected no validators in the current epoch, rewards are zero. Otherwise, the baseline reward rate factors in two deductions. It is multiplied by the slashing penalty for the group, and by the average epoch uptime score for validators in the group elected in the current epoch. Finally, the group's activated pool of Locked CELO is increased by this rate. \ No newline at end of file diff --git a/legacy/protocol/pos/epoch-rewards-validator.mdx b/legacy/protocol/pos/epoch-rewards-validator.mdx deleted file mode 100644 index d50170aa3..000000000 --- a/legacy/protocol/pos/epoch-rewards-validator.mdx +++ /dev/null @@ -1,67 +0,0 @@ ---- -title: "Validator Rewards" -sidebarTitle: "Validator Rewards" -og:description: Overview of epoch rewards for Validators and Validator Groups. ---- - -Overview of epoch rewards for Validators and Validator Groups. - - -This page describes the historical Celo Layer 1 blockchain. It is useful for understanding Celo’s history, but does not reflect the current state of the network. As of block height 31,056,500 (March 26, 2025, 3:00 AM UTC), Celo has transitioned to an Ethereum Layer 2. - - ---- - -The protocol aims to incentivize validator uptime performance and penalize past poor behavior in future rewards, while ensuring that payments are economically reasonable in size independent of fluctuations of the price of CELO. - -**Five factors affect validator and group rewards:** - -- The on-target reward amount for this epoch -- The protocol's [overall spending vs target of epoch rewards](/legacy/protocol/pos/epoch-rewards) -- The validator’s ‘uptime score’ -- The current value of the slashing penalty for the group of which it was a member at the last election -- The group share for the group of which it was a member at the last election - -Epoch rewards to validators and validator groups are denominated in Celo Dollars, since it is anticipated that most of their expenses will be incurred in fiat currencies, allowing organizations to understand their likely return regardless of volatility in the price of CELO. To enable this, the protocol mints new Celo Dollars that correspond to the epoch reward equivalent of CELO which are maintained on chain to preserve the collateralization ratio. Of course, the effect on the target schedule depends on the prevailing exchange rate. - - -![](https://storage.googleapis.com/celo-website/docs/validator-rewards.jpg) - - -## On-target Rewards - -The on-target validator reward is a constant value (as block rewards typically would be) and is intended to cover costs plus an attractive margin for amortized capital and operating expenses associated with a recommended set up that includes redundant hosts with hardware wallets in a secure co-lo facility, proxy nodes at cloud or edge hosting providers, as well as security audits. As with most parameters of the Celo protocol, it can be changed by governance proposal. - -In the usual case where no validator in the group has been slashed recently, and the validator has signed almost every block in the epoch, then the validator receives the full amount of the on-target reward, less the fraction sent to the validator group based on the group share. Unlike in some other proof-of-stake schemes, epoch rewards to validators do not depend on the number of votes the validator’s group has received. - -## Calculating Uptime Score - -The Celo protocol tracks an ‘uptime score’ for each validator. When a validator proposes a block, it also includes in the block body every signature that it has received from validators committing the previous block. - - -![](https://storage.googleapis.com/celo-website/docs/uptime-score.jpg) - - -For a validator to be ‘up’ at a given block, it must have its signature included in at least one in the previous twelve blocks. This cannot be done during the first 11 blocks of the epoch. At each epoch, this counter is reset to 0. Because the proposer order is shuffled at each election, it is very hard for a malicious actor withholding an honest validator’s signatures to affect this measure. - -Then, a validator’s uptime for the epoch is the proportion of blocks in the epoch for which it is ‘up’: `u = (counter + downtime_grace_period) / (epoch_size - 11)`. Its epoch uptime score `S_ve = u ^ k`, where `downtime_grace_period` and `k` are a governable constants. This means that even repeated downtimes of less than around a minute are ignored and longer downtimes also won't count against the validator as long as their total duration stays below `downtime_grace_period`. After that the score will reduce rapidly due to the exponent `k`. - -The validator’s overall uptime score is an exponential moving average of the uptime score from this and previous epochs. `S_{v} = min(S_ve, S_ve * x + S_{v-1} * (1 -x))` where `0 < x < 1` and is governable. Since `S_v` starts out at zero, validators have a disincentive to change identities and an incentive to prioritize activities that improve long-term availability. - -## Calculating Slashing Penalty - -The protocol also tracks for each group a ‘slashing penalty’, initially equal to one but successively reduced on each occasion a validator in that group is slashed. The penalty returns to one 30 days after it was last reduced. - -This factor is applied to all rewards to validators in that group, to the group itself, and to voters for the group. - -The slashing penalty gives groups a further incentive to vet validators they accept as members, not only to avoid reducing their own future rewards from existing validators but to attract and retain the best validators. - -Validators have an incentive to be elected through groups with a high value, so a recent slashing makes a group less attractive. Validators also have an incentive to select groups where they believe careful vetting processes are in place, because poor vetting of other validators in the group reduces their own expectation of future rewards. - -When a validator is slashed, reduced rewards may lead other validators in the same group to consider equivalently ‘safe’ slots in other groups, if they are available. A validator disassociating from the group would cause the group’s rewards to further decline. While that may cause churn in the set of groups through which validators are elected, it is unlikely that a validator would move to a group where they could not be elected (since in this case they would receive no rewards, as opposed to fewer rewards), hence making the votes by which they were previously elected unproductive. - -## Group Share - -Validator groups are compensated by taking a share of the rewards allocated to validators. Validator groups set a **group share** rate when they register, and can change that at any time. The protocol automatically deducts this share, sending that portion of the epoch rewards to the validator group of which they were a member at the time of the last election. - -Since the sum of a validator’s reward and its validator group’s reward are the same regardless of the ‘group share’ that the group chooses, no side-channel collusion is possible to avoid deductions for downtime or previous slashing. \ No newline at end of file diff --git a/legacy/protocol/pos/epoch-rewards.mdx b/legacy/protocol/pos/epoch-rewards.mdx deleted file mode 100644 index a5604f12c..000000000 --- a/legacy/protocol/pos/epoch-rewards.mdx +++ /dev/null @@ -1,50 +0,0 @@ ---- -title: "Epoch Rewards" -sidebarTitle: "Overview" -og:description: Introduction to Celo epoch rewards and the target reward release schedule. ---- - -Introduction to Celo epoch rewards and the target reward release schedule. - - -This page describes the historical Celo Layer 1 blockchain. It is useful for understanding Celo’s history, but does not reflect the current state of the network. As of block height 31,056,500 (March 26, 2025, 3:00 AM UTC), Celo has transitioned to an Ethereum Layer 2. - - ---- - -## What are Epoch Rewards? - -**Epoch Rewards** are similar to the familiar notion of block rewards in other blockchains, minting and distributing new units of CELO as blocks are produced, to create several kinds of incentives. - -**Epoch rewards are paid in the final block of the epoch and are used to:** - -- Distributed [rewards for validators and validator groups](/legacy/protocol/pos/epoch-rewards-validator) -- Distribute [rewards to holders of Locked CELO](/home/protocol/epoch-rewards/index) voting for groups that elected validators -- Make payments into a [Community Fund](/home/protocol/epoch-rewards/community-fund) for protocol infrastructure grants -- Make payments into a [Carbon Offsetting Fund](/home/protocol/epoch-rewards/carbon-offsetting-fund) for carbon offsetting projects - -A total of 400 million CELO will be released for epoch rewards over time. CELO is a utility and governance asset on Celo, and also the reserve collateral for Celo Dollar (and possibly in the future other whitelisted tokens). It has a fixed total supply and in the long term will exhibit deflationary characteristics similarly to Ethereum. - -### Reward Disbursement - -The total amount of disbursements is determined at the end of every epoch via a two step process. - -**Step 1** - -In step one, economically desired **on-target rewards** are derived. These are explained in the following pages. Several factors can increase or decrease the value of the payments that would ideally be made in a given epoch (including the CELO to Dollar exchange rate, the collateralization of the reserve, and whether payments to validators or groups are held back due to poor uptime or prior slashing). - -**Step 2** - -In step two, these on-target rewards are adjusted to generate a drift towards a predefined target epoch rewards schedule. This process aims to solve the trade-off between paying reasonable rewards in terms of purchasing power and avoiding excessive over- or underspending with respect to a predefined epoch rewards schedule. More detail about the two steps is provided below. - -## Adjusting Rewards for Target Schedule - -There is a target schedule for the release of CELO epoch rewards. The proposed target curve \(subject to change\) of remaining epoch rewards declines linearly over 15 years to 50% of the initial 400 million CELO, then decays exponentially with half life of $$h = ln(2)\times15 =10.3$$ afterwards. The choice of $$h$$ guarantees a smooth transition from the linear to the exponential regime. - - -![Chart showing CELO epoch rewards release schedule over time: starting at 400 million CELO, declining linearly over 15 years to 200 million CELO (50% of initial), then transitioning to exponential decay with half-life of 10.3 years](https://storage.googleapis.com/celo-website/docs/epoch-rewards-schedule.png) - - -The total **actual rewards** paid out at the end of a given epoch result from multiplying the total on-target rewards with a `Rewards Multiplier`. This adjustment factor is a function of the percentage deviation of the remaining epoch rewards from the target epoch rewards remaining. It evaluates to `1` if the remaining epoch rewards are at the target and to smaller \(or larger\) than `1` if the remaining rewards are below \(or above, respectively\) the target. This creates a drag towards the target schedule. - -The sensitivity of the adjustment factor to the percentage deviation from the target are governable parameters: one for an underspend, one for an overspend. \ No newline at end of file diff --git a/legacy/protocol/pos/index.mdx b/legacy/protocol/pos/index.mdx deleted file mode 100644 index 2c0bceb81..000000000 --- a/legacy/protocol/pos/index.mdx +++ /dev/null @@ -1,65 +0,0 @@ ---- -title: "Proof of Stake" -sidebarTitle: "Overview" -og:description: Overview of Celo's proof-of-stake algorithm, mechanisms, and implementation. ---- - -import {YouTube} from '/snippets/YouTube.jsx'; - -Overview of Celo's proof-of-stake algorithm, mechanisms, and implementation. - - -This page describes the historical Celo Layer 1 blockchain. It is useful for understanding Celo’s history, but does not reflect the current state of the network. As of block height 31,056,500 (March 26, 2025, 3:00 AM UTC), Celo has transitioned to an Ethereum Layer 2. - - ---- - -## Mastering the Art of Validating - - - -## Validator Types - -Celo uses a Byzantine Fault Tolerant [consensus protocol](/legacy/protocol/consensus/index) to agree on new blocks to append to the blockchain. The instances of the Celo software that participate in this consensus protocol are known as **validators**. More accurately, they are **active validators** or **elected validators**, to distinguish them from **registered validators** which are configured to participate but are not actively selected. - -## Proof-of-Stake - -Celo's proof-of-stake mechanism is the set of processes that determine which nodes become active validators and how incentives are arranged to secure the network. - -## Active Validators - -The first set of active validators are determined in the genesis block. Thereafter at the end of every epoch, a fixed number of blocks fixed at network creation time, an election is run that may lead to validators being added or removed. - - -![](https://storage.googleapis.com/celo-website/docs/concepts.jpg) - - -## Validator Elections - -In Celo's [Validator Elections](/legacy/protocol/pos/validator-elections), holders of the native asset, CELO, may participate and earn rewards for doing so. Accounts do not make votes for validators directly, but instead vote for [validator groups](/legacy/protocol/pos/validator-groups). - -Before they can vote, holders of CELO move balances into the [Locked Gold](/legacy/protocol/pos/locked-gold) smart contract. Locked Gold can be used concurrently for: placing votes in Validator Elections, maintaining a stake to satisfy the requirements of registering as a validator or validator group, and also voting in on-chain [Governance](/home/protocol/governance/overview) proposals. This means that validators and groups can vote and earn rewards with their stake. - - -**note** - -Unlike in other proof-of-stake systems, holding Locked Gold or voting for a group does not put that amount 'at risk' from slashing due to the behavior of validators or validator groups. Only the stake put up by a validator or group may be slashed. - - -## Implementation - -Most of Celo's proof-of-stake mechanism is implemented as smart contracts, and as such can be changed through Celo's on-chain [Governance](/home/protocol/governance/overview) process. - -- [`Accounts.sol`](https://github.com/celo-org/celo-monorepo/blob/master/packages/protocol/contracts/common/Accounts.sol) manages key delegation and metadata for all accounts including Validators, Groups and Locked Gold holders. - -- [`LockedGold.sol`](https://github.com/celo-org/celo-monorepo/blob/master/packages/protocol/contracts/governance/LockedGold.sol) manages the lifecycle of Locked Gold. - -- `Validators.sol` handles registration, deregistration, staking, key management and epoch rewards for validators and validator groups, as well as routines to manage the members of groups. - -- [`Election.sol`](https://github.com/celo-org/celo-monorepo/blob/master/packages/protocol/contracts/governance/Election.sol) manages Locked Gold voting and epoch rewards and runs Validator Elections. - -In Celo blockchain: - -- [`consensus/istanbul/backend/backend.go`](https://github.com/celo-org/celo-blockchain/blob/master/consensus/istanbul/backend/backend.go) performs validator elections in the last block of the epoch and calculates the new [validator set diff](/legacy/protocol/consensus/validator-set-differences). - -- [`consensus/istanbul/backend/pos.go`](https://github.com/celo-org/celo-blockchain/blob/master/consensus/istanbul/backend/pos.go) is called in the last block of the epoch to process validator uptime scores and make epoch rewards. \ No newline at end of file diff --git a/legacy/protocol/pos/locked-gold.mdx b/legacy/protocol/pos/locked-gold.mdx deleted file mode 100644 index 35d88eba2..000000000 --- a/legacy/protocol/pos/locked-gold.mdx +++ /dev/null @@ -1,75 +0,0 @@ ---- -title: Locked CELO and Voting -og:description: Introduction to locked CELO and how to use validator elections to participate in voting. -sidebarTitle: "Locked CELO" ---- - -Introduction to Celo locked gold (CELO) and how to use validator elections to participate in voting. - - -This page describes the historical Celo Layer 1 blockchain. It is useful for understanding Celo’s history, but does not reflect the current state of the network. As of block height 31,056,500 (March 26, 2025, 3:00 AM UTC), Celo has transitioned to an Ethereum Layer 2. - - - -**Terminology** - -This page references "Locked Gold". The native asset of Celo was called Celo Gold (cGLD), but is now called CELO. Many references have been updated, but code and smart contract references may still mention Gold as it is more difficult to reliably and securely update the protocol code. - - ---- - -## Validator Election Participation - -To participate in validator elections, users must first make a transfer of CELO to the `LockedGold` smart contract. - -## Concurrent Use of Locked CELO - -Locking up CELO guarantees that the same asset is not used more than once in the same vote. However every unit of Locked CELO can be deployed in several ways at once. Using an amount for voting for a validator does not preclude that same amount also being used to vote for a governance proposal, or as a stake at the same time. Users do not need to choose whether to have to move funds from validator elections in order to vote on a governance proposal. - -## Unlocking Period - -Celo implements an **unlocking period**, a delay of 3 days after making a request to unlock Locked CELO before it can be recovered from the escrow. - -This value balances two concerns. First, it is long enough that an election will have taken place since the request to unlock, so that those units of CELO will no longer have any impact on which validators are managing the network. This deters an attacker from manipulations in the form of borrowing funds to purchase CELO, then using it to elect malicious validators, since they will not be able to return the borrowed funds until after the attack, when presumably it would have been detected and the borrowed funds’ value have fallen. - -Second, the unlocking period is short enough that it does not represent a significant liquidity risk for most users. This limits the attractiveness to users of exchanges creating secondary markets in Locked CELO and thereby pooling voting power. - -## Locking and Voting Flow - - -![](https://storage.googleapis.com/celo-website/docs/locked-gold-flow.jpg) - - -The flow is as follows: - -- An account calls `lock`, transferring an amount of CELO from their balance to the `LockedGold` smart contract. This increments the account's 'non-voting' balance by the same amount. - -- Then the account calls `vote`, passing in an amount and the address of the group to vote for. This decrements the account's 'non-voting' balance and increments the 'pending' balance associated with that group by the same amount. This counts immediately towards electing validators. Note that the vote may be rejected if it would mean that the account would be voting for more than 3 distinct groups, or that the [voting cap](/legacy/protocol/pos/validator-elections#group-voting-caps) for the group would be exceeded. - -- At the end of the current epoch, the protocol will first deliver [epoch rewards](/legacy/protocol/pos/epoch-rewards) to validators, groups and voters based on the current epoch (pending votes do not count for these purposes), and then run an [election](/legacy/protocol/pos/validator-elections) to select the active validator set for the following epoch. - -- The pending vote continues to contribute towards electing validators until it is changed, but the account must call `activate` (in a subsequent epoch to the one in which the vote was made) to convert the pending vote to one that earns rewards. - -- At the end of that epoch, if the group for which the vote was made had elected one or more validators in the prior election, then the activated vote is eligible for [Locked CELO rewards](/home/protocol/epoch-rewards/index). These are applied to the pool of activated votes for the group. This means that activated voting Locked CELO automatically compounds, with the rewards increasing the account's votes for the same group, thereby increasing future rewards, benefitting participants who have elected to continuously participate in governance. - -- The account may subsequently choose to `unvote` a specific amount of voting Locked CELO from a group, up to the total balance that the account has accrued there. Due to rewards, this Locked CELO amount may be higher than the original value passed to `vote`. - -- This Locked CELO immediately becomes non-voting, receives no further Epoch Rewards, and can be re-used to vote for a different group. - -- The account may choose to `unlock` an amount of Locked CELO at any time, provided that it is inactive: this means it is non-voting in Validator Elections, the `deregistrationPeriod` has elapsed if the amount has been used as a validator or validator group stake, and not active in any [Governance proposals](/home/protocol/governance/overview). Once an unlocking period of 3 days has passed, the account can call `withdraw` to have the `LockedGold` contract transfer them that amount. - -Votes persist between epochs, and the same vote is applied to each election unless and until it is changed. Vote withdrawal, vote changes, and additional CELO being used to vote have no effect on the validator set until the election finalizes at the end of the epoch. - -## Vote Delegation - -[Contract Release 10](https://github.com/celo-org/celo-monorepo/issues/10375) introduced vote delegation, which allows the governance participant to delegate their voting power. - - -Validators and Validator groups cannot delegate. - - -The governance participants who cannot actively participate to vote on governance proposals in the Celo ecosystem can now delegate their votes to utilize the dormant votes. - -Currently, participants can only delegate to 10 other delegatees. - -Participants can follow the steps [here](/home/protocol/governance/voting-in-governance#vote-delegation) to perform delegation using CeloCLI. \ No newline at end of file diff --git a/legacy/protocol/pos/penalties.mdx b/legacy/protocol/pos/penalties.mdx deleted file mode 100644 index 165511c08..000000000 --- a/legacy/protocol/pos/penalties.mdx +++ /dev/null @@ -1,48 +0,0 @@ ---- -title: "Validator Penalties" -sidebarTitle: "Penalties" -og:description: Introduction to validator penalties, enforcement mechanisms, and conditions. ---- - -Introduction to validator penalties, enforcement mechanisms, and conditions. - - -This page describes the historical Celo Layer 1 blockchain. It is useful for understanding Celo’s history, but does not reflect the current state of the network. As of block height 31,056,500 (March 26, 2025, 3:00 AM UTC), Celo has transitioned to an Ethereum Layer 2. - - ---- - -## What is Slashing? - -Slashing accomplishes punishment of misbehaving validators by seizing a portion of their stake. Without these punishments, for example, the Celo Protocol would be subject to the nothing at stake problem. Validator misbehavior is classified as a set of slashing conditions below. - -## Enforcement Mechanisms - -The protocol has three means of recourse for validator misbehavior. Each slashing condition applies a combination of these, as described below. - -- **Slashing of validator and group stake -** Some slashing conditions take a fixed amount of the Locked Gold stake put up by a validator. In these cases, the group through which that validator was elected for the epoch in which the slashing condition was proven is also slashed the same fixed amount. A validator or group's stake may be forfeit while it is registered or, after being deregistered, during the notice period (60 days for validators, 180 days for groups) and before the amount is withdrawn from the `LockedGold` contract. - -- **Suppression of future rewards -** Every validator group has a **slashing penalty**, initially `1.0`. All rewards to the group and to voters for the group are weighted by this factor. If a validator is slashed, the group through which that validator was elected for the epoch in which it misbehaved has the value of its slashing penalty halved. So long as no further slashing occurs, the slashing penalty is reset to `1.0` after `slashing_penalty_reset_epochs` epochs. - -- **Ejection -** When a validator is slashed, it is immediately removed from the group of which it is currently a member (even if this group is not the group that elected the validator at the point the misbehavior was recorded). Since no changes in the active validator set are made during an epoch, this means an elected validator continues participate in consensus until the end of the epoch. The group can choose to re-add the validator at any point, provided the usual conditions are met (including that the validator has sufficient Locked Gold as stake). - -## Slashing Conditions - -There are three categories of slashing conditions: - -- Provable \(initiated off-chain, verifiable on-chain\) -- Governed \(verified only by off-chain knowledge\) - -### Provable - -Provable slashing conditions cannot be initiated automatically on chain but information provided from an external source can be definitively verified on-chain. - -In exchange for sending a transaction which initiates a successful provable slashing condition on-chain, the reporter receives a "reward", a portion of the slashed amount (which will always be greater than the gas costs of the proof). The reward is added to the reporter's balance of non-voting LockedGold. The remainder of the slashed amount is sent to the [Community Fund](/home/protocol/epoch-rewards/community-fund). - -- **Persistent downtime -** A validator which can be shown to be absent from 8640 consecutive BLS signatures will be slashed 100 CELO, have future rewards suppressed, and (most importantly in this case) will be ejected from its current group. - -- **Double Signing -** A validator which can be shown to have produced BLS signatures for 2 distinct blocks at the same height and in the same consensus round but with different hashes will be slashed 9000 CELO, have future rewards suppressed, and will be ejected from its current group. Note that unlike some proof-of-stake networks, Celo does not penalize validators for double signing regular consensus messages. In particular, one side-effect of how Celo provides liveness can result in cases where honest validators may legitimately double sign blocks across different rounds at the same height (Cosmos terms this [amnesia](https://github.com/tendermint/spec/blob/fa3430ad163a2a0ed77aa3f624a70cd9b8b84b78/spec/consensus/signing.md#other-rules) and also specifically excludes it from slashing). - -### **Governed** - -For misbehavior which is harder to formally classify and requires some off-chain knowledge, slashing can be performed via [governance proposals](/home/protocol/governance/overview). These conditions are important for preventing nuanced validator attacks. \ No newline at end of file diff --git a/legacy/protocol/pos/validator-elections.mdx b/legacy/protocol/pos/validator-elections.mdx deleted file mode 100644 index e592f4949..000000000 --- a/legacy/protocol/pos/validator-elections.mdx +++ /dev/null @@ -1,59 +0,0 @@ ---- -title: "Validator Elections" -sidebarTitle: "Validator Elections" -og:description: Introduction to Celo validator elections and management of groups and votes throughout the process. ---- - -Introduction to Celo validator elections and management of groups and votes throughout the process. - - -This page describes the historical Celo Layer 1 blockchain. It is useful for understanding Celo’s history, but does not reflect the current state of the network. As of block height 31,056,500 (March 26, 2025, 3:00 AM UTC), Celo has transitioned to an Ethereum Layer 2. - - ---- - -## Updating the Active Validator Set - -The active validator set is updated by running an election in the final block of each epoch, after processing transactions and [Epoch Rewards](/legacy/protocol/pos/epoch-rewards). - -### Group Voting Caps - -One way to consider the security of a proof-of-stake system is the marginal cost of getting a malicious validator elected. In a steady state, assuming the Celo community set the incentives appropriately, a full complement of validators is likely to be elected, which means the attack cost is the cost of acquiring sufficient CELO to receive more votes than the currently elected validator with fewest votes, and thereby supplant it. - -### Goal of Validator Elections - -The objective of Celo’s validator elections differs from real-world elections: they aim to translate voter preferences into representation while promoting decentralization and creating a moat around existing, well-performing elected validators. Two design choices influence this: a limit on the maximum number of member validator that a group can list, and a **voting cap** on the number of votes that any one group can receive. - -### Handling Excess Votes - -Since voting for a group can cause only the group’s member validators to get elected, and no more, votes in excess of the number needed to achieve that are unproductive in the sense that they do not raise the number of votes needed to get the least-voted-for validator elected. This would translate into a lower cost for a malicious actor to acquire enough CELO to supplant that validator. This is particularly true because the protocol limits the maximum number of members in a group, to promote decentralization. - -### Per-Group Vote Cap - -The Celo protocol addresses this by enforcing a per-group vote cap. This cap is set to be the number of votes that would be needed to elect all of its validators, plus one more validator. The cap is enforced at the point of voting: a user can only cast a vote for a group if it currently has fewer votes than this cap. An account holder may not set or increase the amount of gold they have voting for a particular validator group `j`, if it already has at least `[(group_members_j + 1) / min(total_group_members, max_validators)]` of the total Locked Gold. - -### Adding New Validators - -If a group adds a new validator, or the total amount of voting Locked Gold increases, the group’s cap rises and new votes are permitted. If a group removes a validator or a validator chooses to leave, or the total amount of voting Locked Gold falls, then the group’s cap falls: if it has more votes than this new cap, then new votes are no longer permitted, but all existing votes continue to be counted. - -The Celo protocol allows an account to divide its vote between up to ten groups, since there may be cases where the vote cap prevents an account allocating its entire vote to its first choice group. - -## Running the Election - - -![](https://storage.googleapis.com/celo-website/docs/election.jpg) - - -The `Election` contract is called from the IBFT block finalization code to select the validators for the following epoch. The contract maintains a sorted list of the Locked Gold voting (either pending or activated) for each Validator Group. The [D’Hondt method](https://wikipedia.org/wiki/D'Hondt_method), a closed party list form of proportional representation, is applied to iteratively select validators from the Validator Groups with the greatest associated vote balances. - -### Filtering Groups - -The list of groups is first filtered to remove those that have not achieved a certain fraction of the votes of the total voting Locked Gold. - -### Assigning Seats - -Then, in the first iteration, the algorithm assigns the first seat to the group that has at least one member and with the most votes. Thereafter, it assigns the seat to the group that would ‘pay’, if its next validator were elected, the highest vote averaged over its candidates that have been selected so far plus the one under consideration. - -### Number of Active Validators - -There is a minimum target and a maximum cap on the number of active validators that may be selected. If the minimum target is not reached, the election aborts and no change is made to the validator set this epoch. \ No newline at end of file diff --git a/legacy/protocol/pos/validator-groups.mdx b/legacy/protocol/pos/validator-groups.mdx deleted file mode 100644 index 8fea43ca3..000000000 --- a/legacy/protocol/pos/validator-groups.mdx +++ /dev/null @@ -1,67 +0,0 @@ ---- -title: "Validator Groups" -sidebarTitle: "Validator Groups" -og:description: Celo's proof-of-stake mechanism introduces the concept of Validator Groups as intermediaries between voters and validators. ---- - -Celo's proof-of-stake mechanism introduces the concept of **Validator Groups** as intermediaries between voters and validators. - - -This page describes the historical Celo Layer 1 blockchain. It is useful for understanding Celo’s history, but does not reflect the current state of the network. As of block height 31,056,500 (March 26, 2025, 3:00 AM UTC), Celo has transitioned to an Ethereum Layer 2. - - ---- - -## What is a Validator Group? - -A validator group has **members**, an ordered list of candidate validators. There is a fixed limit to the number of members that a group may have. - -## Why use a Validator Group? - -Validator groups can help mitigate the information disparity between voters and validators. It is anticipated that groups might emerge that do not necessarily operate validators themselves but attract votes for their reputation for ensuring their associated validators have known real-world identities, have high uptime, are well maintained and regularly audited. Since every validator needs to be accepted by a single group to stand for election, that group will be more able to build up long-term judgements on their validators’ operational practices and security setups than each of the numerous CELO holders that might vote for it would. - -## Fielding Multiple Validators - -Equally, a number of organizations may want to attempt to field multiple validators under their own control, or be able to interchange the specific machines or keys under which they validate in the case of hardware or connectivity failure. By switching out validators in the list, groups can accomplish this without users having to change their votes. - -## Validator Group Limits - -Validator groups can have no more than a small, fixed maximum number of validators -- currently 5 in Mainnet. This means an organization wanting to get more validators elected than this maximum has the added challenge of managing multiple group identities and reputations simultaneously. This further promotes decentralization and strengthens operational security, making it more likely that the validator set will be composed of nodes operated in different fashions by independent individuals and organizations. - -## Registration - -Any account that has at least the minimum stake requirement in Locked Gold, whether voting or non-voting, can register an empty validator group. If a validating key is specified it may be used for this registration. - -## Deregistration - -The account that creates a validator group is able to deregister that group if it has no members. - -While an account has a registered validator group, or for up to a `deregistrationPeriod` after it is deregistered, attempts to `unlock` the account's amount of Locked Gold will fail if they would cause the remaining amount to fall below the minimum stake requirement. - -## Group Share - -Validator groups are compensated by taking a share (the 'Group Share') of the [validator rewards](/legacy/protocol/pos/epoch-rewards-validator) from any of its member validators that are elected during an epoch. This value is set at registration time and can be changed later. - -## Changing Group Members - -The account owner controls the list of validators in their group and can at any time add, remove, or re-order validators. - -For a validator to be added to a group, several conditions must hold: the number of members in the group must be less than the maximum; the Locked Gold balance of the group's account must be sufficient (the stake is per-member validator); and the validator must first have set its affiliation to the group. - -This means that while a group can unilaterally remove a validator, and a validator can unilaterally leave by changing its affiliation, both parties have to agree before a validator can become a member of a group. - -## Votes and Voting Cap - -Validator Groups can receive votes from Locked Gold up to a [voting cap](/legacy/protocol/pos/validator-elections#group-voting-caps). This value is set to be the number of votes that would be needed to elect all of its validators, plus one more validator. The cap is enforced at the point of voting: a user can only cast a vote for a group if it currently has fewer votes than this cap. - -## Slashing Penalty - -A [slashing penalty](/legacy/protocol/pos/penalties), initially `1.0`, is also tracked for each validator group. This value may be reduced as a penalty for misbehavior of the validator in the group. It affects the future rewards of the group, its validators, and Locked Gold holders receiving rewards for voting for the group. - -## Metadata - -Both validators and validator groups can use [Accounts Metadata](/legacy/protocol/identity/metadata) to provide unverified metadata (such as name and organizational affiliation) as well as claims that can be verified off-chain for control of third-party accounts. All validators are encouraged to make a verifiable claim for [domain names](/legacy/validator/validator-explorer). - -## Dissolving of a Validator Group - -There is a 180 day unlocking period for Celo locked when creating a validator group. \ No newline at end of file diff --git a/legacy/protocol/randomness.mdx b/legacy/protocol/randomness.mdx deleted file mode 100644 index 491465aae..000000000 --- a/legacy/protocol/randomness.mdx +++ /dev/null @@ -1,55 +0,0 @@ ---- -title: "Randomness" -sidebarTitle: "Celo Randomness" -og:description: How unpredictable pseudo-randomness is achieved on the Celo blockchain. ---- - -How unpredictable pseudo-randomness is achieved on the Celo blockchain and offered as a service for dapp developers. - - -This page describes the historical Celo Layer 1 blockchain. It is useful for understanding Celo’s history, but does not reflect the current state of the network. As of block height 31,056,500 (March 26, 2025, 3:00 AM UTC), Celo has transitioned to an Ethereum Layer 2. - - ---- - -## Producing Pseudo-randomness - -Producing unpredictable pseudo-randomness without a trusted third party is not trivial. Several solutions for this problem exist or are being currently researched. They include Verifiable Random Functions \(for example, based on BLS threshold signatures\), Verifiable Delay Functions, and commit-reveal schemes. - -Currently, Celo implements a simple [RANDAO](https://eth2book.info/altair/part2/building_blocks/randomness#the-randao) commit-reveal scheme which is secure enough for many uses, offering validators only 1 bit of influence: a validator can affect randomness only by choosing _not to propose_ a block, which results in the next validator revealing their pre-commited randomness. A more sophisticated solution might be implemented as the network evolves, especially if randomness becomes necessary for other purposes that require stronger assumptions about the randomness’s security \(for example if it was decided that a randomized leader election algorithm should replace the current round robin\). - -In a proposed block, the proposer attaches two values related to the randomness scheme - randomness corresponding to their previous commitment, and a new commitment to freshly generated random bytes that will be revealed in the future. The revealed randomness is added to an entropy pool accessible on-chain from the Random smart contract. - -## Randomness Equation - -More formally, the $$n * {th} $$ block proposed by a given validator contains values $$(r_n, s_n)$$ such that $$\text{keccack256}(r_n) = s*{n-1}$$. The one exception to this is the validator’s first block, the case where $$n = 1$$, since they have not previously committed to randomness yet. Here, the protocol instead requires that $$r_1 = 1$$. - -## Using Onchain Randomness - -This randomness can be used by any smart contracts deployed to a Celo network using the Random core contract, e.g.: - -```solidity -import "celo-monorepo/packages/protocol/identity/interfaces/IRandom.sol"; -import "celo-monorepo/packages/protocol/common/interfaces/IRegistry.sol"; - -contract Example { - function test() external view returns (bytes32 randomness) { - randomness = IRandom( - IRegistry(0x000000000000000000000000000000000000ce10) - .getAddressFor(keccak256(abi.encodePacked("Random"))) - ).random(); - } -} -``` - -Alternatively, through inheritance of [UsingRegistry](https://github.com/celo-org/celo-monorepo/blob/master/packages/protocol/contracts/common/UsingRegistry.sol). - -```solidity -import "celo-monorepo/packages/protocol/common/UsingRegistryV2.sol"; - -contract Example is UsingRegistryV2 { - function test() external view returns (bytes32 randomness) { - randomness = getRandom().random(); - } -} -``` \ No newline at end of file diff --git a/legacy/protocol/stability/adding-stable-assets.mdx b/legacy/protocol/stability/adding-stable-assets.mdx deleted file mode 100644 index 2e293d5e6..000000000 --- a/legacy/protocol/stability/adding-stable-assets.mdx +++ /dev/null @@ -1,89 +0,0 @@ ---- -title: "Add Stable Assets" -sidebarTitle: "Add Stable Assets to Celo" -og:description: Overview of the requirements and steps to add a new stable asset to the Celo platform. ---- - -Overview of the requirements and steps to add a new stable asset to the Celo platform. - - -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](/build#celo-l2-mainnet). - - ---- - - -**Note** - -This example assumes we want to add to the platform a new stable asset `cX` tracking the value of X (where X can be a fiat currency like ARS or MXN), using the [Mento exchange](/legacy/protocol/stability/doto). - - -## Requirements - -**Liquidity** - -The asset X has to be liquidly traded against CELO, in a CELO/X ticker. In absence of that, X has to be liquidly traded, including weekends, against well known assets that trade 24/7, like BTC or ETH, such that the price of X with respect to Celo can be inferred. In this second case, an implicit pair can be calculated for the oracle reports. - -**Determine pre-mint addresses and amounts** - -It is possible to pre-mint a fixed amount at the time of launching a new stable asset, good candidates to receive the pre-mint are the community fund and other entities commited to distribute this initial allocation to grant recipients and liquidity providers. - - -A good criteria to a successfully decide a pre-mint amount is to check by how much it would affect the reserve collateralization ratio, this is, the ratio of all stable assets, divided by all the reserve holdings. Reserve information, as well as the collateralization ration can be found on the [Reserve website](https://reserve.mento.org/). - - -## Procedure - -### Including contracts on the registry - -Currently, the addition of new assets is tied to the [Contract Release Cycle](/contribute-to-celo/release-process/smart-contracts), as the contracts `ExchangeX` and `StableTokenX` need to be checked in [^1]. These new contracts inherit from Exchange and StableToken, that are the ones originally used for `cUSD`. As StableToken `cX` will be initialized by the contract release, key parameters like `spread` and `reserveFraction` should be included, although they can be later modified by setters in the following governance proposals. The only value that can't be changed is the pre-mint amount. - -### Freezing - -These contracts should be set as frozen to prevent `cX` from being transferable before Mento supports it in a governance proposal. At this point, as there are no oracles, the contract `ExchangeX` can't update buckets and it is thus impossible to mint and burn `cX`. There is [an issue open](https://github.com/celo-org/celo-monorepo/issues/7331) to include this step as part of the Contract Release. - -For the [deployment of cEUR](https://github.com/celo-org/celo-proposals/blob/master/CIPs/cip-0033.md), this was included as part of the [Oracle activation](#oracle-activation) proposal. - -### Constitutional parameters - - {/* TODO: SDK urls will need to be changed when the SDK type docs are separated from the rest of docs */} - -As new contracts are added to the registry, new **constitution parameters** need to be set. There's an [issue open](https://forum.celo.org/t/governance-proposals-for-march-2021/816) to include this in the tooling to support it as part of the Contract Release. - -### Oracle activation - -A following governance proposal needs to be submitted to enable [oracles](/legacy/protocol/stability/oracles) to report. This oracle proposal needs to enable addresses to report to the `StableTokenX` address and, optionally, fund them to pay for gas fees. An example of this proposal is the [cEUR oracle activation proposal](https://github.com/celo-org/celo-proposals/blob/master/CIPs/cip-0033.md)[^2]. - -### Full activation - -The last governance proposal is expected to unfreeze the contract and attach the last strings in the process to get a fully transferable asset stabilized by the Reserve. This propose involves: - -1. Unfreezing both `StableTokenX` & `ExchangeX`. -2. Making `ExchangeX` able to pull CELO out of the Reserve for the buckets `Reserve.addExchangeSpender` -3. Declaring the token to the Reserve as an asset to be stabilized calling `Reserve.addToken` -4. Enable `StableTokenX` as a fee currency, so that it can be used to pay for gas `FeeCurrencyWhitelist.addToken`. -5. In case necessary, parameters such as `reserveFraction` and `spread` can also be updated in this governance proposal. -6. Granda Mento activation - -After passing this last proposal, `cX` should be fully activated. - -## Tooling - -Adding a new stable asset involves updating many parts of the tooling, such as: - -- Update the Ledger app integration such that it displays the names of the newly added token. -- Update oracles and generating their keys and addresses. -- Adding support on `contractkit`. -- Adding support on [kliento](https://github.com/celo-org/kliento). -- Adding support on [eksportisto](https://github.com/celo-org/eksportisto). -- Update on the cli, an example list of things to add are included on [this issue](https://github.com/celo-org/celo-monorepo/issues/6793). -- Supporting on Dapp kit. - -[^1] There are opened issues trying to de-couple the addition of new assets to the reserve to the release cycle. - - -[^2] Please note this example proposal also includes freezing, this is because, at the time of writing (22-march-2021), the tooling for proposing a contract release doesn't support freezing those contracts on the same proposal. Proposals shall not be modified manually given that the tool is meant to run verifications. - \ No newline at end of file diff --git a/legacy/protocol/stability/doto.mdx b/legacy/protocol/stability/doto.mdx deleted file mode 100644 index c8f52a525..000000000 --- a/legacy/protocol/stability/doto.mdx +++ /dev/null @@ -1,60 +0,0 @@ ---- -title: "Stability Algorithm (Mento)" -sidebarTitle: "Celo Stability Algorithm (Mento)" -og:description: How the supply of the Celo Dollar is achieved in the Celo protocol using the constant-product decentralized one-to-one mechanism (CP-DOTO). ---- - -How the supply of the Celo Dollar is achieved in the Celo protocol using the constant-product decentralized one-to-one mechanism. - - -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](/build#celo-l2-mainnet). - - ---- - -## What is Mento? - -On a high level, Mento (previously known as CP-DOTO) allows user demand to determine the supply of celo stable assets by enabling users to create, for example, a new Celo Dollar by sending 1 US Dollar worth of CELO to the reserve, or to burn a Celo Dollar by redeeming it for 1 US Dollar worth of CELO. The mechanism requires an accurate [Oracle](./oracles) value of the CELO to US Dollar market rate to work. - -## Incentives - -This creates incentives such that when demand for the Celo Dollar rises and the market price is above the peg, users can profit using their own efforts by buying 1 US Dollar worth of CELO on the market, exchanging it with the protocol for one Celo Dollar, and selling that Celo Dollar for the market price. - -Similarly, when demand for the Celo Dollar falls and the market price is below the peg, users can profit using their own efforts by purchasing Celo Dollar at the market price, exchanging it with the protocol for 1 US Dollar worth of CELO, and selling the CELO to the market. - -## Mitigating Risk - -In cases in which the CELO to US Dollar oracle value is not an accurate reflection of the market price, exploiting such discrepancies can lead to a depletion of the reserve. Mento, inspired by the [Uniswap](https://uniswap.io/) system, mitigates this risk of depletion as follows: The Celo protocol maintains two virtual buckets of CELO and Celo Dollar. The amounts in these virtual buckets are recalibrated every time the reported oracle value is updated, provided the difference between the current time and the oracle timestamp is less than $$oracle\_staleness\_threshold$$. - -## Model Equations - -The equation for the constant-product-market-maker model fixes the product of the wallet quantities. - -$$ -G_t \times D_t = k -$$ - -where $$G_t$$ and $$D_t$$denote the quantities in the CELO and Celo Dollar buckets respectively and $$k$$ is some constant. Given the above rule, it can be shown that the price of CELO, to be paid in Celo Dollar units, is - -$ -P_t = \frac{D_t}{G_t} -$ - -for traded amounts that are small relative to the bucket quantities. - -## Oracle Rates - -Whenever the CELO to US Dollar oracle rate is updated, the protocol adjusts the bucket quantities such that they equalize the on-chain CELO to Celo Dollar exchange rate $$P_t$$ to the current oracle rate. During such a reset, the CELO bucket must remain smaller than the total reserve gold balance. To achieve this, the CELO bucket size is defined as the total reserve balance times $$gold\_bucket\_size$$, with $$0 < gold\_bucket\_size < 1$$ and the Celo Dollar bucket size is then chosen such that $$P_t$$ mirrors the oracle price. To discourage excessive on-chain trading, a transaction fee is imposed by adding small spread around the above exchange rate. - -If the oracle precisely mirrors the market rate, the on-chain CELO to Celo Dollar rate will equal the CELO to US Dollar market rate and no profit opportunity will exist as long as Celo Dollar precisely tracks the US Dollar. If the oracle price is imprecise, the two rates will differ, and a profit opportunity will be present even if Celo Dollar accurately tracks the US Dollar. However, as traders exploit this opportunity, the on-chain price $$P_t$$ will dynamically adjust in response to changes in the tank quantities until the opportunity ceases to exist. This limits the depletion potential in Mento in the case of imprecise or manipulated oracle rates. - - -For a more detailed explanation, read the article [Zooming in on the Celo Expansion & Contraction Mechanism](https://medium.com/celoorg/zooming-in-on-the-celo-expansion-contraction-mechanism-446ca7abe4f "Zooming in on the Celo Expansion & Contraction Mechanism"). - - -## Multi-mento Deployment - -Many instances of mento can be deployed in parallel for different stable assets. Currently, `cEUR` and `cUSD` live side-by-side, with independent buckets and oracle reports (although both of them are using the same `SortedOracles` instance). They all fill the CELO bucket with funds from the Reserve, but not necessarily at the same time. \ No newline at end of file diff --git a/legacy/protocol/stability/granda-mento.mdx b/legacy/protocol/stability/granda-mento.mdx deleted file mode 100644 index 5e6f62467..000000000 --- a/legacy/protocol/stability/granda-mento.mdx +++ /dev/null @@ -1,56 +0,0 @@ ---- -title: Granda Mento -og:description: Introduction to Granda Mento (CIP 38), its design, and how to manage exchange proposals. ---- - -Introduction to Granda Mento (CIP 38), its design, and how to manage exchange proposals. - - -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](/build#celo-l2-mainnet). - - ---- - -## What is Granda Mento? - -Granda Mento, described in [CIP 38](https://github.com/celo-org/celo-proposals/blob/master/CIPs/cip-0038.md), is a mechanism for exchanging large amounts of CELO for Celo stable tokens that aren't suitable for [Mento](./doto) or over-the-counter (OTC). - -Mento has proven effective at maintaining the stability of Celo's stable tokens, but the intentionally limited liquidity of its constant-product market maker results in meaningful slippage when exchanging tens of thousands of tokens at a time. Slippage is the price movement experienced by a trade. Generally speaking, larger volume trades will incur more slippage and execute at a less favorable price for the trader. - -Similar to Mento, exchanges through Granda Mento are effectively made against the reserve. Purchased stable tokens are created into existence ("minted"), and sold stable tokens are destroyed ("burned"). Purchased CELO is taken from the reserve, and sold CELO is given to the reserve. For example, a sale of 50,000 CELO in exchange for 100,000 cUSD would involve the 50,000 CELO being transferred to the reserve and the 100,000 cUSD being created and given to the exchanger. - -At the time of writing, exchanging about 50,000 cUSD via Mento results in a slippage of about 2%. Without Granda Mento, all launched Celo stable tokens can only be minted and burned using Mento, with the exception of cUSD that is minted as validator rewards each epoch. Granda Mento was created to enable institutional-grade liquidity to mint or burn millions of stable tokens at a time. - -The Mainnet Granda Mento contract address is `0x03f6842B82DD2C9276931A17dd23D73C16454a49` ([link](https://celo.blockscout.com/address/0x03f6842B82DD2C9276931A17dd23D73C16454a49)), was introduced in [Contract Release 5](https://github.com/celo-org/governance/blob/main/CGPs/cgp-0037.md), and activated in [CGP 31](https://github.com/celo-org/governance/blob/main/CGPs/cgp-0031.md). - -## How it works - -A Granda Mento exchange requires rough consensus from the Celo community and, unlike the instant and atomic Mento exchanges, involves the exchanger locking their funds to be sold for multiple days before they are exchanged. - -### Design - -At a high level, the life of an exchange is: - -1. Exchanger creates an "exchange proposal" on-chain that locks their funds to be sold and calculates the amount of the asset being purchased according the current oracle price and a configurable spread. -2. If rough consensus from the community is achieved, a multi-sig (the "approver") that has been set by Governance approves the exchange proposal on-chain. -3. To reduce trust in the approver multi-sig, a veto period takes place where any community member can create a governance proposal to "veto" an approved exchange proposal. -4. After the veto period has elapsed, the exchange is executable by any account. The exchange occurs with the price locked in at stage (1). - -### Processes - -Processes surrounding Granda Mento exchanges, like how to achieve rough consensus from the community, are outlined in [CIP 46](https://github.com/celo-org/celo-proposals/blob/master/CIPs/cip-0046.md). At the minimum, it takes about 7 days to achieve rough consensus. - -The approver multi-sig that is ultimately responsible for approving an exchange proposal that has achieved rough consensus from the community is `0xf10011424A0F35B8411e9abcF120eCF067E4CF27` ([link](https://celo.blockscout.com/address/0xf10011424A0F35B8411e9abcF120eCF067E4CF27/transactions)) and has the following signers: - -| **Name** | **Affiliation** | **Discord Handle** | **Address** | -| --------------- | ----------------------------- | ------------------------- | -------------------------------------------- | -| Andrew Shen | Bi23 Labs | `Shen \| Bi23 Labs #6675` | `0xBecc041a5090cD08AbD3940ab338d4CC94d2Ed3c` | -| Pinotio | Pinotio | `Pinotio.com #5357` | `0x802FE32083fD341D8e9A35E3a351291d948a83E6` | -| Serge Kiema | DuniaPay | `serge_duniapay #5152` | `0xdcac99458a3c5957d8ae7b92e4bafc88a32b80e4` | -| Will Kraft | Celo Governance Working Group | `Will Kraft #2508` | `0x169E992b3c4BE08c42582DAb1DCFb2549d9C23E1` | -| Zviad Metreveli | WOTrust | `zm #1073` | `0xE267D978037B89db06C6a5FcF82fAd8297E290ff` | -| human | OpenCelo | `human #6811` | `0x91f2437f5C8e7A3879e14a75a7C5b4CccC76023a` | -| Deepak Nuli | Kresko | `Deepak \| Kresko#3647` | `0x099f3F5527671594351E30B48ca822cc90778a11` | \ No newline at end of file diff --git a/legacy/protocol/stability/index.mdx b/legacy/protocol/stability/index.mdx deleted file mode 100644 index 90befbd1e..000000000 --- a/legacy/protocol/stability/index.mdx +++ /dev/null @@ -1,36 +0,0 @@ ---- -title: "Stability Mechanism" -sidebarTitle: "Overview" -og:description: Overview of the Celo protocol's Stability Mechanisms. ---- - -import {YouTube} from '/snippets/YouTube.jsx'; -import {ColoredText} from "/snippets/ColoredText.jsx"; - - -Find updated information on Celo's Stability Protocol at [mento.org](https://mento.org). - - - -Overview of the Celo protocol's Stability Mechanisms. - - -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](/build#celo-l2-mainnet). - - ---- - -## Stability of Mento Stablecoin Protocol - - - -The Celo protocol's stability mechanism comprises the following: - -- [Stability Algorithm (Mento)](/legacy/protocol/stability/doto) -- [Granda Mento](/legacy/protocol/stability/granda-mento) -- [Oracles](/legacy/protocol/stability/oracles) -- [Stability Fees](/legacy/protocol/stability/stability-fees) -- [Adding Stable Tokens](/legacy/protocol/stability/adding-stable-assets) \ No newline at end of file diff --git a/legacy/protocol/stability/oracles.mdx b/legacy/protocol/stability/oracles.mdx deleted file mode 100644 index 11bf7b227..000000000 --- a/legacy/protocol/stability/oracles.mdx +++ /dev/null @@ -1,31 +0,0 @@ ---- -title: Oracles -og:description: How the SortedOracles smart contract uses governance to collect reports and maintain the oraclized rate or the Celo dollar. ---- - -How the **SortedOracles** smart contract uses governance to collect reports and maintain the oraclized rate or the Celo dollar. - - -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](/build#celo-l2-mainnet). - - ---- - -## SortedOracles Smart Contract - -As mentioned in the previous section, the stability mechanism needs to know the market price of CELO with respect to the US dollar. This value is made available on-chain in the [SortedOracles smart contract](https://github.com/celo-org/celo-monorepo/blob/master/packages/protocol/contracts/stability/SortedOracles.sol). - -## Collecting Reports - -Through governance, a whitelist of reporters is selected. These addresses are allowed to make reports to the SortedOracles smart contract. The smart contract keeps a list of most recent reports from each reporter. To make it difficult for a dishonest reporter to manipulate the oraclized rate, the official value of the oracle is taken to be the _median_ of this list. - -## Maintaining Oracle Values - -To ensure the oracle's value doesn't go stale due to inactive reporters, any reports that are too old can be removed from the list. "Too old" here is defined based on a protocol parameter that can be modified via governance. - -## Celo-Oracle Repository - -You can find more information about the technical specification of the Celo Oracles feeding data to the reserve in the [GitHub repository here](https://github.com/celo-org/celo-oracle). \ No newline at end of file diff --git a/legacy/protocol/stability/stability-fees.mdx b/legacy/protocol/stability/stability-fees.mdx deleted file mode 100644 index e1e177c90..000000000 --- a/legacy/protocol/stability/stability-fees.mdx +++ /dev/null @@ -1,63 +0,0 @@ ---- -title: "Stability Fees" -sidebarTitle: "Celo Stability Fees" -og:description: Overview of stability fee parameters, timing, frequency, amounts, management, and updates. ---- - -Overview of stability fee parameters, timing, frequency, amounts, management, and updates. - - -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](/build#celo-l2-mainnet). - - ---- - -### Parameters Governing the Stability Fee - -`inflationPeriod` how long to wait between rounds of applying inflation - -`inflationRate` the multiplier by which the inflation factor is adjusted per `inflationPeriod` - -### Timing, Frequency, and Amount of Fee - -The `inflationRate` is the multiplier by which the `inflationFactor` is increased per `inflationPeriod`. It is initially set to `1` which leaves it to governance to enable the stability fee later on. - -Both, the `inflationRate` as well as the `inflationPeriod`, are specified for a given stable token and subject to changes based on governance decisions. - -### Stability Fee Levied on Balance - -Each account’s stable token balance is stored as ‘units’, and `inflationFactor` describes the units/value ratio. The Celo Dollar value of an account can therefore be computed as follows. - -`Account cUSD Value = Account cUSD Units / inflationFactor` - -When a transaction occurs, a modifier checks if the stability fee needs updating and, if so, the `inflationFactor` is updated. - -### Updates to the Inflation Factor - -To apply periodic inflation, the inflation factor must be updated at regular intervals. Every time an event triggering an `inflationFactor` update\(eg a transfer\) occurs, the `updateInflationFactor` modifier is called \(pseudocode below\), which does the following: - -1. Decide if on or more `inflationPeriod` have passed since the last time `inflationFactor` was updated -2. If so, find out how many have passed -3. Compute the new `inflationFactor` and update the last updated time: - -`inflationFactor` = `inflationFactor` \* `inflationRate` ^ `# inflationPeriods since last update` - -### Changes to Inflation Factor - -Desired inflation rates may vary over time. When a new rate needs to be set, a governance proposal is required to update the inflation rate. If successful, the above function is called, which ensures `inflationFactor` is up to date, then updates the `inflationRate` and `inflationPeriod` parameters. - -### Inflation Factor Update Schedule - -The `updateInflationFactor` modifier is called by the following functions: - -- `setInflationParameters` -- `approve` -- `mint` -- `transferWithComment` -- `burn` -- `transferFrom` -- `transfer` -- `debitFrom` \ No newline at end of file diff --git a/legacy/protocol/transaction/erc20-transaction-fees.mdx b/legacy/protocol/transaction/erc20-transaction-fees.mdx deleted file mode 100644 index 1ad6ea3b0..000000000 --- a/legacy/protocol/transaction/erc20-transaction-fees.mdx +++ /dev/null @@ -1,83 +0,0 @@ ---- -title: "Introduction" -sidebarTitle: "Paying for Gas with Tokens" -og:description: How to pay gas fees using allowlisted ERC20 tokens on Celo. ---- - - -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](/build#celo-l2-mainnet). - - -In most L1 and L2 networks, transaction fees can only be paid with one asset, typically, the native asset for the ecosystem which is often volatile in nature. In order to simplify the process of sending funds on Celo, these fees can be paid with allowlisted ERC20 tokens such as USDT, USDC, cUSD, and others, in addition to CELO. This means that a user sending a stablecoin to friends or family will be able to pay the transaction fee out of their stablecoin balance, and will not need to hold a separate CELO balance in order to transact. Critically, Celo supports this functionality natively without Account Abstraction, Pay Masters, or Relay Services. Instead, wallets simply need to add an extra `feeCurrency` field on transaction objects to take advantage of this feature. - -## Fee Currency Field - -The protocol maintains a governable allowlist of smart contract addresses which can be used to pay for transaction fees. These smart contracts implement an extension of the ERC20 interface, with additional functions that allow the protocol to debit and credit transaction fees. When creating a transaction, users can specify the address of the currency they would like to use to pay for gas via the `feeCurrency` field. Leaving this field empty will result in the native currency, CELO, being used. Note that transactions that specify non-CELO gas currencies will cost approximately 50k additional gas. - -## Allowlisted Gas Fee Addresses - -To obtain a list of the gas fee addresses that have been allowlisted using [Celo's Governance Process](/home/protocol/governance/overview), you can run the `getCurrencies` method on the `FeeCurrencyDirectory` contract. All other notable Mainnet core smart contracts are listed [here](/contracts/core-contracts#celo-mainnet). - -### Tokens with Adapters - -After Contract Release 11, addresses in the allowlist are no longer guaranteed to be full ERC20 tokens and can now also be [adapters](https://github.com/celo-org/celo-monorepo/blob/release/core-contracts/11/packages/protocol/contracts-0.8/stability/FeeCurrencyAdapter.sol). Adapters are allowlisted in-lieu of tokens in the scenario that a ERC20 token has decimals other than 18 (e.g. USDT and USDC). - -The Celo Blockchain natively works with 18 decimals when calculating gas pricing, so adapters are needed to normalize the decimals for tokens that use a different one. Some stablecoins use 6 decimals as a standard. - -Transactions with those ERC20 tokens are performed as usual (using the token address), but when paying gas currency with those ERC20 tokens, the adapter address should be used. This adapter address is also the one that should be used when querying [Gas Price Minimum](/legacy/protocol/transaction/gas-pricing). - -Adapters can also be used to query `balanceOf(address)` of an account, but it will return the balance as if the token had 18 decimals and not the native ones. This is useful to calculate if an account has enough balance to cover gas after multiplying `gasPrice * estimatedGas` without having to convert back to the token's native decimals. - -#### Adapters by network - -##### Mainnet - -| Name | Token | Adapter | -| ------ | --------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | -| `USDC` | [`0xcebA9300f2b948710d2653dD7B07f33A8B32118C`](https://celoscan.io/address/0xcebA9300f2b948710d2653dD7B07f33A8B32118C#code) | [`0x2F25deB3848C207fc8E0c34035B3Ba7fC157602B`](https://celoscan.io/address/0x2F25deB3848C207fc8E0c34035B3Ba7fC157602B#code) | -| `USDT` | [`0x48065fbbe25f71c9282ddf5e1cd6d6a887483d5e`](https://celoscan.io/address/0x48065fbbe25f71c9282ddf5e1cd6d6a887483d5e#code) | [`0x0e2a3e05bc9a16f5292a6170456a710cb89c6f72`](https://celoscan.io/address/0x0e2a3e05bc9a16f5292a6170456a710cb89c6f72#code) | - -##### Alfajores (testnet) - -| Name | Token | Adapter | -| ------ | ------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | -| `USDC` | [`0x2F25deB3848C207fc8E0c34035B3Ba7fC157602B`](https://alfajores.celoscan.io/address/0x2f25deb3848c207fc8e0c34035b3ba7fc157602b#code) | [`0x4822e58de6f5e485eF90df51C41CE01721331dC0`](https://alfajores.celoscan.io/address/0x4822e58de6f5e485eF90df51C41CE01721331dC0#code) | - -##### Baklava (testnet) - -N/A - -### Enabling Transactions with ERC20 Token as fee currency in a wallet - -We recommend using the [viem](https://viem.sh/) library as it has support for the `feeCurrency` field in the transaction required for sending transactions where the gas fees will be paid in ERC20 tokens. Ethers.js and web.js currently don't support `feeCurrency`. - -#### Estimating gas price - -To estimate gas price use the token address (in case of cUSD, cEUR and cREAL) or the adapter address (in case of USDC and USDT) as the value for `feeCurrency` field in the transaction. - - -The Gas Price Minimum value returned from the RPC has to be interpreted in 18 decimals. - - -#### Preparing a transaction - -When preparing a transaction that uses ERC20 token for gas fees, use the token address (in case of cUSD, cEUR and cREAL) or the adapter address (in case of USDC and USDT) as the value for `feeCurrency` field in the transaction. - -The recommended transaction `type` is `123`, which is a CIP-64 compliant transaction read more about it [here](/legacy/protocol/transaction/transaction-types). - -Here is how a transaction would look like when using USDC as a medium to pay for gas fees. - -```js -let tx = { - // ... other transaction fields - feeCurrency: "0x2f25deb3848c207fc8e0c34035b3ba7fc157602b", // USDC Adapter address - type: "0x7b", -}; -``` - - -To get details about the underlying token of the adapter you can call `adaptedToken` function on the adapter address, which will return the underlying token address. - \ No newline at end of file diff --git a/legacy/protocol/transaction/escrow.mdx b/legacy/protocol/transaction/escrow.mdx deleted file mode 100644 index fad617745..000000000 --- a/legacy/protocol/transaction/escrow.mdx +++ /dev/null @@ -1,32 +0,0 @@ ---- -title: "Escrow (Celo L1)" -sidebarTitle: "Celo's Escrow Contract" -og:description: Introduction to the Celo Escrow contract and how to use it to withdraw, revoke, and reclaim funds. ---- - -Introduction to the Celo Escrow contract and how to use it to withdraw, revoke, and reclaim funds. - - -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](/build#celo-l2-mainnet). - - ---- - -## What is the Escrow Contract? - -The `Escrow` contract utilizes Celo’s Lightweight identity feature to allow users to _send payments to other users who don’t yet have a public/private key pair or an address_. These payments are stored in this contract itself and can be either withdrawn by the intended recipient or reclaimed by the sender. This functionality supports _both_ versions of Celo’s lightweight identity: identifier-based \(such as a phone number to address mapping\) and privacy-based. This gives applications that intend to use this contract some flexibility in deciding which version of identity they prefer to use. - -## How it works - -If Alice wants to send a payment to Bob, who doesn’t yet have an associated address, she will send that payment to this `Escrow` contract and will also create a temporary public/private key pair. The associated temporary address will be referred to as the `paymentId`. Alice will then externally share the newly created temporary private key, also known as an _invitation_, to Bob, who will later use it to claim the payment. This paymentId will now be stored in this contract and will be mapped to relevant details related to this specific payment such as: the value of the payment, an optional identifier of the intended recipient, an optional amount of `attestations` the recipient must have before being able to withdraw the payment, an amount of time after which the sender can revoke the payment \(via the `expirySeconds` field - more on that in the “withdrawing” section below\), which asset is being transferred in this payment, etc. - -## Withdrawing - -The recipient of an escrowed payment can choose to withdraw their payment assuming they have successfully created their own public/private key pair and now have an address. To prove their identity, the recipient must be able to prove ownership of the paymentId’s private key, which should have been given to them by the original sender. If the sender set a minimum number of attestations required to withdraw the payment, that will also be checked in order to successfully withdraw. Following the same example as above, if Bob wants to withdraw the payment Alice sent him, he must sign a message with the private key given to him by Alice. The message will be the address of Bob’s newly created account. Bob will then be able to withdraw his payment by providing the paymentId and the v, r, and s outputs of the generated ECDSA signature. An escrowed payment may have `expirySeconds` set, which references the amount of time that must pass before the sender can revoke the payment. Note that after `expirySeconds` have passed, the payment recipient may _still withdraw the payment as long as it has not already been revoked_. - -## Revoking & Reclaiming - -Alice sends Bob an escrowed payment. Let’s say Bob never withdraws it, or worse, the temporary private key he needs to withdraw the payment gets lost or sent to the wrong person. For this purpose, Celo’s protocol also allows for senders to reclaim any unclaimed escrowed payment that they sent. After an escrowed payment's `expirySeconds` \(set by the sender on creation of the payment\) has passed, the sender of the payment can revoke the payment and reclaim their funds with just the paymentId. \ No newline at end of file diff --git a/legacy/protocol/transaction/gas-pricing.mdx b/legacy/protocol/transaction/gas-pricing.mdx deleted file mode 100644 index 48812b10e..000000000 --- a/legacy/protocol/transaction/gas-pricing.mdx +++ /dev/null @@ -1,42 +0,0 @@ ---- -title: "Gas Pricing" -sidebarTitle: "Celo Gas Pricing" -og:description: Introduction to gas prices, calculations, transactions, and fees on the Celo network. ---- - -Introduction to gas prices, calculations, transactions, and fees on the Celo network. - - -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](/build#celo-l2-mainnet). - - ---- - -## Gas Price Minimum - -Celo uses a gas market based on [EIP-1559](https://eips.ethereum.org/EIPS/eip-1559). The protocol establishes a **gas price minimum** that applies to all transactions regardless of which validator processes them. - -The gas price minimum will respond to demand, increasing during periods of sustained demand, but allowing temporary spikes in gas demand without price shocks. The Celo protocol aims to have blocks filled at the `target_density`, a certain proportion of the total block gas limit. When blocks are being filled more than the target, the gas price minimum will be raised until demand subsides. If blocks are being filled at less than the target rate, the gas price minimum will decrease until demand rises. - -## Calculating Gas Price - -In the Celo protocol, the gas price minimum for the next block is calculated based on the current block: - -``` -gas_price_minimum' = gas_price_minimum * (1 + ((total_gas_used / block_gas_limit) − target_density) * adjustment_speed) + 1 -``` - -Every transaction is required to pay for gas at or above the gas price minimum in order to be processed. Full nodes will reject transactions whose gas price is below the current gas price minimum, and will discard outstanding transactions if the gas price minimum subsequently falls below the gas price that the transactions specify. - -## Selecting a Transaction Gas Price - -This approach provides a simple mechanism for clients to determine what gas price they should pay. A `GasPriceMinimum` smart contract provides access to the current gas price minimum. For example, with the parameters specified for the Celo testnets, a gas price of 3x the current gas price minimum will be valid in all scenarios for the following 30 seconds. - -When the client wants to ensure that their transaction is processed quickly, they may wish to further increase the gas price to encourage validators proposing new blocks to include it in preference to other transactions. - -## Transaction Fee Recipients - -The required portion of gas fee, known as the **base**, is set as `base = gas_price_minimum * gas_used` and is sent to the Gas Fee Handler smart contract, which is controlled by governance and handles how the fees are used (e.g., for carbon removal and burning). The rest of the gas fee, known as the **tip**, is rewarded to the validator that proposes the block. Block producers only receive the tip and not the base of the gas fee, which means that they do not have an incentive to artificially inflate the gas price minimum by flooding the network with transactions. \ No newline at end of file diff --git a/legacy/protocol/transaction/index.mdx b/legacy/protocol/transaction/index.mdx deleted file mode 100644 index 12231ce31..000000000 --- a/legacy/protocol/transaction/index.mdx +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: "Transactions" -sidebarTitle: "Overview" -og:description: Introduction to Celo transactions and gas prices. ---- - -Introduction to Celo transactions and gas prices. - - -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](/build#celo-l2-mainnet). - - ---- - -## Celo vs Ethereum Transactions - -Transactions in the Celo protocol include payments, contract calls, and other operation which modifies state. They are similar to Ethereum transaction with the following key differences. - -- Gas prices must meet or exceed the [gas price minimum](/legacy/protocol/transaction/gas-pricing). -- Gas fees may be paid in currencies other than the native CELO. \ No newline at end of file diff --git a/legacy/protocol/transaction/native-currency.mdx b/legacy/protocol/transaction/native-currency.mdx deleted file mode 100644 index c1c15aa60..000000000 --- a/legacy/protocol/transaction/native-currency.mdx +++ /dev/null @@ -1,26 +0,0 @@ ---- -title: "Native Currency" -sidebarTitle: "Celo Native Currency" -og:description: Introduction to CELO and its compliance to the ERC20 standard. ---- - -Introduction to CELO and its compliance to the ERC20 standard. - - -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](/build#celo-l2-mainnet). - - ---- - -## What is CELO? - -The native currency in the Celo protocol, CELO, conforms to the ERC20 interface. This is made possible by way of a permissioned “Transfer” precompile, which only the CELO ERC20 smart contract can call. The address of the contract exposing this interface can be looked up via the Registry smart contract, and has the “GoldToken” identifier. - - -**note** - -As the native currency of the protocol, CELO, much like Ether, can still be sent directly via transactions by specifying a non-zero “value”, bypassing the ERC20 interface. - \ No newline at end of file diff --git a/legacy/protocol/transaction/transaction-types.mdx b/legacy/protocol/transaction/transaction-types.mdx deleted file mode 100644 index 43415172b..000000000 --- a/legacy/protocol/transaction/transaction-types.mdx +++ /dev/null @@ -1,471 +0,0 @@ ---- -title: Transaction types on Celo -og:description: This page contains an explainer on transaction types supported on Celo and a demo to make specific transactions. ---- - -import {InlineImage} from "/snippets/InlineImage.mdx"; - -This page contains an explainer on transaction types supported on Celo and a demo to make specific transactions. - - -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](/build#celo-l2-mainnet). - - -> **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](https://github.com/celo-org/celo-proposals/blob/master/CIPs/cip-0064.md) | ✅ | Active 🟢 | Supports paying gas in custom fee currencies | -| | 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 | -| | 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 | -| | 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 deprecation on Celo - -| Chain | Transaction type | # | Specification | Recommended | Support | Comment | -| ------------------------------------------------------------------- | ----------------------- | ----- | -------------------------------------------------------------------------------------------------------------- | ----------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| | Dynamic fee transaction | `124` | [CIP-42](https://github.com/celo-org/celo-proposals/blob/master/CIPs/cip-0042.md) | ❌ | Security 🟠 | Deprecation warning published in [Gingerbread hard fork](https://github.com/celo-org/celo-proposals/blob/8260b49b2ec9a87ded6727fec7d9104586eb0752/CIPs/cip-0062.md#deprecation-warning) | -| | Legacy transaction | `0` | Celo Mainnet launch ([Blockchain client v1.0.0](https://github.com/celo-org/celo-blockchain/tree/celo-v1.0.0)) | ❌ | Security 🟠 | Deprecation warning published in [Gingerbread hard fork](https://github.com/celo-org/celo-proposals/blob/8260b49b2ec9a87ded6727fec7d9104586eb0752/CIPs/cip-0062.md#deprecation-warning) | - -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][1] | --- | -| `ethers` | TS/JS | ✅ | | ❌ | | Support via fork in
`celo-ethers-wrapper` | -| `celo-ethers-wrapper` | TS/JS | ✅ | | ✅ | >[2.0.0](https://github.com/jmrossy/celo-ethers-wrapper/releases/tag/2.0.0) | --- | -| `web3js` | TS/JS | ✅ | | ❌ | | Support via fork in
`contractkit` | -| `contractkit` | TS/JS | ✅ | | ✅ | >[5.0.0](https://github.com/celo-org/celo-monorepo/releases/tag/v5.0) | --- | -| `Web3j` | Java | ✅ | | ❌ | | --- | -| `rust-ethers` | Rust | ✅ | | ❌ | | --- | -| `brownie` | Python | ✅ | | ❌ | | --- | - -[1]: https://github.com/wevm/viem/blob/main/src/CHANGELOG.md#1195 - -## 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](https://eth.wiki/fundamentals/rlp): - - ``` - RLP([nonce, gasprice, gaslimit, recipient, amount, data, chaindId, 0, 0]) - ``` - -1. the RLP-encoded transaction is hashed (using Keccak256). - -1. the hash is signed with a private key using the ECDSA algorithm, which generates the `v`, `r`, - and `s` **signature parameters**. - -1. 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](https://eips.ethereum.org/EIPS/eip-1559)) -or optional access list transactions -([EIP-2930: Optional access lists](https://eips.ethereum.org/EIPS/eip-2930)) -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](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 - -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](https://en.wikipedia.org/wiki/Ethereum) - as specified in the [Ethereum Yellow Paper](https://ethereum.github.io/yellowpaper/paper.pdf). - -- It was introduced on Celo during the - [Celo Donut hard fork](https://github.com/celo-org/celo-proposals/blob/master/CIPs/cip-0027.md) - 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). - -### 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](https://ethereum.org/en/history/#berlin) as specified in - [EIP-2930: Optional access lists](https://eips.ethereum.org/EIPS/eip-2930). - -- It was introduced on Celo during the - [Celo Donut hard fork](https://github.com/celo-org/celo-proposals/blob/master/CIPs/cip-0027.md) - 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). - -### 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](https://ethereum.org/en/history/#london) as specified in - [EIP-1559: Fee market change for ETH 1.0 chain](https://eips.ethereum.org/EIPS/eip-1559). - -- It was introduced on Celo during the - [Celo Espresso hard fork](https://github.com/celo-org/celo-proposals/blob/master/CIPs/cip-0041.md) - 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) - -### 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](https://github.com/celo-org/celo-proposals/blob/8260b49b2ec9a87ded6727fec7d9104586eb0752/CIPs/cip-0062.md#deprecation-warning) -> on [Sep 26, 2023](https://forum.celo.org/t/mainnet-alfajores-gingerbread-hard-fork-release-sep-26-17-00-utc/6499). - -- 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](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). - -### 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](https://github.com/celo-org/celo-proposals/blob/8260b49b2ec9a87ded6727fec7d9104586eb0752/CIPs/cip-0062.md#deprecation-warning) -> on [Sep 26, 2023](https://forum.celo.org/t/mainnet-alfajores-gingerbread-hard-fork-release-sep-26-17-00-utc/6499). - -- 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](https://github.com/celo-org/celo-proposals/blob/master/CIPs/cip-0041.md) - 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). - -### 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](https://github.com/celo-org/celo-proposals/blob/8260b49b2ec9a87ded6727fec7d9104586eb0752/CIPs/cip-0062.md) - on [Sep 26, 2023](https://forum.celo.org/t/mainnet-alfajores-gingerbread-hard-fork-release-sep-26-17-00-utc/6499) - as specified in - [CIP-64: New Transaction Type: Celo Dynamic Fee v2](https://github.com/celo-org/celo-proposals/blob/master/CIPs/cip-0064.md) - -## How to Send Transactions - -### Import Dependencies - - - - - -```ts -import { - createPublicClient, - createWalletClient, - hexToBigInt, - http, - parseEther, - parseGwei, -} from "viem"; -import { privateKeyToAccount } from "viem/accounts"; -import { celoAlfajores } from "viem/chains"; -import "dotenv/config"; // use to read private key from environment variable -``` - - - - - -### Create Public and Wallet Client - - - - - -```ts -const PRIVATE_KEY = process.env.PRIVATE_KEY; - -/** - * Boilerplate to create a viem client - */ -const account = privateKeyToAccount(`0x${PRIVATE_KEY}`); -const publicClient = createPublicClient({ - chain: celoAlfajores, - transport: http(), -}); -const walletClient = createWalletClient({ - chain: celoAlfajores, // Celo testnet - transport: http(), -}); -``` - - - - - -### Function to print Transaction receipt - - - - - - ```ts - function printFormattedTransactionReceipt(transactionReceipt: any) { - - const { - blockHash, - blockNumber, - contractAddress, - cumulativeGasUsed, - effectiveGasPrice, - from, - gasUsed, - logs, - logsBloom, - status, - to, - transactionHash, - transactionIndex, - type, - feeCurrency, - gatewayFee, - gatewayFeeRecipient - } = transactionReceipt; - - const filteredTransactionReceipt = { - type, - status, - transactionHash, - from, - to - }; - - console.log(`Transaction details:`, filteredTransactionReceipt, `\n`); - } - ``` - - - - - -### Code to send Transaction Type (0) - - - - - - ```ts - /** - - Transation type: 0 (0x00) - - Name: "Legacy" - - Description: Ethereum legacy transaction - */ - async function demoLegacyTransactionType() { - console.log(`Initiating legacy transaction...`); - const transactionHash = await walletClient.sendTransaction({ - account, // Sender - to: "0x70997970c51812dc3a010c7d01b50e0d17dc79c8", // Recipient (illustrative address) - value: parseEther("0.01"), // 0.01 CELO - gasPrice: parseGwei("20"), // Special field for legacy transaction type - }); - - const transactionReceipt = await publicClient.waitForTransactionReceipt({ - hash: await transactionHash, - }); - - printFormattedTransactionReceipt(transactionReceipt); - } - ``` - - - - - -### Code to send Transaction Type (2) - - - - - - ```ts - /** - * Transaction type: 2 (0x02) - * Name: "Dynamic fee" - * Description: Ethereum EIP-1559 transaction - */ - async function demoDynamicFeeTransactionType() { - console.log(`Initiating dynamic fee (EIP-1559) transaction...`); - const transactionHash = await walletClient.sendTransaction({ - account, // Sender - to: "0x70997970c51812dc3a010c7d01b50e0d17dc79c8", // Recipient (illustrative address) - value: parseEther("0.01"), // 0.01 CELO - maxFeePerGas: parseGwei("10"), // Special field for dynamic fee transaction type (EIP-1559) - maxPriorityFeePerGas: parseGwei("10"), // Special field for dynamic fee transaction type (EIP-1559) - }); - - const transactionReceipt = await publicClient.waitForTransactionReceipt({ - hash: await transactionHash, - }); - - printFormattedTransactionReceipt(transactionReceipt); - } - ``` - - - - - -### Code to send Transaction Type (123) - - - - - - ```ts - /** - * Transaction type: 123 (0x7b) - * Name: "Dynamic fee" - * Description: Celo dynamic fee transaction (with custom fee currency) - */ - async function demoFeeCurrencyTransactionType() { - console.log(`Initiating custom fee currency transaction...`); - const transactionHash = await walletClient.sendTransaction({ - account, // Sender - to: "0x70997970c51812dc3a010c7d01b50e0d17dc79c8", // Recipient (illustrative address) - value: parseEther("0.01"), // 0.01 CELO - feeCurrency: "0x874069Fa1Eb16D44d622F2e0Ca25eeA172369bC1", // cUSD fee currency - maxFeePerGas: parseGwei("10"), // Special field for dynamic fee transaction type (EIP-1559) - maxPriorityFeePerGas: parseGwei("10"), // Special field for dynamic fee transaction type (EIP-1559) - }); - - const transactionReceipt = await publicClient.waitForTransactionReceipt({ - hash: await transactionHash, - }); - - printFormattedTransactionReceipt(transactionReceipt); - } - ``` - - - - diff --git a/legacy/protocol/transaction/tx-comment-encryption.mdx b/legacy/protocol/transaction/tx-comment-encryption.mdx deleted file mode 100644 index 72029c28c..000000000 --- a/legacy/protocol/transaction/tx-comment-encryption.mdx +++ /dev/null @@ -1,45 +0,0 @@ ---- -title: "Encrypted Payment Comments (Celo L1)" -sidebarTitle: "Celo Encrypted Payment Comments" -og:description: Overview of encrypted payment comments and its technical details related to symmetric and asymmetric encryption. ---- - -Overview of encrypted payment comments and its technical details related to symmetric and asymmetric encryption. - - -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](/build#celo-l2-mainnet). - - ---- - -### 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 - -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\) - -- 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\) - -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\). \ No newline at end of file diff --git a/legacy/transition/guides/bridging-celo-from-l1-to-l2.mdx b/legacy/transition/guides/bridging-celo-from-l1-to-l2.mdx deleted file mode 100644 index 828a645e3..000000000 --- a/legacy/transition/guides/bridging-celo-from-l1-to-l2.mdx +++ /dev/null @@ -1,144 +0,0 @@ ---- -title: Bridging CELO from L1 to L2 -og:description: Programmatically bridge CELO from Sepolia to Celo Sepolia using the viem OP Stack ---- - -In this guide, you'll learn how to programmatically bridge CELO from Sepolia to Celo Sepolia using the [viem OP Stack](https://viem.sh/op-stack). - -## Steps to Bridge CELO - -Before transferring tokens, you must authorize the `OptimismPortalProxy` contract to spend CELO on your behalf. Without this approval, the bridging transaction cannot proceed. - -Call the [`depositERC20Transaction`](https://viem.sh/op-stack/actions/depositTransaction#deposittransaction) function on the `OptimismPortalProxy` contract on Sepolia. This function moves CELO tokens from your account to the Celo Sepolia. - -## Code Example -The following example demonstrates how to configure a file with all the details you need for interacting with the Celo Sepolia. - - - - - ```js index.js - import { createWalletClient, createPublicClient, http, parseEther } from "viem"; - import { privateKeyToAccount } from "viem/accounts"; - import { celoSepolia, sepolia } from "viem/chains"; - import { getL2TransactionHashes, publicActionsL2 } from "viem/op-stack"; - - const CELOL1 = "0xDEd08f6Ec0A57cE6Be62d1876d2CE92AF37eddA0"; - - // https://docs.celo.org/cel2/contract-addresses - const OptimismPortalProxy = "0xB29597c6866c6C2870348f1035335B75eEf79d07"; - - const account = privateKeyToAccount( - "...", - ); - - export const walletClientL1 = createWalletClient({ - account, - chain: sepolia, - transport: http(), - }); - - export const publicClientL1 = createPublicClient({ - account, - chain: sepolia, - transport: http(), - }); - - export const publicClientL2 = createPublicClient({ - chain: celoSepolia, - transport: http(), - }).extend(publicActionsL2()); - - async function main() { - // Approve OptimismPortal to pull CELO on Sepolia - const approve = await walletClientL1.writeContract({ - address: CELOL1, - abi: [ - { - inputs: [ - { name: "spender", type: "address" }, - { name: "amount", type: "uint256" }, - ], - name: "approve", - type: "function", - }, - ], - functionName: "approve", - args: [OptimismPortalProxy, parseEther("0.0001")], - }); - - console.log(`Approval TX Hash: ${approve}`); - - let approveReceipt = await publicClientL1.waitForTransactionReceipt({ - hash: approve, - }); - console.log(`Approve Transaction Receipt: ${approveReceipt}`); - - // Call depositERC20Transaction on OptimismPortal - const deposit = await walletClientL1.writeContract({ - address: OptimismPortalProxy, - abi: [ - { - inputs: [ - { - name: "_to", - type: "address", - }, - { - name: "mint", - type: "uint256", - }, - { - name: "_value", - type: "uint256", - }, - { - name: "_gasLimit", - type: "uint64", - }, - { - name: "_isCreation", - type: "bool", - }, - { - name: "_data", - type: "bytes", - }, - ], - name: "depositERC20Transaction", - type: "function", - }, - ], - functionName: "depositERC20Transaction", - args: [ - account.address, // Account where you want to receive CELO on L2 - parseEther("0.0001"), // Amount you are transferring to the Portal - parseEther("0.0001"), // Amount you want on L2 - 100_000, // Amount of L2 gas to purchase by burning gas on L1. - false, // Whether the transaction is a contract creation - "", // Data to trigger the recipient with - ], - }); - - console.log(`Deposit Transaction: ${deposit}`); - - - let depositReceipt = await publicClientL1.waitForTransactionReceipt({ - hash: deposit, - }); - console.log(`Deposit Transaction Receipt: ${depositReceipt}`); - - // Get the L2 transaction hash from the L1 transaction receipt. - const [l2Hash] = getL2TransactionHashes(depositReceipt); - - // Wait for the L2 transaction to be processed. - const l2Receipt = await publicClientL2.waitForTransactionReceipt({ - hash: l2Hash, - }); - - console.log(`L2Receipt: ${l2Receipt}`); - } - - main(); - ``` - diff --git a/legacy/transition/guides/withdrawing-celo-from-l2-to-l1.mdx b/legacy/transition/guides/withdrawing-celo-from-l2-to-l1.mdx deleted file mode 100644 index 362b1231f..000000000 --- a/legacy/transition/guides/withdrawing-celo-from-l2-to-l1.mdx +++ /dev/null @@ -1,145 +0,0 @@ ---- -title: Withdrawing CELO from L2 to L1 -og:description: Programmatically withdraw CELO from Celo Sepolia back to Sepolia using the viem OP Stack ---- - -In this tutorial, you will learn how to programmatically withdraw CELO from Celo Sepolia to Sepolia using the [viem OP Stack](https://viem.sh/op-stack). - -## Steps to Withdraw CELO - -Withdrawals require the user to submit three transactions: - -1. [Withdrawal initiating a transaction](https://viem.sh/op-stack/actions/initiateWithdrawal), which the user submits on L2. -2. [Withdrawal proving transaction](https://viem.sh/op-stack/actions/proveWithdrawal), which the user submits on L1 to prove that the withdrawal is legitimate. -3. [Withdrawal finalizing transaction](https://viem.sh/op-stack/actions/finalizeWithdrawal), which the user submits on L1 after the fault challenge period has passed, to actually run the transaction on L1. - -## Code Example - -The following example demonstrates how to configure a file with all the details you need for interacting with the Celo Sepolia. - - - ```js index.js - import { - createPublicClient, - createWalletClient, - http, - parseEther, - } from "viem"; - import { privateKeyToAccount } from "viem/accounts"; - import { celoSepolia, sepolia } from "viem/chains"; - import { - publicActionsL1, - walletActionsL2, - walletActionsL1, - publicActionsL2, - } from "viem/op-stack"; - - const account = privateKeyToAccount( - "[PRIVATE_KEY]", - ); - - const value = parseEther("0.0001"); // Amount to Withdraw - - export const publicClientL1 = createPublicClient({ - chain: sepolia, - transport: http(), - }).extend(publicActionsL1()); - - export const publicClientL2 = createPublicClient({ - chain: celoSepolia, - transport: http(), - }).extend(publicActionsL2()); - - export const walletClientL1 = createWalletClient({ - chain: sepolia, - transport: http(), - account, - }).extend(walletActionsL1()); - - export const walletClientL2 = createWalletClient({ - chain: celoSepolia, - transport: http(), - account, - }).extend(walletActionsL2()); - - export default async function main() { - console.log("Building Initiate Withdrawal..."); - const args = await publicClientL1.buildInitiateWithdrawal({ - account, - to: account.address, // Receive on the same address on L1. - value, - }); - - console.log("Initiaiting Withdrawal..."); - const hash = await walletClientL2.initiateWithdrawal(args); - - const initiateWithdrawalReceipt = await publicClientL2.waitForTransactionReceipt({ - hash - }); - console.log(`Withdrawal Initiated: ${initiateWithdrawalReceipt}`); - - /** - * The below step can take upto 2 hours! - * - * Hence, you may want to use viem's `getTimeToProve`. - * - * https://viem.sh/op-stack/actions/getTimeToProve - * - * Store the wait time in a database - * and let the user know to come back later. - * - * */ - console.log("Waiting to prove..."); - const { output, withdrawal } = await publicClientL1.waitToProve({ - receipt: initiateWithdrawalReceipt, - targetChain: walletClientL2.chain, - }); - - console.log("Building Prove Withdrawal..."); - const proveArgs = await publicClientL2.buildProveWithdrawal({ - output, - withdrawal, - }); - - console.log("Proving Withdrawal..."); - const proveHash = await walletClientL1.proveWithdrawal(proveArgs); - - const proveReceipt = await publicClientL1.waitForTransactionReceipt({ - hash: proveHash, - }); - console.log(`Withdrawal Proved: ${proveReceipt}`); - - /** - * The below step can take a few minutes, ideally 2 minutes. - * - * Hence, you may want to use viem's `getTimeToFinalize`. - * - * https://viem.sh/op-stack/actions/getTimeToFinalize - * - * Store the wait time in a database - * and let the user know to come back later. - * - * - */ - console.log("Waiting To Finalize..."); - await publicClientL1.waitToFinalize({ - targetChain: walletClientL2.chain, - withdrawalHash: withdrawal.withdrawalHash, - }); - - console.log("Finalizing Withdrawal..."); - const finalizeWithdrawalHash = await walletClientL1.finalizeWithdrawal({ - targetChain: walletClientL2.chain, - withdrawal, - }); - - const finalizeWithdrawalReceipt = await publicClientL1.waitForTransactionReceipt({ - hash: finalizeWithdrawalHash, - }); - console.log(`Withdrawal Finalized: ${finalizeWithdrawalReceipt}`) - } - - - ``` - - diff --git a/legacy/transition/optimism/op-l2.mdx b/legacy/transition/optimism/op-l2.mdx deleted file mode 100644 index 0ac1df9bc..000000000 --- a/legacy/transition/optimism/op-l2.mdx +++ /dev/null @@ -1,47 +0,0 @@ ---- -title: "Optimism → Celo L2" -og:description: How the Celo L2 differs from a stock Optimism OP Stack chain ---- - -## Blocks - -Celo L2 block times are 1s as opposed to 2s for Optimism. The gas limit per block remains the same. - -## Native token - -The native token is CELO as opposed to ETH. The native token is also an ERC20 token. - -## New transaction type - -Type 123 (`0x7b`) transaction type allows paying for gas in currencies other than the native asset (CELO). It has an additional field `feeCurrency` which allows the sender to choose the gas currency. See [here](/specs/fee-abstraction) for details on using fee currencies. - -The fee currencies available at Mainnet launch will be: - - - USDC (USDC) - - Tether USD (USD₮) - - PUSO (PUSO) - - ECO CFA (eXOF) - - Celo Kenyan Shilling (cKES) - - Celo Dollar (cUSD) - - Celo Euro (cEUR) - - Celo Brazilian Real (cREAL) - -More details on supported transaction types [here](/specs/transaction-types). - -## L1 fees - -In the Optimism model, an extra fee is added in order to cover the cost of transactions on the L1. This can be surprising to users as it is not included in the results of calling `eth_estimateGas` and is challenging to predict. - -The Celo L2 improves upon this experience by always keeping the L1 fee at zero. The L1 costs are covered by raising or lowering the [base fee floor](#eip-1559-implementation). This approach allows the full transaction cost to be estimated ahead of time. - -## EIP-1559 implementation - -The Celo L2 adds a base fee floor, which imposes a lower limit on the base fee. This is currently configured via the chain config. The **starting base fee floor** values are currently **25 gwei** for Celo Sepolia Testnet. - -## MaxCodeSize - -The hardcoded protocol parameter `MaxCodeSize` is raised from 24576 to 65536. - -## Improved finality guarantees - -Celo L2 blocks reference L1 blocks that are finalized, which fully protects against L1 re-orgs. In contrast, Optimism blocks reference only 4 blocks behind the L1 head. diff --git a/legacy/transition/whats-changed/l1-l2.mdx b/legacy/transition/whats-changed/l1-l2.mdx deleted file mode 100644 index f9b230ff2..000000000 --- a/legacy/transition/whats-changed/l1-l2.mdx +++ /dev/null @@ -1,102 +0,0 @@ ---- -title: "Celo L1 → L2" -og:description: What changed for node operators, developers, and users in the move from Celo L1 to Celo L2 ---- - -## Node operators - -In the Celo L1 node, operators simply needed to run the celo-blockchain client, a single service that was a fork of go-ethereum. Moving to the Celo L2 node operators need to run an op-geth instance for execution, an op-node instance for consensus and an eigenda-proxy for data availability. Instructions on operating nodes are [here](/infra-partners/operators/overview). - -## Deprecated transaction types - -Sending these transaction types is no longer be supported, however you can still retrieve any historical instances of these transactions. - -- **Type 0 (`0x0`) _Celo_ legacy transaction**. These are type 0 transactions that had some combination of the following fields set ("feeCurrency", "gatewayFee", "gatewayFeeRecipient") and "ethCompatible" set to false. -- **Type 124 (`0x7c`) Celo dynamic fee transaction**. - -More details on supported transaction types [here](/specs/transaction-types). - -## Native bridge to Ethereum - -An important benefit of becoming an L2 is having a native bridge to Ethereum. -CELO is now an ERC20 token native on Ethereum and users will be able to use the native bridge to move between the Celo L2 and Ethereum. -The Celo Mainnet bridge can be accessed at [Superbridge](https://superbridge.app/celo). - -## Consensus - -The BFT consensus protocol has been removed and replaced with a centralized sequencer. Although validators are no longer needed to secure consensus, the election / voting mechanism and validator set will remain for the time being. - -This is a temporary situation, and we will be working on re-introducing active roles for validators after Mainnet launch. For now, validators will serve as community rpc providers and do not need to run any special L2 infrastructure beyond full nodes. - -## Validator fees and staking rewards - -After the L2 transition, transaction fees will go to the sequencer but validators and stakers will still receive some rewards. Previously, rewards were emitted on epoch blocks but as Celo L2 does not have epoch blocks, rewards will be distributed through periodic calls to a smart contract. -The amount of rewards to be distributed has not been decided. However, rewards will likely be lower than in the Celo L1 to reflect lower infrasture requirements. - -## Hardforks - -See [here](/specs/l2-migration#changes-for-contracts-developers) for the list of hardforks that will be enabled in the first block of the L2. - -## Precompiled contracts - -All Celo specific precompiles have been removed except for the transfer precompile which supports Celo [token duality](/specs/token-duality) (the native asset CELO is also an ERC20 token) - -## Randomness - -The random contract has been removed. If randomness is needed then the PREVRANDAO opcode can be used. See [here](/specs/l2-migration#deactivated-random-contract) for more details. - -## Blocks - -- Block interval has changed from 5s to 1s -- Block gas limit has changed from 50m to 30m - - -Note this results in a 300% increase in gas per second due to the shortened block time - - -### Added fields - -- **withdrawals** & **withdrawalsRoot** - These fields are inherited from Ethereum but not used by the op-stack or Celo. Withdrawals will always be an empty list and `withdrawalsRoot` will always be the empty withdrawals root (`0x56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421`). -- **blobGasUsed** & **excessBlobGas** - These fields are also inherited from Ethereum but not used by the op-stack or Celo. They will always be zero. -- **parentBeaconBlockRoot** - Set to the `parentBeaconRoot` of the L1 origin block. - -### Removed fields - -- **randomness** - Not needed since the [randomness](#randomness) feature has been removed -- **epochSnarkData** - Not needed since the Celo L2 does not support Plumo. -- **extraData** - The BLS aggregated signature has been removed as it is no longer required. - -## EIP-1559 implementation - -Previously our implementation used a smart contract [(here)](https://github.com/celo-org/celo-monorepo/blob/faca88f6a48cc7c8e6104393e49ddf7c2d7d20e3/packages/protocol/contracts-0.8/common/GasPriceMinimum.sol#L162) to calculate the base fee which allowed for governable parameters. Now we use the standard EIP1559 algorithm with the parameter values being defined in the chain config. - -For chain specific parameters see the [deployment information in the Celo specs](/specs/deployments). - -## RPC API - -### Pre-transition data - -Old blocks, transactions, receipts and logs are still be accessible via the RPC API but differ a bit from the corresponding objects retrieved from the L1 RPC API. - -In general the changes involve additional extra unset fields that have been added upstream but were not present on historical Celo L1 objects, and the removal of some unnecessarily set fields on Celo L1 objects. - -For in depth details of what has changed see [here](/specs/l2-migration). - -### Block receipts - -Historically, the Celo L1 generated block receipts when system contract calls emitted logs. The Celo L2 does not have block receipts, but pre-migration block receipts are still retrievable via the RPC API `eth_getBlockReceipt` method. - -### Pre-transition execution and state access - -RPC API calls for pre-transition blocks that are performing execution or accessing state are not directly supported by the new Celo L2 implementation. However, you can configure your Celo L2 node to proxy to an archive Celo L1 node for these calls. See the [archive node docs](/infra-partners/operators/archive-node). - -## Unsupported geth keystore API - -The old geth keystore API is not supported anymore, but you can extract your private key by using [cast](https://book.getfoundry.sh/cast/)'s `decrypt-keystore` keystore command. -Just give it the path to your keystore and the name of your key, e.g. - -``` -> cast wallet decrypt-keystore -k validator-00/keystore/ testkey -Enter password: -testkey's private key is: 0x2089e0db913b30b1c4084f3bd32ca3fd53e28437d76dbd0e609b0884b2c540ef -``` diff --git a/legacy/transition/whats-changed/overview.mdx b/legacy/transition/whats-changed/overview.mdx deleted file mode 100644 index 22b83ecf1..000000000 --- a/legacy/transition/whats-changed/overview.mdx +++ /dev/null @@ -1,11 +0,0 @@ ---- -title: What's changed? -og:description: Changes from L1 to L2 and from op-stack to L2 ---- - -Celo is moving from being a POS (proof of stake) based L1 blockchain to an L2 built on the OP Stack. In Celo L1 both ordering and data availability were provided by the validators participating in the POS consensus mechanism, being an L2 means that Celo will instead rely on the L1 (Ethereum) for ordering and on [EigenDA](https://www.eigenda.xyz/) for data availability. Outsourcing those components allows Celo to offer increased scalability while focussing on providing value for users. See below for more details about all the changes involved. - -## Details - -* [Celo L1 → L2 changes](/legacy/transition/whats-changed/l1-l2) -* [Optimism → Celo L2 changes](/legacy/transition/optimism/op-l2) diff --git a/legacy/validator/celo-foundation-voting-policy.mdx b/legacy/validator/celo-foundation-voting-policy.mdx deleted file mode 100644 index 7b159b24b..000000000 --- a/legacy/validator/celo-foundation-voting-policy.mdx +++ /dev/null @@ -1,162 +0,0 @@ ---- -title: Celo Foundation Voting Policy -og:description: How the Celo Foundation anticipates allocating its votes to validator groups, with special attention to the first allocated groups at the Celo Mainnet release and the months thereafter. -sidebarTitle: "Voting Policy" ---- - -How the Celo Foundation anticipates allocating its votes to validator groups, with special attention to the first allocated groups at the Celo Mainnet release and the months thereafter. - - -This page describes the historical Celo Layer 1 blockchain. It is useful for understanding Celo’s history, but does not reflect the current state of the network. As of block height 31,056,500 (March 26, 2025, 3:00 AM UTC), Celo has transitioned to an Ethereum Layer 2. - - ---- - - -The policy described here can change at any time as determined by the Foundation Board. - - -## Policy Objectives - -The Foundation voting policy aims to: - -- Be fair by avoiding preferential treatment to certain groups; -- Vote in-line with the Foundation’s purpose, which is to encourage financial inclusion and prosperity for all; -- Encourage professional, secure, and reliable validators; -- Be equal opportunity by enabling new groups to have validators elected; and -- Promote network stability by encouraging a gradual turnover in elected validators instead of abrupt election changes - -## Process - -Every 4 months, the Foundation, through its Board, will distribute a portion of its total available votes to a cohort of validator groups. These validators must meet certain basic standards (details below) and alignment with the Foundation’s purpose. The total number of validator groups in a cohort can vary. - -Validator groups who will be selected for a cohort (and will thus receive a portion of the Foundation’s votes) will be informed by the following (non-exhaustive) considerations: - -1. The number of elected validators in earlier cohorts; -2. Network stability; -3. CELO governance participation (e.g., how many CELO holders are actively participating in voting); and -4. The quality of validator group applicants - -Each validator group selected in the cohort will receive a portion of the Foundation votes for a period of 12 months. During this period, so long as a validator in the group is not slashed or otherwise engages in misbehavior, the validator group will continue to receive these votes. If the validator group is slashed or engages in misbehavior, however, the votes for that validator group will be withdrawn for the remainder of the period. If the validator group is slashed, it may reapply to the Foundation after a 6 month period. In addition, the Foundation may also withdraw its votes if the validator group or the validators in the group fail to meet other standards, including running an attestation service. - - -![](https://storage.googleapis.com/celo-website/docs/celo-foundation-cohorts.jpg) - - -## Eligibility Criteria - -### Network Criteria - -To support effective and responsible validators, the Foundation considers the following, main criteria for network performance, which must be met by all applicants who receive Foundation votes. - -- **Zero Slashing Incidents.** The validator members of any applying group must not have been slashed within the last 6 months of application. (Note, there are a variety of reasons for slashing, including downtime, security issues, etc. At the outset, and because groups can re-apply at 6 months and 1 day of the slashing, all slashing will be considered equal at this stage) - -- **Attestation Performance.** Ability and commitment to running attestation services with high completion rates. - -- **Uptime Performance.** High performance uptime score over the past 30 days on Mainnet (or Baklava if not elected on Mainnet) - -**Note**: If you are NOT ELECTED on Mainnet, you must be validating on Baklava testnet for at least 30 days. If you are ELECTED you must run validators and attestation service for at least one month (30 days) on Mainnet. If you are ELECTED on Mainnet but for less than 30 days, you must be validating on Baklava for 30 days at least. - -### Supporting Criteria - -On top of the main criteria outlined in the previous example, the Foundation considers the following, supporting criteria, which must be met by all applicants who receive Foundation votes: - -- **Audit Checklist and Self Reporting.** As part of the application process, the Foundation will publish a list of recommended validator settings. The members of every group applying will self attest to complying with the recommended checklist. - -- **Education.** An effective validator must be secure. Applicants’ members will take an education course. The course must be completed annually. - -- **Basic Diligence.** Because the Foundation holds a substantial number of votes, and its voting may determine whether a validator is elected, the Foundation will conduct a basic diligence process for voted groups. The diligence would include name, location, entity information. This diligence would occur on an annual basis for any group receiving votes. - -### Additional Criteria - -In addition to meeting the main and supporting criteria, outlined above, the Foundation anticipates prioritizing validator groups who are mission aligned and/or will provide greater network resilience. These criteria may include: - -- The geographical location of the validator group - -- Non-profit organizations - -- Organizations who commit to donating a percentage of rewards to non-profit organizations - -- The likelihood of the validator group having substantial network support from other voters - -This criteria assumes the validators perform well in the main and supporting criteria. It is used as an additional way to evaluate validator applicants assuming there’s a limited number of seats in a cohort and that the validators being evaluated all performed well in network performance as outlined in the main criteria. - -## Application - -The following new deadlines will be established for the next 3 cohorts as fixed dates. -Each cohort will last 12 months, there’s a 4 months gap between each cohort. - -- Cohort 11: November 1 new date for voting in - -- Cohort 12: March 1 new date for voting in - -- Cohort 13: July 1 new date for voting in - -For each cohort, the deadline to apply/be evaluated (if you are reapplying) is exactly 1 month prior to the date of being voted in. So for Cohort 8, it’ll be October 1 for the deadline, etc. - -## New Applicants - -### Application Prerequisites - -Before applying all validator group members should have: - -- **Important**: Run at least one Validator and Validator Group on Baklava -- **Important**: Run an Attestation Service on Baklava -- **Important**: Register a validator group on Mainnet and get 150k CELO voted for your validator group -- Completed the [Mastering the Art of Validating](https://youtu.be/3UIudzzCb8o) and [Validator Group Marketing](https://www.youtube.com/watch?v=0_veGIugCGQ) courses -- Completed the [Security Self Assessment Audit](https://docs.google.com/presentation/d/e/2PACX-1vRdKNpXI2mvqwQF6L5LRrxPW2qRK-5MDce5EhqXqLC1MSYmupZMFnhp6YEP0gLYuRKW-FF0fcAqhEAp/pub?start=true&loop=false&delayms=10000&slide=id.g76d52a0216_0_333), which includes completing this [checklist](https://docs.google.com/spreadsheets/d/1FqmUfleCoyNIUep7PoVu3ujHd-OkHZJ8o6p7Affr93w/edit?usp=sharing) - -### Application Details - -Before applying be ready to share the following: - -- A personal statement telling the Foundation why your group should get votes (max 1,500 characters) -- Validator Group details: email, name, website, address on Mainnet and Baklava, and geographic location -- Information about your team: full names, link to professional profiles such as LinkedIn or GitHub, and an explanation of the team’s relevant experience - -- Whether your Group: - - Is validating or has validated in the past 1 month on the Baklava Testnet (Need to provide validator group address and validator address on Baklava) - - Has been slashed in the past 6 months and if so why (for reapplicants) - - Members have all completed the online training (see prerequisites) - - Members have all completed the self-audit (see prerequisites) -- Optional: - - The list of contributions made to the Celo ecosystem - - Date, audit firm name, and report of your last security audit if your Group has been audited by an external firm in the past 12 months - -## Reapplicants - -If you’re part of an existing cohort with expiring votes and interested in reapplying, the re-application process is much more simpler as an existing cohort. - -You will receive an email from Celo Foundation asking you if you are interested in reapplying for the new Cohort. - -At the application deadline date for new applicants, your validator group will be evaluated on Performance Score and Attestation Score. If you score above the Foundation’s threshold, you will be considered for the new cohort along with the new applicants reapplying, limited by seat availability in that cohort. If you don’t make the new cohort, you are invited to reapply for the next cohort application. - -### Cohort Information - -Past Foundation votes recipients: - -- **Cohort 1:** The Great Celo Stake Off [leaderboard](https://docs.google.com/spreadsheets/d/1Me56YkCHYmsN23gSMgDb1hZ_ezN0sTjNW4kyGbAO9vc/edit#gid=1970613133) participants at ranking 26-50 -- votes expired on Aug 1, 2020 -- **Cohort 2:** The Great Celo Stake Off [leaderboard](https://docs.google.com/spreadsheets/d/1Me56YkCHYmsN23gSMgDb1hZ_ezN0sTjNW4kyGbAO9vc/edit#gid=1970613133) participants at ranking 1-25 -- votes expired on Nov 1, 2020 -- **Cohort 3:** [6 validator groups](https://docs.google.com/spreadsheets/d/1OkWnr6EOeFn4pIv0zxmXFNtHLmKWf_qCJOJ4iacov-A/edit?usp=sharing) -- votes expired on Feb 1, 2021 -- **Cohort 4:** [22 validator groups](https://docs.google.com/spreadsheets/d/1bp2nJUxqhWner-uOffBohKQc3N93e--eMpP7XOBrbGI/edit?usp=sharing) -- votes expired on May 1, 2021 -- **Cohort 5:** [24 validator groups](https://docs.google.com/spreadsheets/d/1n2lwFsAsFaohng4Bo_FEWcoXzZl5CrLFxA6EK0nuFSA/edit#gid=0) -- votes expired on November 1, 2021 -- **Cohort 6:** [7 validator groups](https://docs.google.com/spreadsheets/d/1HT_fN-mSAL2etF0Po_h122jeU1zpEtdpb_khogOfBCg/edit?usp=sharing) -- votes will expire on March 1, 2022 -- **Cohort 7:** [23 validator groups](https://docs.google.com/spreadsheets/d/1eYBzQMObTAy-WKs5CHHFnGGl_k1rQo0MBHinV3OgSik/edit#gid=1466530578) -- votes will expire on July 1, 2022 -- **Cohort 8:** [24 validator groups](https://docs.google.com/spreadsheets/d/11fTPMa_2FXAye_mgidE_3Ub-xY_aJLo0WXee_Qn5mC8/edit#gid=0) -- votes will expire on November 1, 2022 -- **Cohort 9:** [7 validator groups](https://docs.google.com/spreadsheets/d/1NcIMKvZnxyqzgbnaICisMR1y0eyxpr0HvCHFCHH-EDA/edit?pli=1#gid=0) -- votes will expire on March 1, 2023 - -Currently receiving Foundation votes: - -- **Cohort 10:** [24 validator groups](https://docs.google.com/spreadsheets/d/1q0FhZJ2wYxg0JaZ-hbdIodRGwZPPNgf3aqD3ubArtj0/edit#gid=0) -- votes will expire on July 1, 2023 -- **Cohort 11:** [24 validator groups](https://docs.google.com/spreadsheets/d/1CPbZmaS_e-dvPu1fujMYhaiUY_1sNqi3nYaYTIIBK6E/edit#gid=0) -- votes will expire on November 1, 2023 -- **Cohort 12:** 5 validator groups -- votes will expire on March 1, 2024 - -Coming soon: -- **Cohort 13:** 24 validator groups -- votes will expire on July 1, 2024 - - - -If you would like to keep up-to-date with all the news happening in the Celo community, including validation, node operation and governance, please sign up to our [Celo Signal mailing list here](https://share.hsforms.com/1Qrhush1vSA2WIamd_yL4ow53n4j). - -You can add the [Celo Signal public calendar](https://calendar.google.com/calendar/u/0/embed?src=c_9su6ich1uhmetr4ob3sij6kaqs@group.calendar.google.com) as well which has relevant dates. - diff --git a/legacy/validator/devops-best-practices.mdx b/legacy/validator/devops-best-practices.mdx deleted file mode 100644 index 379e28961..000000000 --- a/legacy/validator/devops-best-practices.mdx +++ /dev/null @@ -1,35 +0,0 @@ ---- -title: "DevOps Best Practices" -sidebarTitle: "DevOps Best Practices" -og:description: Best practices for running cloud infrastructure for Celo nodes and services. ---- - -Best practices for running cloud infrastructure for Celo nodes and services. - - -This page describes the historical Celo Layer 1 blockchain. It is useful for understanding Celo’s history, but does not reflect the current state of the network. As of block height 31,056,500 (March 26, 2025, 3:00 AM UTC), Celo has transitioned to an Ethereum Layer 2. - - ---- - -## Cloud Infrastructure Best Practices - -### Node Redundancy - -If you are running your celo-blockchain nodes for mainnet in the cloud as a validator, then we recommend having more than one node running. - -You can use the redundant validator node as a backup node. It's important that it should only be used as a backup node so you must not enable block-signing with it (to avoid double signing). - -In case your primary validator node fails for some reason, then having the redundant node is extremely valuable as you can add the validator keys to it and point it to your proxy to continue signing blocks. - -### Snapshotting - -Another useful thing you can do is enabling snapshotting on your redundant node. - -There's no best answer on cadence for snapshotting your redundant node, but one snapshot a week is a good estimate, depending on budget and how the cloud provider charges for snapshotting. - -That way, in the event of a node or instance failure on your validator box, which can potentially lead to database failure and requiring you to resync your validator node, then you can use your snapshot as a starting point for syncing and don't have to wait too long to sync. - -### Kubernetes - -We are working on getting a Kubernetes recommended specification and will update this section once we have a recommended spec. If you are using Kubernetes with your validator node, feel free to submit a PR to update this section with your setup. \ No newline at end of file diff --git a/legacy/validator/index.mdx b/legacy/validator/index.mdx deleted file mode 100644 index 83127615a..000000000 --- a/legacy/validator/index.mdx +++ /dev/null @@ -1,43 +0,0 @@ ---- -title: Celo Validators -og:description: Collection of resources to support Validators on the Celo network. -sidebarTitle: "Overview" ---- - - -Secure the Celo network by participating in the consensus of the Celo protocol. - - -This page describes the historical Celo Layer 1 blockchain. It is useful for understanding Celo’s history, but does not reflect the current state of the network. As of block height 31,056,500 (March 26, 2025, 3:00 AM UTC), Celo has transitioned to an Ethereum Layer 2. - - ---- - -Celo Validators participate in the consensus of the Celo protocol. They help secure the Celo network by verifying transactions and proposing blocks to add to the Celo blockchain. - - -Not ready to become a Celo Validator? [Learn more about Celo](/). - - -## Important Information - -- [Key Management](/legacy/validator/key-management/summary) - -## Nodes and Services - -- [Securing Celo Nodes and Services](/legacy/validator/security) -- [Upgrading a Node](/legacy/validator/node-upgrade) -- [Monitoring](/legacy/validator/monitoring) -- [Running Proxies](/legacy/validator/proxy) - -## Validator Tools - -- [Validator Explorer](/legacy/validator/validator-explorer) - -## Voting Policy - -- [Celo Foundation Voting Policy](/legacy/validator/celo-foundation-voting-policy) - - -For questions, comments, and discussions please use the [Celo Forum](https://forum.celo.org/) or [Discord](https://chat.celo.org/). - diff --git a/legacy/validator/key-management/detailed.mdx b/legacy/validator/key-management/detailed.mdx deleted file mode 100644 index 5b871c651..000000000 --- a/legacy/validator/key-management/detailed.mdx +++ /dev/null @@ -1,162 +0,0 @@ ---- -title: "Detailed Role Descriptions" -sidebarTitle: "Key Management" -og:description: Detailed description of the various account roles found in the Celo protocol with examples of how to designate an account as playing a particular role. ---- - -Detailed descriptions of the various account roles as found in the Celo protocol with examples of how to designate an account as playing a particular role. - - -This page describes the historical Celo Layer 1 blockchain. It is useful for understanding Celo’s history, but does not reflect the current state of the network. As of block height 31,056,500 (March 26, 2025, 3:00 AM UTC), Celo has transitioned to an Ethereum Layer 2. - - ---- - -## Celo Accounts - -Any private key generated for use in the Celo protocol has a corresponding address. The account address is the last 20 bytes of the hash of the corresponding public key, just as in Ethereum. Celo account keys can be used to sign and send transactions on the Celo network. - -Celo Accounts can be designated as Locked Gold Accounts or authorized as signer keys on behalf of a Locked Gold Account by sending special transactions using [celocli](/cli/). Note that Celo accounts that have not been designated as Locked Gold Accounts or authorized signers may not be able to send certain transactions related to proof-of-stake. - -## Locked CELO Accounts - -[Locked CELO](/legacy/protocol/pos/locked-gold) Account keys have the highest level of privilege in the Celo protocol. These keys can be used to lock and unlock CELO in order to be used in proof-of-stake. Furthermore, Locked CELO Account keys can be used to authorize other keys to sign transactions and messages on behalf of the Locked CELO Account. - -In _most_ cases, the Locked CELO Account key has all the privileges as any authorized signers. For example, if a voter signer is authorized, a user can place votes on behalf of the Locked CELO Account with both the authorized vote signer _and_ the Locked CELO Account. - -Because of the significant privileges afforded to the Locked CELO Account, it is best to store this key securely and access it as infrequently as is possible. Authorizing other signers is one way to minimize how frequently you need to access your Locked CELO Account key. The Locked CELO Account key will only be used to send transactions and **can be stored on a Ledger hardware wallet.** - -### Creating a Locked CELO Account - -A Celo account may be designated as a Locked CELO Account by running the following command: - -```shell -# Designate the Celo account as a Locked CELO Account -celocli account:register --from $ADDRESS_TO_DESIGNATE --useLedger - -# Confirm the address was designated as a Locked CELO Account -celocli account:show $ADDRESS_TO_DESIGNATE -``` - -Note that [ReleaseGold](/home/manage/release-gold) beneficiary keys are considered vanilla Celo accounts with respect to proof-of-stake, and that the `ReleaseGold` contract address is what ultimately gets designated as a Locked CELO Account. - -## Authorized Vote Signers - -Any Locked CELO Account may optionally authorize a Celo account as a vote signer. Authorized vote signers can vote for validator groups and for on-chain governance proposals on behalf of the Locked CELO Account. - -Note that the vote signer must first generate a "proof-of-possession" indicating that signer's willingness to be authorized on behalf of the Locked CELO Account. - -Authorized vote signers can only be used to send voting transactions and **can be stored on a Ledger hardware wallet**. - -### Authorizing a Vote Signer - -A Celo account may be authorized as a vote signer on behalf of a Locked CELO Account by running the following commands: - -```shell -# Create a proof-of-possession. Note that the signer private key must be available. -celocli account:proof-of-possession --account $LOCKED_GOLD_ACCOUNT --signer $SIGNER_TO_AUTHORIZE --useLedger - -# Authorize the vote signer. Note that the Locked Gold Account private key must be available. -celocli account:authorize --from $LOCKED_GOLD_ACCOUNT --role vote --signer $SIGNER_TO_AUTHORIZE --signature $SIGNER_PROOF_OF_POSSESSION --useLedger - -# Confirm that the vote signer was authorized -celocli account:show $LOCKED_GOLD_ACCOUNT - -# You can also look up account info via the authorized signer -celocli account:show $SIGNER_TO_AUTHORIZE -``` - -## Authorized Validator Signers - -Any Locked CELO Account may optionally authorize a Celo account as a validator signer. Authorized validator signers can be used to register and manage a validator or validator group on behalf of the Locked CELO Account. If the authorized validator signer is used to register and run a validator, the signer key is also used to sign consensus messages. - -### Authorized Validator Signers for Validator Groups - -An authorized validator signer key that will be used to register a validator group can be used to send group management transactions (e.g. register, add member A, queue commission update to 0.25, etc.) Because this key does not participate directly in consensus it **can be stored on a Ledger hardware wallet.** - -### Authorized Validator Signers for Validators - -An authorized validator signer key that will be used to register a validator can be used to send validator management transactions (e.g. register, affiliate with group A, etc.) This key will also be used to sign consensus messages and thus **cannot be stored on a Ledger hardware wallet** as signing consensus messages is not currently supported by the Celo Ledger App. - -Note that the validator signer must first generate a "proof-of-possession" indicating the signer's willingness to be authorized on behalf of the Locked CELO Account. - -### Authorizing a Validator Signer - -A Celo account may be authorized as a validator signer on behalf of a Locked CELO Account by running the following commands: - -```shell -# Create a proof-of-possession. Note that the signer private key must be available. -# Note that the signing key can be kept on a Ledger if it will be used to run a Validator Group. -celocli account:proof-of-possession --account $LOCKED_GOLD_ACCOUNT --signer $SIGNER_TO_AUTHORIZE - -# Authorize the validator signer. Note that the Locked CELO Account private key must be available. -# Note that if a Validator has previously been registered on behalf of the Locked CELO Account it -# may be desirable to include the BLS key here as well. Please see the documentation on -# validator key rotation for more information. -celocli account:authorize --from $LOCKED_GOLD_ACCOUNT --role validator --signer $SIGNER_TO_AUTHORIZE --signature $SIGNER_PROOF_OF_POSSESSION --useLedger - -# Confirm that the vote signer was authorized -celocli account:show $LOCKED_GOLD_ACCOUNT - -# You can also look up account info via the authorized signer -celocli account:show $SIGNER_TO_AUTHORIZE -``` - -## Authorized Validator BLS Signers - -The Celo protocol uses BLS signatures in consensus to ultimately determine whether or not a particular block is valid. Many BLS signatures over the same content can be combined into a single "aggregated signature", allowing several kilobytes of signatures to be compressed into fewer than 100 bytes, ensuring that the block headers remain compact and light client friendly. - -When registering a Validator on behalf of a Locked CELO Account, users must provide a BLS public key, as well as a proof-of-possession to protect against [rogue key attacks](https://crypto.stanford.edu/~dabo/pubs/papers/BLSmultisig.html). - -By default users can derive the BLS key directly from their authorized validator signer key. From a key management and security perspective, this means that the authorized BLS signer key is **exactly the same** as the authorized validator signer key. - -Most users will only need to think about BLS signer keys when registering a validator, or when authorizing a new validator signer _after_ registering a validator. It follows that when a validator authorizes a new validator signer, the BLS public key and proof-of-possession for the new authorized validator signer should be provided as well. - -Advanced users may optionally derive their BLS key separately, but that is out of the scope of this documentation. - -### Deriving a BLS public key - -To derive a BLS public key and proof-of-possession from the authorized validator signer key, and use that information to register a validator, run the following commands: - -```shell -# Derive the BLS public key and create a proof-of-possession. Note that the signer private key must be available. -# Also note that BLS proof-of-possessions are not currently supported by celocli -docker run -v $PWD:/root/.celo --rm -it $CELO_IMAGE account proof-of-possession $AUTHORIZED_VALIDATOR_SIGNER $LOCKED_GOLD_ACCOUNT --bls - -# Register the Validator with the authorized validator signer on behalf of the Locked CELO Account -celocli validator:register --from $AUTHORIZED_VALIDATOR_SIGNER --blsKey $BLS_SIGNER_PUBLIC_KEY --blsSignature $BLS_SIGNER_PROOF_OF_POSSESSION - -# Confirm that the validator was registered -celocli validator:show $LOCKED_GOLD_ACCOUNT - -# You can also look up the validator via the authorized signer -celocli validator:show $AUTHORIZED_VALIDATOR_SIGNER -``` - -## Authorized Attestation Signers - -Any Locked CELO Account may optionally authorize a Celo account as an attestation signer. Authorized attestation signers can sign attestation messages on behalf of the Locked Gold Account in Celo's [lightweight identity protocol](/legacy/protocol/identity/). - -Note that the Celo Ledger App does yet not support signing attestation messages and as such attestation signer keys **cannot be stored on a Ledger hardware wallet**. - -Note that the attestation signer must first be used to generate a "proof-of-possession" indicating the signer's willingness to be authorized on behalf of the Locked Gold Account. - -### Authorizing an Attestation Signer - -A Celo account may be authorized as a vote signer on behalf of a Locked CELO Account by running the following commands: - -```shell -# Create a proof-of-possession. Note that the signer private key must be available. -celocli account:proof-of-possession --account $LOCKED_GOLD_ACCOUNT --signer $SIGNER_TO_AUTHORIZE -# If celocli is unavailable on the attestations node, the proof-of-possession can be generated with celo-blockchain -docker run -v $PWD:/root/.celo --rm -it $CELO_IMAGE account proof-of-possession $SIGNER_TO_AUTHORIZE $LOCKED_GOLD_ACCOUNT - -# Authorize the attestation signer. Note that the Locked CELO Account private key must be available. -celocli account:authorize --from $LOCKED_GOLD_ACCOUNT --role attestations --signer $SIGNER_TO_AUTHORIZE --signature $SIGNER_PROOF_OF_POSSESSION --useLedger - -# Confirm that the vote signer was authorized -celocli account:show $LOCKED_GOLD_ACCOUNT - -# You can also look up account info via the authorized signer -celocli account:show $SIGNER_TO_AUTHORIZE -``` \ No newline at end of file diff --git a/legacy/validator/key-management/key-rotation.mdx b/legacy/validator/key-management/key-rotation.mdx deleted file mode 100644 index 1b640edc4..000000000 --- a/legacy/validator/key-management/key-rotation.mdx +++ /dev/null @@ -1,70 +0,0 @@ ---- -title: "Validator Signer Key Rotation" -sidebarTitle: "Key Rotation" -og:description: How to manage signer key rotations as a Celo Validator. ---- - -How to manage signer key rotations as a Celo Validator. - - -This page describes the historical Celo Layer 1 blockchain. It is useful for understanding Celo’s history, but does not reflect the current state of the network. As of block height 31,056,500 (March 26, 2025, 3:00 AM UTC), Celo has transitioned to an Ethereum Layer 2. - - ---- - -## Why Rotate Keys? - -As detailed in [the Celo account roles description page](/legacy/validator/key-management/detailed), Celo Locked CELO accounts can authorize separate signer keys for various roles such as voting or validating. This way, if an authorized signer key is lost or compromised, the Locked CELO account can authorize a new signer to replace the old one, without risking the key that custodies funds. This prevents losing an authorized signer key from becoming a catastrophic event. In fact, it is recommended as an operational best practice to regularly rotate keys to limit the impact of keys being silently compromised. - -### Validator Signer Rotation - -Because the Validator signer key is constantly in use to sign consensus messages, special care must be taken when authorizing a new Validator signer key. The following steps detail the recommended procedure for rotating the validator signer key of an active and elected validator: - -1. Create a new Validator instance as detailed in the [Deploy a Validator](/legacy/validator/run/mainnet) section of the getting started documentation. When using a proxy, additionally create a new proxy and peer it with the new validator instance, as described in the same document. Wait for the new instances to sync before proceeding. Please note that when running the proxy, the `--proxy.proxiedvalidatoraddress` flag should reflect the new validator signer address. Otherwise, the proxy will not be able to peer with the validator. - - -Before proceeding to step 2 ensure there is sufficient time until the end of the epoch to complete key rotation. - - -2. Authorize the new Validator signer key with the Locked CELO Account to overwrite the old Validator signer key. - -```bash -# With $SIGNER_TO_AUTHORIZE as the new validator signer: - -# On the new validator node which contains the new $SIGNER_TO_AUTHORIZE key -docker run -v $PWD:/root/.celo --rm -it $CELO_IMAGE account proof-of-possession $SIGNER_TO_AUTHORIZE $VALIDATOR_ACCOUNT_ADDRESS -docker run -v $PWD:/root/.celo --rm -it $CELO_IMAGE account proof-of-possession $SIGNER_TO_AUTHORIZE $VALIDATOR_ACCOUNT_ADDRESS --bls -``` - -1. If `VALIDATOR_ACCOUNT_ADDRESS` corresponds to a key you possess: - -```bash -# From a node with access to the key for VALIDATOR_ACCOUNT_ADDRESS -celocli account:authorize --from $VALIDATOR_ACCOUNT_ADDRESS --role validator --signer $SIGNER_TO_AUTHORIZE --signature 0x$SIGNER_PROOF_OF_POSSESSION --blsKey $BLS_PUBLIC_KEY --blsPop $BLS_PROOF_OF_POSSESSION -``` - -2. If `VALIDATOR_ACCOUNT_ADDRESS` is a `ReleaseGold` contract: - -```bash -# From a node with access to the beneficiary key of VALIDATOR_ACCOUNT_ADDRESS -celocli releasecelo:authorize --contract $VALIDATOR_ACCOUNT_ADDRESS --role validator --signer $SIGNER_TO_AUTHORIZE --signature 0x$SIGNER_PROOF_OF_POSSESSION --blsKey $BLS_PUBLIC_KEY --blsPop $BLS_PROOF_OF_POSSESSION -``` - - -Please note that the BLS key will change along with the validator signer ECDSA key on the node. If the new BLS key is not authorized, then the validator will be unable to process aggregated signatures during consensus, **resulting in downtime**. For more details, please read [the BLS key section of the Celo account role descriptions](/legacy/validator/key-management/detailed#authorized-validator-bls-signers). - - -1. **Leave all validator and proxy nodes running** until the next epoch change. At the start the next epoch, the new Validator signer should take over participation in consensus. - -2. Verify that key rotation was successful. Here are some ways to check: - {/* TODO: The following URL assumes that the user is running against the Baklava network. This will need to be updated */} - -- Open `baklava-blockscout.celo-testnet.org/address//validations` to confirm that blocks are being proposed. -- Open `baklava-celostats.celo-testnet.org` to confirm that your node is signing blocks. -- Run `celocli validator:signed-blocks --signer $SIGNER_TO_AUTHORIZE` with the new validator signer address to further confirm that your node is signing blocks. - - -The newly authorized keys will only take effect in the next epoch, so the instance operating with the old key must remain running until the end of the current epoch to avoid downtime. - - -5. Shut down the validator instance with the now obsolete signer key. \ No newline at end of file diff --git a/legacy/validator/key-management/summary.mdx b/legacy/validator/key-management/summary.mdx deleted file mode 100644 index ac1054fa5..000000000 --- a/legacy/validator/key-management/summary.mdx +++ /dev/null @@ -1,37 +0,0 @@ ---- -title: Validator Key Management -og:description: Introduction to the philosophy and account roles related to key management on Celo. -sidebarTitle: "Summary" ---- - -Introduction to the philosophy and account roles related to key management on Celo. - - -This page describes the historical Celo Layer 1 blockchain. It is useful for understanding Celo’s history, but does not reflect the current state of the network. As of block height 31,056,500 (March 26, 2025, 3:00 AM UTC), Celo has transitioned to an Ethereum Layer 2. - - ---- - -## Philosophy - -The Celo protocol was designed with the understanding that there is often an inherent tradeoff between the convenience of accessing a private key and the security with which that private key can be custodied. In general Celo is unopinionated about how keys are custodied, but also allows users to authorize private keys with specific, limited privileges. This allows users to custody each private key according to its sensitivity (i.e. what is the impact of this key being lost or stolen?) and usage patterns (i.e. how often and under which circumstances will this key need to be accessed). - -## Summary - -The table below outlines a summary of the various account roles in the Celo protocol. Note that these roles are often _mutually exclusive_. An account that has been designated as one role can often not be used for a different purpose. Also note that under the hood, all of these accounts) are based on secp256k1 ECDSA private keys with the exception of the BLS signer. The different account roles are simply a concept encoded into the Celo proof-of-stake smart contracts, specifically [Accounts.sol](https://github.com/celo-org/celo-monorepo/blob/master/packages/protocol/contracts/common/Accounts.sol). - -For more details on a specific key type, please see the more detailed sections below. - -| Role | Description | Ledger compatible | -| ----------------------------------- | ------------------------------------------------------------------------------------------------ | ----------------- | -| Celo Account | An account used to send transactions in the Celo protocol | Yes | -| Locked CELO Account | Used to lock and unlock CELO and authorize signers | Yes | -| Authorized vote signer | Can vote on behalf of a Locked CELO Account | Yes | -| Authorized validator (group) signer | Can register and manage a validator group on behalf of a Locked CELO Account | Yes | -| Authorized validator signer | Can register, manage a validator, and sign consensus messages on behalf of a Locked CELO Account | No | -| Authorized validator BLS signer | Used to sign blocks as a validator | No | -| Authorized attestation signer | Can sign attestation messages on behalf of a Locked CELO account | No | - - -A Locked CELO Account may have at most one authorized signer of each type at any time. Once a signer is authorized, the only way to deauthorize that signer is to authorize a new signer that has never previously been used as an authorized signer or Locked CELO Account. It follows then that a newly deauthorized signer cannot be reauthorized. - \ No newline at end of file diff --git a/legacy/validator/monitoring.mdx b/legacy/validator/monitoring.mdx deleted file mode 100644 index c25498fca..000000000 --- a/legacy/validator/monitoring.mdx +++ /dev/null @@ -1,156 +0,0 @@ ---- -title: "Monitoring" -sidebarTitle: "Monitoring" -og:description: Commands, metrics, APIs, and services for monitoring Validators and Proxies. ---- - -Commands, metrics, APIs, and services for monitoring Validators and Proxies. - - -This page describes the historical Celo Layer 1 blockchain. It is useful for understanding Celo’s history, but does not reflect the current state of the network. As of block height 31,056,500 (March 26, 2025, 3:00 AM UTC), Celo has transitioned to an Ethereum Layer 2. - - ---- - -## Monitoring Validators and Proxies - -### Logging - -Several command line options control logging: - -- `--verbosity`: Sets logging verbosity. `3` outputs logs up to `INFO` level and is recommended. `4` outputs up to `DEBUG` level; `5` is `TRACE`. - -- `--vmodule`: Overrides this verblosity in specific modules. For example, to configure `TRACE` level logging of consensus activity, use `consensus/istanbul/*=5`. - -- `--consoleoutput`: Sends output to the given path, or to `stdout`. - -- (Deprecatedin v1.5) `--consoleformat`: Formats logs for easy viewing in a terminal (`term`), or as structured JSON (`json`). -- (Introduced in v1.5) `--log.json`: Formats logs as structured JSON (`true`), or for easy viewing in a terminal (`false`, default option). - -Useful messages to record or set up log-based metrics on: - -- `msg="Validator Election Results"`: When the last block of any epoch (`number`) has been agreed, `elected` shows whether the validator was selected in the validator election. - -- `msg="Elected but didn't sign block"`: This validator was elected but did not have its signature included in the block given by `number` (in fact, in the child's parent seal). This block could count towards downtime if 12 successive blocks are missed. - -### Metrics - -Celo Blockchain inherits [go-ethereum's metrics](https://github.com/ethereum/go-ethereum/wiki/Metrics-and-Monitoring) system, but additional Celo-specific metrics have been added. - -Metrics reporting is enabled with the `--metrics` flag. - -Pull-based metrics are available using the `--pprof` flag. This enables the `pprof` debugging HTTP server, by default on `http://localhost:6060`. The `--pprof.addr` and `--pprof.port` options can be used to configure the interface and port respectively. If the node is running inside a Docker container, you will need to set `--pprof.addr 0.0.0.0`, then on your Docker command line add `-p 127.0.0.1:6060:6060`. - - -Be sure never to expose the `pprof` service to the public internet. - - -[Prometheus](https://prometheus.io) format metrics are available at `http://localhost:6060/debug/metrics/prometheus`. - -[ExpVar](https://golang.org/pkg/expvar/) format metrics are available at `http://localhost:6060/debug/metrics`. - -Support for pushing metrics to [InfluxDB](https://www.influxdata.com/products/influxdb-overview/) is available via `--metrics.influxdb` and related flags. This works without the `pprof` server. - -Note that metric name separators differ between these endpoints. - -All metrics are soft-state and are cleared when the process is restarted. - -### Memory metrics - -Memory metrics derived from [mstats](https://godoc.org/github.com/go-graphite/carbonzipper/mstats): - -- `system_memory_held`: Gauge of virtual address space allocated by the Celo Blockchain process, measured in bytes. -- `system_memory_used`: Gauge of Memory in use by the Celo Blockchain process, measured as bytes of allocated heap objects. -- `system_memory_allocs`: Counter for memory allocations made, measured in bytes. Consider monitoring the rate. -- `system_memory_pauses`: Counter for stop-the-world Garbage Collection pauses, measured in nanoseconds. Consider monitoring the rate. - -### CPU metrics - -- `system_cpu_sysload`: Gauge of load average for the system. -- `system_cpu_syswait`: Gauge of IO wait time for the system. -- `system_cpu_procload`: Gauge of load average for the Celo Blockchain process. - -### Network metrics - -- `p2p_peers`: The number of connected peers. This should remain at exactly `1` for a proxied validator (just its proxy). It should remain at a relatively steady level for proxy nodes. - -- `p2p_ingress`: Counter for total inbound traffic, measured in bytes. Consider monitoring the rate. - -- `p2p_egress`: Counter for total outbound traffic, measured in bytes. Consider monitoring the rate. - -- `p2p_dials`: Counter for outbound connection attempts. Consider monitoring the rate. - -- `p2p_serves`: Counter for accepted inbound connection attempts. Consider monitoring the rate. - -### Blockchain metrics - -- `chain_inserts_count`: The count of insertions of new blocks into this node's chain. The rate of this metric should be close to constant at `0.2` /second. - -### Validator health metrics - -A number of metrics are tracked for the parent of the last sealed block received (i.e. this is always two fewer than the current consensus sequence): - -- `consensus_istanbul_blocks_elected`: Counts the number of blocks for which this validator has been elected - -- `consensus_istanbul_blocks_signedbyus`: Counts the blocks for which this validator was elected and its signature was included in the seal. This means the validator completed consensus correctly, sent a `COMMIT`, its commit was received in time to make the seal of the parent received by the next proposer, or was received directly by the next proposer itself, and so the block will not count as downtime. Consider monitoring the rate. - -- `consensus_istanbul_blocks_missedbyus`: Counts the blocks for which this validator was elected but not included in the child's parent seal (this block could count towards downtime if 12 successive blocks are missed). Consider monitoring the rate. - -- `consensus_istanbul_blocks_missedbyusinarow`: (_since 1.0.2_) Counts the blocks for which this validator was elected but not included in the child's parent seal in a row. Consider monitoring the gauge. - -- `consensus_istanbul_blocks_proposedbyus`: (_since 1.0.2_) Counts the blocks for which this validator was elected and for which a block it proposed was succesfully included in the chain. Consider monitoring the rate. - -- `consensus_istanbul_blocks_downtimeevent`: (_since 1.0.2_) Counts the blocks for which this validator was elected and for blocks where it is considered down (occurs when `missedbyusinarow` is >= 12). Consider monitoring the rate. - -### Consensus metrics - -- `consensus_istanbul_core_desiredround`: Current desired round for this validator, i.e the round we are waiting to see a quorum of validators send `RoundChange` messages for. Usually this value should be `0`. Desired rounds increment with each timeout, which backoff exponentially. A value of `5` indicates consensus has stalled for more than 30 seconds. Values above that means the validator is unable to participate in quorum (either because it is disconnected, out of sync, etc, or because of network partition or failure of other validators). - -- `consensus_istanbul_core_round`: : Current consensus round for this validator, i.e the round for which this validator has received a quorum of `RoundChange` messages. Usually this value should be `0`. If this value is less than `consensus_istanbul_core_desiredround` the validator is not connected to a quorum of other validators that are also unable to participate (for instance, they did see a proposed block, but this validator did not). If it is equal, it means the validator remains connected to a quorum of other validators but cannot agree on a block. - -- `consensus_istanbul_core_sequence`: Current consensus sequence number, i.e the block number currently being proposed. - -### Network consensus health metrics - -- `consensus_istanbul_blocks_totalsigs`: The number of validators whose signatures were included in the child's parent seal. This can be used to determine how many validators are up and contributing to consensus. If this number falls towards two thirds of validator set size, network block production is at risk. - -- `consensus_istanbul_blocks_missedrounds`: Sum of the `round` included in the `parentAggregatedSeal` for the blocks seen. That is, the cumulative number of consensus round changes these blocks needed to make to get to this agreed block. This metric is only incremented when a block is succesfully produced after consensus rounds fails, indicating down validators or network issues. - -- `consensus_istanbul_blocks_missedroundsasproposer`: (_since 1.0.2_) A meter noting when this validator was elected and could have proposed a block with their signature but did not. In some cases this could be required by the Istanbul BFT protocol. - -- `consensus_istanbul_blocks_validators`: (_since 1.0.2_) Total number of validators eligible to sign blocks. - -- `consensus_istanbul_core_consensus_count`: Count and timer for succesful completions of consensus (Use `quantile` tag to find percentiles: `0.5`, `0.75`, `0.95`, `0.99`, `0.999`) - -### Management APIs - -Celo blockchain inherits and extends go-ethereum's Javascript console, exposing [management APIs](https://geth.ethereum.org/docs/rpc/server) and web3 DApp APIs. - -Connect a client using a variant of the `attach` command line option: - -```bash -geth attach --datadir DATADIR -geth attach ipc:PATH/TO/geth.ipc -geth attach http://localhost:8545 -geth attach ws://localhost:8546 -``` - -{/* -Celo adds specific functions around consensus: - -```bash - -``` */} - -## Community Monitoring Tools - -### [Atalma Signature & Attestation Viewer (Celo Vido)](https://vido.atalma.io/celo/block-map) - -- Visualizer of current and historic data on validator signatures collected in each block on Mainnet and Baklava. -- Visualizer of current and historic attestation requests and completions, and attestation endpoint versions and status on Mainnet and Baklava. - -### [Virtual Hive Celo Network Validator Exporter](https://github.com/virtualhive/celo-network-validator-exporter) - -Prometheus exporter that scrapes downtime and meta information for a specified validator signer address from the Celo blockchain. All data is collected from a blockchain node via RPC. - -{/* ## Monitoring Network Health, Elections, and Accounts */} \ No newline at end of file diff --git a/legacy/validator/node-upgrade.mdx b/legacy/validator/node-upgrade.mdx deleted file mode 100644 index f2a6853fd..000000000 --- a/legacy/validator/node-upgrade.mdx +++ /dev/null @@ -1,169 +0,0 @@ ---- -title: "Upgrade a Node" -sidebarTitle: "Node Upgrades" -og:description: How to upgrade to the newest available version of a Celo node. ---- - -How to upgrade to the newest available version of a Celo node. - - -This page describes the historical Celo Layer 1 blockchain. It is useful for understanding Celo’s history, but does not reflect the current state of the network. As of block height 31,056,500 (March 26, 2025, 3:00 AM UTC), Celo has transitioned to an Ethereum Layer 2. - - ---- - -## Recent Releases - -- [You can view the latest releases here.](https://github.com/celo-org/celo-blockchain/releases) - -## When an upgrade is required - -Upgrades to the Celo node software will often be optional improvements, such as improvements to performance, new useful features, and non-critical bug fixes. Occasionally, they may be required when the upgrade is necessary to continue operating on the network, such as hard forks, or critical bug fixes. - -## Upgrading a non-validating node - -Use these instructions to update non-validating nodes, such as your account node or your attestation node on the Baklava testnet. Also use these instructions to upgrade your proxy node, but remember not to stop the proxy of a running validator. - -### Pull the latest Docker image - -```bash -export CELO_IMAGE=us.gcr.io/celo-org/geth:mainnet -docker pull $CELO_IMAGE -``` - -### Stop and remove the existing node - -Stop and remove the existing node. Make sure to stop the node gracefully (i.e. giving it time to shut down and complete any writes to disk) or your chain data may become corrupted. - -Note: The `docker run` commands in the documentation have been updated to now include `--stop-timeout 300`, which should make the `-t 300` in `docker stop` below redundant. However, it is still recommended to include it just in case. - -```bash -docker stop -t 300 celo-fullnode -docker rm celo-fullnode -``` - - -## Upgrading a Validating Node - -Upgrading a validating node is much the same, but requires extra care to be taken to prevent validator downtime. - -One option to complete a validating node upgrade is to perform a key rotation onto a new node. Pull the latest Docker image, as mentioned above, then execute a Validator signing key rotation, using the latest image as the new Validator signing node. A recommended procedure for key rotation is documented in the [Key Management](/legacy/validator/key-management/key-rotation) guide. - -A second option is to perform a hot-swap to switch over to a new validator node. The new validator node **must** be configured with the same set of proxies as the existing validator node. - -### Hotswapping Validator Nodes - - -Hotswap is being introduced in version 1.2.0. When upgrading nodes that are not yet on 1.2.0 refer to the guide to perform a key rotation. - - -Validators can be configured as primaries or replicas. By default validators start as primaries and will persist all changes around starting or stopping. Through the istanbul management RPC API the validator can be configured to start or stop at a specified block. The validator will participate in consensus for block numbers in the range `[start, stop)`. - - -Note that the replica node **must** use the same set of proxies as the primary node. If it does not it will not be able to switchover without downtime due to needing to the complete the announce protocol from scratch. Replicas behind the same set of proxies as the primary node will be able to switchover without downtime. - - -#### RPC Methods - -- `istanbul.start()` and `istanbul.startAtBlock()` start validating immediately or at a block -- `istanbul.stop()` and `istanbul.stopAtBlock()` stop validating immediately or at a block -- `istanbul.replicaState` will give you the state of the node and the start/stop blocks -- `istanbul.validating` will give you true/false if the node is validating - - -`startAtBlock` and `stopAtBlock` must be given a block in the future. - - -#### Geth Flags - -- `--istanbul.replica` flag which starts a validator in replica mode. - -On startup, nodes will look to see if there is a `replicastate` folder inside it's data directory. If that folder exists the node will configure itself as a validator or replica depending on the previous stored state. The stored state will take precedence over the command line flags. If the folder does not exists the node will stored it's state as configured by the command line. When RPC calls are made to start or stop validating, those changes will be persisted to the `replicastate` folder. - - -If reconfiguring a node to be a replica or reusing a data directory, make sure that the node was previously configured as replica or that the `replicastate` folder is removed. If there is an existing `replicastate` folder from a node that was not configured as a replica the node will attempt to start validating. - - -#### Steps to upgrade - -1. Pull the latest docker image. -2. Start a new validator node on a second host in replica mode (`--istanbul.replica` flag). It should be otherwise configured exactly the same as the existing validator. - - It needs to connect to the existing proxies and the validator signing key to connect to other validators in listen mode. - - If reconfiguring a node to be a replica or reusing a data directory, make sure that the node was previously configured as replica or that the `replicastate` folder is removed. -3. Once the replica is synced and has validator enode urls for all validators, it is ready to swapped in. - - Check validator enode urls with `istanbul.valEnodeTableInfo` in the geth console. The field `enode` should be filled in for each validator peer. -4. In the geth console on the primary run `istanbul.stopAtBlock(xxxx)` - - Make sure to select a block number comfortably in the future. - - You can check what the stop block is with `istanbul.replicaState` in the geth console. - - You can run `istanbul.start()` to clear the stop block -5. In the geth console of the replica run `istanbul.startAtBlock(xxxx)` - - You can check what the start block is with `istanbul.replicaState` in the geth console. - - You can run `istanbul.stop()` to clear the start block -6. Confirm that the transition occurred with `istanbul.replicaState` - - The last block that the old primary will sign is block number `xxxx - 1` - - The first block that the new primary will sign is block number `xxxx` -7. Tear down the old primary once the transition has occurred. - -Example geth console on the old primary. - -```bash -> istanbul.replicaState -{ - isPrimary: true, - startValidatingBlock: null, - state: "Primary", - stopValidatingBlock: null -} -> istanbul.stopAtBlock(21000) -null -> istanbul.replicaState -{ - isPrimary: true, - startValidatingBlock: null, - state: "Primary in given range", - stopValidatingBlock: 21000 -} -> istanbul.replicaState -{ - isPrimary: false, - startValidatingBlock: null, - state: "Replica", - stopValidatingBlock: null -} -``` - -Example geth console on the replica being promoted to primary. Not shown is confirming the node is synced and connected to validator peers. - -```bash -> istanbul.replicaState -{ - isPrimary: false, - startValidatingBlock: null, - state: "Replica", - stopValidatingBlock: null -} -> istanbul.startAtBlock(21000) -null -> istanbul.replicaState -{ - isPrimary: false, - startValidatingBlock: 21000, - state: "Replica waiting to start", - stopValidatingBlock: null -} -> istanbul.replicaState -{ - isPrimary: true, - startValidatingBlock: null, - state: "Primary", - stopValidatingBlock: null -} -``` - -### Upgrading Proxy Nodes - - -Release 1.2.0 is backwards incompatible in the Validator and Proxy connection. Validators and proxies must be upgraded to 1.2.0 at the same time. - - -With multi-proxy, you can upgrade proxies one by one or can add newly synced proxies with the latest Docker image and can remove the old proxies. If upgrading the proxies in place, a rolling upgrade is recommended as the validator will re-assign direct connections as proxies are added and removed. These re-assignments will allow the validator to continue to participate in consensus. \ No newline at end of file diff --git a/legacy/validator/proxy.mdx b/legacy/validator/proxy.mdx deleted file mode 100644 index d45f264a7..000000000 --- a/legacy/validator/proxy.mdx +++ /dev/null @@ -1,34 +0,0 @@ ---- -title: "Running Proxies" -sidebarTitle: "Running Proxies" -og:description: How to ensure Validator uptime by running proxy nodes. ---- - -How to ensure Validator uptime by running proxy nodes. - - -This page describes the historical Celo Layer 1 blockchain. It is useful for understanding Celo’s history, but does not reflect the current state of the network. As of block height 31,056,500 (March 26, 2025, 3:00 AM UTC), Celo has transitioned to an Ethereum Layer 2. - - ---- - -## Why run a Proxy? - -Validator uptime is essential for the health of the Celo blockchain. To help with validator uptime, operators can use the proxy node, which will provide added security for the validator. It allows the validator to run within a private network, and to communicate to the rest of the Celo network via the proxy. - -Also, starting from the Celo client 1.2 release, we will support assigning multiple proxies per validator. This provides better uptime for the validator for the case of a proxy going down. Also, it will help with making each proxy enode URL less public by only sharing it with a subset of the other validators. - - -The communication protocol between the validator and it's proxies implemented in release 1.2 is NOT backwards compatible to the pre-1.2 protocol. So if the proxy or validator is being upgraded to 1.2, then both needs to be upgraded to that version. Note that validators and proxies using release 1.2 are still compatible with remote nodes. - - -There are two ways to specify the proxy information to a validator. It can be done on validator startup via the command line argument, or by the rpc api when the validator is running. - - -## RPC API - -- `istanbul.addProxy(, )` can be used on the validator to add a proxy to the validator's proxy set -- `istanbul.removeProxy()` can be used on the validator to remove a proxy from the validator's proxy set -- `istanbul.proxies` can be used on the validator to list the validator's proxy set - -- `istanbul.proxiedValidators` can be used on the proxies to list the proxied validators \ No newline at end of file diff --git a/legacy/validator/run/mainnet.mdx b/legacy/validator/run/mainnet.mdx deleted file mode 100644 index 40080f19e..000000000 --- a/legacy/validator/run/mainnet.mdx +++ /dev/null @@ -1,25 +0,0 @@ ---- -title: "Running a Validator" -sidebarTitle: "Mainnet Validator" -og:description: How to get a Validator node running on the Celo Mainnet. ---- - -How to get a Validator node running on the Celo Mainnet. - - -This page describes the historical Celo Layer 1 blockchain. It is useful for understanding Celo’s history, but does not reflect the current state of the network. As of block height 31,056,500 (March 26, 2025, 3:00 AM UTC), Celo has transitioned to an Ethereum Layer 2. - - ---- - -## What is a Validator? - -Validators help secure the Celo network by participating in Celo’s proof-of-stake protocol. Validators are organized into Validator Groups, analogous to parties in representative democracies. A Validator Group is essentially an ordered list of Validators. - -Just as anyone in a democracy can create their own political party, or seek to get selected to represent a party in an election, any Celo user can create a Validator group and add themselves to it, or set up a potential Validator and work to get an existing Validator group to include them. - -While other Validator Groups will exist on the Celo Network, the fastest way to get up and running with a Validator will be to register a Validator Group, register a Validator, and affliate that Validator with your Validator Group. The addresses used to register Validator Groups and Validators must be unique, which will require that you create two accounts in the step-by-step guide below. - -Because of the importance of Validator security and availability, Validators are expected to run a "proxy" node in front of each Validator node. In this setup, the Proxy node connects with the rest of the network, and the Validator node communicates only with the Proxy, ideally via a private network. - -[Read more about Celo's mission and why you may want to become a Validator.](https://medium.com/celoorg/calling-all-chefs-become-a-celo-validator-c75d1c2909aa) - This article still uses the term Celo Gold which is the deprecated name for the Celo native asset, which now is referred to simply as "Celo" or preferably "CELO". \ No newline at end of file diff --git a/legacy/validator/security.mdx b/legacy/validator/security.mdx deleted file mode 100644 index 82ebc7c81..000000000 --- a/legacy/validator/security.mdx +++ /dev/null @@ -1,32 +0,0 @@ ---- -title: "Run Secure Nodes and Services" -sidebarTitle: "Nodes and Services" -og:description: Recommendations for running secure Celo nodes and services. ---- - -Recommendations for running secure Celo nodes and services. - - -This page describes the historical Celo Layer 1 blockchain. It is useful for understanding Celo’s history, but does not reflect the current state of the network. As of block height 31,056,500 (March 26, 2025, 3:00 AM UTC), Celo has transitioned to an Ethereum Layer 2. - - ---- - - -Running Celo nodes and services securely, especially as part of running a validator, is of utmost importance. Failure to do so can lead to severe consequences including, but not limited to loss of funds, slashing due to double signing, etc. - - -### RPC Endpoints - -Celo nodes can be interacted with through an RPC interface for common interactions such as querying the blockchain, inspecting network connectivity and much more. The RPC interface is exposed via HTTP, WebSockets or a local IPC socket. There are two considerations: - -1. There is no authentication in the RPC interface. Anyone with access to the interface will be able to execute any actions that are enabled with the command-line options. This includes sensitive RPC modules like `personal` which interacts with the private keys stored on the node (`admin` is another one). It is not recommended to enable RPC modules unless you explicitly need them. Other RPC modules might be less sensitive but could create unnecessary load on your machine (like the `debug` module) to execute a DoS attack. - -2. If you do need access to the RPC modules (for example to use `celocli` or the attestation service), use a firewall and similar mechanisms to restrict access to the RPC interface. You almost never want the interface to be accessible from outside the machine itself. - -### Public Endpoints - -Beyond the RPC interface, Celo nodes and services have other interfaces that actually need to be exposed to the public internet. While varying degrees of protection exist within the software, such as validating attestation requests against the blockchain or monitoring connections in the discovery protocol, additional measures are recommended to reduce the impact of malicious traffic. Examples include, but are not limited to: - -- **DDoS protection:** Protected public endpoints from a DDoS attack is highly recommended to allow valid requests to be served -- **Whitelist endpoints:** The attestation service exposes a limited number of paths to function correctly. You could use a reverse proxy to reject paths that don't match them. \ No newline at end of file diff --git a/legacy/validator/troubleshooting-faq.mdx b/legacy/validator/troubleshooting-faq.mdx deleted file mode 100644 index 514f6e3c7..000000000 --- a/legacy/validator/troubleshooting-faq.mdx +++ /dev/null @@ -1,59 +0,0 @@ ---- -title: "Validator FAQ" -sidebarTitle: "Validator FAQ" -og:description: Answers to frequently asked questions while troubleshooting issues as a Validator. ---- - -Answers to frequently asked questions while troubleshooting issues as a Validator. - - -This page describes the historical Celo Layer 1 blockchain. It is useful for understanding Celo’s history, but does not reflect the current state of the network. As of block height 31,056,500 (March 26, 2025, 3:00 AM UTC), Celo has transitioned to an Ethereum Layer 2. - - ---- - -## How do I reset my local Celo state? - -You may desire to reset your local chain state when updating parameters or wishing to perform a clean reset. Note that this will cause the node to resync from the genesis block which will take a couple hours. - -```bash -# Remove the celo state directory -sudo rm -rf celo -``` - -## How do I backup a local Celo private key? - -It's important that local accounts are properly backed up for disaster recovery. The local keystore files are encrypted with the specified account password and stored in the keystore directory. To copy this file to your local machine you may use ssh: - -```bash -ssh USERNAME@IPADDRESS "sudo cat /root/.celo/keystore/" > ./nodeIdentity -``` - -You can then back this file up to a cloud storage for redundancy. - - -It's important that you use a strong password to encrypt this file since it will be held in potentially insecure environments. - - -## How do I install and use celocli on my node? - -To install celocli on a Linux machine, run the following: - -```bash -sudo apt-get update -sudo apt-get install libusb-1.0-0 -y -sudo npm install -g @celo/celocli --unsafe-perm -``` - -To install celocli on a Mac/Windows machine, run the following: - -```bash -npm install @celo/celocli -``` - -You can then run celocli and point it to your local geth.ipc file: - -```bash -# Check if node is synced using celocli -sudo celocli node:synced --node geth.ipc -``` \ No newline at end of file diff --git a/legacy/validator/validator-explorer.mdx b/legacy/validator/validator-explorer.mdx deleted file mode 100644 index a605d9028..000000000 --- a/legacy/validator/validator-explorer.mdx +++ /dev/null @@ -1,109 +0,0 @@ ---- -title: Validator Explorer -og:description: How to use the Validator Explorer to view Validator performance. ---- - -How to use the Validator Explorer to view Validator performance. - - -This page describes the historical Celo Layer 1 blockchain. It is useful for understanding Celo’s history, but does not reflect the current state of the network. As of block height 31,056,500 (March 26, 2025, 3:00 AM UTC), Celo has transitioned to an Ethereum Layer 2. - - ---- - -## Introduction to the Explorer - **Deprecated** - -You can interact with the Validator Explorer that allows you to have a complete view of how the different validators are performing. This is one resource voters may use to find validator groups to vote for. - -All of the existing validators and groups in the Celo network are included in this view. The default view shows all registered validator groups - if you click on any of the group names it will expand to show the validators affiliated with that group. You can also sort results by each column's value by clicking on the header field. - -If you are looking to see how your validator is performing, you should first find the group your validator is affiliated with. Then you can click on the group name to see your validator and the rest of the validators affiliated with this group. - -If you are running a validator group, one way to demonstrate your credibility to voters is claiming your validator badges by following the instructions [here](https://github.com/celo-org/website/blob/master/validator-badges/README.md). - -A critical element of this explorer is the Validator Group name, which can help voters recognize organizations or active community members. This name is fetched from the `account` information registered on-chain for your validator and validator group. In order to combat name impersonation, a group can register a domain claim within their metadata. This verification is done by adding a [TXT record](https://wikipedia.org/wiki/TXT_record) to their domain which includes a signature of their domain claim signed by their associated account. This claim is then verified by the validator explorer. Individual users may also verify a claim using `celocli account:get-metdata`. - -For example, if a group was run by the owners of `example.com`, they may want to register their Validator Group with the name `Example`. The name does not need to be the same as the name of your domain, but for simplicity we do so here. To give credence to this name, they may want to add a DNS claim. They can do this by adding a DNS claim to their metadata, claiming the URL `example.com`, while simultaneously adding a `TXT Record` to `example.com` that includes this claim signed by their group address. Let’s go through this example in detail, using a `ReleaseGold` contract as our validator group. - -Assuming you have already deployed your Validator Group via a `ReleaseGold` contract, you will need these environment variables set to claim your domain. - -### Environment variables - -| Variable | Explanation | -| ----------------------------------- | ------------------------------------------------------------------------------- | -| CELO_VALIDATOR_GROUP_RG_ADDRESS | The `ReleaseGold` contract address for the Validator Group | -| CELO_VALIDATOR_RG_ADDRESS | The `ReleaseGold` contract address for the Validator | -| CELO_VALIDATOR_SIGNER_ADDRESS | The address of the validator signer authorized by the validator account | -| CELO_VALIDATOR_GROUP_SIGNER_ADDRESS | The address of the validator (group) signer authorized by the validator account | - -First let's create the metadata file: - -```bash -# On your local machine -celocli account:create-metadata ./group_metadata.json --from $CELO_VALIDATOR_GROUP_RG_ADDRESS -``` - -Now we can set the group's name: - -```bash -# On your local machine -celocli releasecelo:set-account --contract $CELO_VALIDATOR_GROUP_RG_ADDRESS --property name --value Example.com -``` - -Now we can generate a claim for the domain associated with this name `example.com`: - -```bash -# On your local machine -celocli account:claim-domain ./group_metadata.json --domain example.com --from $CELO_VALIDATOR_GROUP_SIGNER_ADDRESS -``` - -This will output your claim signed under the provided signer address. This output should then be recorded via a `TXT Record` on your desired domain, so in this case we should add a `TXT Record` to `example.com` with this signed output. - -You can now view and simultaneously verify the claims on your metadata: - -```bash -# On your local machine -celocli account:show-metadata ./group_metadata.json -``` - -Take a look at the output and verify these claims look right to you. This tool also automatically verifies the signatures on claims you've added. - -Once that record is added, we can then register this metadata under on our `Validator Group` account for external validation. - -Before we do this, you may also want to associate some validators with this domain. The benefit of doing this is to extend your DNS claim to your validators as well, meaning your validators can also verifiably be associated with your domain. You could also do this by adding individual DNS claims for each validator, but this would require separate `TXT Record`s for each, which is inconvenient. Instead, you can simply associate the group and validators together under a single claim. - -In order to do so, you will need to claim each validator address on your group's metadata. You will also need to claim your group account on each of your validator's metadata to complete the association. We will run through an example of a single validator now: - -First lets claim the `validator` address from the `group` account: - -```bash -# On your local machine -celocli account:claim-account ./group_metadata.json --address $CELO_VALIDATOR_RG_ADDRESS --from $CELO_VALIDATOR_GROUP_SIGNER_ADDRESS -``` - -Now let's submit the corresponding claim from the `validator` account on the `group` account (note: if you followed the directions to set up the attestation service, you may have already registered metadata for your validator. If that is the case, skip the steps to create the `validator`'s metadata and just add the account claim.) - -```bash -# On your local machine -celocli account:create-metadata ./validator_metadata.json --from $CELO_VALIDATOR_RG_ADDRESS -celocli account:claim-account ./validator_metadata.json --address $CELO_VALIDATOR_GROUP_RG_ADDRESS --from $CELO_VALIDATOR_SIGNER_ADDRESS -``` - -And then host both metadata files somewhere reachable via HTTP. You can use a service like gist.github.com. Create two gists, each with the contents of the respective files and then click on the Raw button to receive the permalinks to the machine-readable file. If you had already registered a metadata URL for your `validator` you just need to update that registerd gist, so you can skip the `validator` metadata registration below. - -Now we can register these URLs on each account: - -```bash -# On your local machine -celocli releasecelo:set-account --contract $CELO_VALIDATOR_GROUP_RG_ADDRESS --property metaURL --value -celocli releasecelo:set-account --contract $CELO_VALIDATOR_RG_ADDRESS --property metaURL --value -``` - -If everything goes well users should be able to see your claims by running: - -```bash -# On your local machine -celocli account:get-metadata $CELO_VALIDATOR_GROUP_RG_ADDRESS -``` - -If everything went well, you should now have your group and validator associated with each other and with your associated domain! \ No newline at end of file diff --git a/legacy/validator/voting.mdx b/legacy/validator/voting.mdx deleted file mode 100644 index 8b679f32d..000000000 --- a/legacy/validator/voting.mdx +++ /dev/null @@ -1,96 +0,0 @@ ---- -title: Voting for Validator Groups -og:description: Overview of Validator elections for Validator groups including technical details, policies, and explorers. ---- - -Resources for Validator Groups elections including technical details, policies, and Validator explorers. - - -This page describes the historical Celo Layer 1 blockchain. It is useful for understanding Celo’s history, but does not reflect the current state of the network. As of block height 31,056,500 (March 26, 2025, 3:00 AM UTC), Celo has transitioned to an Ethereum Layer 2. - - ---- - -## What are Validators? - -Validators play a critical role in the Celo protocol, determining which transactions get applied and producing new blocks. Selecting organizations that operate well-run infrastructure to perform this role effectively is essential for Celo's long-term success. - -The Celo community makes these decisions by locking CELO and voting for [Validator Groups](/legacy/protocol/pos/validator-groups), intermediaries that sit between voters and Validators. Every Validator Group has an ordered list of up to 5 candidate Validators. Some organizations may operate a group with their own Validators in it; some may operate a group to which they have added Validators run by others. - - -If you would like to keep up-to-date with all the news happening in the Celo community, including validation, node operation and governance, please sign up to our [Celo Signal mailing list here](https://share.hsforms.com/1Qrhush1vSA2WIamd_yL4ow53n4j). - -You can add the [Celo Signal public calendar](https://calendar.google.com/calendar/u/0/embed?src=c_9su6ich1uhmetr4ob3sij6kaqs@group.calendar.google.com) as well which has relevant dates. - - -## Validator Elections - -[Validator elections](/legacy/protocol/pos/validator-elections) are held every epoch (approximately once per day). The protocol elects a maximum of 110 Validators. At each epoch, every elected Validator must be re-elected to continue. Validators are selected [in proportion](/legacy/protocol/pos/validator-elections#running-the-election) to votes received for each Validator Group. - -If you hold CELO, or are a beneficiary of a [`ReleaseGold` contract](/home/manage/release-gold) that allows voting, you can vote for Validator Groups. A single account can split their LockedGold balance to have outstanding votes for up to 10 groups. - -CELO that you lock and use to vote for a group that elects one or more Validators receives [epoch rewards](/legacy/protocol/pos/epoch-rewards) every epoch (approximately every day) once the community passes a governance proposal enabling rewards. The initial level of rewards is anticipated to be around 6% per annum equivalent (but is subject to change). - -Unlike a number of Proof of Stake protocols, **CELO used for voting is never at risk**. The actions of the Validator Groups or Validators you vote for can cause you to receive lower or higher rewards, but the CELO you locked will always be available to be unlocked in the future. [Slashing](/legacy/protocol/pos/penalties) in the Celo protocol applies only to Validators and Validator Groups. - -## Choosing a Validator Group - -As a CELO holder, you have the opportunity to impact the Celo network by voting for Validator Groups. As Validators play an integral role in securing Celo, it is crucial that voters choose groups that contribute to both the technical health of the network, as well as the community. Some factors to consider when deciding which Validator Group to vote for include: - -### Technical - -- **Proven identity:** Validators and groups can supply [verifiable DNS claims](/legacy/validator/validator-explorer). You can use these to securely identify that the same entity has access both to the account of a Validator or group and the supplied DNS records. - -- **Can receive votes**: Validator Groups can receive votes up to a certain [voting cap](/legacy/protocol/pos/validator-elections#group-voting-caps). You cannot vote for groups with a balance that would put it beyond its cap. - -- **Will get elected**: CELO holders only receive voter rewards during an epoch if their CELO is used to vote for a Validator Group that elects at least one Validator during that epoch. Put another way, your vote does not contribute to securing the network or earning you rewards if your group does not receive enough other votes to elect at least one Validator. - -- **Secure**: The operational security of Validators is essential for everyone's use of the Celo network. You can see scores under the "Master Validator Challenge" column in the Stake Off leaderboard. Scores of 80% or greater were awarded the "Master Validator" badge, indicating a serious proven commitment to operational security. - -- **Reliable**: Celo's consensus protocol relies on two-thirds of elected Validators being available in order to produce blocks and process transactions. Voter rewards are directly tied to the [uptime score](/legacy/protocol/pos/epoch-rewards-validator#calculating-uptime-score) of all elected Validators in the group for which the vote was made. Any period of consecutive downtime greater than a minute reduces a Validator's uptime score. - -- **No recent slashing:** When Validators and groups register, their Locked Gold becomes "staked", in that it is subject to penalties for conduct that could seriously adversely affect the health of the network. Voters' Locked Gold is never slashed, but voter rewards are affected by a group's [slashing penalty](/legacy/protocol/pos/epoch-rewards-validator#calculating-slashing-penalty), which is halved when a group or one of its Validators is slashed. Look for groups with a last slashing time long in the past, ideally `0` (never), and a slashing penalty value of `1.0`. - -- **Runs an Attestation Service**: The [Attestation Service](/legacy/protocol/identity/) is an important service that Validators can run that allows users to verify that they have access to a phone number and map it to an address. Supporting Validators that run this service makes it easier for new users to begin using Celo. - -- **Runs a Validator on Baklava**: A group that runs a Validator on the [Baklava](/build-on-celo/network-overview) helps maintain the testnet and verify that upgrades to the Celo Blockchain software can be deployed smoothly. - -### Community - -- **Promotes the Celo mission**: Celo's mission is to [build a monetary system that creates the conditions of prosperity for all](https://medium.com/celoorg/an-introductory-guide-to-celo-b185c62d3067). Consider Validator Groups that further this mission through their own activities or initiatives around financial inclusion, education and sustainability. - -- **Broadens Diversity**: The Celo community aims to be inclusive to the largest number of contributors, with the most varied and diverse backgrounds possible. Support that diversity by considering what new perspectives and strengths the teams you support offer. As well as the backgrounds and experiences of the team, consider that the network security and availability is improved by Validators operating at different network locations, on different platforms, and with different toolchains. - -- **Contributes to Celo:** Support Validator Groups that strengthen the Celo developer community, for example through building or operating services for the Celo ecosystem, participating actively in on-chain governance, and answering questions and supporting others, on [Discord](https://chat.celo.org) or the [Forum](https://forum.celo.org). - -## The Celo Foundation Voting Policy - -As described above, there are many criteria to consider when deciding which group to vote for. While it is highly recommended that all CELO holders do their independent research when deciding which group to vote for, another option is to vote for Validator Groups that have received votes from the Celo Foundation. - -The Celo Foundation has a [Validator Group voting policy](/legacy/validator/celo-foundation-voting-policy) that it follows when voting with the CELO that it holds. This policy has been developed by the Foundation board and technical advisors with the express goal of promoting the long-term security and decentralization of the network. Validator Groups have an opportunity to apply for Foundation votes every 3 months, and a new cohort is selected based on past performance and contributions. - -You can find the [full set of Validator Groups currently receiving votes, and their addresses linked here](https://docs.google.com/spreadsheets/d/1ltVNkQfXW3lIZxXU52R3IXeD6w21oacWFVb3a-FYRBY/edit?usp=sharing). - -## Validator Explorers - -The Celo ecosystem includes a number of great services for browsing registered Validator Groups and Validators. - - -**Warning**: Exercise caution in relying on Validator-supplied names to determine their real-world identity. Malicious participants may attempt to impersonate other Validators in order to attract votes. - -Validators and groups can also supply [verifiable DNS claims](/legacy/validator/validator-explorer), and the Celo Validator Explorer displays these. You can use these to securely identify that the same entity has access both to the account of a Validator or group and the supplied DNS records. - - -### [Celo Mondo Validator Explorer](https://mondo.celo.org/) ([cLabs](https://clabs.co)) - -The Celo Mondo "Staking" tab displays information for Mainnet Validators. - -### [Celovote Scores](https://celovote.com/scores) (WOTrust | celovote.com) - -Celovote shows a ranking of Validator groups based on their estimated annual rate of return (ARR). -The estimate is calculated based on past performance. - -### [Vido](https://vido.atalma.io/celo/block-map) ([Atalma](https://www.atalma.io/)) - -Vido is a block visualization and monitoring suite for Mainnet and the Baklava testnet. -It shows missed blocks and downtime for the Validator group set and subscribable metrics to get alerted if your Validator is no longer signing. \ No newline at end of file diff --git a/specs/l2-migration.mdx b/specs/l2-migration.mdx index 2bda3c9e8..a040fa402 100644 --- a/specs/l2-migration.mdx +++ b/specs/l2-migration.mdx @@ -475,6 +475,10 @@ Refer to the [proposal](https://forum.celo.org/t/proposal-validator-engagement-d For the Celo L1, the `effectiveGasPrice` for CIP-64 txs is only available until the block state is pruned. Afterwards, the blockchain client is unable to get the `baseFee` for the relevant `feeCurrency`, which is required to calculate the `effectiveGasPrice`. To avoid this and make the `effectiveGasPrice` available permanently, the `baseFee` is [included as the last field in the RLP-encoded CIP-64 receipt](https://github.com/celo-org/op-geth/commit/6a1996f17b2ae22fcb3c24b82acbaffa1753f667) for CIP-64 txs submitted after the L2 migration. The EIP-2718 `ReceiptPayload` for this transaction type is now `rlp([status, cumulativeGasUsed, logsBloom, logs, baseFee])`. +### Contract Code Size Limit + +The hardcoded protocol parameter `MaxCodeSize` is raised from 24576 to 65536. + ### CIP diff For a full list of changes by CIP, refer to the forum post: [Executed CIPs and Key Changes in Celo’s transition to L2](https://forum.celo.org/t/executed-cips-and-key-changes-in-celo-s-transition-to-l2/10664). From 7b81120857260935428dbcbdcd06124eb63b30a9 Mon Sep 17 00:00:00 2001 From: Paul Lange Date: Mon, 24 Aug 2026 17:14:08 +0200 Subject: [PATCH 3/7] docs: re-point all inbound links from deleted legacy/ pages to their successors --- .../fee-abstraction/using-fee-abstraction.mdx | 4 ++-- build-on-celo/index.mdx | 4 ++-- .../community-rpc-nodes/how-it-works.mdx | 4 ++-- .../community-rpc-nodes/registering-as-rpc-node.mdx | 4 ++-- home/manage/asset.mdx | 2 +- home/manage/self-custody.mdx | 12 ++++++------ home/wallets.mdx | 2 +- infra-partners/notices/archive/isthmus-upgrade.mdx | 2 +- .../contractkit/migrating-to-contractkit-v1.mdx | 2 +- .../contractkit/notes-web3-with-contractkit.mdx | 2 +- tooling/libraries-sdks/contractkit/odis.mdx | 2 +- tooling/oracles/index.mdx | 2 +- tooling/oracles/run.mdx | 2 +- tooling/overview/migrate/from-ethereum.mdx | 4 ++-- tooling/wallets/index.mdx | 2 +- tooling/wallets/metamask/use.mdx | 2 +- 16 files changed, 26 insertions(+), 26 deletions(-) diff --git a/build-on-celo/fee-abstraction/using-fee-abstraction.mdx b/build-on-celo/fee-abstraction/using-fee-abstraction.mdx index 423651682..f51672868 100644 --- a/build-on-celo/fee-abstraction/using-fee-abstraction.mdx +++ b/build-on-celo/fee-abstraction/using-fee-abstraction.mdx @@ -33,7 +33,7 @@ Allowlisted addresses may be **adapters** rather than full ERC20 tokens. Adapter To get the underlying token address for an adapter, call `adaptedToken()` on the adapter contract. Newer adapters — including the USD₮ and USA₮ ones — expose this as `getAdaptedToken()` instead, so try both if the first call reverts. -For more on gas pricing, see [Gas Pricing](/legacy/protocol/transaction/gas-pricing). +For more on gas pricing, see [Transaction Fees](/specs/transaction-fees). ### Adapter Addresses @@ -140,7 +140,7 @@ async function main() { ### 2. Prepare the Transaction -Set `feeCurrency` to the adapter address (USDC/USD₮/USA₮) or token address (USDm, EURm, BRLm). Use transaction type `123` (`0x7b`), which is [CIP-64](/legacy/protocol/transaction/transaction-types) compliant. +Set `feeCurrency` to the adapter address (USDC/USD₮/USA₮) or token address (USDm, EURm, BRLm). Use transaction type `123` (`0x7b`), which is [CIP-64](/home/protocol/transactions/transaction-types) compliant. ```js let tx = { // ... other transaction fields diff --git a/build-on-celo/index.mdx b/build-on-celo/index.mdx index 9aca98af1..11fb8ed29 100644 --- a/build-on-celo/index.mdx +++ b/build-on-celo/index.mdx @@ -71,6 +71,6 @@ Following a successful Baklava upgrade, the Celo L2 Mainnet officially went live * [Layer 2 Specification](/specs) * [Node Operator Guide](/infra-partners/operators/overview) -* [What's Changed?](/legacy/overview) +* [About Celo L1](/home/celo-l1) * [Cel2 Code](https://github.com/celo-org/optimism) -* [FAQ](/legacy/faq) +* [FAQ](/infra-partners/operators/faq) diff --git a/contribute-to-celo/community-rpc-nodes/how-it-works.mdx b/contribute-to-celo/community-rpc-nodes/how-it-works.mdx index c160f7192..885066f89 100644 --- a/contribute-to-celo/community-rpc-nodes/how-it-works.mdx +++ b/contribute-to-celo/community-rpc-nodes/how-it-works.mdx @@ -17,11 +17,11 @@ The term "validator" is used in the code and corresponding explanation due to hi ## RPC Elections -In Celo's RPC elections (formerly [validator elections](/legacy/protocol/pos/validator-elections)), holders of the native asset CELO participate in the process to support network operations and earn rewards for voting. +In Celo's RPC elections (formerly [validator elections](/home/protocol/staking/validator-elections)), holders of the native asset CELO participate in the process to support network operations and earn rewards for voting. The election process follows these steps: -1. **Lock CELO tokens**: Holders must first move their CELO balances into the [Locked Celo](/legacy/protocol/pos/locked-gold) (formerly "Celo Gold") smart contract before participating in elections. +1. **Lock CELO tokens**: Holders must first move their CELO balances into the [Locked Celo](/home/protocol/staking/locked-celo) (formerly "Celo Gold") smart contract before participating in elections. 2. **Vote for Groups**: Rather than voting directly for individual node providers, accounts cast their votes for validator groups that manage collections of nodes. diff --git a/contribute-to-celo/community-rpc-nodes/registering-as-rpc-node.mdx b/contribute-to-celo/community-rpc-nodes/registering-as-rpc-node.mdx index fdc77e751..45df4f734 100644 --- a/contribute-to-celo/community-rpc-nodes/registering-as-rpc-node.mdx +++ b/contribute-to-celo/community-rpc-nodes/registering-as-rpc-node.mdx @@ -33,7 +33,7 @@ If you don't have enough CELO, you can practice the registration process on the Private keys are the central primitive of any cryptographic system and need to be handled with extreme care. Loss of your private key can lead to irreversible loss of assets. -This guide contains a large number of keys, so it is important to understand the purpose of each key. [Read more about key management.](/legacy/validator/key-management/summary) +This guide contains a large number of keys, so it is important to understand the purpose of each key. [Read more about key management.](/home/protocol/staking/key-management/summary) ### Account and Signer Keys @@ -135,7 +135,7 @@ For detailed instructions on registering your node URL and metadata, see [Regist ## Register the Nodes and Group -To participate in elections as an RPC provider, you must register both your group and individual node. When registering a Group, you'll need to specify a [commission](/legacy/protocol/pos/validator-groups#group-share) - this is the percentage of epoch rewards that group members pay to the group. +To participate in elections as an RPC provider, you must register both your group and individual node. When registering a Group, you'll need to specify a [commission](/home/protocol/staking/validator-groups#group-share) - this is the percentage of epoch rewards that group members pay to the group. Since we want to keep our account key secure, we'll first authorize the validator signing key instead of using the account key for validation: diff --git a/home/manage/asset.mdx b/home/manage/asset.mdx index ce480a240..e1c17be94 100644 --- a/home/manage/asset.mdx +++ b/home/manage/asset.mdx @@ -17,7 +17,7 @@ For the most up-to-date information, refer to our [Celo L2 documentation](/build This guide assumes: -- You have read [Key Management](/legacy/validator/key-management/summary) on Celo +- You have read [Key Management](/home/protocol/staking/key-management/summary) on Celo - You have installed the [Celo Command Line Interface](/cli/) (Celo CLI) ## Choose a Node diff --git a/home/manage/self-custody.mdx b/home/manage/self-custody.mdx index 5f517a44f..0d380aaed 100644 --- a/home/manage/self-custody.mdx +++ b/home/manage/self-custody.mdx @@ -43,7 +43,7 @@ In this guide, you will: - Access the `ReleaseGold` account associated with your address using your existing Ledger - Authorize a voting key, which you will hold on a new, second Ledger - Lock some of the Gold in your `ReleaseGold` account -- Use that Locked CELO to vote for Validator Groups to operate Celo's [Proof of Stake](/legacy/protocol/pos/index/) network (and in doing so be ready to receive epoch rewards of 6% when the community enables them in a forthcoming governance proposal) +- Use that Locked CELO to vote for Validator Groups to operate Celo's [staking](/home/protocol/staking/index) mechanism (and in doing so be ready to receive [epoch rewards](/home/protocol/epoch-rewards/index)) ## Preparing Ledgers @@ -149,7 +149,7 @@ Otherwise, you're all set. You don't need to take any further action right now. ## Authorize Vote Signer Keys -To allow you to keep your Beneficiary Ledger offline on a day-to-day basis, it’s recommended to use a separate [Authorized Vote Signer Account](/legacy/validator/key-management/detailed#authorized-vote-signers) that will vote on behalf of the beneficiary. +To allow you to keep your Beneficiary Ledger offline on a day-to-day basis, it’s recommended to use a separate [Authorized Vote Signer Account](/home/protocol/staking/key-management/detailed#authorized-vote-signers) that will vote on behalf of the beneficiary. A vote signer can either be another Ledger device or a cloud Hardware Security Module (HSM). @@ -260,12 +260,12 @@ celocli lockedgold:show $CELO_RG_ADDRESS Similar to staking or delegating in other Proof of Stake cryptocurrency protocols, CELO holders can lock CELO and vote for Validator Groups on the Celo network. By doing this, not only do you contribute to the health and security of the network, but you can also earn [epoch rewards](/home/protocol/epoch-rewards). -For more details, check out the [Voting for Validators page](/legacy/validator/voting), which contains useful background on how voting Validator Elections work, as well as more guidance on how to select a Validator Group to vote for. For now, all you need to know is that: +For more details, check out the [Voting for Validators page](/home/protocol/staking/voting), which contains useful background on how voting Validator Elections work, as well as more guidance on how to select a Validator Group to vote for. For now, all you need to know is that: - in Celo, CELO holders vote for Validator Groups, not Validators directly - you only earn epoch rewards if the Validator Group you voted for gets at least 1 Validator elected -Keeping this in mind, you will need to find a Validator Group to vote for and copy its address. You can find this information on community validator explorers such as the [cLabs Validator explorer](/legacy/validator/validator-explorer) and [Bi23 Labs' `thecelo` dashboard](https://thecelo.com). +Keeping this in mind, you will need to find a Validator Group to vote for and copy its address. You can find this information on community [validator explorers](/home/protocol/staking/voting#validator-explorers) such as [Celo Mondo](https://mondo.celo.org/) and [Bi23 Labs' `thecelo` dashboard](https://thecelo.com). You can also see registered Validator Groups through the Celo CLI. This will display a list of Validator Groups, the number of votes they have received, the number of additional votes they are able to receive, and whether or not they are eligible to elect Validators: @@ -354,11 +354,11 @@ Or by searching for your `ReleaseGold` address on the [Block Explorer](https://e You are now set up to participate in the Celo network! -You might want to read more about [choosing a Validator Group](/legacy/validator/voting) to vote for, and how [voter rewards](/home/protocol/epoch-rewards/index) are calculated. You can vote for up to ten different Groups from a single account. +You might want to read more about [choosing a Validator Group](/home/protocol/staking/voting) to vote for, and how [voter rewards](/home/protocol/epoch-rewards/index) are calculated. You can vote for up to ten different Groups from a single account. Now you've locked CELO, you can use it to participate in voting for or against [Governance proposals](/home/protocol/governance/voting-in-governance). You can do this without affecting any vote you have made for Validator Groups. -You can also read more about how Celo's [Proof of Stake](/legacy/protocol/pos/index/) and on-chain [Governance](/home/protocol/governance/overview) mechanisms work. +You can also read more about how Celo's [staking](/home/protocol/staking/index) and on-chain [Governance](/home/protocol/governance/overview) mechanisms work. ## Revoking Votes diff --git a/home/wallets.mdx b/home/wallets.mdx index 71443e8b5..a37e677f1 100644 --- a/home/wallets.mdx +++ b/home/wallets.mdx @@ -7,7 +7,7 @@ description: Overview of digital wallets available to send, spend, and earn Celo Celo is designed to work seamlessly with a range of wallets, each offering features to meet different user needs. -The [Celo Native Wallets](#celo-native-wallets) section provides an overview of wallets that are optimized for the Celo network. These wallets allow users to fully benefit from Celo’s native functionalities, such as [phone number mapping](/legacy/protocol/identity) and [fee abstraction](/build-on-celo/fee-abstraction/overview). +The [Celo Native Wallets](#celo-native-wallets) section provides an overview of wallets that are optimized for the Celo network. These wallets allow users to fully benefit from Celo’s native functionalities, such as [phone number mapping](/build-on-celo/build-on-socialconnect) and [fee abstraction](/build-on-celo/fee-abstraction/overview). The [Celo Compatible Wallets](#celo-compatible-wallets) section provides an overview of commonly used wallets wallets that support the Celo network. diff --git a/infra-partners/notices/archive/isthmus-upgrade.mdx b/infra-partners/notices/archive/isthmus-upgrade.mdx index 79fb79e8d..54a8980b9 100644 --- a/infra-partners/notices/archive/isthmus-upgrade.mdx +++ b/infra-partners/notices/archive/isthmus-upgrade.mdx @@ -15,7 +15,7 @@ This page will be kept updated with key information about the hardfork. -If you're encountering a stuck node after Alfajores hardfork block (49908280), see the [FAQ](/legacy/faq#my-alfajores-node-stalled-at-the-isthmus-hardfork-block-49908280). +If you're encountering a stuck node after Alfajores hardfork block (49908280), see the [FAQ](/infra-partners/operators/faq). ## What's included in Isthmus diff --git a/tooling/libraries-sdks/contractkit/migrating-to-contractkit-v1.mdx b/tooling/libraries-sdks/contractkit/migrating-to-contractkit-v1.mdx index 063de2e4f..1619b59a2 100644 --- a/tooling/libraries-sdks/contractkit/migrating-to-contractkit-v1.mdx +++ b/tooling/libraries-sdks/contractkit/migrating-to-contractkit-v1.mdx @@ -42,7 +42,7 @@ ContractKit is a suite of packages. - `Explorer` depends on `contractkit` and `connect`. It provides some utility functions that make it easy to listen for new block and log information. - `Governance` depends on `contractkit` and `explorer`. It provides functions to read and interact with Celo Governance Proposals (CGPs). -- `Identity` simplifies interacting with [ODIS](/legacy/protocol/identity/odis), Celo’s lightweight identity layer based on phone numbers. +- `Identity` simplifies interacting with [ODIS](/build-on-celo/build-on-socialconnect), Celo’s lightweight identity layer based on phone numbers. - `Network-utils` provides utilities for getting genesis block and static node information. - `Transactions-uri` makes it easy to generate Celo transaction URIs and QR codes. diff --git a/tooling/libraries-sdks/contractkit/notes-web3-with-contractkit.mdx b/tooling/libraries-sdks/contractkit/notes-web3-with-contractkit.mdx index 775e01f59..8eca22641 100644 --- a/tooling/libraries-sdks/contractkit/notes-web3-with-contractkit.mdx +++ b/tooling/libraries-sdks/contractkit/notes-web3-with-contractkit.mdx @@ -12,7 +12,7 @@ How to use Web3 from ContractKit to read data from the Celo blockchain. 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](/legacy/overview). +For the most up-to-date information, refer to our [Celo L2 documentation](/build-on-celo/index). The ContractKit, for every interaction with the node, uses internally a Web3 instance. diff --git a/tooling/libraries-sdks/contractkit/odis.mdx b/tooling/libraries-sdks/contractkit/odis.mdx index 5b271c6f0..fb8d86281 100644 --- a/tooling/libraries-sdks/contractkit/odis.mdx +++ b/tooling/libraries-sdks/contractkit/odis.mdx @@ -22,7 +22,7 @@ ODIS requests are rate-limited based on transaction history and balance. Ensure The main ODIS method is `getObfuscatedIdentifier`, which queries and computes the on-chain identifier for an off-chain identifier such as a phone number. -See [this overview document](/legacy/protocol/identity/odis-use-case-phone-number-privacy) for more details on ODIS. +See [this overview document](/build-on-celo/build-on-socialconnect) for more details on ODIS. ## Authentication diff --git a/tooling/oracles/index.mdx b/tooling/oracles/index.mdx index 8475df74d..c9031a026 100644 --- a/tooling/oracles/index.mdx +++ b/tooling/oracles/index.mdx @@ -13,7 +13,7 @@ Here are lists of all on-chain Oracles: - [RedStone Oracles](/developer/oracles/redstone) - [Chainlink, Price Feed Oracles](https://docs.chain.link/data-feeds/price-feeds/addresses?network=celo) - [Band](/developer/oracles/band-protocol) -- [Celo Reserve Oracles](/legacy/protocol/stability/oracles) +- [Mento Oracles](https://www.mento.org/) - [Supra](https://supraoracles.com/) - [Pyth Network](https://pyth.network/) - [Randomness](https://docs.pyth.network/entropy/generate-random-numbers-evm#randomness-providers) diff --git a/tooling/oracles/run.mdx b/tooling/oracles/run.mdx index 8d9dad493..83ebf0415 100644 --- a/tooling/oracles/run.mdx +++ b/tooling/oracles/run.mdx @@ -15,7 +15,7 @@ A [reference implementation](https://github.com/celo-org/celo-oracle) of such a ## Requirements - One VM dedicated for each oracle is recommended, but it is acceptable that they run multiple instances in the case they are for different stables. -- A dedicated full node running in its own VM. Minimal hardware requirements and instructions on how to run a full node can be found [here](/legacy/validator/run/mainnet). +- A dedicated full node running in its own VM. Minimal hardware requirements and instructions on how to run a full node can be found [here](/infra-partners/operators/run-node). - The private key of an address on Celo, which can be stored on a private key file, on a Hardware Security Module (HMS) or hosted in the full nodes itself. More information about each can be found below. It is not strictly required but it is recommended to have the [Celo CLI](/cli#what-is-the-celo-cli) available at least in your local environment, and ideally in each VM. It could be especially useful to respond to on-call. diff --git a/tooling/overview/migrate/from-ethereum.mdx b/tooling/overview/migrate/from-ethereum.mdx index 3f321fcde..faf96c0dc 100644 --- a/tooling/overview/migrate/from-ethereum.mdx +++ b/tooling/overview/migrate/from-ethereum.mdx @@ -85,7 +85,7 @@ You can [view the implementation here.](https://celo.blockscout.com/address/0xaa 1) Mnemonic seed phrases can derive different accounts depending on the key derivation path used. While Ethereum wallets typically use the path `m/44'/60'/0'/0`, Celo defines its own path as `m/44'/52752'/0'/0`. Despite this, **most Celo wallets—including Valora—default to the Ethereum derivation path**, except in the case of some legacy accounts. Ledger Wallet, when used with the **Celo Ledger app**, strictly uses the Celo path. Tools like the **Celo CLI and the Celo Ledger app**, however, offer flexibility and allow users to specify either path explicitly. -2) The Valora wallet uses two types of accounts: externally owned accounts and meta-transaction wallets. There are important consequences for wallet developers and dapp developers building on Celo as Valora is one of the main interfaces for Celo users. You can find more information about [Valora accounts here](/legacy/protocol/identity/smart-contract-accounts). +2) The Valora wallet uses two types of accounts: externally owned accounts and meta-transaction wallets. There are important consequences for wallet developers and dapp developers building on Celo as Valora is one of the main interfaces for Celo users. You can find more information about [Valora accounts here](/home/celo-l1). ## Deploying Ethereum Contracts to Celo @@ -103,7 +103,7 @@ Celo includes all of the precompiled contracts in Ethereum, but also adds additi ### Core Contract Calls -The blockchain client makes some core contract calls at the end of a block, outside of transactions. Many are done on epoch blocks ([epoch rewards](/legacy/protocol/pos/epoch-rewards), [validator elections](/legacy/protocol/pos/validator-elections), etc.), but not all. For example, the [gas price minimum](/legacy/protocol/transaction/gas-pricing) update can happen on any block. +The blockchain client makes some core contract calls at the end of a block, outside of transactions. Many are done on epoch blocks ([epoch rewards](/home/protocol/epoch-rewards/index), [validator elections](/home/protocol/staking/validator-elections), etc.), but not all. For example, the [gas price minimum](/specs/transaction-fees) update can happen on any block. Logs created by these contract changes are included in a single additional receipt in that block, which references the block hash as its transaction hash, even though there is no transaction with this hash. If no logs were created by such calls in that block, no receipt is added. ### Node management APIs diff --git a/tooling/wallets/index.mdx b/tooling/wallets/index.mdx index a0cabbd2c..111d2aff5 100644 --- a/tooling/wallets/index.mdx +++ b/tooling/wallets/index.mdx @@ -8,7 +8,7 @@ sidebarTitle: "Overview" Celo is designed to work seamlessly with a range of wallets, each offering features to meet different user needs. -The [Celo Native Wallets](#celo-native-wallets) section provides an overview of wallets that are optimized for the Celo network. These wallets allow users to fully benefit from Celo’s native functionalities, such as [phone number mapping](/legacy/protocol/identity) and [fee abstraction](/build-on-celo/fee-abstraction/overview). +The [Celo Native Wallets](#celo-native-wallets) section provides an overview of wallets that are optimized for the Celo network. These wallets allow users to fully benefit from Celo’s native functionalities, such as [phone number mapping](/build-on-celo/build-on-socialconnect) and [fee abstraction](/build-on-celo/fee-abstraction/overview). The [Wallet Infrastructure](#wallet-infrastructure) section provides an overview of wallet infrastructure solutions you can integrate into your dapp to enable seamless web3 interactions for your users. diff --git a/tooling/wallets/metamask/use.mdx b/tooling/wallets/metamask/use.mdx index cdf684e74..694827e9e 100644 --- a/tooling/wallets/metamask/use.mdx +++ b/tooling/wallets/metamask/use.mdx @@ -37,7 +37,7 @@ Celo and Ethereum use different derivation paths for generating seed phrases. Be ## **Gas Fees Require CELO** -While gas on Celo can usually be paid in [many different currencies](/legacy/protocol/transaction/erc20-transaction-fees), when using MetaMask, gas fees will automatically be paid in CELO. This is because MetaMask will be using the [Ethereum-compatible Celo transaction format](https://github.com/celo-org/celo-proposals/blob/master/CIPs/cip-0035.md), which doesn't include the `feeCurrency` field. +While gas on Celo can usually be paid in [many different currencies](/build-on-celo/fee-abstraction/overview), when using MetaMask, gas fees will automatically be paid in CELO. This is because MetaMask will be using the [Ethereum-compatible Celo transaction format](https://github.com/celo-org/celo-proposals/blob/master/CIPs/cip-0035.md), which doesn't include the `feeCurrency` field. ## **Incorrect Logo** From f66279e7cac7abe0b68250028a2a985d0c75229d Mon Sep 17 00:00:00 2001 From: Paul Lange Date: Mon, 24 Aug 2026 17:16:59 +0200 Subject: [PATCH 4/7] docs: point identity redirects at in-nav odis page, drop legacy/ from AGENTS.md --- AGENTS.md | 2 +- docs.json | 38 +++++++++++++++++++------------------- 2 files changed, 20 insertions(+), 20 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 8c53c56f3..457435abb 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -8,7 +8,7 @@ Structural work in progress is tracked in the restructure epic, [#2266](https:// - A [Mintlify](https://mintlify.com) site. Content is MDX; navigation, redirects and theme live in `docs.json`. There is no build step beyond the Mintlify CLI. - `docs.json` is the single source of truth for what is reachable. **A file on disk is unreachable until it is listed under `navigation`.** -- Content directories today: `home/`, `build-on-celo/`, `tooling/`, `contribute-to-celo/`, `infra-partners/`, `specs/`, `legacy/`. +- Content directories today: `home/`, `build-on-celo/`, `tooling/`, `contribute-to-celo/`, `infra-partners/`, `specs/`. - `snippets/` holds reusable JSX/MDX (`/snippets/ColoredText.jsx`, `/snippets/YouTube.jsx`, `/snippets/AddNetworkButton.jsx`). Import with an absolute path after the frontmatter: `import {YouTube} from '/snippets/YouTube.jsx'`. - Static assets: `img/`, `images/`, `assets/`, `logo/`. diff --git a/docs.json b/docs.json index 3710eca7e..a35b78e85 100644 --- a/docs.json +++ b/docs.json @@ -709,15 +709,15 @@ }, { "source": "/celo-codebase/protocol/identity", - "destination": "/build-on-celo/build-on-socialconnect" + "destination": "/tooling/libraries-sdks/contractkit/odis" }, { "source": "/celo-codebase/protocol/identity/encrypted-cloud-backup", - "destination": "/build-on-celo/build-on-socialconnect" + "destination": "/tooling/libraries-sdks/contractkit/odis" }, { "source": "/celo-codebase/protocol/identity/index", - "destination": "/build-on-celo/build-on-socialconnect" + "destination": "/tooling/libraries-sdks/contractkit/odis" }, { "source": "/celo-codebase/protocol/identity/metadata", @@ -725,7 +725,7 @@ }, { "source": "/celo-codebase/protocol/identity/phone-number-privacy", - "destination": "/build-on-celo/build-on-socialconnect" + "destination": "/tooling/libraries-sdks/contractkit/odis" }, { "source": "/celo-codebase/protocol/identity/privacy-research", @@ -745,7 +745,7 @@ }, { "source": "/celo-codebase/protocol/identity#using-the-mapping-for-payment", - "destination": "/build-on-celo/build-on-socialconnect" + "destination": "/tooling/libraries-sdks/contractkit/odis" }, { "source": "/celo-codebase/protocol/index", @@ -753,31 +753,31 @@ }, { "source": "/celo-codebase/protocol/odis", - "destination": "/build-on-celo/build-on-socialconnect" + "destination": "/tooling/libraries-sdks/contractkit/odis" }, { "source": "/celo-codebase/protocol/odis/domains", - "destination": "/build-on-celo/build-on-socialconnect" + "destination": "/tooling/libraries-sdks/contractkit/odis" }, { "source": "/celo-codebase/protocol/odis/domains/index", - "destination": "/build-on-celo/build-on-socialconnect" + "destination": "/tooling/libraries-sdks/contractkit/odis" }, { "source": "/celo-codebase/protocol/odis/domains/sequential-delay-domain", - "destination": "/build-on-celo/build-on-socialconnect" + "destination": "/tooling/libraries-sdks/contractkit/odis" }, { "source": "/celo-codebase/protocol/odis/index", - "destination": "/build-on-celo/build-on-socialconnect" + "destination": "/tooling/libraries-sdks/contractkit/odis" }, { "source": "/celo-codebase/protocol/odis/use-cases/key-hardening", - "destination": "/build-on-celo/build-on-socialconnect" + "destination": "/tooling/libraries-sdks/contractkit/odis" }, { "source": "/celo-codebase/protocol/odis/use-cases/phone-number-privacy", - "destination": "/build-on-celo/build-on-socialconnect" + "destination": "/tooling/libraries-sdks/contractkit/odis" }, { "source": "/celo-codebase/protocol/optics", @@ -3245,31 +3245,31 @@ }, { "source": "/legacy/protocol/identity/index", - "destination": "/build-on-celo/build-on-socialconnect" + "destination": "/tooling/libraries-sdks/contractkit/odis" }, { "source": "/legacy/protocol/identity/odis", - "destination": "/build-on-celo/build-on-socialconnect" + "destination": "/tooling/libraries-sdks/contractkit/odis" }, { "source": "/legacy/protocol/identity/odis-domain", - "destination": "/build-on-celo/build-on-socialconnect" + "destination": "/tooling/libraries-sdks/contractkit/odis" }, { "source": "/legacy/protocol/identity/odis-domain-sequential-delay-domain", - "destination": "/build-on-celo/build-on-socialconnect" + "destination": "/tooling/libraries-sdks/contractkit/odis" }, { "source": "/legacy/protocol/identity/odis-use-case-phone-number-privacy", - "destination": "/build-on-celo/build-on-socialconnect" + "destination": "/tooling/libraries-sdks/contractkit/odis" }, { "source": "/legacy/protocol/identity/odis-use-case-key-hardening", - "destination": "/build-on-celo/build-on-socialconnect" + "destination": "/tooling/libraries-sdks/contractkit/odis" }, { "source": "/legacy/protocol/identity/encrypted-cloud-backup", - "destination": "/build-on-celo/build-on-socialconnect" + "destination": "/tooling/libraries-sdks/contractkit/odis" }, { "source": "/legacy/protocol/identity/smart-contract-accounts", From fb3666b849fd4541e9c5a2d8bbf5f1855179dec1 Mon Sep 17 00:00:00 2001 From: Paul Lange Date: Mon, 24 Aug 2026 17:26:16 +0200 Subject: [PATCH 5/7] docs: review fixes - CODEOWNERS legacy entry, question headings, code fences, frontmatter quotes --- .github/CODEOWNERS | 3 --- home/bridged-tokens/bridging-celo-from-ethereum.mdx | 2 +- home/bridged-tokens/withdrawing-celo-to-ethereum.mdx | 2 +- home/celo-l1.mdx | 2 +- home/protocol/metadata.mdx | 2 +- home/protocol/staking/index.mdx | 2 +- home/protocol/staking/key-management/detailed.mdx | 2 +- home/protocol/staking/key-management/key-rotation.mdx | 2 +- home/protocol/staking/key-management/summary.mdx | 2 +- home/protocol/staking/locked-celo.mdx | 2 +- home/protocol/staking/validator-elections.mdx | 2 +- home/protocol/staking/validator-groups.mdx | 6 +++--- home/protocol/staking/voting.mdx | 4 ++-- infra-partners/operators/faq.mdx | 2 +- 14 files changed, 16 insertions(+), 19 deletions(-) diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index b2ddac298..fcf7f56d4 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -18,9 +18,6 @@ # Infrastructure Partners section - Blockchain team (was cel2) /infra-partners/ @celo-org/blockchain -# Legacy section - Blockchain team (L1 content) -/legacy/ @celo-org/blockchain - # Specs section (was specs.celo.org) - Blockchain team /specs/ @celo-org/blockchain diff --git a/home/bridged-tokens/bridging-celo-from-ethereum.mdx b/home/bridged-tokens/bridging-celo-from-ethereum.mdx index fe8602523..f89def0a1 100644 --- a/home/bridged-tokens/bridging-celo-from-ethereum.mdx +++ b/home/bridged-tokens/bridging-celo-from-ethereum.mdx @@ -20,7 +20,7 @@ The following example demonstrates how to configure a file with all the details - ```js index.js + ```js import { createWalletClient, createPublicClient, http, parseEther } from "viem"; import { privateKeyToAccount } from "viem/accounts"; import { celoSepolia, sepolia } from "viem/chains"; diff --git a/home/bridged-tokens/withdrawing-celo-to-ethereum.mdx b/home/bridged-tokens/withdrawing-celo-to-ethereum.mdx index 1e6fd3c77..787f3993e 100644 --- a/home/bridged-tokens/withdrawing-celo-to-ethereum.mdx +++ b/home/bridged-tokens/withdrawing-celo-to-ethereum.mdx @@ -20,7 +20,7 @@ Withdrawals require the user to submit three transactions: The following example demonstrates how to configure a file with all the details you need for interacting with Celo Sepolia. - ```js index.js + ```js import { createPublicClient, createWalletClient, diff --git a/home/celo-l1.mdx b/home/celo-l1.mdx index 371b3fea4..650d7ebdd 100644 --- a/home/celo-l1.mdx +++ b/home/celo-l1.mdx @@ -1,5 +1,5 @@ --- -title: "About Celo L1" +title: About Celo L1 sidebarTitle: "Celo L1" description: What the Celo Layer 1 blockchain was, how it worked, and what changed when Celo became an Ethereum Layer 2 in March 2025 --- diff --git a/home/protocol/metadata.mdx b/home/protocol/metadata.mdx index ca89a6452..c4a9e4791 100644 --- a/home/protocol/metadata.mdx +++ b/home/protocol/metadata.mdx @@ -1,5 +1,5 @@ --- -title: "Metadata and Claims" +title: Metadata and Claims sidebarTitle: "Metadata" description: Connect a Celo account with off-chain identities and URLs through signed metadata files registered on the Accounts contract --- diff --git a/home/protocol/staking/index.mdx b/home/protocol/staking/index.mdx index a66a809a2..2dac44fcc 100644 --- a/home/protocol/staking/index.mdx +++ b/home/protocol/staking/index.mdx @@ -1,5 +1,5 @@ --- -title: "Staking" +title: Staking description: Lock CELO to vote in validator elections and governance, back a community RPC provider, and earn epoch rewards --- diff --git a/home/protocol/staking/key-management/detailed.mdx b/home/protocol/staking/key-management/detailed.mdx index 5edd5575f..d44b8c8bf 100644 --- a/home/protocol/staking/key-management/detailed.mdx +++ b/home/protocol/staking/key-management/detailed.mdx @@ -1,5 +1,5 @@ --- -title: "Detailed Role Descriptions" +title: Detailed Role Descriptions sidebarTitle: "Detailed Roles" description: Each Celo account role in detail, with the celocli commands to designate accounts and authorize signers --- diff --git a/home/protocol/staking/key-management/key-rotation.mdx b/home/protocol/staking/key-management/key-rotation.mdx index 9db21064c..ca318baa4 100644 --- a/home/protocol/staking/key-management/key-rotation.mdx +++ b/home/protocol/staking/key-management/key-rotation.mdx @@ -1,5 +1,5 @@ --- -title: "Signer Key Rotation" +title: Signer Key Rotation sidebarTitle: "Key Rotation" description: Replace an authorized signer key with a new one without touching the Locked CELO account key --- diff --git a/home/protocol/staking/key-management/summary.mdx b/home/protocol/staking/key-management/summary.mdx index 311260ad5..af93dfd0d 100644 --- a/home/protocol/staking/key-management/summary.mdx +++ b/home/protocol/staking/key-management/summary.mdx @@ -1,5 +1,5 @@ --- -title: "Key Management" +title: Key Management sidebarTitle: "Summary" description: The account roles and authorized signer keys used for locking CELO, voting, and managing validators on Celo --- diff --git a/home/protocol/staking/locked-celo.mdx b/home/protocol/staking/locked-celo.mdx index 80d43bb1d..556bf06c0 100644 --- a/home/protocol/staking/locked-celo.mdx +++ b/home/protocol/staking/locked-celo.mdx @@ -1,5 +1,5 @@ --- -title: "Locked CELO" +title: Locked CELO description: Lock CELO to vote in validator elections and governance while keeping the same balance available for staking --- diff --git a/home/protocol/staking/validator-elections.mdx b/home/protocol/staking/validator-elections.mdx index 532ec6c43..8c4340bd7 100644 --- a/home/protocol/staking/validator-elections.mdx +++ b/home/protocol/staking/validator-elections.mdx @@ -1,5 +1,5 @@ --- -title: "Validator Elections" +title: Validator Elections description: How Celo elects the active validator set each epoch from locked CELO votes, and how group voting caps protect the election --- diff --git a/home/protocol/staking/validator-groups.mdx b/home/protocol/staking/validator-groups.mdx index 2bf3d8803..f3438838d 100644 --- a/home/protocol/staking/validator-groups.mdx +++ b/home/protocol/staking/validator-groups.mdx @@ -1,5 +1,5 @@ --- -title: "Validator Groups" +title: Validator Groups description: How validator groups mediate between voters and validators, and how membership, commission, and voting caps work --- @@ -11,11 +11,11 @@ This page is for CELO holders choosing where to vote and for operators running a The term "validator" is used in the code and corresponding explanation due to historical reasons, but refers to the community RPC providers. -## What is a validator group? +## The role of a validator group A validator group has **members**, an ordered list of candidate validators. There is a fixed limit to the number of members that a group may have. -## Why use a validator group? +## Why groups exist Validator groups can help mitigate the information disparity between voters and validators. It is anticipated that groups might emerge that do not necessarily operate validators themselves but attract votes for their reputation for ensuring their associated validators have known real-world identities, have high uptime, are well maintained and regularly audited. Since every validator needs to be accepted by a single group to stand for election, that group will be more able to build up long-term judgements on their validators’ operational practices and security setups than each of the numerous CELO holders that might vote for it would. diff --git a/home/protocol/staking/voting.mdx b/home/protocol/staking/voting.mdx index 337c5e0d2..3177fc9cd 100644 --- a/home/protocol/staking/voting.mdx +++ b/home/protocol/staking/voting.mdx @@ -1,5 +1,5 @@ --- -title: "Voting for Validator Groups" +title: Voting for Validator Groups description: How to choose a validator group to vote for with locked CELO, and where to browse candidate groups --- @@ -11,7 +11,7 @@ This page is for CELO holders deciding where to place their validator-election v The term "validator" is used in the code and corresponding explanation due to historical reasons, but refers to the community RPC providers. -## What are validators? +## The role of validators Validators historically produced blocks on the Celo L1; after the L2 migration they [serve the network as community RPC providers](/contribute-to-celo/community-rpc-nodes/community-rpc-node). The Celo community decides who fills this role by locking CELO and voting for [Validator Groups](/home/protocol/staking/validator-groups), intermediaries that sit between voters and Validators. Every Validator Group has an ordered list of up to 5 candidate Validators. Some organizations may operate a group with their own Validators in it; some may operate a group to which they have added Validators run by others. diff --git a/infra-partners/operators/faq.mdx b/infra-partners/operators/faq.mdx index a8581cf72..34d402ccb 100644 --- a/infra-partners/operators/faq.mdx +++ b/infra-partners/operators/faq.mdx @@ -85,7 +85,7 @@ See [Transaction fees in the specs](/specs/transaction-fees): the L1 fee is alwa -The block period is 1 second. +Celo has [1-second blocks](/specs/deployments). From fa2f1c1c82e6b42fcc277681a676eca819870e0b Mon Sep 17 00:00:00 2001 From: Paul Lange Date: Mon, 24 Aug 2026 17:30:44 +0200 Subject: [PATCH 6/7] docs: fix max-groups value (10, verified on chain), add terminology note, correct withdrawal finalization delay --- home/bridged-tokens/withdrawing-celo-to-ethereum.mdx | 3 ++- home/protocol/staking/locked-celo.mdx | 8 +++++++- 2 files changed, 9 insertions(+), 2 deletions(-) diff --git a/home/bridged-tokens/withdrawing-celo-to-ethereum.mdx b/home/bridged-tokens/withdrawing-celo-to-ethereum.mdx index 787f3993e..1dc073f9e 100644 --- a/home/bridged-tokens/withdrawing-celo-to-ethereum.mdx +++ b/home/bridged-tokens/withdrawing-celo-to-ethereum.mdx @@ -112,7 +112,8 @@ The following example demonstrates how to configure a file with all the details console.log(`Withdrawal Proved: ${proveReceipt}`); /** - * The below step can take a few minutes, ideally 2 minutes. + * The fault challenge period is 7 days (proofMaturityDelaySeconds + * is 604800 on Celo mainnet and Celo Sepolia). * * Hence, you may want to use viem's `getTimeToFinalize`. * diff --git a/home/protocol/staking/locked-celo.mdx b/home/protocol/staking/locked-celo.mdx index 556bf06c0..94fa4fcc0 100644 --- a/home/protocol/staking/locked-celo.mdx +++ b/home/protocol/staking/locked-celo.mdx @@ -5,6 +5,12 @@ description: Lock CELO to vote in validator elections and governance while keepi This page is for CELO holders who want to participate in validator elections and on-chain governance. To take part, you first lock CELO; the same locked balance can vote and stake concurrently. + +**Terminology** + +The term "validator" is used in the code and corresponding explanation due to historical reasons, but refers to the community RPC providers. + + **Terminology** @@ -37,7 +43,7 @@ The flow is as follows: - An account calls `lock`, transferring an amount of CELO from their balance to the `LockedGold` smart contract. This increments the account's 'non-voting' balance by the same amount. -- Then the account calls `vote`, passing in an amount and the address of the group to vote for. This decrements the account's 'non-voting' balance and increments the 'pending' balance associated with that group by the same amount. This counts immediately towards electing validators. Note that the vote may be rejected if it would mean that the account would be voting for more than 3 distinct groups, or that the [voting cap](/home/protocol/staking/validator-elections#group-voting-caps) for the group would be exceeded. +- Then the account calls `vote`, passing in an amount and the address of the group to vote for. This decrements the account's 'non-voting' balance and increments the 'pending' balance associated with that group by the same amount. This counts immediately towards electing validators. Note that the vote may be rejected if it would mean that the account would be voting for more than 10 distinct groups, or that the [voting cap](/home/protocol/staking/validator-elections#group-voting-caps) for the group would be exceeded. - At the end of the current epoch (approximately every 24 hours), the protocol first delivers [epoch rewards](/home/protocol/epoch-rewards/index) to validators, groups and voters based on the current epoch (pending votes do not count for these purposes), and then runs an [election](/home/protocol/staking/validator-elections) to select the active validator set for the following epoch. From 0497117a61e74fa618e113ada5fbceb59892c5ef Mon Sep 17 00:00:00 2001 From: Paul Lange Date: Tue, 25 Aug 2026 11:19:13 +0200 Subject: [PATCH 7/7] docs: review fixes - add terminology note to metadata page, point Mento oracle link at their docs --- home/protocol/metadata.mdx | 6 ++++++ tooling/oracles/index.mdx | 2 +- 2 files changed, 7 insertions(+), 1 deletion(-) diff --git a/home/protocol/metadata.mdx b/home/protocol/metadata.mdx index c4a9e4791..73101915c 100644 --- a/home/protocol/metadata.mdx +++ b/home/protocol/metadata.mdx @@ -6,6 +6,12 @@ description: Connect a Celo account with off-chain identities and URLs through s This page is for validators, group operators, and tool builders who want to attach verifiable off-chain information to a Celo account. The Celo protocol's **metadata and claims** feature makes it possible to connect on-chain with off-chain identities. + +**Terminology** + +The term "validator" is used in the code and corresponding explanation due to historical reasons, but refers to the community RPC providers. + + ## Use cases - Tools want to present public metadata supplied by a validator or validator group as part of a list of candidate groups, or a list of current elected validators. diff --git a/tooling/oracles/index.mdx b/tooling/oracles/index.mdx index c9031a026..ce0b6628a 100644 --- a/tooling/oracles/index.mdx +++ b/tooling/oracles/index.mdx @@ -13,7 +13,7 @@ Here are lists of all on-chain Oracles: - [RedStone Oracles](/developer/oracles/redstone) - [Chainlink, Price Feed Oracles](https://docs.chain.link/data-feeds/price-feeds/addresses?network=celo) - [Band](/developer/oracles/band-protocol) -- [Mento Oracles](https://www.mento.org/) +- [Mento Oracles](https://docs.mento.org/mento-v3/build/integration/integrate-oracles) - [Supra](https://supraoracles.com/) - [Pyth Network](https://pyth.network/) - [Randomness](https://docs.pyth.network/entropy/generate-random-numbers-evm#randomness-providers)