diff --git a/_deprecated/what-is-celo/using-celo/index.mdx b/_deprecated/what-is-celo/using-celo/index.mdx index a9b7a3fa2..9a5c7fbf4 100644 --- a/_deprecated/what-is-celo/using-celo/index.mdx +++ b/_deprecated/what-is-celo/using-celo/index.mdx @@ -43,7 +43,6 @@ Swap and trade assets within the Celo ecosystem: - [Self-Custody CELO](/what-is-celo/using-celo/manage/self-custody) - Securely manage your own keys - [ReleaseGold](/what-is-celo/using-celo/manage/release-gold) - Understand time-locked CELO distributions -- [Exchange Assets](/what-is-celo/using-celo/manage/exchange) - Trade between Celo assets - [Asset Management](/what-is-celo/using-celo/manage/asset) - Advanced asset operations ## Participating in the Network diff --git a/docs.json b/docs.json index 3d7d26def..139738b98 100644 --- a/docs.json +++ b/docs.json @@ -102,7 +102,6 @@ "pages": [ "home/manage/self-custody", "home/manage/release-gold", - "home/manage/exchange", "home/manage/asset" ] } @@ -430,17 +429,6 @@ { "group": "Celo L2 Specs", "pages": ["infra-partners/specs"] - }, - { - "group": "Integrate with Celo", - "pages": [ - "infra-partners/integration/index", - "infra-partners/integration/general", - "infra-partners/integration/checklist", - "infra-partners/integration/custody", - "infra-partners/integration/listings", - "infra-partners/integration/cloud-hsm" - ] } ] }, @@ -1042,7 +1030,7 @@ }, { "source": "/celo-holder-guide/celo-exchange-bot", - "destination": "/home/manage/exchange" + "destination": "/home/manage/asset" }, { "source": "/celo-holder-guide/celo-recovery", @@ -1098,7 +1086,7 @@ }, { "source": "/celo-owner-guide/celo-exchange-bot", - "destination": "/home/manage/exchange" + "destination": "/home/manage/asset" }, { "source": "/celo-owner-guide/celo-recovery", @@ -1482,31 +1470,31 @@ }, { "source": "/developer-guide/integrations/checklist", - "destination": "/infra-partners/integration/checklist" + "destination": "/infra-partners/operators/overview" }, { "source": "/developer-guide/integrations/cloud-hsm", - "destination": "/infra-partners/integration/cloud-hsm" + "destination": "/infra-partners/operators/overview" }, { "source": "/developer-guide/integrations/custody", - "destination": "/infra-partners/integration/custody" + "destination": "/infra-partners/operators/overview" }, { "source": "/developer-guide/integrations/dapps", - "destination": "/infra-partners/integration" + "destination": "/infra-partners/operators/overview" }, { "source": "/developer-guide/integrations/general", - "destination": "/infra-partners/integration/general" + "destination": "/infra-partners/operators/overview" }, { "source": "/developer-guide/integrations/integrations", - "destination": "/infra-partners/integration" + "destination": "/infra-partners/operators/overview" }, { "source": "/developer-guide/integrations/listings", - "destination": "/infra-partners/integration/listings" + "destination": "/infra-partners/operators/overview" }, { "source": "/developer-guide/overview", @@ -1522,7 +1510,7 @@ }, { "source": "/developer-guide/overview/integrations/custody", - "destination": "/infra-partners/integration/custody" + "destination": "/infra-partners/operators/overview" }, { "source": "/developer-guide/overview/introduction", @@ -1634,31 +1622,31 @@ }, { "source": "/developer-resources/integrations/checklist", - "destination": "/infra-partners/integration/checklist" + "destination": "/infra-partners/operators/overview" }, { "source": "/developer-resources/integrations/cloud-hsm", - "destination": "/infra-partners/integration/cloud-hsm" + "destination": "/infra-partners/operators/overview" }, { "source": "/developer-resources/integrations/custody", - "destination": "/infra-partners/integration/custody" + "destination": "/infra-partners/operators/overview" }, { "source": "/developer-resources/integrations/dapps", - "destination": "/infra-partners/integration" + "destination": "/infra-partners/operators/overview" }, { "source": "/developer-resources/integrations/general", - "destination": "/infra-partners/integration/general" + "destination": "/infra-partners/operators/overview" }, { "source": "/developer-resources/integrations/integrations", - "destination": "/infra-partners/integration" + "destination": "/infra-partners/operators/overview" }, { "source": "/developer-resources/integrations/listings", - "destination": "/infra-partners/integration/listings" + "destination": "/infra-partners/operators/overview" }, { "source": "/developer-resources/networks/alfajores-testnet", @@ -1998,7 +1986,7 @@ }, { "source": "/holder/exchange", - "destination": "/home/manage/exchange" + "destination": "/home/manage/asset" }, { "source": "/holder/release-gold", @@ -2758,11 +2746,35 @@ }, { "source": "/integration", - "destination": "/infra-partners/integration" + "destination": "/infra-partners/operators/overview" }, { "source": "/integration/:slug*", - "destination": "/infra-partners/integration/:slug*" + "destination": "/infra-partners/operators/overview" + }, + { + "source": "/infra-partners/integration", + "destination": "/infra-partners/operators/overview" + }, + { + "source": "/infra-partners/integration/checklist", + "destination": "/infra-partners/operators/overview" + }, + { + "source": "/infra-partners/integration/cloud-hsm", + "destination": "/infra-partners/operators/overview" + }, + { + "source": "/infra-partners/integration/custody", + "destination": "/infra-partners/operators/overview" + }, + { + "source": "/infra-partners/integration/general", + "destination": "/infra-partners/operators/overview" + }, + { + "source": "/infra-partners/integration/listings", + "destination": "/infra-partners/operators/overview" }, { "source": "/contracts/:slug*", diff --git a/home/manage/exchange.mdx b/home/manage/exchange.mdx deleted file mode 100644 index 2449152cc..000000000 --- a/home/manage/exchange.mdx +++ /dev/null @@ -1,32 +0,0 @@ ---- -title: Exchange Celo Assets -og:description: How to use the Celo exchange bot to exchange CELO and Celo stable tokens. -sidebarTitle: "Exchange Assets" ---- - -How to use the Celo exchange bot to exchange CELO and Celo stable tokens. - - -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). - - ---- - - -The celo-exchange-bot is currently not being maintained. If you want to use please check and update dependencies to solve potential security vulnerabilities of old dependencies - - -## Celo Exchange Bot - -CELO (previously Celo Gold) can be exchanged for Celo stable tokens (e.g. Celo Dollar or Celo Euro) using Mento, an automated market maker that powers the [stability protocol](/legacy/protocol/stability/doto). Mento is a Constant Product Market Maker (CPMM) that allows you to exchange CELO for Celo stable tokens and vice versa. Sales of Celo stable tokens to Mento in exchange for CELO burn the Celo stable tokens from supply, and sales of CELO to Mento in exchange for Celo stable tokens mint Celo stable tokens into supply. Trades with Mento incur slippage, meaning that Mento exchanges move the price out of favor of the trader. Generally, larger trade amounts incur more significant amounts of slippage. Mento also resets the price of CELO quoted in the Celo stable token every few minutes according to a [price oracle](/legacy/protocol/stability/oracles). - -Because of slippage and the Mento price occasionally changing according to a price oracle, those who wish to mint Celo stable tokens into supply may wish to slowly sell CELO for Celo stable tokens over time, rather than in a single exchange. Executing a smaller volume exchange every few seconds over a period of time is likely to result in less slippage when minting Celo stable tokens. [celo-exchange-bot](https://github.com/celo-org/celo-exchange-bot) was created to easily allow community members to exchange CELO for Celo stable tokens over a period of time to avoid incurring significant amounts of slippage. - -## Running the bot - -[celo-exchange-bot](https://github.com/celo-org/celo-exchange-bot) is intended to be operated by the exchanger as it requires access to the source key, which must own CELO funds to exchange and is the account that performs the exchanges. Operating the bot requires some technical knowledge of dealing with keys and operating infrastructure. Currently, the bot requires the source key to be an HSM in Azure's Key Vault service. Information on how to use an Azure Cloud HSM can be found [here](/infra-partners/integration/cloud-hsm). - -See the repository's [README](https://github.com/celo-org/celo-exchange-bot) for information on building a Docker image and configurating the bot. Example infrastructure using Azure's [Container Instances](https://azure.microsoft.com/en-gb/services/container-instances/) is also provided in the repository [here](https://github.com/celo-org/celo-exchange-bot/tree/master/infrastructure-example). While the bot does require Azure Key Vault to be used for the source key and the provided example infrastructure is ran on Azure, the bot itself can be ran from anywhere as long as it's able to access its Azure Key Vault Cloud HSM. \ No newline at end of file diff --git a/home/manage/self-custody.mdx b/home/manage/self-custody.mdx index c7b8f2721..a507afc43 100644 --- a/home/manage/self-custody.mdx +++ b/home/manage/self-custody.mdx @@ -154,7 +154,7 @@ Otherwise, you're all set. You don't need to take any further action right now. 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. -A vote signer can either be another Ledger device or a cloud Hardware Security Module (HSM). Explore [this guide](/infra-partners/integration/cloud-hsm) to learn more about cloud HSM setup and celocli integration. +A vote signer can either be another Ledger device or a cloud Hardware Security Module (HSM). This is a two step process. First, you create a "proof of possession" that shows that the holder of the beneficiary key also holds the vote signer key. Then, you will use that when the beneficiary signs a transaction authorizing the vote signer key. This proves to the Celo network that a single entity holds both keys. diff --git a/infra-partners/integration/checklist.mdx b/infra-partners/integration/checklist.mdx deleted file mode 100644 index 022fa6858..000000000 --- a/infra-partners/integration/checklist.mdx +++ /dev/null @@ -1,86 +0,0 @@ ---- -title: "Checklist" -sidebarTitle: "Checklist" -og:description: Checklist for applications building and integrating on Celo. ---- - -Checklist for applications building and integrating 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). - - ---- - -## General - -### Addresses - -Addresses are identical to Ethereum addresses. When displaying and asking for user-inputted addresses, consider using and validating address checksums following the [EIP55 standard](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-55.md) to detect typos. - -For core smart contracts, developers are highly encouraged to use the Registry to reference the contracts in case they will have to be repointed (via Governance) - -### QR Codes - -Celo has [WIP QR code standard CIP16](https://github.com/celo-org/celo-proposals/pull/40) that aims to standardize how applications can ask wallets for transactions to avoid the user having to manually copy/paste addresses and other transaction metadata. - -## Custodian/Exchange - -Please read more under [Custody](/infra-partners/integration/custody), but here is a shortened version: - -### Detect Transfers - -Stable-value currencies, currently USDm and EURm, are contracts, `StableToken` and `StableTokenEUR` respectively, that can be accessed via the ERC20 interface. The native asset CELO can be accessed via the `GoldToken` ERC20 interface, or natively, similar to ETH on Ethereum. - -Addresses for those contracts can be found by querying the [registry](/developer/contractkit/contracts-wrappers-registry) or in the [Listing Guide](/infra-partners/integration/listings). - -### Proof of Stake - -Users may want to participate in Celo's Proof of Stake system to help secure the network and earn rewards. - -### Authorized Signers - -Celo's core smart contracts use Celo's `Accounts` abstraction to allow balance-moving keys to be held in cold storage, while other keys can be authorized to vote and be held in warm storage or online. - -### Release Gold - -There is an audited `ReleaseGold` smart contract which allows for the release of CELO over a set schedule through which CELO might be distributed to a user. - -## Wallets - -These suggestions apply to any application that custodies a key and allows users to interact and transfer value on the Celo platform. - -### Key Derivation - -Celo wallets should follow the [BIP44](https://github.com/bitcoin/bips/blob/master/bip-0044.mediawiki) for deriving private keys from [BIP39 mnemonics](https://github.com/bitcoin/bips/blob/master/bip-0039.mediawiki). Celo's key derivation path is at `m/44'/52752'/0'/0`. The first key typically is the `account key` that wallets should register themselves with and accept balance transfers on. The second key can be derived to be an account's `dataEncryptionKey` to allow other users on Celo to encrypt information to. - -### Identity Protocol - -Celo has a [lightweight identity protocol](/legacy/protocol/identity) that allows users to address each other via their phone number instead of addresses that Celo wallets should implement. Since user privacy is important, Celo wallets should leverage the built-in [Phone Number Privacy protocol](/legacy/protocol/identity/odis-use-case-phone-number-privacy) to protect against large-scale harvesting of user phone numbers. - -### Wallet Address - -When transferring assets to an account, wallets should check the receiving account's `walletAddress` at which they want to receive funds at. Use cases might be smart contract accounts that want different recovery characteristics, but receive funds at a different address. Also, `walletAddresses` of `0x0` should indicate that the account requires a different mechanism to acquire the `walletAddress`. - -### Transaction metadata - -USDm (aka StableToken) adds an additional method to the ERC20 interface called `transferWithComment` which allows senders to specify an additional comment that Celo wallets should support. Additionally, comments should be encrypted to the `dataEncryptionKey` when applicable. - -## Validator Group Explorers - -[Validator Group Explorers](/legacy/validator/validator-explorer) are critical to Celo's Proof of Stake system. Explorers will consider using the following standards to provide a minimum experience across all explorers. - -### Names - -All Celo accounts on `Accounts.sol` can claim any name they want. While explorers should display it, they should also be cognizant of the fraud potential. - -### Identities - -Celo accounts can make claims to existing identities, some of which are verifiable (Domain Names or Keybase profiles). Explorers should consider displaying those identities to reduce the potential for impersonation. - -### Performance indicators - -Validator Groups and their validators can perform their duties differently and explorers should reflect that to allow voters to ensure an optimal validator set. While uptime in the form of block signatures by the validators ultimately affect rewards, explorers should also consider displaying [other metrics](/legacy/validator/voting) that impact the success of the Celo ecosystem, such as validators' performance in the identity protocol. \ No newline at end of file diff --git a/infra-partners/integration/cloud-hsm.mdx b/infra-partners/integration/cloud-hsm.mdx deleted file mode 100644 index 4a1656530..000000000 --- a/infra-partners/integration/cloud-hsm.mdx +++ /dev/null @@ -1,123 +0,0 @@ ---- -title: "Using a Cloud HSM" -sidebarTitle: "Cloud HSM" -og:description: How to create a cloud HSM in Azure and connect it to celocli. ---- - -How to create a cloud HSM in Azure and connect it to `celocli`. - - -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 HSM - -A cloud Hardware Security Module (HSM) provides a good balance between security and accessibility. A cloud HSM can manage a Celo private key and can be used seamlessly with `celocli` and `contractkit`. Similar to a ledger device, a key in an HSM avoids the key from ever being sent over the network or stored on disk since the key can never leave the hardware boundary and all signing is performed within the HSM. To authenticate to the HSM, it's recommended to create a service principal account that has been granted access to sign with the managed keys. A cloud HSM can be a great option for managing vote signer keys, since you may want these keys to be portable but also maintain good security practices. - -## Create an Azure subscription - -If you don't have an Azure subscription already, you can [create a free trial here](https://azure.microsoft.com/free/) that starts with $200 credit. You can [view the pricing for Eliptic Curve Cryptography (ECC) HSM keys here](https://azure.microsoft.com/pricing/details/key-vault/). - -## Deploy your Azure Key Vault - -The Key Vault can store keys, secrets, and certificates. Permission can be specified to perform certain actions across the entire Key Vault (ex. key signing). - -- Search the marketplace for "Key Vault" -- Click Create and fill out the deployment information -- Ensure you select the Premium pricing tier for HSM support -- Enable soft-delete and purge protection to ensure your keys aren't accidentally deleted - -## Create your key - -Next, we'll create the ECDSA key. - -- Navigate to your newly created Key Vault and click on the `Keys` section. -- Click on "Generate/Import" -- Select "EC-HSM" -- Select "SECP256K1" - -You'll see your newly generated key listed in the `Keys` section. - -```bash -# On your local machine -export AZURE_VAULT_NAME= -export AZURE_KEY_NAME= -``` - -## Create a Service Principal - -A Service Principal (SP) is preferred over your personal account so that permission can be heavily restricted. In general, Service Principal accounts should be used for any automation or services that need to access Azure resources. - -Use the [Cloud Shell](https://shell.azure.com/bash) to create the client credentials. - -Create a service principal and configure its access to Azure resources: - -```bash -# In the Cloud Shell -az ad sp create-for-rbac -n --skip-assignment -``` - -The account will be created and will output the account's credentials. - -```bash -{ - "appId": "generated-app-ID", - "displayName": "dummy-app-name", - "name": "http://dummy-app-name", - "password": "random-password", - "tenant": "tenant-ID" -} -``` - -Set these as environment variables so that they can be used by `celocli` or `contractkit`. - -```bash -# On your local machine -export AZURE_CLIENT_ID= -export AZURE_CLIENT_SECRET= -export AZURE_TENANT_ID= -``` - -## Grant your Service Principal access to the key - -In the Cloud Shell or Access Policies pane of the Key Vault, set the [GET, LIST, SIGN] permission for the new account. - -```bash -# In the Cloud Shell -az keyvault set-policy --name --spn $AZURE_CLIENT_ID --key-permissions get list sign -``` - -## Connecting CeloCLI to KeyVault - -Now that your environment variables are set, we just need to let `celocli` know that we want to use this Key Vault signer. We do this by passing in the flag `--useAKV` and `--azureVaultName`. Similar to `--useLedger`, all CLI commands will use the HSM signer when `--useAKV` is specified. - -```bash -# On your local machine -celocli account:list --useAKV --azureVaultName $AZURE_VAULT_NAME -``` - -Your Key Vault address will show up under "Local Addresses". If you'd like to use this key as your vote signer key, you can follow [this guide](/home/protocol/governance/voting-in-governance) and replace `--useLedger` with `--useAKV --azureVaultName $AZURE_VAULT_NAME`. - -## Connecting ContractKit to KeyVault - -To leverage your HSM keys in `contractkit`, first create an `AzureHSMWallet` object and use it to create a `ContractKit` object with `newKitFromWeb3`. Note that `AzureHSMWallet` expects AZURE_CLIENT_ID, AZURE_CLIENT_SECRET, and AZURE_TENANT_ID environment variables to be specified. - -```js -import { ContractKit, newKitFromWeb3 } from "@celo/contractkit"; -import { AzureHSMWallet } from "@celo/wallet-hsm-azure"; - -const azureVaultName = "AZURE-VAULT-NAME"; -const akvWallet = await new AzureHSMWallet(azureVaultName); -await akvWallet.init(); -console.log(`Found addresses: ${await akvWallet.getAccounts()}`); -const contractKit = newKitFromWeb3(this.web3, akvWallet); -``` - -## Summary - -You can now leverage a cloud HSM key to perform signing as a user or application. This improves both security and availability of your Celo keys. We also recommend enabling two-factor authentication across your Azure subscription and to leverage [Managed Service Identities](https://docs.microsoft.com/azure/active-directory/managed-identities-azure-resources/overview) where possible. \ No newline at end of file diff --git a/infra-partners/integration/custody.mdx b/infra-partners/integration/custody.mdx deleted file mode 100644 index 911a61f0c..000000000 --- a/infra-partners/integration/custody.mdx +++ /dev/null @@ -1,88 +0,0 @@ ---- -title: "Custody" -sidebarTitle: "Custody" -og:description: Details for custodians, exchanges, and other services that intend to custody Celo assets such as Mento stablecoins and CELO on behalf of a user. ---- - -Details for custodians, exchanges, and other services that intend to custody Celo assets such as Mento stablecoins and CELO on behalf of a user. - - -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). - - ---- - -## Custody Overview - -Generally speaking, custodying CELO, the native token on the Celo network, requires understanding the various states that CELO can exist in at any time. This is to provide useful services beyond custody such as allowing users to lock up their CELO and vote with it. Many of these "states" are implemented as smart contracts, and involve sending CELO from a user owned account to a contract address. Thus, in order to be able to show a user's true balance, services need to be able to observe every balance changing operation and reconcile CELO balances from all the various contracts and states CELO can be in. - -## Balance Model - -As a fork of Ethereum, Celo retains the account model to keep track of users' balances. Mento stablecoins (like USDm) and CELO implement the [ERC20](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-20.md) interface. As mentioned previously, it is common for smart contracts to hold balances on behalf of other addresses. One example is the [`LockedGold`](/legacy/protocol/pos/locked-gold) smart contract that holds the "locked portion of a user's `CELO` balance". Another one is the [`ReleaseGold`](https://github.com/celo-org/celo-monorepo/blob/master/packages/protocol/contracts/governance/ReleaseGold.sol) smart contract that holds `CELO` that is being released to a beneficiary address over time according to some schedule. - - -Celo assets assets exist on an independent blockchain, and although they implement the ERC20 interface, they cannot be accessed through wallets that connect to the Ethereum network. Wallets and other integrations must connect to the Celo network to transfer tokens on Celo. - - -Applications that display balances may need to be written to be aware of this possibility. - -## Transfers - -CELO and Mento stablecoins implement the ERC20 interface, as will any future stable currencies. CELO, as the native currency of the network, can also be transferred by specifying the value field of a transaction, in the same way that ETH can be transferred in Ethereum. Therefore, for CELO, application developers should be aware that transactions can be specified in both ways. - -## CELO State Machine - -CELO as described previously can also exist in various states that represent a specific user behavior. For example, if a user wants to lock CELO to either participate in consensus directly or vote, that CELO will be sent to the `LockedGold` smart contract. To understand the high level flow, please read [this description of the various states CELO can exist in](/legacy/protocol/pos/locked-gold#locking-and-voting-flow). - -## Smart Contracts - -The following smart contracts are helpful to understand in order to map the conceptual states to actual accounts and function calls. - -### Accounts - -[Accounts.sol](https://github.com/celo-org/celo-monorepo/blob/master/packages/protocol/contracts/common/Accounts.sol) allows the mapping of an address to an account in storage, after which all further functionality (locking, voting, etc.) can be accessed. - -The [`createAccount`](https://github.com/celo-org/celo-monorepo/blob/master/packages/protocol/contracts/common/Accounts.sol#L103) function indexes the address as an account in storage, and is required to differentiate an arbitrary key-pair from a user-owned account in the Celo network. - -The `Accounts` contract also allows for the authorization of various signer keys, such as a [vote signer key](https://github.com/celo-org/celo-monorepo/blob/master/packages/protocol/contracts/common/Accounts.sol#L175). This allows for the user who owns the primary account key to authorize a separate key that can only vote on behalf of the account. This allows for the ability to custody keys in a manner corresponding to their exposure or "warmth". Eg. the primary account private key can be kept in cold storage after authorizing the signer keys, which can be in warmer environments, and potentially more exposed to the network. See the [key management guide](/legacy/validator/key-management/detailed) for more details. - -### LockedGold - -[LockedGold.sol](https://github.com/celo-org/celo-monorepo/blob/master/packages/protocol/contracts/governance/LockedGold.sol), which references Celo Gold, the deprecated name for the native token, is used as part of Celo's [proof-of-stake](/legacy/protocol/pos/index/) mechanism. Users can lock CELO by sending it to the `LockedGold` contract after creating an account via the `Accounts` contract as described above. This allows users to vote in validator elections, receive epoch rewards, and participate in on-chain governance. - -There are two ways in which users can vote: - -- Directly, by sending voting transactions with the same key used to lock up CELO -- Via an authorized vote signer, which can submit voting transactions on behalf of the account with locked CELO - -`LockedGold` has a mapping of addresses to `balances` which is a [type](https://github.com/celo-org/celo-monorepo/blob/master/packages/protocol/contracts/governance/LockedGold.sol#L26) that contains both the `nonvoting` amount of CELO as well as `pendingWithdrawals`, which contain values corresponding to timestamps at which they can be withdrawn. The reason for the latter is because all locked CELO has an unlocking period that is [set at time of contract initialization](https://github.com/celo-org/celo-monorepo/blob/master/packages/protocol/contracts/governance/LockedGold.sol#L78), which is 3 days in the Celo network's deployed `LockedGold` contract. Hence, if users unlock CELO in tranches, multiple pending withdrawals could exist at once. Once the timestamp has eclipsed, CELO can be [withdrawn back to the user's address](https://github.com/celo-org/celo-monorepo/blob/master/packages/protocol/contracts/governance/LockedGold.sol#L193). - -### Election - -Once CELO has been locked via `LockedGold`, it can then be used to vote for validator groups. [Election.sol](https://github.com/celo-org/celo-monorepo/blob/master/packages/protocol/contracts/governance/Election.sol) is the contract that manages this functionality. - -The `votes` in this contract are tracked by a [Votes type](https://github.com/celo-org/celo-monorepo/blob/master/packages/protocol/contracts/governance/Election.sol#L87) which has `pending`, `active`, and `total` votes. Pending votes are those that have been cast for a validator group, and active votes are those that have been activated after an epoch, meaning that these votes generate voter rewards. - - -From a technical perspective, `ReleaseGold` can be thought of as a "puppet" account controlled by the "puppeteer", or the beneficiary private key corresponding to the `beneficiary` address in the contract. This beneficiary key can then authorize validator signer and vote signer keys that can then call respective functions associated with validating or voting. Most of the required function calls described above can be made by the signer keys directly to the `LockedGold` or `Election` contracts associated with the `ReleaseGold` account. However, some functions in the `ReleaseGold` contract are proxied to the underlying `LockedGold` or `Election` contracts, and have a separate function signature that can be called by the `beneficiary` address. Notably: - -- [`createAccount`](https://github.com/celo-org/celo-monorepo/blob/master/packages/protocol/contracts/governance/ReleaseGold.sol#L669) -- [`authorizeVoteSigner`](https://github.com/celo-org/celo-monorepo/blob/master/packages/protocol/contracts/governance/ReleaseGold.sol#L525) and similar functions for other signer keys - -Notice that all these functions have corresponding functions that are called on the underlying contract. The `ReleaseGold` contract can then just be thought of as brokering the transaction to the correct place, when necessary. - -## Other Balance Changing Operations - -In addition to transfers (both native and ERC-20) and locking / voting flows affecting user balances, there are also several additional Celo network features that may cause user balances to change: - -- Gas fee payments: the fee paid by transaction senders to use the network -- Epoch rewards distribution: reward payments to voters, validators, and validator groups - -Some of these may occur as events rather than transactions on the network, and therefore when updating balances, special attention should be paid to them. - -## Useful Tools - -Since monitoring balance changing operations is important to be able to display user balances properly, it can be helpful to use a tracing or reconciling system. [Celo Rosetta](https://github.com/celo-org/rosetta) is an RPC server that exposes an API to query the Celo blockchain, obtain balance changing operations, and construct airgapped transactions. With a special focus on getting balance change operations, Celo Rosetta provides an easy way to obtain changes that are not easily queryable using the celo-blockchain RPC. \ No newline at end of file diff --git a/infra-partners/integration/general.mdx b/infra-partners/integration/general.mdx deleted file mode 100644 index cb76a8168..000000000 --- a/infra-partners/integration/general.mdx +++ /dev/null @@ -1,78 +0,0 @@ ---- -title: "General" -sidebarTitle: "General" -og:description: General information about integrations regardless of your service or use case. ---- - -General information about integrations regardless of your service or use case. - - -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). - - ---- - -## Accessing the chain - -There are a myriad of ways through which you can access chain data. - -### Running your own node - -To be completely independent and have a reliable view into the latest chain data, you will likely want to run your own node(s). - -You can just clone [`celo-blockchain`](https://github.com/celo-org/celo-blockchain) and then run `make geth` to receive the binary. - -By default, `geth` will use `/root/.celo` as the data dir, if you would like to change that specify the `--datadir` argument. - -This is all you should need to connect to a network: - -For Mainnet: - -```bash -geth -``` - -For more command line options, please see [https://geth.ethereum.org/docs/fundamentals/command-line-options](https://geth.ethereum.org/docs/fundamentals/command-line-options) - -### Forno - -Forno is a hosted node service for interacting with the Celo network. This allow the user to get connected to the Celo Blockchain without having to run its own node. - -Can be used as an `Http Provider` with `ContractKit` - -As Forno is a public node you will have to sign transactions locally because with your own private key, because Forno doesn't store them. But don't worry, the `ContractKit` will handle this for you. - -Forno networks: - -``` -Celo Sepolia: 'https://forno.celo-sepolia.celo-testnet.org/' - -Mainnet: 'https://forno.celo.org' -``` - -### Blockscout - -We also expose data on the cLabs run blockscout instance. Blockscout itself exposes an API. - -``` -Celo Sepolia: 'https://celo-sepolia.blockscout.com/' - -Mainnet: 'https://celo.blockscout.com/' -``` - -## Signing Transactions - -Compared to Ethereum transactions, Celo transactions have an additional optional field: - -- `feeCurrency` - Specifies the address of the currency in which fees should be paid. If `null`, the native token `CELO` is assumed. - - {/* TODO: Fix this link when this part of the docs is done -[Read more about Celo Transactions](/celo-codebase/what-is-celo/about-celo-l1/protocol/transactions) */} - -To sign transactions, you have the following options: - -- Use the JSON-RPC [`sendTransaction`](https://github.com/ethereum/execution-apis/blob/c710097abda52b5a190d831eb8b1eddd3d28c603/tests/eth_sendRawTransaction/send-legacy-transaction.io) method to your node which would have the account in question unlocked. (Either manually or via a library such as `web3`) -- Use [ContractKit's](/developer/contractkit/) local signing feature. \ No newline at end of file diff --git a/infra-partners/integration/index.mdx b/infra-partners/integration/index.mdx deleted file mode 100644 index f7ae8f932..000000000 --- a/infra-partners/integration/index.mdx +++ /dev/null @@ -1,26 +0,0 @@ ---- -title: Integrate with Celo -og:description: Collection of resources to help integrate Celo with your service. -sidebarTitle: "Overview" ---- - -## Celo Integrations - -Collection of resources to help integrate Celo with your service. - - -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 provides you with the tools to easily integrate DeFi into your existing mobile application or blockchain service. Integrating with Celo allows you to accept payments, send payouts, and manage all of your DeFi needs using our global financial infrastructure. - -- [General information](/infra-partners/integration/general) -- [Integration Checklist](/infra-partners/integration/checklist) -- [Custody](/infra-partners/integration/custody) -- [Listings](/infra-partners/integration/listings) -- [Using a Cloud HSM](/infra-partners/integration/cloud-hsm) diff --git a/infra-partners/integration/listings.mdx b/infra-partners/integration/listings.mdx deleted file mode 100644 index 96afe5831..000000000 --- a/infra-partners/integration/listings.mdx +++ /dev/null @@ -1,165 +0,0 @@ ---- -title: "Listings" -sidebarTitle: "Listing" -og:description: Support for digital asset exchanges or ranking sites that would like to run a Celo node and audit your setup. ---- - -Support for digital asset exchanges or ranking sites that would like to run a Celo node and audit your setup. - - -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). - - ---- - -## Support - -If you have any questions or need assistance with these instructions, please contact cLabs or ask in the #exchanges channel on [Celo’s Discord server](https://chat.celo.org/). Remember that Discord is a public channel: never disclose recovery phrases (also known as backup keys, or mnemonics), private keys, unsanitized log output, or personal information. - -This guide will also help you find all the necessary information about brand assets, how to integrate with Celo and what useful listing information are made available to you as well as any information about looking for support. - -## Celo Brand Assets for Listing - -If you are listing Celo on your exchange, you will probably need access to the Celo Platform brand assets. They can be found [here](https://celo.org/brand-kit). - -Please ensure your use of the Celo Platform assets provided follows the brand policy found [here](https://celo.org/brand-kit-policy). - -## How To's - -### Integrating Celo With Your Infrastructure - -There are several ways to integrate the Celo Platform with your infrastructure. - -A general overview of integrations that would be relevant to you listing Celo Platform are shown [here](/infra-partners/integration/general). - -For more specific use-cases for exchanges, please checkout the [Custody and Exchange Integration Guide](/infra-partners/integration/custody) as well. - -## Important Information - -### Celo Native Asset and Stable Value Currencies - -There are key assets on the Celo network, the Celo native asset (CELO) and Mento Stablecoins, such as USDm (Mento Dollar) and EURm (Mento Euro). CELO was formerly called Celo Gold (cGLD) when the contract was deployed, so you will often see references to Celo Gold and CGLD in the codebase. To learn more about the two, please read [this](/tooling/overview/migrate/from-ethereum#the-celo-native-asset-and-mento-stablecoins) section of the docs. - -You can also view the forum post about the name change [here](https://forum.celo.org/t/proposal-to-rename-celo-gold-to-celo-native-asset/528). - -## Resources - -### Address for CELO and Stable Value Currencies - -- CELO (\$CELO) - [`0x471ece3750da237f93b8e339c536989b8978a438`](https://celo.blockscout.com/address/0x471ece3750da237f93b8e339c536989b8978a438/transactions) -- Mento Dollar (\$USDm) - [`0x765de816845861e75a25fca122bb6898b8b1282a`](https://celo.blockscout.com/address/0x765de816845861e75a25fca122bb6898b8b1282a/transactions) -- Mento Euro (\$EURm) - [`0xd8763cba276a3738e6de85b4b3bf5fded6d6ca73`](https://celo.blockscout.com/address/0xd8763cba276a3738e6de85b4b3bf5fded6d6ca73/transactions) -- Mento Brazilian Real (\$BRLm) - [`0xe8537a3d056DA446677B9E9d6c5dB704EaAb4787`](https://celo.blockscout.com/address/0xe8537a3d056DA446677B9E9d6c5dB704EaAb4787/transactions) - -### Useful API endpoints - -The following are useful API endpoints available to you that would help you in your listings of the CELO and USDm digital assets. - -#### CELO and Stable Value Currencies - -##### Total CELO supply - -For querying the API on total coins in circulation in CELO, which are the total amount of coins in existence right now, the following endpoint will provide you with that: - -```sh -$ curl https://thecelo.com/api/v0.1.js?method=ex_totalcoins -{"code":"200","msg":"success","data":{"CELO":608485841.9959723,"cUSD":10250632.56099673}} -``` - -##### Stable Value Currencies - -###### USDm Circulating Supply - -Circulating Supply refers to the # of coins that are circulating in the market and in the general public's hands. - -```sh -$ curl https://thecelo.com/api/v0.1.js?method=ex_cusd_circulating -11353464.550486518 -``` - -###### EURm Circulating Supply - -This endpoint is not yet available. - -#### CP-DOTO (Stability Algorithm) - -CP-DOTO information can be found [here](/legacy/protocol/stability/doto). - -For API endpoints useful for listing that follow [CMC requirements](https://docs.google.com/document/d/1S4urpzUnO2t7DmS_1dc4EL4tgnnbTObPYXvDeBnukCg/edit#) - -##### Mento Addresses - -- USDm/CELO contract - [`0x67316300f17f063085Ca8bCa4bd3f7a5a3C66275`](https://celo.blockscout.com/address/0x67316300f17f063085Ca8bCa4bd3f7a5a3C66275/transactions) -- EURm/CELO contract - [`0xE383394B913d7302c49F794C7d3243c429d53D1d`](https://celo.blockscout.com/address/0xE383394B913d7302c49F794C7d3243c429d53D1d/transactions) -- BRLm/CELO contract - [`0x8f2cf9855C919AFAC8Bd2E7acEc0205ed568a4EA`](https://celo.blockscout.com/address/0x8f2cf9855C919AFAC8Bd2E7acEc0205ed568a4EA/transactions) - -##### Summary - -Summary overview of market data for all tickers and all markets. These endpoints don't yet support EURm. - -```sh -$ curl https://thecelo.com/api/v0.1.js?method=ex_summary - -{"trading_pairs":"CELO_CUSD","last_price":2.6143,"lowest_ask":2.5933609958506225,"highest_bid":2.5676,"base_volume":37524.32000000003,"quote_volume":14714.520000000002,"price_change_percent_24h":3.7027120070382127,"highest_price_24h":2.649,"lowest_price_24h":2.4787}} -``` - -##### Assets - -In depth details of the assets available on the exchange. - -```sh -$ curl https://thecelo.com/api/v0.1.js?method=ex_assets - -{"code":"200","msg":"success","data":{"CELO":{"name":"CELO","unified_cryptoasset_id":"5567","can_withdraw":"true","can_deposit":"true","min_withdraw":"0.000000000000000001","max_withdraw":"0.000000000000000001","maker_fee":"0.00","taker_fee":"0.005"},"CUSD":{"name":"Celo Dollars","unified_cryptoasset_id":"825","can_withdraw":"true","can_deposit":"true","min_withdraw":"0.000000000000000001","max_withdraw":"0.000000000000000001","maker_fee":"0.00","taker_fee":"0.005"}}} -``` - -##### Ticker - -24-hour rolling window price change statistics. - -```sh -$ curl https://thecelo.com/api/v0.1.js?method=ex_ticker - -{"code":"200","msg":"success","data":{"CELO_CUSD":{"base_id":"5567","quote_id":"825","last_price":2.6124,"quote_volume":14789.520000000002,"base_volume":37720.30000000003,"isFrozen":"0"}}} -``` - -##### Orderbook - -Market depth of a trading pair. One array containing a list of ask prices and another array containing bid prices. - -```sh -$ curl https://thecelo.com/api/v0.1.js?method=ex_orderbook - -{"code":"200","msg":"success","data":{"timestamp":1601061465962,"bids":[["2.5964","100"]],"asks":[["2.622606871230003","100"]]}} -``` - -##### CELO USDm - -Recently completed (past 24h) trades. - -```sh -$ curl https://thecelo.com/api/v0.1.js?method=ex_celocusd - -{"code":"200","msg":"success","data":{"CELO_CUSD":[{"trade_id":2697341,"timestamp":1601061491,"price":0.38238291620515147,"quote_volume":25,"base_volume":65.37948987916423,"type":"Sell"},{"trade_id":2697336,"timestamp":1601061466,"price":0.382293821845672,"quote_volume":25,"base_volume":65.39472670341044,"type":"Sell"}]}} - -### Whitepapers - -To learn about the Celo Protocol, please refer to the [whitepaper](https://celo.org/papers). - -If you need more information to explore other aspects of the Celo Protocol, there's a [useful links](/home/index) page. - -To learn more about the Stability Mechanism, you can find it over [here](/legacy/protocol/stability/doto). -The [Stability Analysis Whitepaper](https://celo.org/papers/Celo_Stability_Analysis.pdf) and [blog post](https://medium.com/celohq/a-look-at-the-celo-stability-analysis-white-paper-part-1-23edd5ef8b5) will provide a lot more information on the stability algorithm. - -If you want to find more information about the Celo Reserve, a diversified portfolio of currencies supporting the ability of the Celo protocol to expand and contract the supply of Celo stable assets, please visit [https://reserve.mento.org/](https://reserve.mento.org/). -{{ ... }} -### Github - -The Celo Protocol GitHub is located [here.](https://github.com/celo-org/) - -### Audits - -All the security audits on the smart contracts, security and economics of the Celo Platform can be found [here](https://celo.org/audits). \ No newline at end of file