NUTs for prediction markets by joemphilips · Pull Request #337 · cashubtc/nuts

joemphilips · 2026-02-07T15:07:48Z

This is my ongoing attempt to support encoding Prediction Market Token with cashu.
My primary motivation is to

Emulate Conditional Token Framework for flexible markets
Support existing oracle infrastructure from DLC as much as possible.

There have been previous attempts to support DLCs on Cashu, for example:
#128

The purpose of those attempts was essentially to emulate a two-party DLC transaction using eCash tokens.

This approach is completely different. Each outcome is encoded as a separate token, and the mint is agnostic to the oracles. I believe this is a more natural representation of a prediction-market security token and enables a more liquid market.

This PR contains three NUTs

NUT-CTF: Conditional token redemption via oracle-attested outcome keysets
NUT-CTF-split-merge: Conditional token split and merge for trading positions
NUT-CTF-numeric: Numeric outcome conditions with digit decomposition

Done self-reviewing, it is now ready for review from others. I will try to have a reference implementation ready when I have time. I may update the spec based on what I've learn during implementation.

It is possible to split CTF.md (Conditional Token Framework) into an independent PR if the maintainer wishes. Since this is quite a huge PR.

Reference implementation: cashubtc/cdk#1666

joemphilips · 2026-02-17T04:32:18Z

Reference implementation in CDK(WIP)
and cashu-ts

lescuer97 · 2026-02-18T15:42:00Z

@joemphilips have you taken a look at this PR: #128? its a previous standard for DLCs in cashu. you might want to take a look

joemphilips · 2026-02-19T11:43:24Z

Hi @lescuer97, thanks for pointing it out. Yes, I've read it.

I didn't go into detail because the approach is quite different from mine. IIUC, PR #128 proposes an
ecash-native DLC framework, using the mint as a blind intermediary for two-party conditional
contracts.

My concern with that approach is that it's primarily suited for bilateral contracts (two parties
locking funds against a predefined outcome tree), whereas CTF is designed for prediction markets —
where you need liquidity, composable positions, and the ability to enter/exit freely before
settlement. The two have different scopes:

DLC is for "Contract" - enforce a pre-agreed bilateral payout when an oracle attests to an
outcome.
CTF (this PR) is for "Market" - represent outcome exposure as tradeable tokens, enabling open market
participation.

They're not in conflict. In fact, both can share the same oracle infrastructure (DLC oracle
announcements/attestations), which could benefit the broader ecosystem. But I believe CTF is the
more appropriate primitive for prediction markets within Cashu's trust model.

joemphilips · 2026-04-02T02:47:43Z

In case anyone's interested, I've been building a PoC application based on this protocol.

Mockup website (very much a WIP): https://frontend-bitcaster-staging.azurewebsites.net/markets
documentation: https://bitcasterdoc.com/user-guide/getting-started/overview/

joemphilips · 2026-04-02T13:03:50Z

+[22]: 22.md
+[CTF-split-merge]: CTF-split-merge.md
+[CTF-numeric]: CTF-numeric.md
+[NIP-88]: https://github.com/nostr-protocol/nips/pull/1681


This link should be replaced with an actual NIP after nostr-protocol/nips#1681 gets merged.

Add NUT-CTF (Conditional Token Framework), NUT-CTF-split-merge (split/merge operations), and NUT-CTF-numeric (numeric outcome conditions) specs with test vectors, supplementary material, error codes, and README entries. Squashed from 9 commits after rebasing onto upstream/main to resolve NUT-28/29 filename conflicts (upstream now uses those numbers for P2BK and Batched Mint).

joemphilips · 2026-04-06T09:34:52Z

squashed and rebased

sktr · 2026-05-26T02:10:50Z

