Skip to content

feat(contracts): view and claim contract fee pots - #1121

Draft
Claudius-Maginificent wants to merge 15 commits into
fix/protocol14-signing-key-selectionfrom
feat/contract-fee-pots
Draft

Claudius-Maginificent wants to merge 15 commits into
fix/protocol14-signing-key-selectionfrom
feat/contract-fee-pots

Conversation

@Claudius-Maginificent

@Claudius-Maginificent Claudius-Maginificent commented Oct 24, 2026 •

Copy link
Copy Markdown
Collaborator

TL;DR: On networks running protocol 14, the Contracts screen has a new Fee Pots view. It shows the owner and moderators fee pots of a contract and lets an identity that receives a pot claim it, including the seated moderation team of an elected contract.

Stacked atop #1117.

User story

As a contract owner or moderator, I want to see what my contract's document fees have collected and claim it, so that the fees reach my identity (DOC-012).

Scenario

Base flow

  1. Connect to a protocol 14 network. Own a contract whose document types charge an action fee, and open Contracts → Fee Pots and pick the contract.
  2. Claim the owner pot with the owner identity.
  3. Claim it again in the same epoch.

Actual

The app had no way to see or claim a contract's fee pots.

Expected

  • Both pots are shown with their balance and last payout (epoch, time, claimant).
  • Claiming the owner pot shows the pot and the identity's new balance. Every identity the claim paid that is kept on this device gets its new balance stored.
  • A second claim in the same epoch is refused by the network, and the message says fees can be claimed once per epoch and to try again in the next one.
  • The moderators pot of an elected contract can be claimed only by a member of its seated moderation team.
  • On a network below protocol 14, such as mainnet, the Fee Pots entry is not offered.

Detailed discussion

  • Capability (src/context/feature_gate.rs): Capability::ContractFeePots / FeatureGate::ContractFeePots opens at upstream's CONTRACT_FEE_CLAIM_INITIAL_PROTOCOL_VERSION, and only once the network has proven it runs that version. Before that, the backend refuses both the read and the claim (TaskError::ContractFeePotsNotSupported).
  • Reading (src/backend_task/contract_fee_pots.rs):
    • ContractTask::FetchContractFeePots reads both pots. A contract nobody has paid fees to reads as two empty pots.
    • For an elected contract, the same task reads the seated moderation team (leader and active members), which claims the moderators pot instead of the interim team. If the team read fails, the pots still show and the claim is left to Platform.
    • Failed contract or identity reads are reported on the Fee Pots screen. Reads and claims are routed back to that screen.
  • Who may claim (src/model/contract_fee_pots.rs): only identities that receive a pot are offered. The owner pot goes to the contract owner; the moderators pot goes to a member of the moderation team.
  • Signing key: a claim needs a CRITICAL authentication key that is not bound to a contract, because a claim is not a document batch. It uses fix(identity): choose signing keys Platform accepts on protocol 14 #1117's key selection (SigningScope::NonBatch). Without such a key, the claim is refused before anything is signed (TaskError::NoFeeClaimSigningKey).
  • Last payout epoch: the app shows it but does not block a claim on it, because the response epoch is unsigned. Platform refuses a second claim in the same epoch (TaskError::ContractFeesAlreadyClaimedThisEpoch).
  • After a claim: the proved result carries the new balance of every identity the pot paid. Each one kept on this device is stored; paid identities not kept here are skipped. If saving fails after the network paid out, the claim is still reported as paid out (ContractFeesClaimedButBalanceNotSaved), so the user does not claim again.
  • Errors (src/backend_task/error.rs): dedicated messages cover an identity that does not receive the pot, a pot already claimed this epoch, an empty pot, a network without fee pots, and no usable claim key. Each refusal from the network keeps the SDK error as its source.
  • Docs: user story DOC-012.

Testing

  • New unit tests:
    • model::contract_fee_pots: who may claim each pot, including seated and interim teams, an unread team, and a contract without moderation.
    • backend_task::contract_fee_pots::tests:
      • fee_pots_need_a_network_that_keeps_them;
      • a_claim_needs_a_critical_unbound_key;
      • a_claim_whose_balance_cannot_be_saved_is_reported_as_paid_out;
      • a_claim_stores_the_new_balance_of_every_paid_identity_kept_here.
    • ui::contracts_documents::contract_fee_pots_screen::tests:
      • a recipient can claim a filled pot, and claims Platform would refuse are blocked;
      • reads and claims come back to this screen;
      • a storage failure is reported and can be retried;
      • a paid-out claim that was not saved rereads the pots.
    • context::feature_gate (the capability gate) and backend_task::error (the refusal mappings).
  • Library tests for contract_fee_pots: 15 passed.
  • cargo clippy --all-features --lib --tests -- -D warnings and cargo fmt --all pass.
  • No live network or GUI flows were run.

