{"id":22437056,"url":"https://github.com/blockfrost/blockfrost-backend-ryo","last_synced_at":"2025-04-06T10:10:37.586Z","repository":{"id":62839515,"uuid":"529308237","full_name":"blockfrost/blockfrost-backend-ryo","owner":"blockfrost","description":"Blockfrost API backend. You can now Run-Your-Own.","archived":false,"fork":false,"pushed_at":"2025-04-02T16:41:59.000Z","size":291876,"stargazers_count":73,"open_issues_count":11,"forks_count":23,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-04-03T00:49:46.805Z","etag":null,"topics":["api","blockfrost","cardano"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/blockfrost.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-08-26T15:20:42.000Z","updated_at":"2025-03-26T15:42:59.000Z","dependencies_parsed_at":"2023-10-27T13:29:38.845Z","dependency_job_id":"d3efaad2-cdde-466e-a381-34347cf1f22e","html_url":"https://github.com/blockfrost/blockfrost-backend-ryo","commit_stats":null,"previous_names":[],"tags_count":47,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blockfrost%2Fblockfrost-backend-ryo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blockfrost%2Fblockfrost-backend-ryo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blockfrost%2Fblockfrost-backend-ryo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blockfrost%2Fblockfrost-backend-ryo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/blockfrost","download_url":"https://codeload.github.com/blockfrost/blockfrost-backend-ryo/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247464220,"owners_count":20942970,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","blockfrost","cardano"],"created_at":"2024-12-06T00:11:27.645Z","updated_at":"2025-04-06T10:10:37.566Z","avatar_url":"https://github.com/blockfrost.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ca href=\"https://fivebinaries.com/\"\u003e\u003cimg src=\"https://img.shields.io/badge/made%20by-Five%20Binaries-darkviolet.svg?style=flat-square\" /\u003e\u003c/a\u003e\n\n\u003cimg src=\"https://blockfrost.io/images/logo.svg\" width=\"250\" align=\"right\" height=\"90\"\u003e\u003cbr\u003e\n\n# Blockfrost.io backend service\n\n\u003cp align=\"center\"\u003e\u003ca href=\"https://blockfrost.io\"\u003eBlockfrost.io\u003c/a\u003e backend is \u003ca href=\"https://github.com/blockfrost/openapi\"\u003ean API service\u003c/a\u003e providing abstraction between you and Cardano blockchain data, taking away the burden of complexity, so you can focus on what really matters - developing your applications. \u003cbr\u003e\u003cbr\u003e You can now Run-Your-Own.\u003c/p\u003e\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"#getting-started\"\u003eGetting started\u003c/a\u003e •\n  \u003ca href=\"#running-your-own\"\u003eRunning your own\u003c/a\u003e •\n  \u003ca href=\"#developing\"\u003eDeveloping\u003c/a\u003e •\n  \u003ca href=\"https://github.com/orgs/blockfrost/projects/8\"\u003e:pushpin: Roadmap\u003c/a\u003e\n\u003c/p\u003e\n\u003cbr\u003e\n\n## Getting started\n\nThe backend is Node.js app written in Typescript using Fastify. To run it you need Node.js version 16 and higher (LTS is highly recommended). Blockchain data are queried from [cardano-db-sync](https://github.com/input-output-hk/cardano-db-sync). Follow their documentation to learn more about running your own instance.\n\n## Running your own\n\nWe made it simple to run your own version of the Blockfrost backend.\n\n### System requirements\n\nThe system requirements for the basic Blockfrost backend stack (which means `blockfrost-backend`, `cardano-node`, `cardano-db-sync` and `postgresql` on the same machine) are:\n\n- 64 GB of RAM or more\n- 8 CPU cores or more\n- 250 GB of disk space or more\n- SSD disk with at least 80k IOPS (measured as chunk size)\n\n### Configuration\n\nThere are several configuration files in `config` directory. Config file is picked based on a value in an environment variable `NODE_ENV` (value set in `NODE_ENV` must match the name of the config file). This environment variable is set automatically while running the backend via prepared `yarn` scripts.\n\nIf you are using an authenticated db connection that requires a password, you'd need to provide a `PGPASSWORD` environment variable and the postgres library will automatically pick it up.\n\n#### Schema\n\n```yaml\n\n  // Blockfrost backend settings\n  server:\n    # Server listen address, you need to set this to 0.0.0.0 if running within docker\n    listenAddress: 'localhost'\n    # Server port\n    port: 3000\n    # Whether to enable verbose logging, when disabled only ERRORs are printed to a console\n    debug: true\n    # Whether to expose /prometheus endpoint\n    prometheusMetrics: false\n  # Cardano DB Sync SQL connection\n  dbSync:\n    host: 'cdbsync-dev.mydomain.com'\n    user: 'username'\n    database: 'dbname'\n    # Optionally define a password\n    password: 'randomstringthatissolongandpowerfulthatnoonecanguess'\n  # Cardano network - mainnet, testnet, preview, preprod, custom\n  network: 'mainnet'\n  # path to the folder containing genesis data. If left blank, ./genesis/${network} will be used\n  genesisDataFolder: './genesis/mainnet'\n  # Path to token registry directory (see next section for more details)\n  tokenRegistryUrl: 'https://tokens.cardano.org'\n  # Experimental Mithril proxy\n  mithril:\n    enabled: true # ENV var BLOCKFROST_MITHRIL_ENABLED=true\n    aggregator: \"https://aggregator.pre-release-preview.api.mithril.network/aggregator\" # ENV var BLOCKFROST_MITHRIL_AGGREGATOR\n    snapshotMirrors:\n    - originalUrl: \"https://storage.googleapis.com/cdn.aggregator.pre-release-preview.api.mithril.network\"\n      mirrorUrl: \"https://dummy-mithril-snapshot-cdn.com\"\n```\n\n\u003cdetails\u003e\n\u003csummary\u003e:bulb: All config variables can be also set via environment variables which take precedence over values from a config file.\u003c/summary\u003e\n\nThese values are `BLOCKFROST_CONFIG_SERVER_PORT`, `BLOCKFROST_CONFIG_SERVER_DEBUG`, `BLOCKFROST_CONFIG_SERVER_PROMETHEUS_METRICS`, `BLOCKFROST_CONFIG_DBSYNC_HOST`, `BLOCKFROST_CONFIG_DBSYNC_USER`, `BLOCKFROST_CONFIG_DBSYNC_DATABASE`, `BLOCKFROST_CONFIG_DBSYNC_MAX_CONN`, `BLOCKFROST_CONFIG_NETWORK`, `BLOCKFROST_CONFIG_GENESIS_DATA_FOLDER`, `BLOCKFROST_CONFIG_TOKEN_REGISTRY_URL`.\n\n\u003c/details\u003e\n\n#### Token registry\n\nBlockfrost Backend uses token registry to provide off-chain metadata for native assets (eg. number of decimals). [The token registry](https://developers.cardano.org/docs/native-tokens/token-registry/cardano-token-registry/) operated by Cardano Foundation and hosted at \u003chttps://tokens.cardano.org\u003e is used by default. You can use self-hosted registry by setting `tokenRegistryUrl` in the config file.\n\n#### Indices\n\nAlthough it is possible to run RYO with vanilla db sync, Blockfrost usually queries hex values in the already encoded form.\n\nTherefore, in order to speed up queries, it is recommended to create the following, custom, indices:\n\n```\nCREATE INDEX IF NOT EXISTS bf_idx_block_hash_encoded ON block USING HASH (encode(hash, 'hex'));\nCREATE INDEX IF NOT EXISTS bf_idx_datum_hash ON datum USING HASH (encode(hash, 'hex'));\nCREATE INDEX IF NOT EXISTS bf_idx_multi_asset_policy ON multi_asset USING HASH (encode(policy, 'hex'));\nCREATE INDEX IF NOT EXISTS bf_idx_multi_asset_policy_name ON multi_asset USING HASH ((encode(policy, 'hex') || encode(name, 'hex')));\nCREATE INDEX IF NOT EXISTS bf_idx_pool_hash_view ON pool_hash USING HASH (view);\nCREATE INDEX IF NOT EXISTS bf_idx_redeemer_data_hash ON redeemer_data USING HASH (encode(hash, 'hex'));\nCREATE INDEX IF NOT EXISTS bf_idx_scripts_hash ON script USING HASH (encode(hash, 'hex'));\nCREATE INDEX IF NOT EXISTS bf_idx_tx_hash ON tx USING HASH (encode(hash, 'hex'));\nCREATE UNIQUE INDEX IF NOT EXISTS bf_u_idx_epoch_stake_epoch_and_id ON epoch_stake (epoch_no, id);\nCREATE INDEX IF NOT EXISTS bf_idx_reference_tx_in_tx_in_id ON reference_tx_in (tx_in_id);\nCREATE INDEX IF NOT EXISTS bf_idx_collateral_tx_in_tx_in_id ON collateral_tx_in (tx_in_id);\nCREATE INDEX IF NOT EXISTS bf_idx_redeemer_script_hash ON redeemer USING HASH (encode(script_hash, 'hex'));\nCREATE INDEX IF NOT EXISTS bf_idx_redeemer_tx_id ON redeemer USING btree (tx_id);\nCREATE INDEX IF NOT EXISTS bf_idx_col_tx_out ON collateral_tx_out USING btree (tx_id);\nCREATE INDEX IF NOT EXISTS bf_idx_ma_tx_mint_ident ON ma_tx_mint USING btree (ident);\nCREATE INDEX IF NOT EXISTS bf_idx_ma_tx_out_ident ON ma_tx_out USING btree (ident);\nCREATE INDEX IF NOT EXISTS bf_idx_reward_rest_addr_id ON reward_rest USING btree (addr_id);\nCREATE INDEX IF NOT EXISTS bf_idx_reward_rest_spendable_epoch ON reward_rest USING btree (spendable_epoch);\nCREATE INDEX IF NOT EXISTS bf_idx_drep_hash_raw ON drep_hash USING hash (raw);\nCREATE INDEX IF NOT EXISTS bf_idx_drep_hash_view ON drep_hash USING hash (view);\nCREATE INDEX IF NOT EXISTS bf_idx_drep_hash_has_script ON drep_hash USING hash (has_script);\nCREATE INDEX IF NOT EXISTS bf_idx_delegation_vote_addr_id ON delegation_vote USING hash (addr_id);\n\n```\n\n### Experimental features\n\n### Mithril\n\nBlockfrost Backend optionally provides a proxy for the Mithril aggregator API. This feature allows users to interact with Mithril's endpoints through Blockfrost, with additional enhancements and customizations specific to Blockfrost.\n\n\u003e This is an experimental feature. Mithril is currently a work in progress and its API may change.\n\nAll Mithril-related endpoints are available under the `/mithril` path.\nFor list of available endpoints please visit https://mithril.network/doc/aggregator-api/.\n\nTo enable this experimental feature add following lines to your config:\n\n```yaml\nmithril:\n  enabled: true # ENV var BLOCKFROST_MITHRIL_ENABLED=true\n  aggregator: 'https://aggregator.pre-release-preview.api.mithril.network/aggregator' # ENV var BLOCKFROST_MITHRIL_AGGREGATOR\n  snapshotMirrors: # Optional\n    - originalUrl: \"https://storage.googleapis.com/cdn.aggregator.pre-release-preview.api.mithril.network\"\n    mirrorUrl: \"https://dummy-mithril-snapshot-cdn.com\"\n\nThen you can simply query Mithril API using Blockfrost Backend:\n\n```\n\ncurl localhost:3000/mithril/artifact/snapshots\n\n````\n\nIf you set `mithril.snapshotCDN` option, then the response of `/artifact/snapshots` and `/artifact/snapshot/{digest}` endpoints is enhanced with additional link to the list of snapshot locations.\n\n### Docker\n\nWe are hosting latest release of this software on Dockerhub. To run it using Docker:\n\n```console\ndocker run --rm \\\n  --name blockfrost-ryo \\\n  -p 3000:3000 \\\n  -e BLOCKFROST_CONFIG_SERVER_LISTEN_ADDRESS=0.0.0.0 \\\n  -v $PWD/config:/app/config \\\n  blockfrost/backend-ryo:latest\n````\n\nYou can also generate a Docker image using Nix instead of the `Dockerfile` running\n\n```console\nnix build .#dockerImage\n```\n\n### Nix\n\nTo start the Blockfrost backend under nix, just run:\n\n```console\n$(nix-build -A blockfrost-backend-ryo --no-out-link)/bin/blockfrost-backend-ryo\n```\n\nOr, since this repository is also a Nix flake, you can also run\n\n```console\nnix run # inside this repo folder\n# Otherwise, without manually cloning the repo before:\n# nix run github:blockfrost/blockfrost-backend-ryo\n```\n\n#### NixOS module\n\nIt's also possible enabling the Blockfrost backend on NixOS using the module provided by the flake.\nA minimal usage example is:\n\n```nix\n{config, ...}: {\n  imports = [\n    # official IOG cardano node NixOS  module\n    # official IOG cardano-db-sync NixOS module\n    # module provided by this flake\n  ];\n  services = {\n    cardano-node = {\n      enable = true;\n      # rest of you config...\n    };\n    cardano-db-sync = {\n      enable = true;\n      socketPath = config.services.cardano-node.socketPath;\n      # rest of your config...\n    };\n    postgresql = {\n      enable = true;\n      ensureDatabases = [ config.services.cardano-db-sync.postgres.database ];\n      ensureUsers = [{\n        name = config.services.cardano-db-sync.postgres.user;\n        ensurePermissions = {\n          \"DATABASE ${config.services.cardano-db-sync.postgres.database}\" = \"ALL PRIVILEGES\";\n        };\n      }];\n       identMap = ''\n        users root ${config.services.cardano-db-sync.postgres.user}\n        users cardano-db-sync ${config.services.cardano-db-sync.postgres.user}\n        users ${config.services.blockfrost.user} ${config.services.cardano-db-sync.postgres.user}\n        users postgres postgres\n      '';\n      authentication = ''\n        local all all ident map=users\n      '';\n    };\n    blockfrost = {\n      enable = true;\n      settings.dbSync = {\n        user = config.services.cardano-db-sync.postgres.user;\n        port = config.services.cardano-db-sync.postgres.port;\n        database = config.services.cardano-db-sync.postgres.database;\n        host = config.services.cardano-db-sync.postgres.socketdir;\n      };\n    };\n  };\n}\n```\n\nCheck the [nixos-module.nix file](./nixos-module.nix) to check options and the default values.\n\n## Custom Networks\n\nblockfrost-ryo can be configured to run with any genesis parameters. Setting network to `custom`, and using `genesisDataFolder` value in the yaml configuration or environment variable `BLOCKFROST_CONFIG_GENESIS_DATA_FOLDER` you can specify your genesis details.\n\n## Developing\n\nThis is an open-source project and anyone is welcome to contribute, please see [CONTRIBUTING](CONTRIBUTING.md) for more information.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fblockfrost%2Fblockfrost-backend-ryo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fblockfrost%2Fblockfrost-backend-ryo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fblockfrost%2Fblockfrost-backend-ryo/lists"}