graphsense-lib 2.17.0

[2.17.0] - 2026-09-30

Upgrade notes

• Full transforms now honour data_configuration. transformation raw-to-transformed passes the keyspace layout to the Spark job instead of letting the job use its own defaults. A configured value that differs from graphsense-lib's defaults now fails the command unless --override-defaults is given. Use Spark pipeline spark-v26.09.1 or later.
• Tagstore: existing databases need GRANT INSERT ON TABLE public.address TO userinsertedtags; (new databases get it from tagpack/init.sh). To give already-reported tags cluster mappings, run scripts/one-off-fixes/backfill_tag_addresses.py apply, then a cluster-mapping run and tagstore refresh-views.
• REST with external backends: currency role gating is on by default for externally served networks. Deployments without a gateway that sets the roles header must set auth.enforce_currency_roles: false.
• Dependencies: fastmcp >=4.0; sqlmodel is capped <0.0.45.

Library

Added

• CoW Protocol swaps in tx conversions. Every order in a CoW settlement is reported as its own dex_swap. ETH sell orders placed through the eth-flow contract are linked from the placement tx to the settlement that filled them. Turn it off with cow_protocol_swaps: false (GSREST_COW_PROTOCOL_SWAPS=false).
• graphsense-cli monitoring check-consistency checks that raw, Delta Lake and transformed keyspaces agree over the last N blocks (default 100). It covers bookkeeping (pending WAL, interrupted batches), per-block tx, trace and log counts, exchange rates, and a sampled recount of UTXO address counters. It is read-only and exits 92 on failure, so it can gate cron jobs. --topic sends failures to a notification topic.
• Direction-aware Pathfinder layout and the new graphsense-cli convert gs-files layout command. Each tx's inputs and outputs are looked up through the REST API: senders go left, receivers right, and swaps and bridges are arranged the way Pathfinder shows them. Without lookups it falls back to the previous layout. MCP build_pathfinder_file uses the new layout. New public helpers: layout_metrics, spec_from_pathfinder, annotate_tx_flows, annotate_conversions.
• MCP investigation skills. The MCP server serves agent skills as skill:// resources (GS_MCP_SKILLS_ENABLED, GS_MCP_SKILLS_DIR). The repository is also a Claude Code plugin marketplace: claude plugin marketplace add graphsense/graphsense-lib.
• Named and hex colors in Pathfinder files. build_pathfinder_file (MCP) and builder_from_spec accept a node color as a Pathfinder annotation palette name (green, red, orange, blue, purple, pink, yellow, gold, cyan, dark_green, exported as ANNOTATION_PALETTE), a #rrggbb / #rrggbbaa hex string, or RGBA floats as before. Palette colors, including a hex that matches a swatch, keep the dashboard's exact values, so the annotation dialog shows them as selected. The tool description now tells agents to color nodes by their role in the case.
• Tx identifiers accept lowercase sub-tx markers (…_t1 as well as …_T1).

Changed

• The default transformed data_configuration for trx and eth now matches the Spark job defaults: trx bucket_size 25000, block_bucket_size_address_txs 150000 (eth) / 50000 (trx), addressrelations_ids_nbuckets 100.
• Dependencies: fastmcp 4, deltalake 1.6.6, bcprov-jdk18on 1.85 for the slim Spark submit path.

Fixed

• Delta updater: batch writes are applied in dependency order (entities, lookup prefixes, relations, deletes, then the checkpoint). REST no longer briefly sees an address whose cluster row is not written yet, which used to cause HTTP 500s. The rows written are the same as before.
• Addresses of user-reported tags are registered in the tagstore, so they get cluster mappings.
• The MCP server sends its instructions again when run from the Docker image; the file was missing from the wheel.
• A malformed GRAPHSENSE_SLACK_TOPICS is now logged at startup instead of silently disabling Slack notifications.

Web API + Python client

The API and client versions move to 2.17.0, in line with the library.

Added

• External backends. A network without a Cassandra keyspace can be served by a GraphSense-API-compatible backend, configured under external_backends (enabled, networks: {code: {url, api_key}}). Requests for that network are proxied to the backend. Tags stay local, and /stats, /search, /capabilities and pubkey related_addresses merge the backend's entries into the local answer. Clients can opt out per request with X-Ikn-Currency-Opt-Out: all-light.
• Currency role gating for externally served networks, configured under auth (roles_header, currency_role_prefix, gated_currencies, enforce_currency_roles). A request needs the currency-<code> role, otherwise it gets a 403. Listings leave out the currencies the caller cannot access.
• GET /capabilities lists, per network, the feature families that are not available there (relations, clusters, tags, conversions, exact_stats).
• is_possible_service on address detail responses, a structural heuristic for exchanges and other services.
• qualifiers on Address, marking lower-bound (gt) or approximate (approx) values. Only external backends set it.

Changed

• /{currency}/txs/{tx_hash}/conversions returns CoW Protocol swaps (see Library).

Fixed

• POST /tags/report-tag for an already reported tag returns the existing report id instead of a 500, and no longer sends a duplicate notification.

What's Changed

• Detect 1inch swaps from transaction input by @frederik-raphael in #156
• test: build the testcontainers on first use by @mkzung in #160
• fix(mcp): default list-tool pagesize and advertise it in schemas by @frederik-raphael in #149
• fix(ingest): account ZEC Orchard and Ironwood value balances as shielded I/O by @steven3002 in #163
• test(spark): cap the shared test session's status-store retention by @soad003 in #174
• Cow protocol swaps by @soad003 in #175

New Contributors

• @mkzung made their first contribution in #160
• @steven3002 made their first contribution in #163

Full Changelog: v2.16.3...v2.17.0