Skip to content

D2 — a key that places orders and nothing else, and flet acts only while the venue lists it - #33

Draft
napkinstack-agent[bot] wants to merge 1 commit into
mainfrom
d2/the-key
Draft

napkinstack-agent[bot] wants to merge 1 commit into
mainfrom
d2/the-key

Conversation

@napkinstack-agent

@napkinstack-agent napkinstack-agent Bot commented Sep 24, 2026 •

Copy link
Copy Markdown
Contributor

D2 — a key that places orders and nothing else, and flet acts only while the venue lists it

Draft. The venue tests — the oracle for criteria 1 to 3 — are written and not run:
they need the decider's funded testnet wallet. This pull request is not ready for a verifier
until they have run.


Module

modules/copying — exactly one.

  • This pull request touches a single module
  • ⚠️ Cross-module — the cross-module label is required, justification below

Deliverable

Deliverable: D2

What it changes

A member can now be handed a key, and nothing in flet can act on it unless the venue says it
lives.

  • copying authorise MEMBER generates a fresh agent and prints what to approve on the
    venue's API page: the address and the name flet valid_until <30 days>.
  • copying status MEMBER asks the venue once, no retry, and says one of three different
    things: alive (per the venue), not listed or expired (flet will not act), or no answer —
    exit 3, nothing done, nothing concluded.
  • copying forget MEMBER drops flet's copy and says it does not revoke.
  • act_for is the only way to act for a member: it runs the action only if extraAgents lists
    our agent unexpired. Seen once and then absent, or listed expired → the key is deleted. Not
    yet approved → kept until its own expiry. Unheard venue → NoAnswer, key kept.
  • At rest: Fernet, one file per member, created 0600, written atomically; the member address
    is validated before it names a file; the key is excluded from the dataclass's repr.

Why the venue tests read the member's funds and not only the refusal. A user-signed action
(withdrawal, transfer, approval) is attributed to whoever signs it. Signed by the agent, the
venue may refuse because the agent's own account is empty — which says nothing about the
member's. So each forbidden-action test also asserts the member's perp and spot balances and
their agent list did not move.

Oracle

docs/os/05-workflow.md §3

  • The success criterion was written before the implementation
  • It was seen failing, for the right reason — collection failed on the missing modules
  • It passes now — offline yes (45 passed); on the venue, not run (12 skipped)

Kind of oracle: unit test · integration (venue testnet, not yet run)

Hand mutants, offline suite: 10 applied, each verified applied, __pycache__ cleared between
them — all 10 killed. The tenth (deleting a key the venue lists expired but we never saw alive)
survived first and the assertion it exposed was added.


Review budget

docs/os/05-workflow.md §4

  • Lines changed (excluding generated): ~950 — 274 of code, ~620 of tests, the rest docs
  • Files touched: 19
  • Within budget
  • ⚠️ Over budget — justification: two thirds are tests, and for the first critical module
    the tests are the deliverable — one per forbidden action by the criterion's own wording.
    Splitting the code from its oracle would put untested key-handling code on main.

Contracts

  • No contract affected
  • Contract consumed — the version is declared in the manifest

Test sheet

Verifier: <to be named — a session that is not 98242fbe-7c26-467e-a3e9-e8816ec93493>

# Given · when · then Kind Result Evidence Commit
S1 Given a member who authorised nothing, when flet's agent is approved, then the venue lists it with the validUntil we asked for, and userRole of the agent names the member automated not verified test_the_venue_lists_the_agent_with_the_expiry_we_asked_for
S2 Given that agent, when it places a resting order and cancels it, then the venue accepts both (the positive control for S4) automated not verified test_the_agent_can_place_and_cancel_an_order
S3 Given the agent, when it attempts withdraw3, usdSend, spotSend, usdClassTransfer, sendAsset, approveAgent, approveBuilderFee, then each is refused, the refusal is recorded, and the member's funds and agents are unchanged automated not verified test_the_venue_refuses_the_agent[*], 7 cases
S4 Given a member who revokes, when an order is then placed with the key, then the venue refuses it automated not verified test_after_revocation_the_venue_refuses_an_order
S5 Given an agent past its expiry, when it places an order, then the venue refuses it automated not verified test_after_expiry_the_venue_refuses_an_order
S6 Given a revoked key, when flet would act, then it does not, asks once, and deletes the key automated not verified test_after_revocation_flet_does_nothing + test_guard.py
S7 Given every command path run with a known key, then the key is in no stdout, stderr, log record, repr, or clear on disk; the file is 0600 automated not verified test_the_key_appears_in_no_output_and_no_log_on_any_path, test_store.py
S8 Given the venue's real API page, when the member pastes the address and the name flet valid_until …, then the page accepts the name and the venue lists the expiry human only — the venue's page needs the member's own wallet not verified

