{"id":13616966,"url":"https://github.com/CardanoSolutions/kupo","last_synced_at":"2025-04-14T03:32:09.001Z","repository":{"id":37933437,"uuid":"448956605","full_name":"CardanoSolutions/kupo","owner":"CardanoSolutions","description":"🐹 Fast, lightweight \u0026 configurable chain-index for Cardano.","archived":false,"fork":false,"pushed_at":"2025-02-15T16:21:10.000Z","size":11218,"stargazers_count":129,"open_issues_count":3,"forks_count":30,"subscribers_count":10,"default_branch":"master","last_synced_at":"2025-04-03T21:12:25.383Z","etag":null,"topics":["blockchain","cardano","chain-index","database-as-a-service","http"],"latest_commit_sha":null,"homepage":"https://cardanosolutions.github.io/kupo/","language":"Haskell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/CardanoSolutions.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","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},"funding":{"github":"KtorZ"}},"created_at":"2022-01-17T15:53:45.000Z","updated_at":"2025-03-25T13:17:15.000Z","dependencies_parsed_at":"2023-10-14T16:20:55.971Z","dependency_job_id":"c83585e1-4ba6-401c-9367-4fdaf92d29cd","html_url":"https://github.com/CardanoSolutions/kupo","commit_stats":{"total_commits":405,"total_committers":6,"mean_commits":67.5,"dds":0.03950617283950619,"last_synced_commit":"1ee9006d1513037cf0b662feaecbc444d6584bce"},"previous_names":[],"tags_count":31,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CardanoSolutions%2Fkupo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CardanoSolutions%2Fkupo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CardanoSolutions%2Fkupo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CardanoSolutions%2Fkupo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/CardanoSolutions","download_url":"https://codeload.github.com/CardanoSolutions/kupo/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248617428,"owners_count":21134190,"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":["blockchain","cardano","chain-index","database-as-a-service","http"],"created_at":"2024-08-01T20:01:35.386Z","updated_at":"2025-04-14T03:32:08.995Z","avatar_url":"https://github.com/CardanoSolutions.png","language":"Haskell","funding_links":["https://github.com/sponsors/KtorZ"],"categories":["Haskell"],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"./docs/kupo.png\" width=\"240\" /\u003e \u003cimg src=\".github/preview.gif\" width=\"480\" /\u003e\n\u003c/p\u003e\n\n\u003cp\u003e\n  \u003cimg align=\"left\" src=\".github/installation.png\" width=\"300\" alt=\"installation instructions\" /\u003e\n\n  \u003ca href=\"https://cardanosolutions.github.io/kupo\"\u003e📖 User Manual\u003c/a\u003e\n  |\n  \u003ca href=\"CONTRIBUTING.md\"\u003e🤝 Contributing\u003c/a\u003e\n  |\n  \u003ca href=\"CHANGELOG.md\"\u003e 💾 Changelog\u003c/a\u003e\n  |\n  \u003ca href=\"https://twitter.com/_KtorZ_\"\u003e\u003cimg src=\".github/twitter.svg\" alt=\"Twitter\"\u003e Twitter (@_KtorZ_)\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n**Kupo** is fast, lightweight and configurable **chain-index** for the Cardano blockchain. It synchronizes data from the blockchain according to **patterns** matching addresses present in transaction outputs and builds a **lookup table** from matches to their associated **output references**, **values**, **datums** and **scripts**.\n\n\n# Roadmap\n\n### Cutting-edge work\n\nThe project keeps a [changelog 💾](./CHANGELOG.md) in which all _recent-but-not-yet-released_ changes can be seen. Changes in the changelog have been implemented and are available in latest builds from the `master` branch.\n\n\u003e [!WARNING]\n\u003e Work available on the `master` branch shall be considered _unstable_ in the sense that interfaces may slightly change and database migrations may not work from a previous `master` commit. Keeping stability between unreleased commits is only a best-effort.\n\n### Planned work\n\nThe [issues list 🎯][roadmap] references planned tasks that haven't been implemented but have reached enough maturity to be well-defined and scoped.\n\n### Future work\n\nFinally, [discussions 💡][discussions] contains ongoing discussions regarding the future of Kupo, with design decisions still under consideration.\n\n# Compatibility\n\nKupo      | Cardano-node                | Ogmios   | Hydra\n---       | ---                         | ---      | ---\n`v2.10.*` | `10.1.*`, `10.0.*`, `9.0.0` | `v6.*.*` | `0.16.0`\n`v2.9.*`  | `10.1.*`, `10.0.*`, `9.0.0` | `v6.*.*` | `0.16.0`\n`v2.8.*`  | `8.7.*`                     | `v6.*.*` | `0.13.0`\n`v2.7.*`  | `8.1.*`, `8.6.*`            | `v6.*.*` | `0.13.0`\n`v2.6.*`  | `8.1.*`                     | `v6.*.*` | N/A\n`v2.5.*`  | `1.35.*`, `8.1.*`           | `v5.*.*` | N/A\n\n# System Requirements\n\n| Category         | Value            |\n| ---              | ---              |\n| Operating System | Linux / MacOS    |\n| Architecture     | arm64 / amd64    |\n| RAM              | 256MB-2048MB[^1] |\n| CPU              | 2+ cores         |\n| Disk Storage     | 1MB-220GB[^2]    |\n\n# Continuous Integration\n\n| Status | Description |\n| --- | --- |\n| \u003ca href=\"https://hub.docker.com/r/cardanosolutions/kupo\"\u003e\u003cimg src=\"https://img.shields.io/docker/pulls/cardanosolutions/kupo?style=for-the-badge\u0026label=\u0026logo=Docker\u0026logoColor=000000\u0026color=f9dd24\" /\u003e\u003c/a\u003e | Docker image pulls |\n| \u003ca href=\"https://github.com/CardanoSolutions/kupo/actions/workflows/build.yaml\"\u003e\u003cimg src=\"https://img.shields.io/github/actions/workflow/status/cardanosolutions/kupo/build.yaml?style=for-the-badge\u0026label=\u0026logo=NixOS\u0026logoColor=000000\u0026color=f9dd24\" /\u003e\u003c/a\u003e | Nix build, providing static binary executables as artifacts. |\n| \u003ca href=\"https://github.com/CardanoSolutions/kupo/actions/workflows/pages/pages-build-deployment\"\u003e\u003cimg src=\"https://img.shields.io/github/deployments/cardanosolutions/kupo/github-pages?style=for-the-badge\u0026label=\u0026logo=readthedocs\u0026logoColor=000000\u0026color=f9dd24\"\u003e\u003c/a\u003e | [User manual][] and API reference deployment. |\n| \u003cimg src=\"https://img.shields.io/static/v1?style=for-the-badge\u0026label=\u0026message=82%\u0026logo=codecov\u0026logoColor=000000\u0026color=f9dd24\"\u003e | Test code coverage. Learn more about the [testing strategy][]. |\n\n# Alternatives\n\nKupo is well-suited for small (or large) applications which need either:\n\n- a global chain index for resolving outputs by address, policy id or output reference;\n- a on-the-fly monitoring of an address, policy id or specific transaction output over a short period of time.\n\nIt runs in constant memory and is blazing fast. Yet, its use-cases are limited. Here below we provide some possible alternatives with different trade-offs:\n\n| **Solution** | **Ecosystem** | **Key difference(s)** |\n| ---          | ---           | ---                   |\n| \u003ca href=\"https://github.com/txpipe/oura/#readme\"\u003e\u003cimg width=150 src=\"https://github.com/txpipe/oura/raw/main/assets/logo.svg\" alt=\"oura\"\u003e\u003c/a\u003e | Rust | Oura in itself does not provide any chain-indexing, but it supports pluggable sinks where filtered data from the Cardano blockchain can be dumped into (e.g. Elastic Search or Kafka). It also supports a wider variety of events. All-in-all, a good fit for more elaborate solutions. |\n| \u003ca href=\"https://github.com/blinklabs-io/adder\"\u003e\u003cimg width=150 src=\"https://github.com/blinklabs-io/adder/raw/main/.github/assets/adder-logo-with-text-horizontal.png\" alt=\"adder\" /\u003e\u003c/a\u003e | Go | Similar to Oura, Adder is is an event-emitter coupled with filters. Therefore, it requires a backend storage or an additional solution for handling and serving events coming from the chain. Like Kupo, it supports a variety of filters on addresses or assets albeit in a more direct way. |\n| \u003ca href=\"https://github.com/bloxbean/yaci-store\"\u003e\u003cimg width=150 src=\"https://github.com/bloxbean/yaci-store/raw/main/static/YaciStore.png\" alt=\"\"\u003e\u003c/a\u003e | Java | Yaci Store is a small component built on top of the Yaci libraries -- a collection of Java libraries for interacting with the Cardano networking protocols. It can be used as a library to deal with an event stream similar to Oura and Adder, or as a full blackbox solution storing into various storage solutions (SQLite, Redis, MongoDB, ...). |\n| \u003ca href=\"https://github.com/txpipe/scrolls\"\u003e\u003cimg width=150 src=\"https://github.com/txpipe/scrolls/raw/main/assets/logo-dark.png?sanitize=true#gh-dark-mode-only\" alt=\"scrolls\"\u003e\u003c/a\u003e | Rust | Scrolls provides (at this stage) an in-memory aggregation engine via Redis. It allows applications to watch and react instantly on the evolution of some aggregated metric (see Scrolls' README for details about what metrics are supported). Because the data is fully stored in-memory, it is not possible to index the entire chain without resorting to large memory requirements. Hence it is more tailored to specific handpicked pieces of information. It also synchronizes blocks from the chain using the node-to-node protocol which means that it can do so on any remote node relay, but it is also slower (because a more defensive protocol) than the node-to-client protocol upon which Kupo relies. |\n| \u003ca href=\"https://dcspark.github.io/carp/docs/intro/\"\u003e\u003cimg width=150 src=\"https://dcspark.github.io/carp/img/logo.svg\" alt=\"carp\"/\u003e\u003c/a\u003e | Rust | Carp is a modular blockchain indexer built on top of Oura; it synchronizes data in a PostgreSQL database based on behaviors described in _tasks_ (Rust standalone plugins). Some pre-defined common tasks are already available, other can be written on-demand to fit one's use case. As a primary interface, Carps fully relies on PostgreSQL. |\n| \u003ca href=\"https://github.com/input-output-hk/cardano-db-sync#cardano-db-sync\"\u003ecardano-db-sync\u003c/a\u003e | Haskell | cardano-db-sync synchronizes ALL data from the Cardano blockchain, whereas Kupo focuses only on transaction outputs. This comes with obvious trade-offs in both on-disk storage, runtime requirements and performances. Kupo is usually an order of magnitude faster for retrieving outputs by address, stake address or policy id. Note also that like Carp, cardano-db-sync's primary interface is a PostgreSQL database whereas Kupo offers a higher-level HTTP API over JSON.\n\n## Sponsors\n\nA big thank to [all our sponsors 💖](https://github.com/CardanoSolutions#-sponsors).\n\n[testing strategy]: https://github.com/CardanoSolutions/kupo/tree/master/test#testing-strategy\n[user manual]: https://cardanosolutions.github.io/kupo\n[discussions]: https://github.com/CardanoSolutions/kupo/discussions/categories/ideas?discussions_q=category%3AIdeas+sort%3Atop\n[roadmap]: https://github.com/CardanoSolutions/kupo/issues?q=is%3Aopen+is%3Aissue+label%3Aenhancement\n\n[^1]: The maximum memory usage depends on runtime flags and internal settings. This can be made lower if necessary (possibly as small as a hundred megabytes) by tweaking those settings. The obvious counter-part being slower synchronization times when syncing over large chunks of data. When synchronized, however, this has close to no impact.\n\n[^2]: The size of the database depends on the patterns the indexer is configured with. Storing every single entry of Mainnet currently come close to ~220GB. However, if pruned (i.e. only keep unspent entries), Mainnet is around 12GB.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FCardanoSolutions%2Fkupo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FCardanoSolutions%2Fkupo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FCardanoSolutions%2Fkupo/lists"}