From b48867f8efe5b305428e561d0a55a8d6d308c2a4 Mon Sep 17 00:00:00 2001 From: Trajan0x Date: Wed, 26 Jun 2024 21:32:39 -0400 Subject: [PATCH 1/2] document scribe --- docs/bridge/docs/Services/Scribe.md | 120 ++++++++++++++++++++++++++++ docs/bridge/docusaurus.config.ts | 8 +- 2 files changed, 121 insertions(+), 7 deletions(-) create mode 100644 docs/bridge/docs/Services/Scribe.md diff --git a/docs/bridge/docs/Services/Scribe.md b/docs/bridge/docs/Services/Scribe.md new file mode 100644 index 0000000000..9f2e75a082 --- /dev/null +++ b/docs/bridge/docs/Services/Scribe.md @@ -0,0 +1,120 @@ +--- +sidebar_position: 0 +sidebar_label: Scribe +--- + +# Scribe + +Scribe is a multi-chain indexing service designed to store logs, receipts, and transactions for every event from specified contracts across multiple blockchains. It provides a powerful tool for analytics, event streaming, and monitoring on-chain activities. + +## Key Features + +1. **Multi-Chain Support**: Currently indexes over 900 contracts across 18 different chains. +2. **Flexible Indexing**: Supports indexing any number of contracts on any chain. +3. **Real-Time and Historical Data**: Indexes from a specified start block up to real-time events. +4. **Reorg Protection**: Stores "unconfirmed" events near the chain tip in separate tables. +5. **GraphQL API**: Provides a GraphQL/IQL endpoint for easy data querying. + +## Architecture + +Scribe consists of two main components: + +1. **Scribe Indexer**: Responsible for fetching and storing blockchain data. +2. **Scribe Server**: Provides a GraphQL API for querying indexed data. + +The indexer architecture consists of three main components: + +1. **Fetcher**: Retrieves logs for specified contracts and block ranges. +2. **Indexer**: Stores logs, receipts, and transactions for events for a given contract. +3. **ChainIndexer**: Manages multiple indexers per chain for different indexing stages (backfill, livefill, unconfirmed livefill). + +## Running Scribe + +### Building From Source + +To build Scribe 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 Scribe by running the following commands: + +1. `git clone https://github.com/synapsecns/sanguine --recursive` +2. `cd sanguine/services/scribe` +3. `go build` + + +There is also a [docker image](https://github.com/synapsecns/sanguine/pkgs/container/sanguine%2Fscribe) available for scribe. + +### Running the Components + +To start the Scribe indexer: + +```bash +./scribe --config --db --path +``` + +To start the Scribe server: + +```bash +./server --port --db --path +``` + +### Deployment + +Scribe can be deployed using Helm charts. You can see the scribe chart on [artifacthub](https://artifacthub.io/packages/helm/synapse/scribe) + +### Configuration + +Most deployments of scribe will run two components, the indexer and the server. The indexer is responsible for fetching and storing blockchain data, while the server provides a GraphQL API for querying indexed data. The configuration file for Scribe is a YAML file with the following structure: + +indexer.yaml: +
+ example config + ```yaml + + ``` +
+ +```yaml +chains: + - chain_id: 1 + get_logs_range: 500 + get_block_batch_amount: 1 + store_concurrency: 100 + concurrency_threshold: 50000 + livefill_threshold: 300 + livefill_range: 200 + livefill_flush_interval: 10000 + confirmations: 200 + contracts: + - address: 0xAf41a65F786339e7911F4acDAD6BD49426F2Dc6b + start_block: 18646320 +``` + +Key configuration parameters include: + +- `rpc_url`: The omnirpc url to use for querying chain data (no trailing slash). For more information on omnirpc, see [here](Services//Omnirpc.md). +- `chains`: List of chains to index, including chain-specific parameters: + - `chain_id`: The ID of the chain. + - `get_logs_range`: The number of blocks to request in a single `getLogs` request. + - `get_logs_batch_amount`: The number of `getLogs` requests to include in a batch request. + - `store_concurrency`: The number of goroutines to use when storing data. + - `concurrency_threshold`: The maximum number of blocks from the head in which concurrent operations (store, getLogs) are allowed. + - `livefill_threshold`: Number of blocks away from the head to start livefilling. + - `livefill_range`: Range in which the `getLogs` request for the livefill contracts will be requesting. + - `livefill_flush_interval`: The interval in which the unconfirmed livefill table will be flushed. + - `confirmations`: The number of blocks from the head that the livefiller will livefill up to (and where the unconfirmed livefill indexer will begin). + - `contracts`: List of contracts to index per chain, including: + - `address`: Address of the contract. + - `start_block`: Block to start indexing the contract from (block with the first transaction). + +## API + +Scribe provides a GraphQL API for querying indexed data. Some basic queries include: + +- `lastIndexed(chain_id, contract_address)` +- `logsRange(chain_id, contract_address, start_block, end_block, page)` +- `blockTime(chain_id, block_number)` +- `txSender(tx_hash, chain_id)` + +For a full list of available queries, refer to the GraphQL schema. + +## Observability + +Scribe implements open telemetry for both tracing and metrics. Please see the [Observability](../../Observability) page for more info. diff --git a/docs/bridge/docusaurus.config.ts b/docs/bridge/docusaurus.config.ts index da123b7f81..63a90080b5 100644 --- a/docs/bridge/docusaurus.config.ts +++ b/docs/bridge/docusaurus.config.ts @@ -67,13 +67,7 @@ const config: Config = { }, items: [ { - type: 'docSidebar', - sidebarId: 'tutorialSidebar', - position: 'left', - label: 'Tutorial', - }, - { - href: 'https://github.com/facebook/docusaurus', + href: 'https://github.com/synapsecns/sanguine', label: 'GitHub', position: 'right', }, From 7105159ef3b011817b844734e9d1db3de11e4a7b Mon Sep 17 00:00:00 2001 From: Trajan0x Date: Wed, 26 Jun 2024 21:39:09 -0400 Subject: [PATCH 2/2] deploy fix --- docs/bridge/docs/Services/Scribe.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/bridge/docs/Services/Scribe.md b/docs/bridge/docs/Services/Scribe.md index 9f2e75a082..0b58a1edab 100644 --- a/docs/bridge/docs/Services/Scribe.md +++ b/docs/bridge/docs/Services/Scribe.md @@ -117,4 +117,4 @@ For a full list of available queries, refer to the GraphQL schema. ## Observability -Scribe implements open telemetry for both tracing and metrics. Please see the [Observability](../../Observability) page for more info. +Scribe implements open telemetry for both tracing and metrics. Please see the [Observability](../Observability) page for more info.