Crate partner_chains_db_sync_data_sources

Expand description

Crate providing implementations of Partner Chain Data Sources that read from Db-Sync Postgres.

§Usage

§Adding to the node

All data sources defined in this crate require a Postgres connection pool PgPool to run queries, which should be shared between all data sources. For convenience, this crate provides a helper function get_connection_from_env that will create a connection pool based on configuration read from node environment.

Each data source also accepts an optional Prometheus metrics client McFollowerMetrics for reporting metrics to the Substrate’s Prometheus metrics service. This client can be obtained using the register_metrics_warn_errors function.

In addition to these two common arguments, some data sources depend on BlockDataSourceImpl which provides basic queries about blocks, and additional configuration for their data cache size.

An example node code that creates the data sources can look like the following:

use partner_chains_db_sync_data_sources::*;

pub const CANDIDATES_FOR_EPOCH_CACHE_SIZE: usize = 64;
pub const STAKE_CACHE_SIZE: usize = 100;
pub const GOVERNED_MAP_CACHE_SIZE: u16 = 100;

async fn create_data_sources(
    metrics_registry_opt: Option<&substrate_prometheus_endpoint::Registry>
) -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
    let metrics = register_metrics_warn_errors(metrics_registry_opt);
    let pool = get_connection_from_env().await?;

    // Block data source is shared by others for cache reuse
    let block = Arc::new(BlockDataSourceImpl::new_from_env(pool.clone()).await?);

    let sidechain_rpc = SidechainRpcDataSourceImpl::new(block.clone(), metrics.clone());

    let mc_hash = Arc::new(McHashDataSourceImpl::new(block.clone(), metrics.clone()));

    let authority_selection =
        CandidatesDataSourceImpl::new(pool.clone(), metrics.clone())
    	.await?
    	.cached(CANDIDATES_FOR_EPOCH_CACHE_SIZE)?;

    let native_token =
        NativeTokenManagementDataSourceImpl::new_from_env(pool.clone(), metrics.clone()).await?;

    let block_participation =
    	StakeDistributionDataSourceImpl::new(pool.clone(), metrics.clone(), STAKE_CACHE_SIZE);

    let governed_map =
        GovernedMapDataSourceCachedImpl::new(pool, metrics.clone(), GOVERNED_MAP_CACHE_SIZE, block).await?;
    Ok(())
}

§Cardano DB Sync configuration

Partner Chains data sources require specific Db-Sync configuration to be set for them to operate correctly:

insert_options.tx_out.value: must be either "enable" (default) or "consumed". When "consumed" is used then tx_out.force_tx_in has to be true. Code in this crate depends on tx_in table being present.
insert_options.tx_out.use_address_table: must be false (default).
insert_options.ledger: must be "enable" (default).
insert_options.multi_asset: must be true (default).
insert_options.governance: must "enable" (default).
insert_options.remove_jsonb_from_schema: must be "disable" (default).
insert_options.plutus: must be "enable" (default).

The default Cardano DB Sync configuration meets these requirements, so Partner Chain node operators that do not wish to use any custom configuration can use the defaults, otherwise they must preserve the values described above. See Db-Sync configuration docs for more information.

§Custom Indexes

In addition to indexes automatically created by Db-Sync itself, data sources in this crate require additional ones to be created for some of the queries to execute efficiently. These indexes are:

idx_ma_tx_out_ident ON ma_tx_out(ident)
idx_tx_out_address ON tx_out USING hash (address)

The data sources in this crate automatically create these indexes when needed at node startup.

Macros§

observed_async_trait: Logs each method invocation and each returned result. Has to be made at the level of trait, because otherwise #async_trait is expanded first. ‘&self’ matching yields “__self” identifier not found error, so “&$self:tt” is required. Works only if return type is Result.

Structs§

BlockDataSourceImpl: Db-Sync data source that queries Cardano block information
CandidatesDataSourceImpl: Db-Sync data source serving data for Partner Chain committee selection
ConnectionConfig: Postgres connection config used when creating a PgPool.
DbSyncBlockDataSourceConfig: Configuration for BlockDataSourceImpl
GovernedMapDataSourceCachedImpl: Cached data source serving the Governed Map feature of Partner Chains toolkit
GovernedMapDataSourceImpl: Data source for the Governed Map feature of Partner Chains toolkit
McFollowerMetrics: Substrate Prometheus metrics client used by Partner Chain data sources
McHashDataSourceImpl: Db-Sync data source used by the Main Chain Reference feature of Partner Chain toolkit.
NativeTokenManagementDataSourceImpl: Db-Sync data source for the Native Token Management feature of the Partner Chains toolkit.
SidechainRpcDataSourceImpl: Db-Sync data source serving basic Cardano block data
SqlxError: Wrapper error type for [sqlx::Error]
StakeDistributionDataSourceImpl: Db-Sync data source serving data about Cardano delegations

Enums§

DataSourceError: Error type returned by Db-Sync based data sources

Functions§

get_connection_from_env: Returns a Postgres connection pool constructed using configuration read from environment
read_mc_epoch_config: Reads Cardano main chain epoch configuration from the environment.
register_metrics_warn_errors: Registers new metrics with Substrate Prometheus metrics service and returns a client instance

Type Aliases§

PgPool: An alias for [Pool][crate::pool::Pool], specialized for Postgres.

Crate partner_chains_db_sync_data_sourcesCopy item path