@cardano-sdk/cardano-services

Cardano JS SDK | Cardano GraphQL Services

Libraries and program entrypoints for services to facilitate remote data and submit access using Provider interfaces over HTTP; The TxSubmitHttpService can be configured to submit via Ogmios or via submit-api. Data is sourced from Cardano DB Sync, the local Cardano Node via Ogmios Local State Queries, genesis files, and remote sources.

Features

• CLI with configuration via command line arguments or environment variables and optional loading of secrets from disk.
• Service port discovery via DNS resolution, or static configuration.
• Fault-tolerant transaction submission.
• Optional Prometheus metrics available at /metrics
• Data sourced from Cardano DB Sync PostgreSQL, Local State Queries, genesis files, and remote sources.

Services

The services require instances of Cardano Node and Ogmios as a minimum, with Cardano DB Sync dependent on the run command. Please refer to docker-compose.json for the current supported version of each service dependency.

Provider Server

The Provider server can be started with one or more services by name, segmented by URL path. Run the CLI with start-provider-server --help to see the full list of options.

Examples

The following examples require the install and build steps to be completed.

All Providers | Static Service Config | Direct Tx Submission

• The server will expose all Provider HTTP services
• Transactions will be submitted directly via Ogmios, running at ws://localhost:1338.
• Connects to PostgreSQL service running at localhost:5432
• HTTP API exposed using a custom API URL

start-provider-server using CLI options:

./dist/cjs/cli.js \
  start-provider-server \
    --api-url http://localhost:6000 \
    --cardano-node-config-path ./config/network/preprod/cardano-node/config.json \
    --postgres-connection-string-db-sync postgresql://somePgUser:somePassword@localhost:5432/someDbName \
    --ogmios-url  ws://localhost:1338 \
    asset chain-history stake-pool tx-submit network-info utxo rewards

start-provider-server using env variables:

SERVICE_NAMES=asset,chain-history,stake-pool,tx-submit,network-info,utxo,rewards \
API_URL=http://localhost:6000 \
CARDANO_NODE_CONFIG_PATH=./config/network/preprod/cardano-node/config.json \
POSTGRES_CONNECTION_STRING_DB_SYNC=postgresql://somePgUser:somePassword@localhost:5432/someDbName \
OGMIOS_URL=ws://localhost:1338 \
./dist/cjs/cli.js start-provider-server

All Providers | Service Discovery | Metrics

• The server will expose all Provider HTTP services
• Ports for Ogmios and PostgreSQL, discovered using DNS resolution.
• HTTP API exposed using a custom API URL
• Prometheus metrics exporter enabled at http://localhost:6000/metrics

start-provider-server using CLI options:

./dist/cjs/cli.js \
  start-provider-server \
    --api-url http://localhost:6000 \
    --enable-metrics \
    --cardano-node-config-path ./config/network/preprod/cardano-node/config.json \
    --postgres-srv-service-name-db-sync someHostName \
    --postgres-db-db-sync someDbName \
    --postgres-user-db-sync somePgUser \
    --postgres-password-db-sync somePassword \
    --ogmios-srv-service-name  some-domain-for-ogmios \
    asset chain-history stake-pool tx-submit network-info utxo rewards

start-provider-server using env variables:

SERVICE_NAMES=asset,chain-history,stake-pool,tx-submit,network-info,utxo,rewards \
API_URL=http://localhost:6000 \
ENABLE_METRICS=true \
CARDANO_NODE_CONFIG_PATH=./config/network/preprod/cardano-node/config.json \
POSTGRES_SRV_SERVICE_NAME_DB_SYNC=some-domain-for-postgres-db
POSTGRES_DB_DB_SYNC=someDbName \
POSTGRES_USER_DB_SYNC=someUser \
POSTGRES_PASSWORD_DB_SYNC=somePassword \
OGMIOS_SRV_SERVICE_NAME=some-domain-for-ogmios \
./dist/cjs/cli.js start-provider-server

start-pg-boss-worker using CLI options:

./dist/cjs/cli.js start-pg-boss-worker --queues=pool-metadata --postgres-connection-string-stake-pool "postgresql://postgres:doNoUseThisSecret\!@localhost:5432/projection" --postgres-connection-string-db-sync "postgresql://postgres:doNoUseThisSecret\!@localhost:5432/cexplorer"

start-pg-boss-worker using env variables:

QUEUES=pool-metadata POSTGRES_CONNECTION_STRING_STAKE_POOL=postgresql://postgres:doNoUseThisSecret\!@localhost:5432/projection POSTGRES_CONNECTION_STRING_DB_SYNC=postgresql://postgres:doNoUseThisSecret\!@localhost:5432/cexplorer ./dist/cjs/cli.js start-pg-boss-worker

start-projector using CLI options with Ogmios and PostgreSQL running on localhost:

./dist/cjs/cli.js \
  start-projector \
    --ogmios-url 'ws://localhost:1339' \
    --postgres-connection-string 'postgresql://postgres:doNoUseThisSecret!@localhost/projection' \
    stake-pool,stake-pool-metadata-job

Production

The Docker images produced by the SDK and the docker compose infrastructures (mainnet, preprod and local-network) it includes are ready to be used in production environment.

Note: the docker compose infrastructures included in the SDK are mainly used for development purposes: to use them in production environments, the projector service(s) must be instructed to run the migration scripts rather than to use the synchronize development option from TypeORM. This can be achieved through environment variables:

SYNCHRONIZE=false yarn preprod:up

Development

To speed up the development process, developers can ignore the migrations while developing or debugging changes. This freedom is granted by the synchronize development option from TypeORM, which is enabled by default in the docker compose infrastructures included in the SDK.

Generating Projector Schema Migrations

In order to grant to the projection service the ability to choose which projections it needs to activate, the migrations must be scoped to a single model: if a single change has impact on more models, one migration for each impacted model must be generated.

Hint: isolating all the changes to each model in distinct commits can be so helpful for this target!

For each migration, once the change is finalized (all the new entities are added to the entities object at src/Projection/prepareTypeormProjection.ts, apart from last minor refinements the PR is approved, etc...), the relative migration can be generated following these steps.

Hint: if previous hint was followed, to checkout each commit which requires a migration to produce a fixup commit for each of them can be an easy way to iterate over all the impacted models.

1. Start a new fresh database with DROP_PROJECTOR_SCHEMA=true SYNCHRONIZE=false yarn preprod up
   • Note: do not override PROJECTION_NAMES since in this scope all the projections must be loaded
   • Note: this will not apply the current changes to the models into the database schema, so the currently developed feature may not work properly, this is not relevant for the target of creating the migration
   • DROP_PROJECTOR_SCHEMA=true is used to let the projection service to create the database schema from scratch
   • with SYNCHRONIZE=false the projection service runs all migrations rather than reflecting the changes to the models on the schema (through the synchronize development option from TypeORM)
2. Run yarn generate-migration to produce a new migration in src/Projections/migrations directory
   • this compares the database schema against all the models (repeat: only one of them should be changed) and generates the required migration
3. Inspect the generated migration
   • Check: if the migration has impact on more than one table, the changes was not isolated per model! (the change must be reworked)
4. Add the static entity property to the migration class (to see other migrations for reference)
5. Rename the newly generated migration file and class giving them mnemonic names
6. Export the new migration from migrations array at src/Projections/migrations/index.ts

Tests

See code coverage report