Document Modules (#2611)

Co-authored-by: Trajan0x <trajan0x@users.noreply.github.com>

.github/workflows/goreleaser-actions.yml

@@ -27,7 +27,7 @@ jobs:
         with:
           key: docker-release-${{ runner.os }}-${{ matrix.package }}
 
-      - uses: dorny/paths-filter@v2
+      - uses: dorny/paths-filter@v3
         name: check if any changes warrant a new build of goreleaser-cgo-cross-compiler
         id: changes
         with:

.github/workflows/solidity.yml

@@ -30,7 +30,7 @@ jobs:
           fetch-depth: 0
           # if any of these packages use submodules in the future, please uncomment this line
           # submodules: 'recursive'
-      - uses: dorny/paths-filter@v2
+      - uses: dorny/paths-filter@v3
         id: filter_solidity
         with:
           #  make sure to update run-goreleaser when adding a new package here

.github/workflows/ui-preview.yaml

@@ -6,7 +6,7 @@ on:
   pull_request:
     paths:
       - 'packages/explorer-ui/**'
-      - 'packages/docs/**'
+      - 'docs/bridge/**'
       - 'packages/synapse-interface/**'
 jobs:
   changes:
@@ -21,14 +21,14 @@ jobs:
           fetch-depth: 0
           # if any of these packages use submodules in the future, please uncomment this line
           # submodules: 'recursive'
-      - uses: dorny/paths-filter@v2
+      - uses: dorny/paths-filter@v3
         id: filter_ui
         with:
           #  make sure to update run-goreleaser when adding a new package here
           # also add to the get-project-id step
           filters: |
             explorer-ui: 'packages/explorer-ui/**'
-            docs: 'packages/docs/**'
+            docs: 'docs/bridge/**'
             synapse-interface: 'packages/synapse-interface/**'
       - id: length
         run: |

CODEOWNERS

@@ -16,7 +16,6 @@ make/ @trajan0x
 
 packages/contracts-core/ @ChiTimesChi @trajan0x
 packages/contracts-rfq @ChiTimesChi @mikeyrf
-packages/docs/  @trajan0x
 packages/sdk-router/ @aureliusbtc @ChiTimesChi @trajan0x
 packages/explorer-ui/ @trajan0x  @bigboydiamonds @abtestingalpha
 packages/rest-api/ @trajan0x @Defi-Moses

packages/docs/README.md → docs/bridge/README.md

@@ -1,6 +1,10 @@
 # Website
 
-This website is built using [Docusaurus 2](https://docusaurus.io/), a modern static website generator.
+This website is built using [Docusaurus](https://docusaurus.io/), a modern static website generator.
+
+## Generating API Docs
+
+`yarn docusaurus gen-api-docs all`: <!--todo: needs to be done from ci to ensure regenration is done-->
 
 ### Installation
 
@@ -23,19 +27,3 @@ $ yarn build
 ```
 
 This command generates static content into the `build` directory and can be served using any static contents hosting service.
-
-### Deployment
-
-Using SSH:
-
-```
-$ USE_SSH=true yarn deploy
-```
-
-Not using SSH:
-
-```
-$ GIT_USER=<Your GitHub username> yarn deploy
-```
-
-If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.

docs/bridge/docs/CCTP/Contracts.md

@@ -0,0 +1,18 @@
+# Contracts
+
+Synapse CCTP contracts deployed on several chains and are documented inline.  Synapse CCTP  routes tokens through the CCTP module and [SynapseCCTP](https://github.com/synapsecns/synapse-contracts/blob/master/contracts/cctp/SynapseCCTP.sol) interacts with the Circle contracts to mint/burn USDC. These contracts sit on top of the Circle CCTP contracts and are responsible for minting and burning USDC on supported chains.
+
+### Synapse CCTP
+
+| Chain     | Address                                                                                                                          |
+| --------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| Arbitrum  | [0x12715a66773bd9c54534a01abf01d05f6b4bd35e](https://arbiscan.io/address/0x12715a66773bd9c54534a01abf01d05f6b4bd35e)             |
+| Avalanche | [0x12715a66773bd9c54534a01abf01d05f6b4bd35e](https://snowtrace.io/address/0x12715a66773BD9C54534a01aBF01d05F6B4Bd35E)            |
+| Base      | [0x12715a66773bd9c54534a01abf01d05f6b4bd35e](https://basescan.org/address/0x12715a66773BD9C54534a01aBF01d05F6B4Bd35E)            |
+| Ethereum  | [0x12715a66773BD9C54534a01aBF01d05F6B4Bd35E](https://etherscan.io/address/0x12715a66773BD9C54534a01aBF01d05F6B4Bd35E)            |
+| Optimism  | [0x12715a66773bd9c54534a01abf01d05f6b4bd35e](https://optimistic.etherscan.io/address/0x12715a66773BD9C54534a01aBF01d05F6B4Bd35E) |
+| Polygon   | [0x12715a66773bd9c54534a01abf01d05f6b4bd35e](https://polygonscan.com/address/0x12715a66773BD9C54534a01aBF01d05F6B4Bd35E)         |
+
+## Circle Contracts
+
+Please refer to [this page](https://developers.circle.com/stablecoins/docs/evm-smart-contracts) for Circle contract addresses.

docs/bridge/docs/CCTP/Overview.md

@@ -0,0 +1,8 @@
+Synapse CCTP is a custom module built on top of Circle's [Cross-Chain Transfer Protocol](https://www.circle.com/en/cross-chain-transfer-protocol) that allows for bridge requests to natively mint & burn USDC on [supported chains](https://developers.circle.com/stablecoins/docs/cctp-getting-started#supported-blockchains).
+
+Synapse's CCTP implementation consists of two main components:
+
+- [CCTP Relayer](./Relayer.md): An off-chain service that fulfills transactions requested through the CCTP contracts. The relayer is responsible for fetching attestations from the [Circle API](https://developers.circle.com/stablecoin/reference) and submitting them to the CCTP contracts. Anyone can run a relayer.
+- [CCTP Contracts](./Contracts.md): A set of smart contracts that allow for the minting and burning of USDC on supported chains, and instant swaps to/from any supported asset. These contracts are deployed on each supported chain and are responsible for minting and burning USDC.
+
+As a modular component of Synapse's router system, CCTP can be configured to bridge through any supported liquidity source, such as [Curve](https://github.com/synapsecns/synapse-contracts/blob/885cbe06a960591b1bdef330f3d3d57c49dba8e2/contracts/router/modules/pool/curve/CurveV1Module.sol), [Algebra](https://github.com/synapsecns/synapse-contracts/blob/885cbe06a960591b1bdef330f3d3d57c49dba8e2/contracts/router/modules/pool/algebra/AlgebraModule.sol), [DAI PSM](https://github.com/synapsecns/synapse-contracts/blob/885cbe06a960591b1bdef330f3d3d57c49dba8e2/contracts/router/modules/pool/dss/DssPsmModule.sol),  and others.

docs/bridge/docs/CCTP/Relayer.md

@@ -0,0 +1,107 @@
+# CCTP Relayer
+
+The CCTP relayer is an off-chain service aimed at fulfilling transactions requested through the [CCTP Contracts](./Contracts.md). The relayer is responsible for fetching attestations from the [Circle API](https://developers.circle.com/stablecoin/reference) and submitting them to the CCTP contracts. Anyone can run a relayer.
+
+### Architecture
+
+The relayer is a Golang application that polls for events on chain and uses a combo state (db status) and event (on-chain logs) driven [architecture](https://medium.com/@matt.denobrega/state-vs-event-based-web-architectures-59ab1f47656b) to process transactions. The relayer is designed to be run by anyone and be easily observable.
+
+At a high level, the relayer works like this:
+
+1. Poll for new transactions from the CCTP contracts and add them to the database as [Pending](https://pkg.go.dev/github.com/synapsecns/sanguine/services/cctp-relayer@v0.10.0/types#MessageState)
+2. Fetch the attestation from the Circle API. Once successful add attestation to the database and update status to be [Attested](https://pkg.go.dev/github.com/synapsecns/sanguine/services/cctp-relayer@v0.10.0/types#MessageState)
+3. Submit the attestation to the CCTP contracts. Once the transaction has been added to [Submitter](../Services/Submitter.md), mark as [Submitted](https://pkg.go.dev/github.com/synapsecns/sanguine/services/cctp-relayer@v0.10.0/types#MessageState)
+4. Poll for the transaction receipt and mark as [Confirmed](https://pkg.go.dev/github.com/synapsecns/sanguine/services/cctp-relayer@v0.10.0/types#MessageState)
+
+### Modes
+
+As specified by the [cctp_type](#Configuration), the CCTP relayer can be run in one of two modes. In [Synapse mode](https://pkg.go.dev/github.com/synapsecns/sanguine/services/cctp-relayer@v0.10.0/types#MessageType), the [Synapse CCTP](./Contracts.md)contracts are listened to and events relayed through there (including metadata). In [Circle Mode](https://pkg.go.dev/github.com/synapsecns/sanguine/services/cctp-relayer@v0.10.0/types#MessageType), raw [TokenMessenger](https://github.com/circlefin/evm-cctp-contracts/blob/817397db0a12963accc08ff86065491577bbc0e5/src/TokenMessenger.sol) events are relayed. This mode can only be used for USDC to USDC bridges and is not commonly used.
+
+## Running the Relayer
+
+### Building From Source
+
+To build the CCTP Relayer from source, you will need to clone the repository and run the main.go file with the config file. Building from source requires go 1.21 or higher and is generally not recommended for end-users.
+
+1. `git clone https://github.com/synapsecns/sanguine --recursive`
+2. `cd sanguine/services/cctp-relayer`
+3. `go run main.go --config /path/to/config.yaml`
+
+### Running the Docker Image
+
+The CCTP Relayer can also be run with docker. To do this, you will need to pull the [docker image](https://github.com/synapsecns/sanguine/pkgs/container/sanguine%2Fcctp-relayer) and run it with the config file:
+
+```bash
+docker run ghcr.io/synapsecns/sanguine/cctp-relayer:latest --config /path/to/config
+```
+
+There is also a helm chart available for the CCTP Relayer [here](https://artifacthub.io/packages/helm/synapse/cctp/0.2.0), but it is recommended you create your own.
+
+### Configuration
+
+The CCTP Relayer is configured with a yaml file. The following is an example configuration:
+
+<details>
+  <summary>example config</summary>
+```yaml
+    cctp_type: "synapse"
+    # prod contract addresses
+    chains:
+      - chain_id: 1
+        synapse_cctp_address: "0x12715a66773BD9C54534a01aBF01d05F6B4Bd35E"
+      - chain_id: 43114
+        synapse_cctp_address: "0x12715a66773BD9C54534a01aBF01d05F6B4Bd35E"
+      - chain_id: 42161
+        synapse_cctp_address: "0x12715a66773BD9C54534a01aBF01d05F6B4Bd35E"
+      - chain_id: 10
+        synapse_cctp_address: "0x12715a66773BD9C54534a01aBF01d05F6B4Bd35E"
+      - chain_id: 8453
+        synapse_cctp_address: "0x12715a66773BD9C54534a01aBF01d05F6B4Bd35E"
+      - chain_id: 137
+        synapse_cctp_address: "0x12715a66773BD9C54534a01aBF01d05F6B4Bd35E"
+    base_omnirpc_url: "http://omnrpc-url/"
+    unbonded_signer:
+      type: "AWS"
+      # should be a mounted secret
+      file: "/config/aws.txt"
+    http_backoff_initial_interval_ms: 1000
+    http_backoff_max_elapsed_time_ms: 300000
+    # submitter config for cctp
+    submitter_config:
+      chains:
+        1:
+          supports_eip_1559: true
+          gas_estimate: 1000000
+        42161:
+          gas_estimate: 30000000
+          max_gas_price: 10000000000
+          supports_eip_1559: true
+        43114:
+          gas_estimate: 5000000
+          max_gas_price: 1000000000000
+          supports_eip_1559: true
+        10:
+          gas_estimate: 5000000
+          max_gas_price: 2000000000
+          supports_eip_1559: true
+        8453:
+          gas_estimate: 5000000
+        137:
+          gas_estimate: 5000000
+          max_gas_price: 10000000000000
+          supports_eip_1559: true
+```
+</details>
+
+ - `cctp_type`: The type of CCTP to listen to. Can be either `synapse` or `circle`.
+ - `chains`: A list of chain ids and their corresponding CCTP contract addresses. If synapse mode, this should be `synapse_cctp_address` and if circle mode, this should be `token_messenger_address`. Both modes cannot be used at once and the other will be ignored if both are set.
+ - `base_omnirpc_url`: The base URL for the OmniRPC service.
+ - `unbonded_signer`: The signer to use for transactions. Can be either `AWS`, `File` or `GCP`. The file should be a mounted secret. More details can be found [here](../Services/Signer).
+ - `port`: The port to run the relayer on (e.g. 8080)
+ - `host`: The host to run the relayer on (e.g. localhost). Note: this should not be publicly exposed
+ - `http_backoff_initial_interval_ms`: The initial interval for the backoff in milliseconds.
+ - `retry_interval_ms`: The interval to wait between attestation request retries in milliseconds. The [CCTP API Rate Limit](https://developers.circle.com/stablecoins/docs/limits) should be kept in mind.
+
+### Observability
+
+The CCTP relayer implements open telemetry for both tracing and metrics. Please see the [Observability](../Observability) page for more info.

docs/bridge/docs/CCTP/_category_.json

@@ -0,0 +1,8 @@
+{
+  "label": "CCTP",
+  "position": 3,
+  "link": {
+    "type": "doc",
+    "id": "CCTP/Overview"
+  }
+}

docs/bridge/docs/Observability.md

@@ -0,0 +1,29 @@
+All off-chain systems are by default observable and configured through the [metrics](https://pkg.go.dev/github.com/synapsecns/sanguine/core/metrics#section-readme) package. The observability stack is built around [open telemetry](https://opentelemetry.io/) with metrics also being exported using this standard.
+
+"Metrics" themselves are divided into 3 different types of metrics:
+
+1. **Traces**: These are used to trace the flow of a request through the system. Our code uses traces for all sorts of events, from the start of a request to the end of a request. Traces are used to debug and profile the system. Traces are made up of spans, which are individual events that occur during the lifetime of a trace. Traces are aggregated ex-post facto by observability solutions. Please see [this article](https://grafana.com/docs/tempo/latest/traces/) for a good overview.
+2. **Metrics**: Metrics consist of things like gauges, counters, and histograms. These are used to monitor the health of the system. Metrics are aggregated in real-time by observability solutions. Please see [this article](https://grafana.com/docs/grafana-cloud/metrics/) for a good overview. We use the Prometheus exporter for metrics and by default make them available on `METRICS_PORT` at `METRICS_PATH`.
+3. **APM (Application Performance Monitoring)**: APM is a combination of traces and metrics. It is used to monitor the performance of the system. We use Pyroscope for APM and by default make it available on `PYROSCOPE_ENDPOINT`.
+
+:::tip
+Sanguine is an open-source repo and tries to be as unopinionated as possible when it comes to which libraries it uses for observability. If you're interested in maintaining an unsupported module as part of the [metrics](https://pkg.go.dev/github.com/synapsecns/sanguine/core/metrics#section-readme) package, pull requests are always welcome!
+:::
+
+### Configuring Observability
+
+**Configuring Tracing**:
+
+1. Pick a vendor that supports the [OTLP](https://opentelemetry.io/ecosystem/vendors/) standard. We recommend Signoz for OSS.
+2. Set the `METRICS_HANDLER` environment variable to `OTLP`. If you're using a legacy jaeger instance, you can also use `JAEGER`
+3. Set the `OTLP_ENDPOINT` environment variable to the endpoint of your observability solution.
+
+**Configuring Metrics**
+
+1. Pick a vendor that supports the [prometheus](https://prometheus.io/docs/instrumenting/exporters/) standard. We recommend Grafana for OSS.
+2. Set the `METRICS_PORT_ENABLED` environment variable to `true` to enable the metrics endpoint.
+3. Find your metrics on `METRICS_PORT` at `METRICS_PATH` and configure scrapers.
+
+**Configuring APM**
+
+Set the `PYROSCOPE_ENDPOINT` environment variable to the endpoint of your [pyroscope instance](https://pyroscope.io/).

docs/bridge/docs/Services/Omnirpc.md

@@ -0,0 +1,77 @@
+Omnirpc is an rpc load balancer and verifier that allows users to query chain data from multiple chains. It is a service that should be run by Quoters and interfaces that allow Solvers to post quotes. Omnirpc takes in a yaml config that allows the user to specify which chains it should run on.
+
+### Running OmniRPC
+
+### Building From Source
+
+To build omnirpc from source, you will need to have Go installed. You can install Go by following the instructions [here](https://golang.org/doc/install). Once you have Go installed, you can build the relayer by running the following commands:
+
+1. `git clone https://github.com/synapsecns/sanguine --recursive`
+2. `cd sanguine/services/omnirpc`
+3. `go run main.go --config /path/to/config.yaml`
+
+### Running the Docker Image
+
+The relayer can also be run with docker. To do this, you will need to pull the [docker image](https://github.com/synapsecns/sanguine/pkgs/container/sanguine%2Frfq-relayer) and run it with the config file:
+
+```bash
+docker run ghcr.io/synapsecns/sanguine/omnirpc:latest --config /path/to/config
+```
+
+There is also a helm chart available for omnirpc [here](https://artifacthub.io/packages/helm/synapse/omnirpc).
+
+### Configuration
+
+Omnirpc is configured with a yaml file. The following is an example configuration:
+
+```yaml
+chains:
+  1:
+    rpcs:
+      - https://api.mycryptoapi.com/eth
+      - https://rpc.flashbots.net/
+      - https://eth-mainnet.gateway.pokt.network/v1/5f3453978e354ab992c4da79
+      - https://cloudflare-eth.com/
+      - https://mainnet-nethermind.blockscout.com/
+      - https://nodes.mewapi.io/rpc/eth
+      - https://main-rpc.linkpool.io/
+      - https://mainnet.eth.cloud.ava.do/
+      - https://ethereumnodelight.app.runonflux.io
+      - https://rpc.ankr.com/eth
+      - https://eth-rpc.gateway.pokt.network
+      - https://main-light.eth.linkpool.io
+      - https://eth-mainnet.public.blastapi.io
+      - http://18.211.207.34:8545
+      - https://eth-mainnet.nodereal.io/v1/1659dfb40aa24bbb8153a677b98064d7
+      - wss://eth-mainnet.nodereal.io/ws/v1/1659dfb40aa24bbb8153a677b98064d7
+      - https://api.bitstack.com/v1/wNFxbiJyQsSeLrX8RRCHi7NpRxrlErZk/DjShIqLishPCTB9HiMkPHXjUM9CNM9Na/ETH/mainnet
+    confirmations: 5
+  10:
+    rpcs:
+      - https://mainnet.optimism.io
+    confirmations: 1
+# port to run on
+port: 5000
+# expressed in seconds
+refreshInterval: 60
+```
+
+In this example, any request to ethereum (chain id: 1) will need at least 5 rpcs to agree on the data before it is considered valid, but op will only need 1.
+
+Data can be fetched like so, where the last character is the chain id:
+
+```bash
+curl --location --request POST 'http://localhost:5000/rpc/1' \
+--header 'Content-Type: application/json' \
+--data-raw '{
+	"jsonrpc":"2.0",
+	"method":"eth_getTransactionCount",
+	"params":[
+		"0x230a1ac45690b9ae1176389434610b9526d2f21b",
+		"0xec1d40"
+	],
+	"id":1
+}'
+```
+
+Not all requests are confirmable. Please see [here](https://pkg.go.dev/github.com/synapsecns/sanguine/services/omnirpc#section-readme) for details.

docs/bridge/docs/Services/Signer.md

@@ -0,0 +1,3 @@
+# Signer
+
+This section is still in progress, please see [here](https://pkg.go.dev/github.com/synapsecns/sanguine/ethergo@v0.9.0/signer/signer#section-readme) for details.

docs/bridge/docs/Services/Submitter.md

@@ -0,0 +1,7 @@
+# Submitter
+
+This section is still in progress, please see [here](https://pkg.go.dev/github.com/synapsecns/sanguine/ethergo/submitter#section-readme) for details.
+
+### Submitter Config
+
+This section is still in progress, please see [here](https://pkg.go.dev/github.com/synapsecns/sanguine/ethergo@v0.9.0/submitter/config) for details.