🤖 Co-authored by Claudius the Magnificent AI Agent

🤖 Generated with Claude Code

https://claude.ai/code/session_012ujJpB9DBhvtbjhYB3aG9Q

lklimek and others added 4 commits October 24, 2026 19:50
On protocol 14 a contract keeps an owner and a moderators fee pot,
filled by document action fees (ContractFeePots capability). Both pots
are read together with an elected contract's seated moderation team,
which claims the moderators pot instead of the interim team.

A claim needs a CRITICAL authentication key not bound to a contract and
is refused before signing without one. The claimant's new balance is
stored afterwards; a claim the network paid out is reported as paid out
even if saving that balance fails.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012ujJpB9DBhvtbjhYB3aG9Q
Map Platform's refusals of a fee claim (identity not a recipient, pot
already claimed this epoch, nothing to claim) to dedicated TaskError
variants, plus local refusals for networks without fee pots and for a
claimant without a usable key.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012ujJpB9DBhvtbjhYB3aG9Q
The Contracts screen offers Fee Pots where the network keeps them. It
shows both pots of a contract with their balance and last payout, offers
a claim only to an identity that receives the pot, blocks claims
Platform would refuse, and reports failed reads and claims on the
screen.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012ujJpB9DBhvtbjhYB3aG9Q
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012ujJpB9DBhvtbjhYB3aG9Q
@coderabbitai

coderabbitai Bot commented Oct 24, 2026

Copy link
Copy Markdown
Contributor

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

  • Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@thepastaclaw

thepastaclaw commented Oct 24, 2026 •

Copy link
Copy Markdown
Collaborator

🕓 Review not started yet because this PR is a draft.

  • Request normal review — click when the PR is ready for review.
  • Request priority review — click to move this review to the front of the queue.

Commit bf2b257. Normal review starts when eligible; priority review starts as soon as a slot is available.

lklimek and others added 4 commits October 24, 2026 20:09
…efusals from the signing key branch

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012ujJpB9DBhvtbjhYB3aG9Q
A moderators-pot claim pays the whole team, and the proved claim result
carries every paid identity's new balance. Each one kept on this device
is stored now, not only the claimant's; paid identities not kept here
are skipped, and a failed write still reports the claim as paid out.

Also merges the module's two impl blocks and drops an unrelated
dpns_contract() cleanup from this branch.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012ujJpB9DBhvtbjhYB3aG9Q
…ract fee pot branch

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012ujJpB9DBhvtbjhYB3aG9Q
lklimek and others added 3 commits October 26, 2026 11:21
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012ujJpB9DBhvtbjhYB3aG9Q

# Conflicts:
#	src/context/feature_gate.rs
The Platform bump dropped DET's protocol version copy, so fee pot tests
have the SDK prove the version instead of setting it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012ujJpB9DBhvtbjhYB3aG9Q
…to the contract fee pots branch

Conflict in src/context/feature_gate.rs: this branch adds the
ContractFeePots capability and gate, v1.0-dev (via #1117) adds
NonTransferableTokens. Both stay, and the protocol 14 gate tests cover
both.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012ujJpB9DBhvtbjhYB3aG9Q
@Claudius-Maginificent

Copy link
Copy Markdown
Collaborator Author

Next steps: the updated #1117 head is merged into this branch locally and verified (fmt, clippy, area tests); it will be pushed right after #1117. Once #1117 merges, this PR gets retargeted to v1.0-dev and goes through the normal review gate.

🤖 Co-authored by Claudius the Magnificent AI Agent

lklimek and others added 2 commits October 26, 2026 20:34
…t-fee-pots

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012ujJpB9DBhvtbjhYB3aG9Q
@Claudius-Maginificent Claudius-Maginificent added priority: low Low priority — nice to have priority: medium Medium priority and removed priority: low Low priority — nice to have priority: medium Medium priority labels Nov 5, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

priority: low Low priority — nice to have

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants