POD-158 Adds pod precompiles documentation

docs/devnet/content.md

@@ -9,7 +9,3 @@ url: /
 ! import ./intro.md
 
 ! import ./config.md
-
----
-
-! import ./precompile.md

docs/devnet/intro.md

@@ -7,4 +7,7 @@ layout: single
 The pod devnet is a test network for developers to experiment 
 with the pod network. It is designed to be a sandbox for testing 
 and development purposes, allowing developers to build and test 
-their applications without the need for real assets or transactions.
+their applications without the need for real assets or transactions.
+
+
+> We expect the devnet to have breaking changes or be reset (pruned completely) at any time.

docs/menu.yaml

@@ -21,6 +21,8 @@ menu:
 
 
   - heading: Building on pod
+  - href: /precompiles
+    label: Precompiles
   - href: /json-rpc
     label: JSON-RPC
   - href: /solidity-sdk

docs/precompiles/callWithState.md

@@ -0,0 +1,138 @@
+---
+layout: simple
+---
+
+! content id="callWithState"
+
+! anchor callWithState go-up
+## Call With State
+
+Simulates an EVM call against a supplied header and state on a specified chain. Executes the provided call in an ephemeral VM and returns the call's raw return bytes.
+
+### Address
+
+0xB4BBff8874b41f97535bC8dAFBaAff0DC5c72E5A
+
+### Inputs
+
+! table style1
+| Byte range         | Name       | Description                                                                 |
+| ------------------ | ---------- | --------------------------------------------------------------------------- |
+| [0; I size]        | input (I)  | struct `EVMCallWithStateArgs` with `chainId`, `header`, `call`, and `state` |
+! table end
+
+The EVMCallWithStateArgs struct is defined as:
+```solidity
+struct EVMCallWithStateArgs {
+    uint256 chainId;
+    Header header;
+    EVMCall call;
+    EVMState state;
+}
+
+struct Header {
+    bytes32 parentHash;
+    bytes32 uncleHash;
+    address coinbase;
+    bytes32 root;
+    bytes32 txHash;
+    bytes32 receiptHash;
+    bytes   bloom;
+    uint256 difficulty;
+    uint256 number;
+    uint256 gasLimit;
+    uint256 gasUsed;
+    uint256 time;
+    bytes   extra;
+    bytes32 mixDigest;
+    bytes8  nonce;
+}
+
+struct EVMCall {
+    address from;
+    address to;
+    bytes   input;
+}
+
+struct EVMState {
+    Account[] accounts;
+}
+
+struct Account {
+    AccountProof proof;
+    bytes code;
+}
+
+struct StorageProof {
+    bytes32 key;
+    bytes32 value;
+    bytes[] proof;
+}
+
+struct AccountProof {
+    address addr;
+    bytes[] accountProof;
+    uint256 balance;
+    bytes32 codeHash;
+    uint256 nonce;
+    bytes32 storageHash;
+    StorageProof[] storageProof;
+}
+```
+
+### Output
+
+! table style1
+| Byte range         | Name       | Description                        |
+| ------------------ | ---------- | ---------------------------------- |
+| [0; R size]        | result (R) | Return bytes of the EVM execution  |
+! table end
+
+### Errors
+
+- Out of gas if provided gas is less than base cost.
+- Input must not be empty.
+- Input decoding failed.
+- Chain ID must fit in `uint64`.
+- EVM creation failed (invalid header / state / account proofs / storage proofs).
+- Returned empty output.
+- Call failed or reverted.
+
+### Gas Cost
+
+Static gas: 500
+
+Dynamic gas: gas used by the simulated EVM call
+
+! content end
+
+
+! content
+! sticky
+
+### Example
+
+! codeblock title=""
+```solidity
+address internal constant EVM_CALL_WITH_STATE = address(
+    uint160(uint256(keccak256("POD_EVM_CALL_WITH_STATE")))
+);
+
+function call_precompile(EVMCallWithStateArgs memory args) public view returns (bytes memory) {
+    bytes memory inputData = abi.encode(
+    args.chainId,
+    args.header,
+    args.call,
+    args.state
+    );
+
+    (bool success, bytes memory returnData) = EVM_CALL_WITH_STATE.staticcall{ gas: gasleft() }(inputData);
+    require(success, "Precompile call failed");
+
+    return returnData;
+}
+```
+! codeblock end
+
+! sticky end
+! content end

docs/precompiles/content.md

@@ -0,0 +1,39 @@
+---
+title: pod Precompiles
+layout: blank
+
+url: /precompiles
+
+toc:
+  precompiles-overview: Overview
+  timestamp: timestamp
+  requireQuorum: requireQuorum
+  txInfo: txInfo
+  externalCall: externalCall
+  # callWithState: callWithState
+---
+
+! import ./overview.md
+! import ./precompiles-table.md
+
+---
+
+! import ./timestamp.md
+
+---
+
+! import ./requireQuorum.md
+
+---
+
+! import ./txInfo.md
+
+---
+
+! import ./externalCall.md
+
+---
+
+<!-- ! import ./callWithState.md
+
+--- -->

