doc: precompiles (#103)

docs/build-with-0g/contracts.md → docs/build-with-0g/contracts-on-0g/deploy-contracts.md

@@ -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
 

docs/build-with-0g/contracts-on-0g/precompiles/dasigners.md

@@ -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.
+---

docs/build-with-0g/contracts-on-0g/precompiles/overview.md

@@ -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.
+
+
+
+
+
+
+

docs/build-with-0g/contracts-on-0g/precompiles/staking.md

@@ -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). 

docs/build-with-0g/contracts-on-0g/precompiles/wrappeda0gibase.md

@@ -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.
+
+---

sidebars.ts

@@ -13,7 +13,7 @@ const sidebars: SidebarsConfig = {
       },
       items: [
         '0g-chain',
-        '0g-storage', 
+        '0g-storage',
         '0g-compute',
         {
           type: 'category',
@@ -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',