Merge pull request #96 from bob-collective/nakul/feat_contract_docs

fix: Add docs for Smart Contracts

.github/workflows/test.yml

@@ -7,11 +7,12 @@ env:
 
 jobs:
   check:
-    strategy:
-      fail-fast: true
-
     name: Foundry
     runs-on: ubuntu-latest
+
+    permissions:
+      contents: write
+
     steps:
       - uses: actions/checkout@v4
         with:
@@ -37,3 +38,14 @@ jobs:
         run: |
           forge test -vvv
         id: test
+
+      - name: Run Forge docs
+        run: |
+          forge doc --out docs/docs/contracts
+          python3 docs/scripts/forge_doc_reformat.py
+
+      - name: Commit Forge docs
+        uses: stefanzweifel/git-auto-commit-action@v5
+        with:
+          commit_message: "chore: Generate Foundry docs"
+          file_pattern: "./docs/"

.gitignore

@@ -39,4 +39,4 @@ out/
 node_modules/*
 
 # generated docs
-/docs/docs/api/*
+/docs/docs/api/*

docs/docs/contracts/.gitignore

@@ -0,0 +1 @@
+book/

docs/docs/contracts/book.css

@@ -0,0 +1,13 @@
+table {
+    margin: 0 auto;
+    border-collapse: collapse;
+    width: 100%;
+}
+
+table td:first-child {
+    width: 15%;
+}
+
+table td:nth-child(2) {
+    width: 25%;
+}

docs/docs/contracts/book.toml

@@ -0,0 +1,12 @@
+[book]
+src = "src"
+title = ""
+
+[output.html]
+no-section-label = true
+additional-js = ["solidity.min.js"]
+additional-css = ["book.css"]
+git-repository-url = "https://github.com/bob-collective/bob"
+
+[output.html.fold]
+enable = true

docs/docs/contracts/contract_references.md

@@ -0,0 +1,7 @@
+# Smart Contracts
+
+The source code for the smart contracts can be found in the following repository:
+
+- [Relay Smart Contracts](https://github.com/bob-collective/bob/tree/master/src/relay)
+- [Bridge Smart Contracts](https://github.com/bob-collective/bob/tree/master/src/bridge)
+- [Swap Smart Contracts](https://github.com/bob-collective/bob/tree/master/src/swap)

docs/docs/contracts/solidity.min.js

@@ -0,0 +1,74 @@
+hljs.registerLanguage("solidity",(()=>{"use strict";function e(){try{return!0
+}catch(e){return!1}}
+var a=/-?(\b0[xX]([a-fA-F0-9]_?)*[a-fA-F0-9]|(\b[1-9](_?\d)*(\.((\d_?)*\d)?)?|\.\d(_?\d)*)([eE][-+]?\d(_?\d)*)?|\b0)(?!\w|\$)/
+;e()&&(a=a.source.replace(/\\b/g,"(?<!\\$)\\b"));var s={className:"number",
+begin:a,relevance:0},n={
+keyword:"assembly let function if switch case default for leave break continue u256 jump jumpi stop return revert selfdestruct invalid",
+built_in:"add sub mul div sdiv mod smod exp not lt gt slt sgt eq iszero and or xor byte shl shr sar addmod mulmod signextend keccak256 pc pop dup1 dup2 dup3 dup4 dup5 dup6 dup7 dup8 dup9 dup10 dup11 dup12 dup13 dup14 dup15 dup16 swap1 swap2 swap3 swap4 swap5 swap6 swap7 swap8 swap9 swap10 swap11 swap12 swap13 swap14 swap15 swap16 mload mstore mstore8 sload sstore msize gas address balance selfbalance caller callvalue calldataload calldatasize calldatacopy codesize codecopy extcodesize extcodecopy returndatasize returndatacopy extcodehash create create2 call callcode delegatecall staticcall log0 log1 log2 log3 log4 chainid origin gasprice basefee blockhash coinbase timestamp number difficulty gaslimit",
+literal:"true false"},i={className:"string",
+begin:/\bhex'(([0-9a-fA-F]{2}_?)*[0-9a-fA-F]{2})?'/},t={className:"string",
+begin:/\bhex"(([0-9a-fA-F]{2}_?)*[0-9a-fA-F]{2})?"/};function r(e){
+return e.inherit(e.APOS_STRING_MODE,{begin:/(\bunicode)?'/})}function l(e){
+return e.inherit(e.QUOTE_STRING_MODE,{begin:/(\bunicode)?"/})}var o={
+SOL_ASSEMBLY_KEYWORDS:n,baseAssembly:e=>{
+var a=r(e),o=l(e),c=/[A-Za-z_$][A-Za-z_$0-9.]*/,d=e.inherit(e.TITLE_MODE,{
+begin:/[A-Za-z$_][0-9A-Za-z$_]*/,lexemes:c,keywords:n}),u={className:"params",
+begin:/\(/,end:/\)/,excludeBegin:!0,excludeEnd:!0,lexemes:c,keywords:n,
+contains:[e.C_LINE_COMMENT_MODE,e.C_BLOCK_COMMENT_MODE,a,o,s]},_={
+className:"operator",begin:/:=|->/};return{keywords:n,lexemes:c,
+contains:[a,o,i,t,e.C_LINE_COMMENT_MODE,e.C_BLOCK_COMMENT_MODE,s,_,{
+className:"function",lexemes:c,beginKeywords:"function",end:"{",excludeEnd:!0,
+contains:[d,u,e.C_LINE_COMMENT_MODE,e.C_BLOCK_COMMENT_MODE,_]}]}},
+solAposStringMode:r,solQuoteStringMode:l,HEX_APOS_STRING_MODE:i,
+HEX_QUOTE_STRING_MODE:t,SOL_NUMBER:s,isNegativeLookbehindAvailable:e}
+;const{baseAssembly:c,solAposStringMode:d,solQuoteStringMode:u,HEX_APOS_STRING_MODE:_,HEX_QUOTE_STRING_MODE:m,SOL_NUMBER:b,isNegativeLookbehindAvailable:E}=o
+;return e=>{for(var a=d(e),s=u(e),n=[],i=0;i<32;i++)n[i]=i+1
+;var t=n.map((e=>8*e)),r=[];for(i=0;i<=80;i++)r[i]=i
+;var l=n.map((e=>"bytes"+e)).join(" ")+" ",o=t.map((e=>"uint"+e)).join(" ")+" ",g=t.map((e=>"int"+e)).join(" ")+" ",M=[].concat.apply([],t.map((e=>r.map((a=>e+"x"+a))))),p={
+keyword:"var bool string int uint "+g+o+"byte bytes "+l+"fixed ufixed "+M.map((e=>"fixed"+e)).join(" ")+" "+M.map((e=>"ufixed"+e)).join(" ")+" enum struct mapping address new delete if else for while continue break return throw emit try catch revert unchecked _ function modifier event constructor fallback receive error virtual override constant immutable anonymous indexed storage memory calldata external public internal payable pure view private returns import from as using pragma contract interface library is abstract type assembly",
+literal:"true false wei gwei szabo finney ether seconds minutes hours days weeks years",
+built_in:"self this super selfdestruct suicide now msg block tx abi blockhash gasleft assert require Error Panic sha3 sha256 keccak256 ripemd160 ecrecover addmod mulmod log0 log1 log2 log3 log4"
+},O={className:"operator",begin:/[+\-!~*\/%<>&^|=]/
+},C=/[A-Za-z_$][A-Za-z_$0-9]*/,N={className:"params",begin:/\(/,end:/\)/,
+excludeBegin:!0,excludeEnd:!0,lexemes:C,keywords:p,
+contains:[e.C_LINE_COMMENT_MODE,e.C_BLOCK_COMMENT_MODE,a,s,b,"self"]},f={
+begin:/\.\s*/,end:/[^A-Za-z0-9$_\.]/,excludeBegin:!0,excludeEnd:!0,keywords:{
+built_in:"gas value selector address length push pop send transfer call callcode delegatecall staticcall balance code codehash wrap unwrap name creationCode runtimeCode interfaceId min max"
+},relevance:2},y=e.inherit(e.TITLE_MODE,{begin:/[A-Za-z$_][0-9A-Za-z$_]*/,
+lexemes:C,keywords:p}),w={className:"built_in",
+begin:(E()?"(?<!\\$)\\b":"\\b")+"(gas|value|salt)(?=:)"};function x(e,a){return{
+begin:(E()?"(?<!\\$)\\b":"\\b")+e+"\\.\\s*",end:/[^A-Za-z0-9$_\.]/,
+excludeBegin:!1,excludeEnd:!0,lexemes:C,keywords:{built_in:e+" "+a},
+contains:[f],relevance:10}}var h=c(e),v=e.inherit(h,{
+contains:h.contains.concat([{begin:/\./,end:/[^A-Za-z0-9$.]/,excludeBegin:!0,
+excludeEnd:!0,keywords:{built_in:"slot offset length address selector"},
+relevance:2},{begin:/_/,end:/[^A-Za-z0-9$.]/,excludeBegin:!0,excludeEnd:!0,
+keywords:{built_in:"slot offset"},relevance:2}])});return{aliases:["sol"],
+keywords:p,lexemes:C,
+contains:[a,s,_,m,e.C_LINE_COMMENT_MODE,e.C_BLOCK_COMMENT_MODE,b,w,O,{
+className:"function",lexemes:C,
+beginKeywords:"function modifier event constructor fallback receive error",
+end:/[{;]/,excludeEnd:!0,
+contains:[y,N,w,e.C_LINE_COMMENT_MODE,e.C_BLOCK_COMMENT_MODE],illegal:/%/
+},x("msg","gas value data sender sig"),x("block","blockhash coinbase difficulty gaslimit basefee number timestamp chainid"),x("tx","gasprice origin"),x("abi","decode encode encodePacked encodeWithSelector encodeWithSignature encodeCall"),x("bytes","concat"),f,{
+className:"class",lexemes:C,beginKeywords:"contract interface library",end:"{",
+excludeEnd:!0,illegal:/[:"\[\]]/,contains:[{beginKeywords:"is",lexemes:C
+},y,N,w,e.C_LINE_COMMENT_MODE,e.C_BLOCK_COMMENT_MODE]},{lexemes:C,
+beginKeywords:"struct enum",end:"{",excludeEnd:!0,illegal:/[:"\[\]]/,
+contains:[y,e.C_LINE_COMMENT_MODE,e.C_BLOCK_COMMENT_MODE]},{
+beginKeywords:"import",end:";",lexemes:C,keywords:"import from as",
+contains:[y,a,s,_,m,e.C_LINE_COMMENT_MODE,e.C_BLOCK_COMMENT_MODE,O]},{
+beginKeywords:"using",end:";",lexemes:C,keywords:"using for",
+contains:[y,e.C_LINE_COMMENT_MODE,e.C_BLOCK_COMMENT_MODE,O]},{className:"meta",
+beginKeywords:"pragma",end:";",lexemes:C,keywords:{
+keyword:"pragma solidity experimental abicoder",
+built_in:"ABIEncoderV2 SMTChecker v1 v2"},
+contains:[e.C_LINE_COMMENT_MODE,e.C_BLOCK_COMMENT_MODE,e.inherit(a,{
+className:"meta-string"}),e.inherit(s,{className:"meta-string"})]},{
+beginKeywords:"assembly",end:/\b\B/,
+contains:[e.C_LINE_COMMENT_MODE,e.C_BLOCK_COMMENT_MODE,e.inherit(v,{begin:"{",
+end:"}",endsParent:!0,contains:v.contains.concat([e.inherit(v,{begin:"{",
+end:"}",contains:v.contains.concat(["self"])})])})]}],illegal:/#/}}})());
+
+// Ugly hack to reload HLJS
+hljs.initHighlightingOnLoad();

docs/docs/contracts/src/src/TestingErc20.sol/contract.TestingErc20.md

@@ -0,0 +1,58 @@
+# TestingErc20
+[Git Source](https://github.com/bob-collective/bob/blob/9dd94230dd2abcab7dfb659e986743be10093c68/src/TestingErc20.sol)
+
+**Inherits:**
+ERC20, ERC20Burnable, Ownable, ERC2771Recipient
+
+
+## State Variables
+### _numDecimals
+
+```solidity
+uint8 _numDecimals;
+```
+
+
+## Functions
+### constructor
+
+
+```solidity
+constructor(string memory _name, string memory _symbol, uint8 _decimals) ERC20(_name, _symbol);
+```
+
+### setTrustedForwarder
+
+
+```solidity
+function setTrustedForwarder(address _forwarder) public onlyOwner;
+```
+
+### mint
+
+
+```solidity
+function mint(uint256 amount) external;
+```
+
+### _msgSender
+
+
+```solidity
+function _msgSender() internal view override(Context, ERC2771Recipient) returns (address sender);
+```
+
+### _msgData
+
+
+```solidity
+function _msgData() internal view override(Context, ERC2771Recipient) returns (bytes calldata);
+```
+
+### decimals
+
+
+```solidity
+function decimals() public view virtual override returns (uint8);
+```
+

docs/docs/contracts/src/src/bridge/BitcoinTx.sol/library.BitcoinTx.md

@@ -0,0 +1,164 @@
+# BitcoinTx
+[Git Source](https://github.com/bob-collective/bob/blob/9dd94230dd2abcab7dfb659e986743be10093c68/src/bridge/BitcoinTx.sol)
+
+Allows to reference Bitcoin raw transaction in Solidity.
+
+*See https://developer.bitcoin.org/reference/transactions.html#raw-transaction-format*
+
+
+## Functions
+### validateProof
+
+Validates the SPV proof of the Bitcoin transaction.
+Reverts in case the validation or proof verification fail.
+
+
+```solidity
+function validateProof(BridgeState.Storage storage self, Info memory txInfo, Proof memory proof)
+    internal
+    view
+    returns (bytes32 txHash);
+```
+**Parameters**
+
+|Name|Type|Description|
+|----|----|-----------|
+|`self`|`BridgeState.Storage`||
+|`txInfo`|`Info`|Bitcoin transaction data.|
+|`proof`|`Proof`|Bitcoin proof data.|
+
+**Returns**
+
+|Name|Type|Description|
+|----|----|-----------|
+|`txHash`|`bytes32`|Proven 32-byte transaction hash.|
+
+
+### evaluateProofDifficulty
+
+Evaluates the given Bitcoin proof difficulty against the actual
+Bitcoin chain difficulty provided by the relay oracle.
+Reverts in case the evaluation fails.
+
+
+```solidity
+function evaluateProofDifficulty(BridgeState.Storage storage self, bytes memory bitcoinHeaders) internal view;
+```
+**Parameters**
+
+|Name|Type|Description|
+|----|----|-----------|
+|`self`|`BridgeState.Storage`||
+|`bitcoinHeaders`|`bytes`|Bitcoin headers chain being part of the SPV proof. Used to extract the observed proof difficulty.|
+
+
+### getTxOutputValue
+
+Processes the Bitcoin transaction output vector.
+
+
+```solidity
+function getTxOutputValue(bytes32 scriptPubKeyHash, bytes memory txOutputVector) internal returns (uint64 value);
+```
+**Parameters**
+
+|Name|Type|Description|
+|----|----|-----------|
+|`scriptPubKeyHash`|`bytes32`|Expected Bitcoin scriptPubKey keccak256 hash.|
+|`txOutputVector`|`bytes`|Bitcoin transaction output vector. This function assumes vector's structure is valid so it must be validated using e.g. `BTCUtils.validateVout` function before it is passed here.|
+
+**Returns**
+
+|Name|Type|Description|
+|----|----|-----------|
+|`value`|`uint64`|Outcomes of the processing.|
+
+
+### getTxOutputValue
+
+Processes all outputs from the transaction.
+
+
+```solidity
+function getTxOutputValue(
+    bytes32 scriptPubKeyHash,
+    bytes memory txOutputVector,
+    TxOutputsProcessingInfo memory processInfo
+) internal returns (uint64 value);
+```
+**Parameters**
+
+|Name|Type|Description|
+|----|----|-----------|
+|`scriptPubKeyHash`|`bytes32`|Expected Bitcoin scriptPubKey keccak256 hash.|
+|`txOutputVector`|`bytes`|Bitcoin transaction output vector. This function assumes vector's structure is valid so it must be validated using e.g. `BTCUtils.validateVout` function before it is passed here.|
+|`processInfo`|`TxOutputsProcessingInfo`|TxOutputsProcessingInfo identifying output starting index and the number of outputs.|
+
+
+### reverseEndianness
+
+
+```solidity
+function reverseEndianness(bytes32 b) internal pure returns (bytes32 txHash);
+```
+
+### ensureTxInputSpendsUtxo
+
+
+```solidity
+function ensureTxInputSpendsUtxo(bytes memory _vin, BitcoinTx.UTXO memory utxo) internal pure;
+```
+
+## Structs
+### Info
+Represents Bitcoin transaction data.
+
+
+```solidity
+struct Info {
+    bytes4 version;
+    bytes inputVector;
+    bytes outputVector;
+    bytes4 locktime;
+}
+```
+
+### Proof
+Represents data needed to perform a Bitcoin SPV proof.
+
+
+```solidity
+struct Proof {
+    bytes merkleProof;
+    uint256 txIndexInBlock;
+    bytes bitcoinHeaders;
+}
+```
+
+### UTXO
+Represents info about an unspent transaction output.
+
+
+```solidity
+struct UTXO {
+    bytes32 txHash;
+    uint32 txOutputIndex;
+    uint64 txOutputValue;
+}
+```
+
+### TxOutputsProcessingInfo
+Represents temporary information needed during the processing of
+the Bitcoin transaction outputs. This structure is an internal one
+and should not be exported outside of the transaction processing code.
+
+*Allows to mitigate "stack too deep" errors on EVM.*
+
+
+```solidity
+struct TxOutputsProcessingInfo {
+    uint256 outputStartingIndex;
+    uint256 outputsCount;
+}
+```
+

docs/docs/contracts/src/src/bridge/BridgeState.sol/library.BridgeState.md

@@ -0,0 +1,14 @@
+# BridgeState
+[Git Source](https://github.com/bob-collective/bob/blob/9dd94230dd2abcab7dfb659e986743be10093c68/src/bridge/BridgeState.sol)
+
+
+## Structs
+### Storage
+
+```solidity
+struct Storage {
+    IRelay relay;
+    uint96 txProofDifficultyFactor;
+}
+```
+