docs/precompiles/externalCall.md

@@ -0,0 +1,84 @@
+---
+layout: simple
+---
+
+! content id="externalCall"
+
+! anchor externalCall go-up
+## External Call
+
+Calls a smart contract on another EVM-compatible chain via the configured validators's RPC URL. Input specifies chain ID, transaction fields, and a block tag/number; output is the raw result of the remote `eth_call`.
+
+### Address
+
+0x8712E00C337971f876621faB9326908fdF330d77
+
+### Inputs
+
+! table style1
+| Byte range         | Name                | Description                                                                                               |
+| ------------------ | ------------------- | --------------------------------------------------------------------------------------------------------- |
+| [0; I size]        | input (I)           | struct ExternalEthCallArgs defining the targeted chain and the arguments of the call (see details below)  |
+! table end
+
+The ExternalEthCallArgs struct is defined as:
+```solidity
+ struct Transaction {
+    address from;
+    address to;
+    uint256 gas;
+    uint256 gasPrice;
+    uint256 value;
+    bytes data;
+}
+
+struct EthCallArgs {
+    Transaction transaction;
+    bytes blockNumber;
+}
+
+struct ExternalEthCallArgs {
+    uint256 chainId;
+    EthCallArgs ethCallArgs;
+}
+```
+
+### Output
+
+Raw bytes returned by the remote `eth_call`.
+
+! table style1
+| Byte range         | Name       | Description                 |
+| ------------------ | ---------- | --------------------------- |
+| [0; R size]        | result (R) | Remote `eth_call` return    |
+! table end
+
+### Errors
+
+- Out of gas if provided gas is less than base cost.
+- Empty input.
+- Input decoding failed.
+- No RPC URL configured for the specified chain ID.
+- Invalid argument: block number/tag format.
+- Invalid argument: `to` is zero.
+
+### Gas Cost
+
+Static gas: 100
+
+! content end
+
+
+! content
+! sticky
+
+### Example
+
+This example uses the POD_EXTERNAL_ETH_CALL precompile to run an eth_call on Ethereum mainnet, returning the USDC balance for a given account.
+
+! codeblock title="examples/solidity/src/EthereumERC20Balance.sol"
+! codeblock import solidity "./src/EthereumERC20Balance.sol"
+! codeblock end
+
+! sticky end
+! content end

docs/precompiles/overview.md

@@ -0,0 +1,15 @@
+---
+layout: single
+---
+
+! anchor precompiles-overview
+# Precompiles
+In pod, precompiles work similarly to Ethereum. We currently support all precompiles available in the Prague version of the EVM, plus some Pod-specific ones listed in the table below.
+
+
+## Precompile Addressing Scheme
+The address of each Pod precompile is derived from the precompile name as the last 20 bytes of the `keccak256` hash of the name.
+
+```solidity
+address constant POD_TIMESTAMP_PRECOMPILE = address(uint160(uint256(keccak256("POD_TIMESTAMP"))));
+```

docs/precompiles/precompiles-table.md

@@ -0,0 +1,16 @@
+---
+layout: full
+---
+
+! anchor precompiles-table
+## Available Precompiles
+
+! table style1 rowLink="hash" rowLinkBy="id" rowLinkBase="/precompiles" hideFields="id"
+| id            | Address                                    | Name                    | Minimum Gas  | Description                                                                    |
+| ------------- | ------------------------------------------ | ----------------------- | ------------ | ------------------------------------------------------------------------------ |
+| timestamp     | 0x423Bb123D9d5143e662606Fd343b6766d7BCf721 | POD_TIMESTAMP           | 100          | Fetches the current system timestamp                                           |
+| requireQuorum | 0x6AD9145E866c7A7DcCc6c277Ea86abBD268FBAc9 | POD_REQUIRE_QUORUM      | 100          | Like `require` but passes if supermajority agrees                              |
+| txInfo        | 0x7687A3413739715807812b529f2d5f7Ef9057697 | POD_TX_INFO             | 100          | Fetches information about the current transaction (nonce and transaction hash) |
+| externalCall  | 0x8712E00C337971f876621faB9326908fdF330d77 | POD_EXTERNAL_ETH_CALL   | 100          | Call a smart contract on another EVM-compatible chain                          |
+<!-- | callWithState | 0xB4BBff8874b41f97535bC8dAFBaAff0DC5c72E5A | POD_EVM_CALL_WITH_STATE | 500          | Simulate an EVM transaction execution given a particular initial state         | -->
+! table end