From 1070d38c17fdeaca2f8a567675d3c89522cc307b Mon Sep 17 00:00:00 2001 From: golangisfun123 Date: Wed, 3 Jul 2024 12:12:50 -0500 Subject: [PATCH] comments --- docs/bridge/docs/Services/Submitter.md | 70 ++++++++++++++++++++++---- docs/bridge/docusaurus.config.ts | 7 ++- docs/bridge/package.json | 1 + 3 files changed, 67 insertions(+), 11 deletions(-) diff --git a/docs/bridge/docs/Services/Submitter.md b/docs/bridge/docs/Services/Submitter.md index 8084d5a8bf..9d62d3d2a0 100644 --- a/docs/bridge/docs/Services/Submitter.md +++ b/docs/bridge/docs/Services/Submitter.md @@ -8,8 +8,6 @@ This section is still in progress, please see [here](https://pkg.go.dev/github.c The Ethergo Submitter module is designed to submit transactions to an EVM-based blockchain. It handles gas bumping and confirmation checking to ensure that transactions are eventually confirmed. This module is essential because the EVM does not specify transaction submission or consensus, and rate limits can affect transaction submission. -![submitter flow](img/submitter/submitter_flow.svg) - ## Key Features The module is the `SubmitTransaction` method, which returns a nonce and ensures that the transaction will eventually be confirmed. The nonce may then be used in the `GetSubmissionStatus` method to check the state: `Pending`, `Stored`, `Submitted`, `FailedSubmit`, `ReplacedOrConfirmed`, `Replaced`, `Confirmed`. @@ -18,6 +16,36 @@ The module is the `SubmitTransaction` method, which returns a nonce and ensures - **Confirmation Checking**: Continuously checks the status of submitted transactions to confirm their inclusion in the blockchain. - **Reaper Functionality**: Flushes old entries in the database that have reached a terminal state. +#### Note: Status Enum + +In the DB, `Status`, is an enum, represented as a uint8. It is important to know what number indicates what status. + +```go title="submitter/db/service.go" +type Status uint8 + +// Important: do not modify the order of these constants. +// if one needs to be removed, replace it with a no-op status. +// additionally, due to the GetMaxNoncestatus function, statuses are currently assumed to be in order. +// if you need to modify this functionality, please update that function. to reflect that the highest status +// is no longer the expected end status. +const ( + // Pending is the status of a tx that has not been processed yet. + Pending Status = iota + 1 // Pending + // Stored is the status of a tx that has been stored. + Stored // Stored + // Submitted is the status of a tx that has been submitted. + Submitted // Submitted + // FailedSubmit is the status of a tx that has failed to submit. + FailedSubmit // Failed + // ReplacedOrConfirmed is the status of a tx that has been replaced by a new tx or confirmed. The actual status will be set later. + ReplacedOrConfirmed // ReplacedOrConfirmed + // Replaced is the status of a tx that has been replaced by a new tx. + Replaced // Replaced + // Confirmed is the status of a tx that has been confirmed. + Confirmed // Confirmed +) +``` + ### Reaper The Submitter also has "reaper" functionality, which flushes old entries in the database that have reached a terminal state (`Replaced`, `ReplacedOrConfirmed`, `Confirmed`). By default, entries are flushed after a week, but this functionality is configurable by the `MaxRecordAge` config value. @@ -34,17 +62,39 @@ for each chain. If a chain-specific item is not provided, the global config is u submitter_config: chains: 1: - supports_eip_1559: true + # MaxBatchSize is the maximum number of transactions to send in a batch. + # If this is zero, the default will be used. + # This field is ignored if batching is disabled. + max_batch_size: 50 + # Batch is whether or not to batch transactions at the rpc level. + skip_batching: false + # MaxGasPrice is the maximum gas price to use for transactions. + max_gas_price: 200000000000 # 200 Gwei + # MinGasPrice is the gas price that will be used if 0 is returned + # from the gas price oracle. + min_gas_price: 1000000000 # 1 Gwei + # BumpIntervalSeconds is the number of seconds to + # wait before bumping a transaction. + bump_interval_seconds: 120 + # GasBumpPercentages is the percentage to bump the gas price by. + # This is applied to the greatrer of the chainprice or the last price. + gas_bump_percentage: 10 + # GasEstimate is the gas estimate to use for transactions if + # dynamic gas estimation is enabled. + # This is only used as a default if the estimate fails. gas_estimate: 1000000 - 43114: - gas_estimate: 30000000 - max_gas_price: 100000000000 + # DynamicGasEstimate is whether or not to use dynamic gas estimation. + dynamic_gas_estimate: true + # SupportsEIP1559 is whether or not this chain supports EIP1559. supports_eip_1559: true + 43114: + max_gas_price: 100000000000 # 100 Gwei 10: - gas_estimate: 400000 - max_gas_price: 90000000000 - gas_bump_percentage: 20 + max_gas_price: 90000000000 # 90 Gwei + min_gas_price: 100000000 # 0.1 Gwei + # ReaperInterval is the interval at which scan for transactions to flush reaper_interval: 604800000000000 # int64(7 * 24 * time.Hour) + # MaxRecordAge is the maximum age of a record before it is flushed max_record_age: 86400000000000 # int64(1 * 24 * time.Hour) ``` @@ -94,7 +144,7 @@ The Chain Queue db interface, [Service](https://github.com/synapsecns/sanguine/b The schema for a transaction to be stored in the Transaction DB is: -```go +```go title="submitter/db/txdb/model.go" // ETHTX contains a raw evm transaction that is unsigned. type ETHTX struct { ID uint64 `gorm:"column:id;primaryKey;autoIncrement:true"` diff --git a/docs/bridge/docusaurus.config.ts b/docs/bridge/docusaurus.config.ts index 63a90080b5..3c15ca2cca 100644 --- a/docs/bridge/docusaurus.config.ts +++ b/docs/bridge/docusaurus.config.ts @@ -22,6 +22,11 @@ const config: Config = { onBrokenLinks: 'throw', onBrokenMarkdownLinks: 'throw', + // support Mermaid + markdown: { + mermaid: true, + }, + // Even if you don't use internationalization, you can use this field to set // useful metadata like html lang. For example, if your site is Chinese, you // may want to replace "en" with "zh-Hans". @@ -119,7 +124,7 @@ const config: Config = { darkTheme: prismThemes.dracula, }, } satisfies Preset.ThemeConfig, - themes: ["docusaurus-theme-openapi-docs"], // export theme components + themes: ["docusaurus-theme-openapi-docs", '@docusaurus/theme-mermaid'], // export theme components plugins: [ [ 'docusaurus-plugin-openapi-docs', diff --git a/docs/bridge/package.json b/docs/bridge/package.json index 52f0e24202..350778abf2 100644 --- a/docs/bridge/package.json +++ b/docs/bridge/package.json @@ -24,6 +24,7 @@ "@docusaurus/plugin-content-docs": "3.1.1", "@docusaurus/preset-classic": "3.1.1", "@docusaurus/theme-common": "3.1.1", + "@docusaurus/theme-mermaid": "3.1.1", "@docusaurus/utils": "3.1.1", "@docusaurus/utils-common": "3.1.1", "@docusaurus/utils-validation": "3.1.1",