Skip to content

Add compact state filters - #2477

Draft
crodas wants to merge 1 commit into
cashubtc:mainfrom
crodas:feat/compact-state-filters
Draft

crodas wants to merge 1 commit into
cashubtc:mainfrom
crodas:feat/compact-state-filters

Conversation

@crodas

@crodas crodas commented Sep 6, 2026

Copy link
Copy Markdown
Collaborator

Description

Following ecash today means naming it: checkstate carries the exact Y values, quote polling carries the quote id, and a seed restore hands the mint every recovered Y including the unspent ones. Compact state filters replace that with public Golomb-Rice filters, published once per epoch and identical for every requester, that a wallet tests locally. A wallet learns that its ecash was spent, or its quote paid, without telling the mint which, and makes an identifying request only when something has probably happened.

The mint records one element per observable state change in the same transaction that makes it, builds one filter per closed epoch, and serves them as pages that never change again. The wallet sweeps new filters, tests its own objects offline, and confirms a match through NUT-07 or the quote endpoint before acting on it, since a filter is never authoritative. Restore and the pending-proof and quote sweeps prefer filters whenever the mint advertises them and fall back otherwise.

Spec: cashubtc/nuts#433


Notes to the reviewers


Suggested CHANGELOG Updates

CHANGED

ADDED

REMOVED

FIXED


Checklist

  • I followed the code style guidelines
  • I ran just quick-check before committing
  • If the Wallet API was modified (added/removed/changed), I have reflected those changes in the FFI bindings (crates/cdk-ffi)

@crodas crodas added the new nut This PR is held pending the merge of a new or updated NUT label Sep 6, 2026
@github-project-automation github-project-automation Bot moved this to Backlog in CDK Sep 6, 2026
Following ecash today means naming it: checkstate carries the exact Y values,
quote polling carries the quote id, and a seed restore hands the mint every
recovered Y including the unspent ones. Compact state filters replace that with
public Golomb-Rice filters, published once per epoch and identical for every
requester, that a wallet tests locally. A wallet learns that its ecash was
spent, or its quote paid, without telling the mint which, and makes an
identifying request only when something has probably happened.

The mint records one element per observable state change in the same
transaction that makes it, builds one filter per closed epoch, and serves them
as pages that never change again. The wallet sweeps new filters, tests its own
objects offline, and confirms a match through NUT-07 or the quote endpoint
before acting on it, since a filter is never authoritative.  Restore and the
pending-proof and quote sweeps prefer filters whenever the mint advertises them
and fall back otherwise.

Spec: cashubtc/nuts#433
@crodas
crodas force-pushed the feat/compact-state-filters branch from 9128a21 to b752c07 Compare September 6, 2026 15:27
@codecov

codecov Bot commented Sep 6, 2026

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 78.29060% with 254 lines in your changes missing coverage. Please review.
✅ Project coverage is 78.92%. Comparing base (bb139ef) to head (b752c07).

Files with missing lines Patch % Lines
crates/cdk/src/wallet/state_filters/mod.rs 53.67% 82 Missing ⚠️
crates/cdk-mintd/src/lib.rs 26.66% 22 Missing ⚠️
crates/cdk-axum/src/filters_handlers.rs 0.00% 21 Missing ⚠️
crates/cdk-mintd/src/env_vars/state_filters.rs 43.24% 21 Missing ⚠️
crates/cdk/src/wallet/state_filters/cursor.rs 64.28% 20 Missing ⚠️
crates/cdk/src/mint/state_filters/mod.rs 80.64% 18 Missing ⚠️
crates/cdk-common/src/error.rs 0.00% 14 Missing ⚠️
crates/cdk/src/mint/state_filters/service.rs 91.66% 11 Missing ⚠️
crates/cdk-axum/src/lib.rs 0.00% 8 Missing ⚠️
crates/cdk/src/mint/mod.rs 84.00% 8 Missing ⚠️
... and 10 more
Additional details and impacted files
@@            Coverage Diff             @@
##             main    #2477      +/-   ##
==========================================
- Coverage   78.93%   78.92%   -0.02%     
==========================================
  Files         387      398      +11     
  Lines      105293   106391    +1098     
==========================================
+ Hits        83115    83968     +853     
- Misses      22178    22423     +245     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

new nut This PR is held pending the merge of a new or updated NUT

Projects

Status: Backlog

Development

Successfully merging this pull request may close these issues.

1 participant