+
+## Terminology
+
+- **Condition**: A question with defined outcomes, resolved by an oracle. Identified by a `condition_id`. Equivalent to "condition" in the [Gnosis Conditional Token Framework](https://docs.gnosis.io/conditionaltokens/).


The Gnosis Conditional Token Framework link appears to be broken.
It currently shows a "Page Not Found" page.

Thanks. It seems like the website is not well maintained. Perhaps I should link to the contract itself (https://github.com/gnosis/conditional-tokens-contracts)

Or referencce the Polymarket's version (https://github.com/Polymarket/ctf-exchange-v2) but this one has slightly different terminology so I must be careful. Let me think

broken link fixed.
It seems to be referencing Polymarket version CTF is not a good idea for now since it has a much broader scope than this (off-chain CLOB matching, UMA oracle, etc.)

The docs.gnosis.io/conditionaltokens/ URL returns 404. Replace with the official readthedocs site (rendered from the same gnosis/conditional-tokens-contracts repo) and link the contracts repo alongside as a stable fallback. Add Polymarket as a real-world production example of the same model in CTF.md's Terminology section.

…SPIKE-02) SPIKE-02 resolved by pivot: NUT-CTF (cashubtc/nuts#337) is still draft/WIP and was the only blocker left in the Phase 2 backend. It isn't needed. A Hunch outcome token is a vanilla NUT-11 P2PK proof locked to L = B + S_X (bettor key + oracle outcome signature point). The spend key b + s_X exists only after the oracle attests X, so the token is spendable iff the outcome occurred. The mint enforces only NUT-11 — no custom NUT, builds on shipping CDK. Refund/INVALID maps to NUT-11 locktime+refund tags. - token.rs: build_outcome_token (NUT-11 secret with lock + refund + locktime), redeem_spend_secret, verify_token_unlock - 3 tests against the real oracle attestation path: YES attestation redeems the YES token only; wrong bettor can't redeem; secret carries lock/refund/locktime - spikes/nut-ctf/SPIKE-02-RESOLUTION.md documents the pivot, math, safety, and the HIP-3 update needed Remaining mint work (CDK issuance, LDK Lightning, DLC funding tx) is standard engineering on stable primitives — no longer blocked. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Replace POST /v1/ctf/split and /v1/ctf/merge with a single POST /v1/ctf/convert that performs any payoff-preserving rebalance of conditional positions within one condition at one nesting level. Split, merge, recombine, and negative-risk-style conversion all become special cases. Core rule: for every outcome o in Omega, out(o) == in(o) - F, valid only if in(o) >= F, where F = ceil(sum input_fee_ppk / 1000). The flat fee is retained non-contingently on every outcome (real collateral the mint keeps regardless of the attested outcome), which bounds free operations. Collateral is the reserved map key '*' (regular keyset at root, parent conditional keyset when nested). Coverage is computed from registered keyset metadata, not request map keys. Canonical collection encoding fixed (enum: announcements[0] outcome index; numeric: [HI,LO]). Partitions must have >=2 elements with no full-set conditional collection. Issuance invariant: every conditional token backed by >= its face in collateral. Adds error codes 13041/13042/13043; updates CTF.md, CTF-numeric.md, error_codes, suppl, and test vectors accordingly. Design and post-implementation passes adversarially reviewed via Codex (verdict: sound to merge).

Remove partition registration from the CTF specs and describe condition-time keyset creation, managed default policies, root-only convert scope, and updated numeric behavior.

Add NUT-08-style blank outputs and change signatures for condition registration fees so mints retain only the authoritative required fee.

Use a distinct 13047 error for invalid registration fee change outputs and disambiguate the idempotency cross-reference.

github-project-automation Bot added this to nuts Feb 7, 2026

github-project-automation Bot moved this to Backlog in nuts Feb 7, 2026

joemphilips force-pushed the nuts_for_prediction_markets branch from 2657a60 to 3f6850a Compare February 15, 2026 14:10

joemphilips marked this pull request as ready for review February 15, 2026 14:11

joemphilips changed the title ~~WIP: NUTs for prediction markets~~ NUTs for prediction markets Feb 15, 2026

joemphilips mentioned this pull request Feb 17, 2026

feat: NUT-CTF conditional tokens for prediction markets cashubtc/cdk#1648

Closed

joemphilips force-pushed the nuts_for_prediction_markets branch 2 times, most recently from ee15247 to 63af400 Compare February 18, 2026 01:18

joemphilips mentioned this pull request Feb 22, 2026

feat: NUT-CTF conditional tokens for prediction markets cashubtc/cdk#1666

Draft

joemphilips force-pushed the nuts_for_prediction_markets branch 2 times, most recently from 94336aa to 16b650c Compare February 23, 2026 13:25

joemphilips commented Apr 2, 2026

View reviewed changes

joemphilips mentioned this pull request Apr 6, 2026

NUT-XX: Token possession proof #360

Open

joemphilips force-pushed the nuts_for_prediction_markets branch from f94f19e to 618bf78 Compare April 6, 2026 09:20

Update test vectors according to the recent update

572e190

joemphilips mentioned this pull request May 24, 2026

Add conditional token primitives for NUT-CTF cashubtc/cashu-ts#682

Draft

sktr reviewed May 26, 2026

View reviewed changes

joemphilips added 5 commits June 5, 2026 14:55

Update NUT-CTF keyset registration model

99a884c

Remove partition registration from the CTF specs and describe condition-time keyset creation, managed default policies, root-only convert scope, and updated numeric behavior.

feat: document CTF registration fees

d61fda7

feat: define CTF registration fee change

a3f6544

Add NUT-08-style blank outputs and change signatures for condition registration fees so mints retain only the authoritative required fee.

fix: clarify CTF fee change errors

399aca9

Use a distinct 13047 error for invalid registration fee change outputs and disambiguate the idempotency cross-reference.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

NUTs for prediction markets#337

NUTs for prediction markets#337
joemphilips wants to merge 8 commits into
cashubtc:mainfrom
joemphilips:nuts_for_prediction_markets

joemphilips commented Feb 7, 2026 •

edited

Loading

Uh oh!

joemphilips commented Feb 17, 2026 •

edited

Loading

Uh oh!

lescuer97 commented Feb 18, 2026

Uh oh!

joemphilips commented Feb 19, 2026

Uh oh!

joemphilips commented Apr 2, 2026

Uh oh!

joemphilips Apr 2, 2026

Uh oh!

joemphilips commented Apr 6, 2026

Uh oh!

sktr May 26, 2026

Uh oh!

joemphilips May 26, 2026

Uh oh!

joemphilips May 27, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants


		## Terminology

		- Condition: A question with defined outcomes, resolved by an oracle. Identified by a `condition_id`. Equivalent to "condition" in the [Gnosis Conditional Token Framework](https://docs.gnosis.io/conditionaltokens/).

Conversation

joemphilips commented Feb 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

joemphilips commented Feb 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

lescuer97 commented Feb 18, 2026

Uh oh!

joemphilips commented Feb 19, 2026

Uh oh!

joemphilips commented Apr 2, 2026

Uh oh!

joemphilips Apr 2, 2026

Choose a reason for hiding this comment

Uh oh!

joemphilips commented Apr 6, 2026

Uh oh!

sktr May 26, 2026

Choose a reason for hiding this comment

Uh oh!

joemphilips May 26, 2026

Choose a reason for hiding this comment

Uh oh!

joemphilips May 27, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

joemphilips commented Feb 7, 2026 •

edited

Loading

joemphilips commented Feb 17, 2026 •

edited

Loading