Skip to content

Commit

Permalink
doc: precompiles (#103)
Browse files Browse the repository at this point in the history
  • Loading branch information
MiniFrenchBread authored Jan 29, 2025
1 parent 18e72fb commit 30561eb
Show file tree
Hide file tree
Showing 6 changed files with 355 additions and 4 deletions.
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
id: contracts
title: Contracts on 0G Chain
id: deploy-contracts
title: Deploy Contracts on 0G Chain
---
# Deploying Contracts on 0G Chain

Expand Down
210 changes: 210 additions & 0 deletions docs/build-with-0g/contracts-on-0g/precompiles/dasigners.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,210 @@
---
id: precompiles-dasigners
title: DASigners
---
# Overview

DAsigners is a wrapper for the `x/dasigners` module in the 0g chain, allowing querying the state of this module from EVM calls.

# Address

`0x0000000000000000000000000000000000001000`

# Interface

[https://github.com/0glabs/0g-chain/blob/dev/precompiles/interfaces/contracts/IDASigners.sol](https://github.com/0glabs/0g-chain/blob/dev/precompiles/interfaces/contracts/IDASigners.sol)

## Structs

### `SignerDetail`
```solidity
struct SignerDetail {
address signer;
string socket;
BN254.G1Point pkG1;
BN254.G2Point pkG2;
}
```
- **Description**: Contains details of a signer, including the address, socket, and bn254 public keys (G1 and G2 points).

- **Fields**:
- `signer`: The address of the signer.
- `socket`: The socket associated with the signer.
- `pkG1`: The G1 public key of the signer.
- `pkG2`: The G2 public key of the signer.

### `Params`
```solidity
struct Params {
uint tokensPerVote;
uint maxVotesPerSigner;
uint maxQuorums;
uint epochBlocks;
uint encodedSlices;
}
```
- **Description**: Defines parameters for the DAsigners module.

- **Fields**:
- `tokensPerVote`: The number of tokens required for one vote.
- `maxVotesPerSigner`: The maximum number of votes a signer can cast.
- `maxQuorums`: The maximum number of quorums allowed.
- `epochBlocks`: The number of blocks in an epoch.
- `encodedSlices`: The number of encoded slices in one DA blob.

---

## Functions

### `params()`
```solidity
function params() external view returns (Params memory);
```
- **Description**: Retrieves the current parameters of the DAsigners module.
- **Returns**: `Params` structure containing the current module parameters.

---

### `epochNumber()`
```solidity
function epochNumber() external view returns (uint);
```
- **Description**: Returns the current epoch number.
- **Returns**: `uint` representing the current epoch number.

---

### `quorumCount(uint _epoch)`
```solidity
function quorumCount(uint _epoch) external view returns (uint);
```
- **Description**: Returns the number of quorums for a given epoch.
- **Parameters**:
- `_epoch`: The epoch number.
- **Returns**: `uint` representing the quorum count for the given epoch.

---

### `isSigner(address _account)`
```solidity
function isSigner(address _account) external view returns (bool);
```
- **Description**: Checks if a given account is a registered signer.
- **Parameters**:
- `_account`: The address to check.
- **Returns**: `bool` indicating whether the account is a signer.

---

### `getSigner(address[] memory _account)`
```solidity
function getSigner(
address[] memory _account
) external view returns (SignerDetail[] memory);
```
- **Description**: Retrieves details for the signers of the provided addresses.
- **Parameters**:
- `_account`: An array of addresses to fetch the signer details for.
- **Returns**: An array of `SignerDetail` structures for each signer.

---

### `getQuorum(uint _epoch, uint _quorumId)`
```solidity
function getQuorum(
uint _epoch,
uint _quorumId
) external view returns (address[] memory);
```
- **Description**: Returns the addresses of the members in a specific quorum for a given epoch.
- **Parameters**:
- `_epoch`: The epoch number.
- `_quorumId`: The ID of the quorum.
- **Returns**: An array of addresses that are members of the quorum.

---

### `getQuorumRow(uint _epoch, uint _quorumId, uint32 _rowIndex)`
```solidity
function getQuorumRow(
uint _epoch,
uint _quorumId,
uint32 _rowIndex
) external view returns (address);
```
- **Description**: Retrieves a specific address from a quorum's row for a given epoch and quorum ID.
- **Parameters**:
- `_epoch`: The epoch number.
- `_quorumId`: The quorum ID.
- `_rowIndex`: The row index within the quorum.
- **Returns**: The address at the specified row index in the quorum.

---

### `registerSigner(SignerDetail memory _signer, BN254.G1Point memory _signature)`
```solidity
function registerSigner(
SignerDetail memory _signer,
BN254.G1Point memory _signature
) external;
```
- **Description**: Registers a new signer with the provided details and signature.
- **Parameters**:
- `_signer`: The details of the signer to register.
- `_signature`: The signature to verify the registration.

---

### `updateSocket(string memory _socket)`
```solidity
function updateSocket(string memory _socket) external;
```
- **Description**: Updates the socket used by the module.
- **Parameters**:
- `_socket`: The new socket address to update.

---

### `registeredEpoch(address _account, uint _epoch)`
```solidity
function registeredEpoch(
address _account,
uint _epoch
) external view returns (bool);
```
- **Description**: Checks if a specific account is registered in a given epoch.
- **Parameters**:
- `_account`: The address to check.
- `_epoch`: The epoch number.
- **Returns**: `bool` indicating whether the account is registered for the specified epoch.

---

### `registerNextEpoch(BN254.G1Point memory _signature)`
```solidity
function registerNextEpoch(BN254.G1Point memory _signature) external;
```
- **Description**: Registers the next epoch using the provided signature.
- **Parameters**:
- `_signature`: The signature used to register the next epoch.

---

### `getAggPkG1(uint _epoch, uint _quorumId, bytes memory _quorumBitmap)`
```solidity
function getAggPkG1(
uint _epoch,
uint _quorumId,
bytes memory _quorumBitmap
) external view returns (BN254.G1Point memory aggPkG1, uint total, uint hit);
```
- **Description**: Retrieves the aggregated public key for a given epoch and quorum ID.
- **Parameters**:
- `_epoch`: The epoch number.
- `_quorumId`: The quorum ID.
- `_quorumBitmap`: The quorum bitmap.
- **Returns**:
- `aggPkG1`: The aggregated public key.
- `total`: The number of rows.
- `hit`: The number of rows that contributed to the aggregation.
---
24 changes: 24 additions & 0 deletions docs/build-with-0g/contracts-on-0g/precompiles/overview.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
---
id: precompiles-overview
title: Overview
---
# EVM Precompiles on 0G Chain

EVM (Ethereum Virtual Machine) precompile contracts are special, built-in contracts provided by the Ethereum protocol to perform specific, commonly-used operations more efficiently than if they were implemented in Solidity or another high-level language.

The current version of 0g chain supports the Istanbul version of the EVM and all the EVM precompiles it includes(check it out [here](https://www.evm.codes/precompiled?fork=istanbul)). In addition to the native EVM precompiles, we have also defined additional precompile contracts to enable modifying the state of Cosmos modules through EVM transactions:

* [DASigners precompile](dasigners.md)
* [Staking Precompile](staking.md)
* [WrappedA0GIBase Precompile](wrappeda0gibase.md)

# Interact with 0G Precompiles in Smart Contracts

Calling 0g precompiles in a contract can be a bit tricky. Since some of the newly added precompiles are stateful, interacting with their non-read-only functions in a contract requires using a low-level call. The `mint` function of [WA0GI](https://github.com/0glabs/A0GI-contracts/blob/main/contracts/WrappedA0GI.sol) can be used as a reference for implementation.







18 changes: 18 additions & 0 deletions docs/build-with-0g/contracts-on-0g/precompiles/staking.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
---
id: precompiles-staking
title: Staking
---

# Overview

DAsigners is a wrapper for the `x/staking` module in the 0g chain.

# Address

`0x0000000000000000000000000000000000001001`

# Interface

[https://github.com/0glabs/0g-chain/blob/dev/precompiles/interfaces/contracts/IStaking.sol](https://github.com/0glabs/0g-chain/blob/dev/precompiles/interfaces/contracts/IStaking.sol)

Basically, its functions and struct definitions are consistent with Cosmos' [staking module](https://docs.cosmos.network/v0.47/build/modules/staking).
83 changes: 83 additions & 0 deletions docs/build-with-0g/contracts-on-0g/precompiles/wrappeda0gibase.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,83 @@
---
id: precompiles-wrappeda0gibase
title: Wrapped A0GI Base
---

# Overview

WrappedA0GIBase is a wrapper for the `x/wrapped-a0gi-base` module in the 0g chain. Wrapped A0GI is a wrapped ERC20 token for native A0GI. It supports quota-based mint/burn functions based on native A0GI transfers, on top of traditional wrapped token implementation. The minting/burning quota for each address will be determined through governance voting. `x/wrapped-a0gi-base` is the module that supports and maintains the minting/burning quota.

In most cases this precompile should be only called by WA0GI contract.

# Address

`0x0000000000000000000000000000000000001002`

# Interface

[https://github.com/0glabs/0g-chain/blob/dev/precompiles/interfaces/contracts/IWrappedA0GIBase.sol](https://github.com/0glabs/0g-chain/blob/dev/precompiles/interfaces/contracts/IWrappedA0GIBase.sol)

## Structs

### `Supply`
```solidity
struct Supply {
uint256 cap;
uint256 initialSupply;
uint256 supply;
}
```
- **Description**: Defines the supply details of a minter, including the cap, initial supply, and the current supply.

- **Fields**:
- `cap`: The maximum allowed mint supply for the minter.
- `initialSupply`: The initial mint supply to the minter, equivalent to the initial allowed burn amount.
- `supply`: The current mint supply used by the minter, set to `initialSupply` at beginning.

---

## Functions

### `getWA0GI()`
```solidity
function getWA0GI() external view returns (address);
```
- **Description**: Retrieves the address of the wrapped A0GI (WA0GI) contract.
- **Returns**: `address` of the WA0GI contract.

---

### `minterSupply(address minter)`
```solidity
function minterSupply(address minter) external view returns (Supply memory);
```
- **Description**: Retrieves the mint supply details for a given minter.
- **Parameters**:
- `minter`: The address of the minter.
- **Returns**: A `Supply` structure containing the mint cap, initial supply, and current supply of the specified minter.

---

### `mint(address minter, uint256 amount)`
```solidity
function mint(address minter, uint256 amount) external;
```
- **Description**: Mints A0GI to WA0GI contract and adds the corresponding amount to the minter's mint supply. If the minter's final mint supply exceeds their mint cap, the transaction will revert.
- **Parameters**:
- `minter`: The address of the minter.
- `amount`: The amount of A0GI to mint.
- **Restrictions**: Can only be called by the WA0GI contract.

---

### `burn(address minter, uint256 amount)`
```solidity
function burn(address minter, uint256 amount) external;
```
- **Description**: Burns the specified amount of A0GI in WA0GI contract on behalf of the minter and reduces the corresponding amount from the minter's mint supply.
- **Parameters**:
- `minter`: The address of the minter.
- `amount`: The amount of A0GI to burn.
- **Restrictions**: Can only be called by the WA0GI contract.

---
20 changes: 18 additions & 2 deletions sidebars.ts
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ const sidebars: SidebarsConfig = {
},
items: [
'0g-chain',
'0g-storage',
'0g-storage',
'0g-compute',
{
type: 'category',
Expand Down Expand Up @@ -70,7 +70,23 @@ const sidebars: SidebarsConfig = {
'build-with-0g/rollup-as-a-service/caldera-on-0g-da',
],
},
'build-with-0g/contracts',
{
type: 'category',
label: 'Contracts on 0G',
items: [
'build-with-0g/contracts-on-0g/deploy-contracts',
{
type: 'category',
label: 'Precompiles',
items: [
'build-with-0g/contracts-on-0g/precompiles/precompiles-overview',
'build-with-0g/contracts-on-0g/precompiles/precompiles-dasigners',
'build-with-0g/contracts-on-0g/precompiles/precompiles-staking',
'build-with-0g/contracts-on-0g/precompiles/precompiles-wrappeda0gibase',
],
},
],
},
'build-with-0g/marketplace',
'build-with-0g/faucet',
'build-with-0g/explorer',
Expand Down

0 comments on commit 30561eb

Please sign in to comment.