Summary

DONE

  • The module's code: agent generation, encrypted store, venue reader, the act_for guard, and the
    authorise / status / forget command.
  • Offline tests for criteria 4 and 5; venue tests for criteria 1 to 3.
  • commands.check, test, bootstrap declared; AGENTS.md and README.md updated.

VERIFIED

  • nstack check copying 0 · nstack test copying 45 passed, 12 skipped · nstack fitness 0.
  • Ten hand mutants killed.
  • Read-only against the testnet, no key: extraAgents returns a list, userRole a role, USDC's
    spot token id and BTC's szDecimals are what the tests assume.

ASSUMED

  • validUntil is in milliseconds, like every other venue timestamp. S1 establishes it.
  • Replacing an agent under the same full name — flet valid_until … included — deregisters
    it. The docs say "a matching name" without saying whether the valid_until suffix is part of
    it. S4 establishes it; if it does not hold, the member's path is the API page's removal.
  • The venue's API page accepts a name carrying valid_until (S8).

NOT VERIFIED

  • Everything on the venue: S1–S6 need the decider's wallet in FLET_TESTNET_MAIN_KEY.
  • convertToMultiSigUser, vaultTransfer and subAccountTransfer are not attempted: the first
    would, if accepted, lock the test account; the other two need a vault or a sub-account the
    test account does not have. Named here rather than silently omitted.
  • The account holds at most three named agents; whether the test suite's approvals exhaust them
    on a run is unknown until one runs.

RISKS

  • The encryption secret lives beside the ciphertext (ADR-0001): a server compromise is a key
    incident for every member.
  • status builds the SDK's Info, which reads the venue while being constructed; any failure
    there is reported as no answer, by design.

Signals to report

  • I had to look at another module's implementation
  • A kernel or playbook rule got in my way for no good reason
  • A quality gate blocked without improving quality
  • A rule applied by hand would be worth automating — the hand mutants, for critical modules

🤖 Generated with Claude Code

…ile the venue lists it

`copying authorise` generates a fresh agent for a member and prints what to
approve on the venue's API page: the address, and the name
`flet valid_until <30 days>`. `status` asks the venue — once, no retry — and
says alive, not listed, or no answer, which are three different things.
`forget` drops flet's copy and says in as many words that it does not revoke.

Everything that would act for a member goes through `act_for`, which runs the
action only if the venue's `extraAgents` lists our agent unexpired. Not
listed after having been seen, or listed expired, deletes the key. Not yet
approved keeps it until its own expiry. An unheard venue raises NoAnswer and
changes nothing: egress denied is not a revocation.

At rest: Fernet, one file per member, created 0600, written atomically. The
member address is validated before it names a file. The key is kept out of
the dataclass's repr, and one test runs every command path with the key known
and searches stdout, stderr and every log record for it.

The venue tests are the oracle for criteria 1 to 3 and they are written but
NOT RUN: they need the decider's funded testnet wallet. They attempt each
forbidden action as the agent and assert the member's funds and agents did
not move — a refusal alone could be the agent's own empty account refusing,
since a user-signed action is attributed to whoever signs it.

Offline: 45 passed, 12 skipped (the venue tests). Ten hand mutants of the
guard, the venue reader, the store, the key and the command: all ten killed,
the last one after adding the assertion it exposed.

Agent-Session: 98242fbe-7c26-467e-a3e9-e8816ec93493
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

0 participants