Resource · 2.4 in the design proposal

Key Management

Establish and maintain the authority structure — Key Books, Key Pages, and m-of-n thresholds — that governs who can act on an ADI or any of its sub-accounts.

8 operations 5 MVP candidates 3 Phase 2+ (KM05–KM07)

Key Books, Key Pages, and thresholds — before the operations list

Accumulate separates authority to act from the account being acted on. Per 004.References/AboutAccumulate.md §2:

A Key Book is an ordered set of Key Pages, prioritized so a higher-priority page can modify itself or any lower-priority page.
A Key Page lists the public key hashes (and/or delegate URLs) allowed to sign, plus an m-of-n signature threshold (e.g. 2-of-3) and a credit balance used to pay for the page's own transactions.
A transaction is accepted once all of the target account's authorities accept it, and an authority accepts once any one of its signers (key pages) reaches its own threshold. Cross-ADI authority approval is relayed via synthetic "forward" transactions.

This authority model is what makes Accumulate naturally suited to organizational key hierarchies — "a payment over $10,000 needs 2 of 3 finance-team signatures" — without a custom smart contract. Every operation below is either building this structure (KM01/KM02), maintaining it over time (KM03/KM04/KM05/KM06), locking it down (KM07), or reading its history (KM09). Actually signing against it lives one resource over, in SmartSigner.

Operations

Code	Operation	Maps to	Why a workflow author wants it	Priority
KM01	Create Key Book	`TxBody.CreateKeyBook()`	Establish the authority structure for a new ADI or sub-account	MVP
KM02	Create Key Page	`TxBody.CreateKeyPage()`	Add a signer set + threshold under a key book	MVP
KM03	Add/Remove Key Operation	`TxBody.AddKeyOperation()`	Onboard/offboard a signer on an existing key page — common lifecycle operation	MVP
KM04	Set Signature Threshold	`TxBody.SetThresholdOperation()`	Change the m-of-n requirement on a key page (e.g. tighten approval policy)	MVP
KM05	Update Key Page (generic)	`TxBody.UpdateKeyPage()`	Generic multi-op container for key-page changes not covered by KM03/KM04 individually	Phase 2
KM06	Update Account Auth	`TxBody.UpdateAccountAuth()`	Change which authorities govern an account (advanced authority management)	Phase 2
KM07	Lock Account	`TxBody.LockAccount()`	Freeze an account's ability to transact — an incident-response/compliance operation	Phase 2
KM09	Get Key Page Transaction History	V2 `query-tx-history` scoped to the key page's `acc://` URL	List transactions against this key page — key rotations, threshold changes, multi-sig co-sign activity (SS04)	MVP

Where did KM08 go?

"Query Key Page" was originally proposed as KM08. It's been moved to SmartSigner as SS02 — it wraps KeyManager from the SDK's Signing namespace, not a TxBody/account-structure call, so it now lives with the rest of the signing-related operations per the owner's decision to make Signing its own resource. There is intentionally no KM08 in this resource's operation table.

How it works — the authority structure a Key Book expresses

Key Book → Key Pages → m-of-n threshold

graph TD
  KB["Key Book
acc://company.acme/book"]
  KB --> P1["Key Page 1 (priority 1)
can modify itself or lower pages"]
  KB --> P2["Key Page 2 (priority 2)
"Finance — payments over $10k""]
  P2 --> S1["Signer A (public key hash)"]
  P2 --> S2["Signer B (public key hash)"]
  P2 --> S3["Signer C (public key hash)"]
  P2 -. "2-of-3 threshold (KM04)" .-> ACC["Transaction accepted once
threshold is met"]

Signer lifecycle — onboarding, offboarding, tightening policy

sequenceDiagram
  participant Admin as Workflow (team change)
  participant KM as KeyManagementService
  participant Page as Key Page

  Admin->>KM: KM03 Add Key Operation (new hire's public key)
  KM->>Page: signer set += new hire
  Admin->>KM: KM03 Add/Remove Key Operation (departure)
  KM->>Page: signer set -= departing signer
  Admin->>KM: KM04 Set Signature Threshold (2-of-3 -> 3-of-4)
  KM->>Page: threshold updated
  Admin->>KM: KM09 Get Key Page Transaction History
  KM-->>Admin: full audit of every rotation and threshold change

Business use case — multi-party approval with non-repudiable accountability

From 001.BusinessIdeas/README.md §2.2

Extend BizFirst's existing ApprovalNode (NofM strategy) so each approver's action produces a cryptographic signature against a real authority structure, not just a database row. KM01/KM02 set up a Key Book/Key Page for the approving group once (e.g. "Finance — payments over $10k requires 2 of 3"); KM03/KM04 onboard/offboard approvers and adjust the threshold as the team changes, without redesigning the workflow. The actual co-signing is SS04 on the SmartSigner page — see that page for the full consolidation flow with ApprovalNode.

The business value isn't faster approvals — it's that the resulting record is a set of cryptographic signatures against a defined authority structure, not database rows an administrator could technically alter.

Open questions affecting this resource

Open · KM05 vs. KM03/KM04 overlap

Is UpdateKeyPage() (KM05, generic multi-op) meant to fully subsume the more specific AddKeyOperation()/SetThresholdOperation() calls — making KM03/KM04 the "easy mode" and KM05 the "advanced mode" — or are these functionally distinct enough to design independently? This directly affects whether KM05 stays Phase 2 or folds into MVP.