npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@cardano-sdk/cardano-services

v0.33.4

Published

Cardano GraphQL Services

Downloads

602

Readme

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