{"id":50770972,"url":"https://github.com/bsv-blockchain/merkle-service","last_synced_at":"2026-06-11T18:30:41.952Z","repository":{"id":354781287,"uuid":"1222787954","full_name":"bsv-blockchain/merkle-service","owner":"bsv-blockchain","description":"High-throughput BSV Blockchain merkle proof delivery service for subscribers, interoperable with Teranode and Arcade.","archived":false,"fork":false,"pushed_at":"2026-06-11T15:05:05.000Z","size":118369,"stargazers_count":1,"open_issues_count":52,"forks_count":2,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-11T17:06:59.538Z","etag":null,"topics":["arcade","bitcoin","bitcoinsv","bsv","golang","merkle-proof","merkle-tree","teranode"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bsv-blockchain.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":".github/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":".github/SECURITY.md","support":".github/SUPPORT.md","governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":".github/AGENTS.md","dco":null,"cla":null}},"created_at":"2026-04-27T17:53:56.000Z","updated_at":"2026-06-11T15:07:43.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/bsv-blockchain/merkle-service","commit_stats":null,"previous_names":["bsv-blockchain/merkle-service"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/bsv-blockchain/merkle-service","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bsv-blockchain%2Fmerkle-service","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bsv-blockchain%2Fmerkle-service/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bsv-blockchain%2Fmerkle-service/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bsv-blockchain%2Fmerkle-service/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bsv-blockchain","download_url":"https://codeload.github.com/bsv-blockchain/merkle-service/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bsv-blockchain%2Fmerkle-service/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34213179,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-11T02:00:06.485Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["arcade","bitcoin","bitcoinsv","bsv","golang","merkle-proof","merkle-tree","teranode"],"created_at":"2026-06-11T18:30:41.043Z","updated_at":"2026-06-11T18:30:41.943Z","avatar_url":"https://github.com/bsv-blockchain.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# 🌳\u0026nbsp;\u0026nbsp;merkle-service\n\n**High-throughput delivery of [BSV Blockchain](https://bsvblockchain.org) merkle proofs to subscribers as transactions propagate the network and land in mined blocks.**\n\n\u003cbr/\u003e\n\n\u003ca href=\"https://github.com/bsv-blockchain/merkle-service/releases\"\u003e\u003cimg src=\"https://img.shields.io/github/release-pre/bsv-blockchain/merkle-service?include_prereleases\u0026style=flat-square\u0026logo=github\u0026color=black\" alt=\"Release\"\u003e\u003c/a\u003e\n\u003ca href=\"https://golang.org/\"\u003e\u003cimg src=\"https://img.shields.io/github/go-mod/go-version/bsv-blockchain/merkle-service?style=flat-square\u0026logo=go\u0026color=00ADD8\" alt=\"Go Version\"\u003e\u003c/a\u003e\n\u003ca href=\"https://github.com/bsv-blockchain/merkle-service/blob/main/LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/badge/license-OpenBSV-blue?style=flat-square\" alt=\"License\"\u003e\u003c/a\u003e\n\n\u003cbr/\u003e\n\n\u003ctable align=\"center\" border=\"0\"\u003e\n  \u003ctr\u003e\n    \u003ctd align=\"right\"\u003e\n       \u003ccode\u003eCI / CD\u003c/code\u003e \u0026nbsp;\u0026nbsp;\n    \u003c/td\u003e\n    \u003ctd align=\"left\"\u003e\n       \u003ca href=\"https://github.com/bsv-blockchain/merkle-service/actions\"\u003e\u003cimg src=\"https://img.shields.io/github/actions/workflow/status/bsv-blockchain/merkle-service/fortress.yml?branch=main\u0026label=build\u0026logo=github\u0026style=flat-square\" alt=\"Build\"\u003e\u003c/a\u003e\n       \u003ca href=\"https://github.com/bsv-blockchain/merkle-service/actions\"\u003e\u003cimg src=\"https://img.shields.io/github/last-commit/bsv-blockchain/merkle-service?style=flat-square\u0026logo=git\u0026logoColor=white\u0026label=last%20update\" alt=\"Last Commit\"\u003e\u003c/a\u003e\n    \u003c/td\u003e\n    \u003ctd align=\"right\"\u003e\n       \u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp; \u003ccode\u003eQuality\u003c/code\u003e \u0026nbsp;\u0026nbsp;\n    \u003c/td\u003e\n    \u003ctd align=\"left\"\u003e\n       \u003ca href=\"https://goreportcard.com/report/github.com/bsv-blockchain/merkle-service\"\u003e\u003cimg src=\"https://goreportcard.com/badge/github.com/bsv-blockchain/merkle-service?style=flat-square\" alt=\"Go Report\"\u003e\u003c/a\u003e\n       \u003ca href=\"https://codecov.io/gh/bsv-blockchain/merkle-service\"\u003e\u003cimg src=\"https://codecov.io/gh/bsv-blockchain/merkle-service/branch/main/graph/badge.svg?style=flat-square\" alt=\"Coverage\"\u003e\u003c/a\u003e\n    \u003c/td\u003e\n  \u003c/tr\u003e\n\n  \u003ctr\u003e\n    \u003ctd align=\"right\"\u003e\n       \u003ccode\u003eSecurity\u003c/code\u003e \u0026nbsp;\u0026nbsp;\n    \u003c/td\u003e\n    \u003ctd align=\"left\"\u003e\n       \u003ca href=\"https://scorecard.dev/viewer/?uri=github.com/bsv-blockchain/merkle-service\"\u003e\u003cimg src=\"https://api.scorecard.dev/projects/github.com/bsv-blockchain/merkle-service/badge?style=flat-square\" alt=\"Scorecard\"\u003e\u003c/a\u003e\n       \u003ca href=\".github/SECURITY.md\"\u003e\u003cimg src=\"https://img.shields.io/badge/policy-active-success?style=flat-square\u0026logo=security\u0026logoColor=white\" alt=\"Security\"\u003e\u003c/a\u003e\n    \u003c/td\u003e\n    \u003ctd align=\"right\"\u003e\n       \u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp; \u003ccode\u003eCommunity\u003c/code\u003e \u0026nbsp;\u0026nbsp;\n    \u003c/td\u003e\n    \u003ctd align=\"left\"\u003e\n       \u003ca href=\"https://github.com/bsv-blockchain/merkle-service/graphs/contributors\"\u003e\u003cimg src=\"https://img.shields.io/github/contributors/bsv-blockchain/merkle-service?style=flat-square\u0026color=orange\" alt=\"Contributors\"\u003e\u003c/a\u003e\n       \u003ca href=\"https://deepwiki.com/bsv-blockchain/merkle-service\"\u003e\u003cimg src=\"https://deepwiki.com/badge.svg\" alt=\"Ask DeepWiki\"\u003e\u003c/a\u003e\n    \u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\n\u003c/div\u003e\n\n\u003cbr/\u003e\n\u003cbr/\u003e\n\n\u003cdiv align=\"center\"\u003e\n\n### \u003ccode\u003eProject Navigation\u003c/code\u003e\n\n\u003c/div\u003e\n\n\u003ctable align=\"center\"\u003e\n  \u003ctr\u003e\n    \u003ctd align=\"center\" width=\"33%\"\u003e\n       📦\u0026nbsp;\u003ca href=\"#-installation\"\u003e\u003ccode\u003eInstallation\u003c/code\u003e\u003c/a\u003e\n    \u003c/td\u003e\n    \u003ctd align=\"center\" width=\"33%\"\u003e\n       ✨\u0026nbsp;\u003ca href=\"#-features\"\u003e\u003ccode\u003eFeatures\u003c/code\u003e\u003c/a\u003e\n    \u003c/td\u003e\n    \u003ctd align=\"center\" width=\"33%\"\u003e\n       📚\u0026nbsp;\u003ca href=\"#-documentation\"\u003e\u003ccode\u003eDocumentation\u003c/code\u003e\u003c/a\u003e\n    \u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd align=\"center\"\u003e\n       🧪\u0026nbsp;\u003ca href=\"#-examples--tests\"\u003e\u003ccode\u003eExamples\u0026nbsp;\u0026\u0026nbsp;Tests\u003c/code\u003e\u003c/a\u003e\n    \u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\n       ⚡\u0026nbsp;\u003ca href=\"#-benchmarks\"\u003e\u003ccode\u003eBenchmarks\u003c/code\u003e\u003c/a\u003e\n    \u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\n       🛠️\u0026nbsp;\u003ca href=\"#-code-standards\"\u003e\u003ccode\u003eCode\u0026nbsp;Standards\u003c/code\u003e\u003c/a\u003e\n    \u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd align=\"center\"\u003e\n       🤖\u0026nbsp;\u003ca href=\"#-ai-usage--assistant-guidelines\"\u003e\u003ccode\u003eAI\u0026nbsp;Usage\u003c/code\u003e\u003c/a\u003e\n    \u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\n       🤝\u0026nbsp;\u003ca href=\"#-contributing\"\u003e\u003ccode\u003eContributing\u003c/code\u003e\u003c/a\u003e\n    \u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\n       👥\u0026nbsp;\u003ca href=\"#-maintainers\"\u003e\u003ccode\u003eMaintainers\u003c/code\u003e\u003c/a\u003e\n    \u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd align=\"center\" colspan=\"3\"\u003e\n       📝\u0026nbsp;\u003ca href=\"#-license\"\u003e\u003ccode\u003eLicense\u003c/code\u003e\u003c/a\u003e\n    \u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\u003cbr/\u003e\n\n## 🌐 Overview\n\nClients register a `(txid, callbackUrl)` pair. The service watches the BSV network over P2P, and as a transaction is observed in subtrees and then in a block, it `POST`s status updates and a **STUMP** (Subtree Unified Merkle Path) back to the callback URL.\n\nBuilt to interoperate with [Teranode](https://github.com/bsv-blockchain/teranode) and [Arcade](https://github.com/bsv-blockchain/arcade), the service scales horizontally to handle blocks containing millions of transactions — validated to ~92k txids/sec with two delivery instances.\n\n### Terminology\n\n- **BUMP** — [Bitcoin Unified Merkle Path](https://github.com/bitcoin-sv/BRCs/blob/master/transactions/0074.md) for a transaction within a full block.\n- **STUMP** — Subtree Unified Merkle Path. Same wire format as BUMP, but scoped to a single subtree. The service emits one STUMP per subtree (not per transaction), letting downstream consumers reconstruct the BUMP.\n\n\u003cbr/\u003e\n\n## ✨ Features\n\n- **Real-Time Merkle Proof Delivery**\n  Streams `SEEN_ON_NETWORK`, `MINED`, and `IMMUTABLE` callbacks to subscribers as transactions move through the BSV lifecycle.\n\n- **STUMP-Based Compound Proofs**\n  Emits one STUMP per subtree rather than per transaction, allowing downstream consumers to reconstruct full BUMPs efficiently.\n\n- **Horizontally Scalable Pipeline**\n  Stages connected by Kafka topics, each independently scalable to subtree- and partition-count limits — validated past 92k txids/sec.\n\n- **Pluggable Storage Backends**\n  Aerospike for production workloads, PostgreSQL/SQLite for environments without Aerospike or for testing.\n\n- **Teranode-Compatible P2P Client**\n  Connects to the BSV P2P network via libp2p with the same wire format as Teranode for subtree and block announcements.\n\n- **All-In-One or Microservice Topology**\n  Run every stage in a single binary for development and small deployments, or deploy each stage independently on Kubernetes.\n\n\u003cbr\u003e\n\n### Built-in Components\n\n- **Bulk Registration CLI** — `cmd/watch` registers thousands of txids from a flat file in a single shot.\n- **Debug Dashboard** — `tools/debug-dashboard` exposes a local web UI for inspecting in-flight pipeline state.\n- **Idempotent Callback Delivery** — Hash-partitioned by callback URL with retry-on-failure and dead-letter queue for poison messages.\n- **Negative-Lookup Cache Hardening** — Registration cache rejects negative entries to prevent stale-miss propagation.\n- **SSRF Protection** — DataHub client rejects URLs targeting private address space and blocks private dials.\n- **Blob Path Hardening** — File blob store rejects keys that escape the configured root directory.\n- **Health \u0026 Readiness Endpoints** — `GET /health` exposes liveness/readiness suitable for orchestration tools.\n- **Schema-Migrated SQL Backend** — PostgreSQL/SQLite migrations embedded in the binary; TTL emulated by a sweeper goroutine.\n\n\u003cbr\u003e\n\n## 📦 Installation\n\n**merkle-service** requires a [supported release of Go](https://golang.org/doc/devel/release.html#policy) (the version pinned in [go.mod](go.mod); currently **1.26**).\n\n\u003cbr\u003e\n\n### Prerequisites\n\n- Go (version pinned in [go.mod](go.mod))\n- Docker / Podman + Compose (for local Aerospike, Zookeeper, and Kafka)\n\n\u003cbr\u003e\n\n### Run Locally (All-in-One)\n\n1. **Clone the repository**\n   ```shell\n   git clone https://github.com/bsv-blockchain/merkle-service.git\n   cd merkle-service\n   ```\n\n2. **Start dependencies**\n   ```shell\n   make docker-up    # starts Aerospike, Zookeeper, Kafka\n   ```\n\n3. **Run the all-in-one binary**\n   ```shell\n   make run          # go run ./cmd/merkle-service\n   ```\n\nThe API listens on `:8080`. Stop dependencies with `make docker-down`.\n\n\u003cbr\u003e\n\n### Register a Transaction\n\n```shell\ncurl -X POST http://localhost:8080/watch \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n    \"txid\": \"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2\",\n    \"callbackUrl\": \"https://example.com/callback\"\n  }'\n```\n\nOr use the bundled CLI for bulk registration:\n\n```shell\ngo run ./cmd/watch \\\n  --url http://localhost:8080 \\\n  --callback https://example.com/callback \\\n  --file txids.txt\n```\n\nSee [docs/api.md](docs/api.md) for the full API reference.\n\n\u003cbr\u003e\n\n### Build Binaries\n\n```shell\nmake build    # builds every binary under cmd/\n```\n\nThe Dockerfile builds all binaries into a single Alpine runtime image. Choose which one runs by overriding the entrypoint, e.g. `--entrypoint api-server`.\n\n\u003cbr\u003e\n\n## 📚 Documentation\n\n### Architecture\n\nThe service is a set of stages connected by Kafka topics, designed to scale horizontally for blocks containing millions of transactions.\n\n```\n                BSV Network (libp2p)\n                       │\n                       ▼\n                  P2P Client ──► Kafka: subtree, block\n                       │\n       ┌───────────────┴────────────────┐\n       ▼                                ▼\n Subtree Fetcher                  Block Processor\n (fan-out by sub-                 (fan-out subtrees\n  scribing to subtree              of a mined block to\n  topic, fetches blob,             subtree-work topic)\n  emits SEEN callbacks)                  │\n       │                                 ▼\n       │                          Subtree Worker\n       │                          (builds STUMP,\n       │                           accumulates in\n       │                           Aerospike,\n       │                           flushes batched\n       │                           callbacks)\n       │                                 │\n       └─────────► Kafka: callback ◄─────┘\n                       │\n                       ▼\n              Callback Delivery\n              (HTTP POST → subscriber URL,\n               retries via DLQ)\n```\n\n\u003cbr\u003e\n\n### Pipeline Stages\n\n| Stage             | Binary                  | Replicas                       | Role                                                                                       |\n|-------------------|-------------------------|--------------------------------|--------------------------------------------------------------------------------------------|\n| API server        | `cmd/api-server`        | unlimited                      | Accepts `POST /watch` registrations and serves `GET /health`.                              |\n| P2P client        | `cmd/p2p-client`        | 1 (singleton)                  | Connects to the BSV P2P network; publishes subtree/block announcements to Kafka.           |\n| Subtree fetcher   | `cmd/subtree-fetcher`   | up to `subtree` partitions     | Resolves subtree blobs, persists them, emits `SEEN_ON_NETWORK` callbacks.                  |\n| Block processor   | `cmd/block-processor`   | 1 (active)                     | Fans out a mined block's subtrees to `subtree-work` for parallel processing.               |\n| Subtree worker    | `cmd/subtree-worker`    | up to `subtree-work` partitions | Builds STUMPs, accumulates per-callback batches in Aerospike, emits batched callbacks.    |\n| Callback delivery | `cmd/callback-delivery` | up to `callback` partitions    | Hash-partitions HTTP delivery by callback URL; retries failures and DLQs the dead.         |\n| All-in-one        | `cmd/merkle-service`    | 1                              | Runs every stage in a single process for development and small deployments.                |\n\nThere is also `cmd/watch`, a small CLI for bulk-registering txids, and `tools/debug-dashboard`, a local web UI for inspecting in-flight state.\n\n\u003cbr\u003e\n\n### Supported API Endpoints\n\n| HTTP Method | Endpoint    | Description                                                                            | Protection |\n|-------------|-------------|----------------------------------------------------------------------------------------|------------|\n| POST        | `/watch`    | Registers a `(txid, callbackUrl)` pair to receive lifecycle callbacks                  | Public     |\n| GET         | `/health`   | Liveness/readiness probe suitable for Kubernetes and other orchestrators               | Public     |\n\nSee [docs/api.md](docs/api.md) for full request/response schemas and callback payload formats.\n\n\u003cbr\u003e\n\n### Configuration\n\nConfiguration is loaded from (highest priority first):\n\n1. Environment variables\n2. YAML file ([config.yaml](config.yaml) by default; override with `CONFIG_FILE=/path/to/config.yaml`)\n3. Built-in defaults\n\n[config.yaml](config.yaml) lists every setting with its default value and corresponding env var. Key knobs:\n\n| Field                       | Description                                                              | Notes                                                  |\n|-----------------------------|--------------------------------------------------------------------------|--------------------------------------------------------|\n| `mode`                      | Topology selector                                                        | `all-in-one` or `microservice`                         |\n| `store.backend`             | Storage backend                                                          | `aerospike` (default, recommended) or `sql`            |\n| `kafka.brokers`             | Kafka bootstrap brokers                                                  | Comma-separated host:port list                         |\n| `aerospike.host`            | Aerospike connection target                                              | Required when `store.backend=aerospike`                |\n| `blobStore.url`             | Subtree blob backing store                                               | File or remote URL                                     |\n| `block.workerPoolSize`      | Worker concurrency for subtree fan-out                                   | Tune for block-processor throughput                    |\n| `callback.deliveryWorkers`  | HTTP delivery worker concurrency                                         | Tune per delivery instance                             |\n\nSee [docs/deployment.md](docs/deployment.md) for the full env-var reference and [docs/sql-backend.md](docs/sql-backend.md) for running against PostgreSQL or SQLite instead of Aerospike.\n\n\u003cbr\u003e\n\n### Storage Backends\n\n| Backend     | Use for                          | Notes                                                                                  |\n|-------------|----------------------------------|----------------------------------------------------------------------------------------|\n| Aerospike   | Production                       | Default. Native record TTL, batched ops, scales to teranode-grade workloads.           |\n| PostgreSQL  | Environments without Aerospike   | Schema migrations embedded in the binary; TTL emulated by a sweeper goroutine.         |\n| SQLite      | Tests, lightweight single-node   | Same SQL backend; not for multi-writer workloads.                                      |\n\nSwitch with `store.backend: sql` (and the `store.sql.*` block) in [config.yaml](config.yaml). The CI suite runs every store against a real PostgreSQL container — `make test-e2e-postgres`.\n\n\u003cbr\u003e\n\n### Deployment\n\n#### Docker Compose\n\n[docker-compose.yml](docker-compose.yml) brings up Aerospike, Zookeeper, and Kafka for local development. Aerospike data persists in the `aerospike-data` volume.\n\n#### Kubernetes\n\n[deploy/k8s/](deploy/k8s/) contains manifests for running the microservice topology on Kubernetes — one deployment per stage, plus a shared ConfigMap. See [deploy/k8s/README.md](deploy/k8s/README.md) for the deployment order, partition-count guidance, and horizontal-scaling notes.\n\n\u003cbr\u003e\n\n### Repository Layout\n\n```\ncmd/                  service binaries (one per stage + all-in-one + watch CLI)\ninternal/\n  api/                HTTP handlers for /watch and /health\n  block/              block processor (fans subtrees out to workers)\n  cache/              in-memory caches (txmetacache, dedup)\n  callback/           callback delivery, batching, DLQ handling\n  config/             YAML + env loading\n  datahub/            Teranode HTTP client (subtree/block fallback)\n  e2e/                cross-stage end-to-end tests\n  kafka/              producer/consumer wrappers\n  p2p/                Teranode-compatible libp2p client\n  service/            all-in-one orchestrator\n  store/              storage interfaces + aerospike \u0026 sql backends\n  stump/              STUMP construction and parsing\n  subtree/            subtree fetcher and worker logic\ndeploy/k8s/           Kubernetes manifests\ndocs/                 design / api / deployment / sql-backend docs\ntest/scale/           large-input scale-test fixtures and runners\ntools/debug-dashboard local web UI for inspecting state\n```\n\n\u003cbr\u003e\n\n### Documentation Index\n\n- [docs/design.md](docs/design.md) — Arcade integration design and transaction lifecycle (RECEIVED → SEEN → MINED → IMMUTABLE), including the per-subtree STUMP and compound-BUMP design rationale.\n- [docs/api.md](docs/api.md) — HTTP API reference.\n- [docs/deployment.md](docs/deployment.md) — full configuration and env-var reference.\n- [docs/sql-backend.md](docs/sql-backend.md) — running against PostgreSQL / SQLite.\n- [deploy/k8s/README.md](deploy/k8s/README.md) — Kubernetes topology and scaling.\n- [requirements.md](requirements.md) — original requirements and design intent.\n\n\u003cbr\u003e\n\n### Related Projects\n\n- [Teranode](https://github.com/bsv-blockchain/teranode) — high-throughput BSV node this service interoperates with.\n- [Arcade](https://github.com/bsv-blockchain/arcade) — transaction broadcast and lifecycle service that consumes merkle-service callbacks.\n\n\u003cbr/\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e\u003ccode\u003eRepository Features\u003c/code\u003e\u003c/strong\u003e\u003c/summary\u003e\n\u003cbr/\u003e\n\nThis repository includes 25+ built-in features covering CI/CD, security, code quality, developer experience, and community tooling.\n\n**[View the full Repository Features list →](.github/docs/repository-features.md)**\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e\u003ccode\u003eLibrary Deployment\u003c/code\u003e\u003c/strong\u003e\u003c/summary\u003e\n\u003cbr/\u003e\n\nThis project uses [goreleaser](https://github.com/goreleaser/goreleaser) for streamlined binary and library deployment to GitHub. To get started, install it via:\n\n```bash\nbrew install goreleaser\n```\n\nThe release process is defined in the [.goreleaser.yml](.goreleaser.yml) configuration file. Tags trigger the release workflow which produces signed binaries, container images, and citation metadata.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e\u003ccode\u003eGitHub Workflows\u003c/code\u003e\u003c/strong\u003e\u003c/summary\u003e\n\u003cbr/\u003e\n\nAll workflows are driven by modular configuration in [`.github/env/`](.github/env/) — no YAML editing required.\n\n**[View all workflows and the control center →](.github/docs/workflows.md)**\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e\u003ccode\u003eUpdating Dependencies\u003c/code\u003e\u003c/strong\u003e\u003c/summary\u003e\n\u003cbr/\u003e\n\nTo update Go module dependencies:\n\n```bash\ngo get -u ./...\ngo mod tidy\nor\nmagex deps:update\n```\n\nDependabot is configured via [.github/dependabot.yml](.github/dependabot.yml) to keep dependencies and GitHub Actions up to date automatically.\n\n\u003c/details\u003e\n\n\u003cbr/\u003e\n\n## 🧪 Examples \u0026 Tests\n\nAll unit tests run via [GitHub Actions](https://github.com/bsv-blockchain/merkle-service/actions) on the Go version pinned in [go.mod](go.mod).\n\nRun unit tests:\n\n```bash\nmake test\nor\nmagex test\n```\n\nRun the PostgreSQL-backed end-to-end suite (requires Docker):\n\n```bash\nmake test-e2e-postgres\n```\n\nRun the synthetic scale-test suites:\n\n```bash\nmake scale-test          # large-block scale tests\nmake mega-scale-test     # 100 instances × 10k txids × 250 subtrees × 4k tx/subtree\n```\n\n[`make lint-store-imports`](Makefile) enforces that nothing under `cmd/` imports a backend implementation directly — backends are pulled in only via blank imports for side-effect registration.\n\n\u003cbr/\u003e\n\n## ⚡ Benchmarks\n\nRun the Go benchmarks:\n\n```bash\ngo test -bench=. -benchmem ./...\nor\nmagex bench\n```\n\nThe microservice topology has been validated to ~92k txids/sec with two delivery instances against a real PostgreSQL backend. See [deploy/k8s/README.md](deploy/k8s/README.md) for scaling guidance.\n\n\u003cbr/\u003e\n\n## 🛠️ Code Standards\n\nRead more about this Go project's [code standards](.github/CODE_STANDARDS.md) and [linting configuration](.golangci.json). Run linters locally with:\n\n```bash\nmake lint\nor\nmagex lint\n```\n\n\u003cbr/\u003e\n\n## 🤖 AI Usage \u0026 Assistant Guidelines\n\nRead the [AGENTS.md](.github/AGENTS.md) for details on how AI assistants should interact with this codebase, including coding conventions, workflow expectations, and quality bars.\n\n\u003cbr/\u003e\n\n## 👥 Maintainers\n\n| [\u003cimg src=\"https://github.com/icellan.png\" height=\"50\" alt=\"Siggi\" /\u003e](https://github.com/icellan) | [\u003cimg src=\"https://github.com/galt-tr.png\" height=\"50\" alt=\"Galt\" /\u003e](https://github.com/galt-tr) | [\u003cimg src=\"https://github.com/mrz1836.png\" height=\"50\" alt=\"MrZ\" /\u003e](https://github.com/mrz1836) |\n|:--------------------------------------------------------------------------------------------------:|:-------------------------------------------------------------------------------------------------:|:------------------------------------------------------------------------------------------------:|\n|                                [Siggi](https://github.com/icellan)                                 |                                [Dylan](https://github.com/galt-tr)                                |                                [MrZ](https://github.com/mrz1836)                                 |\n\n\u003cbr/\u003e\n\n## 🤝 Contributing\n\nView the [contributing guidelines](.github/CONTRIBUTING.md) and please follow the [code of conduct](.github/CODE_OF_CONDUCT.md).\n\n### How can I help?\n\nAll kinds of contributions are welcome :raised_hands:!\nThe most basic way to show your support is to star :star2: the project, or to raise issues :speech_balloon:.\n\n[![Stars](https://img.shields.io/github/stars/bsv-blockchain/merkle-service?label=Please%20like%20us\u0026style=social\u0026v=1)](https://github.com/bsv-blockchain/merkle-service/stargazers)\n\n\u003cbr/\u003e\n\n## 📝 License\n\n[![License](https://img.shields.io/badge/license-OpenBSV-blue?style=flat\u0026logo=springsecurity\u0026logoColor=white)](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbsv-blockchain%2Fmerkle-service","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbsv-blockchain%2Fmerkle-service","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbsv-blockchain%2Fmerkle-service/lists"}