Feature/docs gen (#62)

* Add docsgen

* Add more stuff

* Fix things

.gitignore

@@ -1,3 +1,4 @@
 cache/
 out/
-src-forge-test/
+src-forge-test/
+docs/

src/Context.sol

@@ -3,11 +3,16 @@ pragma solidity ^0.8.13;
 
 import "./suavelib/Suave.sol";
 
+/// @notice Context is a library with functions to retrieve the context of the MEVM execution.
 library Context {
+    /// @notice returns the confidential inputs of the confidential compute request.
+    /// @return output bytes of the confidential inputs.
     function confidentialInputs() internal returns (bytes memory) {
         return Suave.contextGet("confidentialInputs");
     }
 
+    /// @notice returns the address of the Kettle that executes the confidential compute request.
+    /// @return kettleAddress address of the kettle.
     function kettleAddress() internal returns (address) {
         bytes memory _bytes = Suave.contextGet("kettleAddress");
 

src/Random.sol

@@ -3,42 +3,55 @@ pragma solidity ^0.8.8;
 
 import "./suavelib/Suave.sol";
 
+/// @notice Random is a library with utilities to generate random data.
 library Random {
+    /// @notice generate a random uint8 number.
+    /// @return value is the random number
     function randomUint8() internal returns (uint8 value) {
         bytes memory random = Suave.randomBytes(1);
         assembly {
             value := mload(add(random, 0x01))
         }
     }
 
+    /// @notice generate a random uint16 number.
+    /// @return value is the random number
     function randomUint16() internal returns (uint16 value) {
         bytes memory random = Suave.randomBytes(2);
         assembly {
             value := mload(add(random, 0x02))
         }
     }
 
-    function randomUint32() internal returns (uint32 value) {
+    /// @notice generate a random uint32 number.
+    /// @return value is the random number
+    function randomUint32() public returns (uint32 value) {
         bytes memory random = Suave.randomBytes(4);
         assembly {
             value := mload(add(random, 0x04))
         }
     }
 
+    /// @notice generate a random uint64 number.
+    /// @return value is the random number
     function randomUint64() internal returns (uint64 value) {
         bytes memory random = Suave.randomBytes(8);
         assembly {
             value := mload(add(random, 0x08))
         }
     }
 
+    /// @notice generate a random uint128 number.
+    /// @return value is the random number
     function randomUint128() internal returns (uint128 value) {
         bytes memory random = Suave.randomBytes(16);
         assembly {
             value := mload(add(random, 0x10))
         }
     }
 
+    /// @notice generate a random uint256 number.
+    /// @return value is the random number
     function randomUint256() internal returns (uint256 value) {
         bytes memory random = Suave.randomBytes(32);
         assembly {

src/Suapp.sol

@@ -3,7 +3,9 @@ pragma solidity ^0.8.8;
 
 import "./Logs.sol";
 
+/// @notice Suapp is a contract with general utilities for a Suapp.
 contract Suapp {
+    /// @notice modifier to emit the offchain logs.
     modifier emitOffchainLogs() {
         Logs.decodeLogs(msg.data);
         _;

src/Transactions.sol

@@ -5,11 +5,23 @@ import "./utils/RLPWriter.sol";
 import "./suavelib/Suave.sol";
 import "Solidity-RLP/RLPReader.sol";
 
+/// @notice Transactions is a library with utilities to encode, decode and sign Ethereum transactions.
 library Transactions {
     using RLPReader for RLPReader.RLPItem;
     using RLPReader for RLPReader.Iterator;
     using RLPReader for bytes;
 
+    /// @notice EIP-155 transaction structure.
+    /// @param to is the target address.
+    /// @param gas is the gas limit.
+    /// @param gasPrice is the gas price.
+    /// @param value is the transfer value in gwei.
+    /// @param nonce is the latest nonce of the sender.
+    /// @param data is the transaction data.
+    /// @param chainId is the id of the chain where the transaction will be executed.
+    /// @param r is the 'r' signature value.
+    /// @param s is the 's' signature value.
+    /// @param v is the 'v' signature value.
     struct EIP155 {
         address to;
         uint256 gas;
@@ -23,6 +35,14 @@ library Transactions {
         uint256 v;
     }
 
+    /// @notice EIP-155 transaction request structure.
+    /// @param to is the target address.
+    /// @param gas is the gas limit.
+    /// @param gasPrice is the gas price.
+    /// @param value is the transfer value in gwei.
+    /// @param nonce is the latest nonce of the sender.
+    /// @param data is the transaction data.
+    /// @param chainId is the id of the chain where the transaction will be executed.
     struct EIP155Request {
         address to;
         uint256 gas;
@@ -33,6 +53,19 @@ library Transactions {
         uint256 chainId;
     }
 
+    /// @notice EIP-1559 transaction structure.
+    /// @param to is the target address.
+    /// @param gas is the gas limit.
+    /// @param maxFeePerGas is the maximum fee per gas.
+    /// @param maxPriorityFeePerGas is the maximum priority fee per gas.
+    /// @param value is the transfer value in gwei.
+    /// @param nonce is the latest nonce of the sender.
+    /// @param data is the transaction data.
+    /// @param chainId is the id of the chain where the transaction will be executed.
+    /// @param accessList is the access list.
+    /// @param r is the 'r' signature value.
+    /// @param s is the 's' signature value.
+    /// @param v is the 'v' signature value.
     struct EIP1559 {
         address to;
         uint256 gas;
@@ -48,6 +81,16 @@ library Transactions {
         uint256 v;
     }
 
+    /// @notice EIP-1559 transaction request structure.
+    /// @param to is the target address.
+    /// @param gas is the gas limit.
+    /// @param maxFeePerGas is the maximum fee per gas.
+    /// @param maxPriorityFeePerGas is the maximum priority fee per gas.
+    /// @param value is the transfer value in gwei.
+    /// @param nonce is the latest nonce of the sender.
+    /// @param data is the transaction data.
+    /// @param chainId is the id of the chain where the transaction will be executed.
+    /// @param accessList is the access list.
     struct EIP1559Request {
         address to;
         uint256 gas;
@@ -60,6 +103,9 @@ library Transactions {
         bytes accessList;
     }
 
+    /// @notice encode a EIP-155 transaction in RLP.
+    /// @param txStruct is the transaction structure.
+    /// @return output the encoded RLP bytes.
     function encodeRLP(EIP155 memory txStruct) internal pure returns (bytes memory) {
         bytes[] memory items = new bytes[](9);
 
@@ -81,6 +127,9 @@ library Transactions {
         return RLPWriter.writeList(items);
     }
 
+    /// @notice encode a EIP-1559 request transaction in RLP.
+    /// @param txStruct is the transaction structure.
+    /// @return output the encoded RLP bytes.
     function encodeRLP(EIP155Request memory txStruct) internal pure returns (bytes memory) {
         bytes[] memory items = new bytes[](9);
 
@@ -102,6 +151,9 @@ library Transactions {
         return RLPWriter.writeList(items);
     }
 
+    /// @notice encode a EIP-1559 transaction in RLP.
+    /// @param txStruct is the transaction structure.
+    /// @return output the encoded RLP bytes.
     function encodeRLP(EIP1559 memory txStruct) internal pure returns (bytes memory) {
         bytes[] memory items = new bytes[](12);
 
@@ -142,6 +194,9 @@ library Transactions {
         return txn;
     }
 
+    /// @notice encode a EIP-1559 request transaction in RLP.
+    /// @param txStruct is the transaction structure.
+    /// @return output the encoded RLP bytes.
     function encodeRLP(EIP1559Request memory txStruct) internal pure returns (bytes memory) {
         bytes[] memory items = new bytes[](9);
 
@@ -178,6 +233,9 @@ library Transactions {
         return txn;
     }
 
+    /// @notice decode a EIP-155 transaction from RLP.
+    /// @param rlp is the encoded RLP bytes.
+    /// @return txStruct the transaction structure.
     function decodeRLP_EIP155(bytes memory rlp) internal pure returns (EIP155 memory) {
         EIP155 memory txStruct;
 
@@ -203,6 +261,9 @@ library Transactions {
         return txStruct;
     }
 
+    /// @notice decode a EIP-155 request transaction from RLP.
+    /// @param rlp is the encoded RLP bytes.
+    /// @return txStruct the transaction structure.
     function decodeRLP_EIP155Request(bytes memory rlp) internal pure returns (EIP155Request memory) {
         EIP155Request memory txStruct;
 
@@ -226,6 +287,9 @@ library Transactions {
         return txStruct;
     }
 
+    /// @notice decode a EIP-1559 transaction from RLP.
+    /// @param rlp is the encoded RLP bytes.
+    /// @return txStruct the transaction structure.
     function decodeRLP_EIP1559(bytes memory rlp) internal pure returns (EIP1559 memory) {
         EIP1559 memory txStruct;
 
@@ -260,6 +324,9 @@ library Transactions {
         return txStruct;
     }
 
+    /// @notice decode a EIP-1559 request transaction from RLP.
+    /// @param rlp is the encoded RLP bytes.
+    /// @return txStruct the transaction structure.
     function decodeRLP_EIP1559Request(bytes memory rlp) internal pure returns (EIP1559Request memory) {
         EIP1559Request memory txStruct;
 
@@ -297,6 +364,10 @@ library Transactions {
         }
     }
 
+    /// @notice sign a EIP-155 transaction request.
+    /// @param request is the transaction request.
+    /// @param signingKey is the private key to sign the transaction.
+    /// @return response the signed transaction.
     function signTxn(Transactions.EIP1559Request memory request, string memory signingKey)
         internal
         returns (Transactions.EIP1559 memory response)
@@ -322,6 +393,10 @@ library Transactions {
         return response;
     }
 
+    /// @notice sign a EIP-155 transaction request.
+    /// @param request is the transaction request.
+    /// @param signingKey is the private key to sign the transaction.
+    /// @return response the signed transaction.
     function signTxn(Transactions.EIP155Request memory request, string memory signingKey)
         internal
         returns (Transactions.EIP155 memory response)

src/protocols/Bundle.sol

@@ -6,7 +6,7 @@ import "../utils/HexStrings.sol";
 import "solady/src/utils/LibString.sol";
 import "solady/src/utils/JSONParserLib.sol";
 
-// https://docs.flashbots.net/flashbots-auction/advanced/rpc-endpoint#eth_sendbundle
+/// @notice Bundle is a library with utilities to interact with the Flashbots bundle API described in https://docs.flashbots.net/flashbots-auction/advanced/rpc-endpoint#eth_sendbundle
 library Bundle {
     struct BundleObj {
         uint64 blockNumber;
@@ -18,6 +18,10 @@ library Bundle {
     using JSONParserLib for string;
     using JSONParserLib for JSONParserLib.Item;
 
+    /// @notice send a bundle to the Flashbots relay.
+    /// @param url the URL of the Flashbots relay.
+    /// @param bundle the bundle to send.
+    /// @return response raw bytes response from the Flashbots relay.
     function sendBundle(string memory url, BundleObj memory bundle) internal returns (bytes memory) {
         Suave.HttpRequest memory request = encodeBundle(bundle);
         request.url = url;
@@ -67,6 +71,9 @@ library Bundle {
         return string(result);
     }
 
+    /// @notice decode a bundle from a JSON string.
+    /// @param bundleJson the JSON string of the bundle.
+    /// @return bundle the decoded bundle.
     function decodeBundle(string memory bundleJson) public pure returns (Bundle.BundleObj memory) {
         JSONParserLib.Item memory root = bundleJson.parse();
         JSONParserLib.Item memory txnsNode = root.at('"txs"');

src/protocols/ChatGPT.sol

@@ -4,6 +4,7 @@ pragma solidity ^0.8.13;
 import "src/suavelib/Suave.sol";
 import "solady/src/utils/JSONParserLib.sol";
 
+/// @notice ChatGPT is a library with utilities to interact with the OpenAI ChatGPT API.
 contract ChatGPT {
     using JSONParserLib for *;
 
@@ -19,11 +20,15 @@ contract ChatGPT {
         string content;
     }
 
+    /// @notice constructor to create a ChatGPT instance.
+    /// @param _apiKey the API key to interact with the OpenAI ChatGPT.
     constructor(string memory _apiKey) {
         apiKey = _apiKey;
     }
 
-    // https://platform.openai.com/docs/api-reference/making-requests
+    /// @notice complete a chat with the OpenAI ChatGPT.
+    /// @param messages the messages to complete the chat.
+    /// @return message the response from the OpenAI ChatGPT.
     function complete(Message[] memory messages) public returns (string memory) {
         bytes memory body;
         body = abi.encodePacked('{"model": "gpt-3.5-turbo", "messages": [');

src/protocols/EthJsonRPC.sol

@@ -5,6 +5,7 @@ import "src/suavelib/Suave.sol";
 import "solady/src/utils/JSONParserLib.sol";
 import "solady/src/utils/LibString.sol";
 
+/// @notice EthJsonRPC is a library with utilities to interact with an Ethereum JSON-RPC endpoint.
 contract EthJsonRPC {
     using JSONParserLib for *;
 
@@ -14,6 +15,9 @@ contract EthJsonRPC {
         endpoint = _endpoint;
     }
 
+    /// @notice get the nonce of an address.
+    /// @param addr the address to get the nonce.
+    /// @return val the nonce of the address.
     function nonce(address addr) public returns (uint256) {
         bytes memory body = abi.encodePacked(
             '{"jsonrpc":"2.0","method":"eth_getTransactionCount","params":["',

src/protocols/MevShare.sol

@@ -5,7 +5,7 @@ import "../suavelib/Suave.sol";
 import "solady/src/utils/LibString.sol";
 import "solady/src/utils/JSONParserLib.sol";
 
-// https://github.com/flashbots/mev-share/blob/main/specs/bundles/v0.1.md#json-rpc-request-scheme
+/// @notice MevShare is a library with utilities to interact with the Flashbots Mev-Share API described in https://github.com/flashbots/mev-share/blob/main/specs/bundles/v0.1.md#json-rpc-request-scheme
 library MevShare {
     struct Bundle {
         uint64 inclusionBlock;
@@ -71,6 +71,9 @@ library MevShare {
         return request;
     }
 
+    /// @notice send a Mev-Share to the Flashbots Mev-Share API.
+    /// @param url the URL of the Flashbots Mev-Share API.
+    /// @param bundle the Mev-Share bundle to send.
     function sendBundle(string memory url, Bundle memory bundle) internal {
         Suave.HttpRequest memory request = encodeBundle(bundle);
         request.url = url;

tools/docs-gen/go.mod

@@ -0,0 +1,10 @@
+module github.com/flashbots/suave-std/tools/docs-gen
+
+go 1.21.0
+
+require github.com/Kunde21/markdownfmt/v3 v3.1.0
+
+require (
+	github.com/mattn/go-runewidth v0.0.9 // indirect
+	github.com/yuin/goldmark v1.3.5 // indirect
+)

tools/docs-gen/go.sum

@@ -0,0 +1,14 @@
+github.com/Kunde21/markdownfmt/v3 v3.1.0 h1:KiZu9LKs+wFFBQKhrZJrFZwtLnCCWJahL+S+E/3VnM0=
+github.com/Kunde21/markdownfmt/v3 v3.1.0/go.mod h1:tPXN1RTyOzJwhfHoon9wUr4HGYmWgVxSQN6VBJDkrVc=
+github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
+github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/mattn/go-runewidth v0.0.9 h1:Lm995f3rfxdpd6TSmuVCHVb/QhupuXlYr8sCI/QdE+0=
+github.com/mattn/go-runewidth v0.0.9/go.mod h1:H031xJmbD/WCDINGzjvQ9THkh0rPKHF+m2gUSrubnMI=
+github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
+github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/stretchr/testify v1.8.1 h1:w7B6lhMri9wdJUVmEZPGGhZzrYTPvgJArz7wNPgYKsk=
+github.com/stretchr/testify v1.8.1/go.mod h1:w2LPCIKwWwSfY2zedu0+kehJoqGctiVI29o6fzry7u4=
+github.com/yuin/goldmark v1.3.5 h1:dPmz1Snjq0kmkz159iL7S6WzdahUTHnHB5M56WFVifs=
+github.com/yuin/goldmark v1.3.5/go.mod h1:mwnBkeHKe2W/ZEtQ+71ViKU8L12m81fl3OWwC1Zlc8k=
+gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
+gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=