Skip to content

docs(specs): operation lists under libid.operations - #178

Open
SupremaLex wants to merge 13 commits into
mainfrom
feat/operation-lists
Open

SupremaLex wants to merge 13 commits into
mainfrom
feat/operation-lists

Conversation

@SupremaLex

@SupremaLex SupremaLex commented Nov 12, 2026 •

Copy link
Copy Markdown
Member

Summary

One sign-in can authorize actions at several Consumers. A proof under the operation domain libid.operations commits an Operation List: an ordered list of (domain, keccak256(data)) entries. A Consumer gets its own entry's data beside the Submission, or rebuilds it from values it authenticates, checks it against its entry's hash, and acts on that entry only. It never sees another entry's data.

The motivating case is onboarding: one proof binds a handle at IdentityRegistry (libid.bind-identity) and links the identity, with a first session, at WalletRegistry (libid.webwallet.link-identity).

Requirements

specs/ceremony-common.md:

  • REQ-COMMON-01G: under libid.operations, the domain of a Consumer's own entry is the operation domain for every per-Consumer rule, and that entry's data is the Authorized Transaction Data those rules name. libid.operations itself selects no effect (REQ-COMMON-01A).
  • REQ-COMMON-01H: the canonical encoding, fixed by each Chain Profile.
  • REQ-COMMON-01I: a Consumer's candidates are the entries under its own domains; exactly one must match the hash of its data, and that one is its own entry. Several candidates are allowed only under domains whose data commits a chain id, so one list can carry link entries for two chains; the chain is checked where the own data is decoded. No nested lists.
  • REQ-COMMON-01J: a Consumer decodes the list only to check its encoding and read domains and hashes.
  • REQ-COMMON-01K: list support is optional; a Consumer without it rejects libid.operations under REQ-COMMON-06A.
  • REQ-COMMON-01L: what an Application may put in a list: entries only for Consumers that accept lists, one per Consumer deployment (or per chain), nothing that must stay private or is unsafe for someone else to apply first. Entries stay bound by proof validity and staleness, so a list is not guaranteed to apply in full.
  • REQ-COMMON-01M: the Application shows the user every entry, with its Consumer and effect, before the ceremony.
  • REQ-COMMON-01N: anyone can read whether a list-accepting Consumer spent a digest.
  • REQ-COMMON-01O: an Application applying several entries submits them so that an entry someone else spent first counts as done (EVM: a try-mode batch call, or the REQ-COMMON-01N check in the same transaction), not after an off-chain read.
  • REQ-COMMON-05 / 06F: a Consumer forwards the value it received and does not price verification. Within one transaction the Proof Verifier may return, for zero value, a result it already verified for the same payload and Platform Verifier; with the quoted value it always verifies. A repeat charges no Notary Fee.
  • REQ-COMMON-01A, 01F and 06A count an entry's domain as the operation domain for every per-Consumer rule (01G). Domain strings belong to one Consumer protocol; §5 lists every libid. operation domain with its owner and data encoding, and a Consumer fixes a libid. domain only if that table lists it. 06A selects the handler after the own entry is selected under 01I.
  • Tests: TEST-COMMON-02 (06A, 01K), 02B–02F (02E checks the domain table and 01O), 16A (06, 06F).

specs/chain-profiles.md:

  • REQ-CHAIN-07B: the EVM encoding is abi.encode(Operation[]) with Operation { bytes32 domain; bytes32 dataHash; }; canonical means word 0 is 0x20, word 1 is n, the length is at least 64 and exceeds 64 by a multiple of 64, and n equals (length − 64) / 64. §3.3 holds the conformance vector (digest 0x8eb21531…82c1fb) and its derived rejections. TEST-CHAIN-05 covers both.

specs/platform-ceremonies.md:

  • REQ-PLAT-08P: the bind Consumer rebuilds its entry data as abi.encode(TransactionAuthor), so bind takes no extra argument.
  • REQ-PLAT-08Q: a bind value below feeAmount is rejected; the rest is forwarded to the Proof Verifier. TEST-PLAT-20E covers lists and the fee.

A proof with a single operation is unchanged, and there is no downgrade: a list's digest commits the list domain.

Implementation

libID-contracts implements this:

Checks

  • The §3.3 vector is computed with cast and pinned in ts/packages/ceremony/src/platforms/authorization.test.ts, which builds the list from its literal words and derives the digest with deriveAuthorizationDigest.
  • pnpm lint and format checks pass.
  • The spec lint has no new findings against main.

One ceremony can now authorize operations at several Consumers. The
operation domain libid.operations commits an Operation List, on EVM
abi.encode(Operation[] {bytes32 domain; bytes data}), and each entry
carries a domain and that domain's own Authorized Transaction Data.

REQ-COMMON-01G makes the domain of a Consumer's own entry the operation
domain for every per-Consumer rule, so REQ-COMMON-01A, 01F, 06A and
platform REQ-PLAT-08P read through it; each is amended to say so.
REQ-COMMON-01H requires decode, re-encode and compare, because Solidity's
abi.decode accepts trailing bytes, a gap before the array and aliased
offsets. REQ-COMMON-01I allows at most one entry among one Consumer's
domains, since the Consumer spends the digest once and a second entry of
its own would be lost; it also forbids nesting and the empty list.
REQ-COMMON-01J keeps a Consumer off other entries' data.

The digest layout and platformCeremonyVersion are unchanged: the list is
opaque Authorized Transaction Data to the Platform Verifier, so the
ceremony boundary of REQ-COMMON-01B is untouched. The ceremony layer gets
no consent screen; the Application that composes a list shows the
entries. There is no verify cache, so REQ-COMMON-06E stands.

The list vector was computed with a from-scratch keccak256 and ABI
encoder, checked against the existing §5 vector and against an
independent encoder.

Assisted-by: Claude Opus 5.5
Signed-off-by: SupremaLex <georglutsenko@gmail.com>
…ector

The Operation List vector's second entry used the placeholder domain
libid.claim-identity with four opaque bytes. It now carries a real
WalletRegistry libid.webwallet.link-identity entry, data
abi.encode(uint256 chainId, address wallet, bytes sessionKey, bytes32
policyHash) with chain 8453, wallet 0x2222..2222, a 20-byte session key
0x3333..3333 and policy hash 0x44..44. transactionData grows to 544 bytes
and the digest becomes 0x3241ec09...00b9f.

The derived rejections gain a concrete two-own-domains list
(libid.webwallet.add-session and libid.webwallet.link-identity), which
TEST-COMMON-02B now names as rejected by WalletRegistry under
REQ-COMMON-01I.

The list section also states that the spec sets no entry-count limit;
the four-byte transactionData length field of section 5, enforced by
REQ-COMMON-01, bounds the list.

Vectors were recomputed with an independent keccak256 and ABI encoder
and cross-checked against viem; the spec's words were fed back through
the independent keccak to reproduce the digest.

Assisted-by: Claude Opus 5.5
Signed-off-by: SupremaLex <georglutsenko@gmail.com>
The common specification now states an Operation List only as an ordered
sequence of (32-byte domain, bytes data) entries and requires one
canonical encoding (REQ-COMMON-01H), with the reason that the Application
and every Consumer read the same entries from the same bytes. The EVM
layout abi.encode(Operation[]), the decode, re-encode and compare method,
and the Solidity abi.decode leniencies it closes move to chain profiles
REQ-CHAIN-07B. REQ-CHAIN-07 now requires a decoder that accepts only the
bytes abi.encode produces, and TEST-CHAIN-05 carries the noncanonical
list vectors.

The list vector drops the WalletRegistry entry for an opaque libid.test.a
entry whose data is the single byte 0xff, so a bind Consumer that decoded
another entry's data would fail on the accepted vector (REQ-COMMON-01J).
The aliased-offsets negative, which also produced a duplicate domain, is
replaced by a swapped-bodies list that decodes to the vector's entries and
re-encodes to its bytes, and an outer-padding list that dirties only the
foreign entry's padding. Every negative names its Consumer and clause;
the REQ-COMMON-01I lists are canonical.

REQ-COMMON-01A applies its one-effect rule to the own entry's domain and
reserves libid.operations to applying a list entry. REQ-COMMON-01I reads
as exactly one own entry, not under libid.operations; its empty-list
clause is folded into "no own entry". The atomicity paragraph no longer
claims one transaction makes entries atomic: a third party can spend an
entry first, so an Application checks each Consumer's spent state and
gets eventual application. Section 12 says a list adds no replay beyond
each entry's own domain, and TEST-COMMON-02B splits into the accepted
vector and the rejection set (TEST-COMMON-02C).

Vectors were recomputed with a from-scratch keccak256 and ABI encoder and
checked against two independent encoders and a Solidity harness.

Assisted-by: Claude Opus 5.5
Signed-off-by: SupremaLex <georglutsenko@gmail.com>
@cloudflare-workers-and-pages

cloudflare-workers-and-pages Bot commented Nov 12, 2026 •

Copy link
Copy Markdown

🚀 Deploying Preview to Cloudflare 🚀

Preview URL: https://feat-operation-lists.previews.lib.id, https://feat-operation-lists-libid.grounded-systems.workers.dev (commit f140b87)

This URL reflects your latest Preview deployment

Preview Deployments by commit

Status Deployment URL Commit Updated (UTC) See this deployment's details
  • Build: Success ✅
  • Deployment: Success ✅

View logs ↗
https://d8c802ff.previews.lib.id, https://d8c802ff-libid.grounded-systems.workers.dev f140b87 2026-11-18T17:03:16.620Z Visit the dashboard ↗
  • Build: Success ✅
  • Deployment: Success ✅

View logs ↗
https://c27c2547.previews.lib.id, https://c27c2547-libid.grounded-systems.workers.dev 3389a20 2026-11-17T10:09:09.244Z Visit the dashboard ↗
  • Build: Success ✅
  • Deployment: Success ✅

View logs ↗
https://c2098dbc.previews.lib.id, https://c2098dbc-libid.grounded-systems.workers.dev 4fb63a2 2026-11-16T19:38:46.587Z Visit the dashboard ↗
  • Build: Success ✅
  • Deployment: Success ✅

View logs ↗
https://01809445.previews.lib.id, https://01809445-libid.grounded-systems.workers.dev 3fc9896 2026-11-12T16:18:26.972Z Visit the dashboard ↗

An Operation List entry is now (bytes32 domain, bytes32 dataHash) with
dataHash = keccak256(data). The digest still commits the whole list under
libid.operations, so platformCeremonyVersion is unchanged. A Consumer
takes its own entry's data from its call, or rebuilds it from values it
authenticates, selects the entry whose hash matches, and never sees
another entry's data. The bind Consumer rebuilds data from the
Transaction Author, so a list bind carries no data.

The EVM encoding is abi.encode(Operation[]) with Operation { bytes32
domain; bytes32 dataHash; }: 64 + 64n bytes, checked by width and the
leading 0x20 word (REQ-CHAIN-07B). The list vector and its derived lists
move to chain profiles §3.3; the new digest is
0x8eb2153142c324145458f77cd7709e6375ae24b22fa59351549afc522d82c1fb.

Alongside:
- List support is optional per Consumer (REQ-COMMON-01K); list tests
  and TEST-PLAT-20E apply only where it is supported.
- REQ-COMMON-01I selects one candidate; several candidates are allowed
  only under chain-specific domains, one per Consumer Chain, which a
  Consumer tells apart by the chain its own data names.
- Domain strings are unique to one Consumer protocol (REQ-COMMON-01A).
- The Application composes only list-capable entries, at most one per
  deployment, nothing private or unsafe to apply first (REQ-COMMON-01L),
  and shows every entry before the ceremony (REQ-COMMON-01M).
- A list-capable Consumer exposes whether it recorded a digest
  (REQ-COMMON-01N).
- Unapplied entries stay bound by proof validity and the watermark rule;
  callers tolerate an entry already spent rather than check then apply.
- One list serves one list encoding; other families take a separate
  ceremony.
- The Consumer forwards the verification value it received; the Proof
  Verifier may return, for zero value, a result it verified for the same
  payload and Platform Verifier earlier in the same transaction
  (REQ-COMMON-06F, TEST-COMMON-16A). The bind fee rule follows.
- Terminology, the system model, and chain profiles §1 no longer say one
  authorization is one transaction.
- TEST-COMMON-02 cites REQ-COMMON-06A; TEST-CHAIN-05 adds a dirty bind
  target word; TEST-COMMON-02D covers chain-specific entries.

Assisted-by: Claude Opus 5.5
Signed-off-by: SupremaLex <georglutsenko@gmail.com>
Builds the chain profiles §3.3 list from its six literal words, checks
each domain and data hash, and pins the digest
0x8eb2153142c324145458f77cd7709e6375ae24b22fa59351549afc522d82c1fb.

Assisted-by: Claude Opus 5.5
Signed-off-by: SupremaLex <georglutsenko@gmail.com>
REQ-COMMON-01L limits the Application to one entry per Consumer
deployment, matching what REQ-COMMON-01I accepts. REQ-COMMON-01I states
each rejection as its own MUST. TEST-COMMON-02C's encoding case uses a
list whose entry commits malformed data. The replay section places a
chain-specific entry's chain in its data. TEST-PLAT-20E covers a bind
value below the fee amount.

Assisted-by: Claude Opus 5.5
Signed-off-by: SupremaLex <georglutsenko@gmail.com>
At a zero quotation the quoted value and zero are one value, so REQ-COMMON-06F's
two clauses collided. A zero-value call now returns a result held from earlier
in the transaction and verifies otherwise; a non-zero quotation keeps its rules.

Assisted-by: Claude Opus 5.5
Signed-off-by: SupremaLex <georglutsenko@gmail.com>
Assisted-by: Claude Opus 5.5
Signed-off-by: SupremaLex <georglutsenko@gmail.com>

@xgreenx xgreenx left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The rules say what the contracts do, and the §3.3 vector reproduces. The comments ask for six text fixes:

  • one step order that contradicts itself;
  • a list of libid.* domains for the new collision rule;
  • a numbered duty for the front-run case;
  • two test clauses;
  • one length rule.

I checked it against libid-org/libID-contracts#131 (operation lists), libid-org/libID-contracts#138 (verify once) and libid-org/libID-contracts#140, which carries both.

  • Operation lists: the canonical encoding, the nesting ban, chain-bound candidates and "spent means applied" each say what OperationList.select and the two registries do. The vector recomputes to the same domains, data hashes and digest, and the derived lists are rejected with the errors they name.
  • Onboarding in one proof: a bind entry and a libid.webwallet.link-identity entry share one list. The paid call must come first; a zero-value call before it reverts.
  • Verify once (REQ-COMMON-06F): every clause matches CeremonyProofVerifier.verify. The Notary Fee is paid once per payload per transaction, however many Consumers share the proof.
  • Bind value (REQ-PLAT-08Q): matches IdentityRegistry._bind, and agrees with REQ-COMMON-05.
  • Spec lint: there are no new errors; the count is 108 before and after, all already on main. There are 17 new warnings:
    • The 13 W2 come from the lint reading only "The X" as an actor, so "It MUST" and "A Consumer MUST" trip it.
    • The 4 W4 each put two duties in one sentence: REQ-COMMON-01L, 05 and 06F, and REQ-PLAT-08Q.
    • Could we name the actor in each "It MUST" and split those four sentences?
  • PR description:
    • The 01G bullet describes selecting the own entry, which is 01I. 01G's rule, that the entry's domain counts as the operation domain, is the later bullet on 01A, 01F and 06A.
    • "Implementation" could link the contract PRs.

Comment thread specs/ceremony-common.md Resolved
Comment thread specs/ceremony-common.md Resolved
Comment thread specs/ceremony-common.md Resolved
Comment thread specs/ceremony-common.md Resolved
Comment thread specs/ceremony-common.md Resolved
Comment thread specs/chain-profiles.md Resolved
REQ-COMMON-01A forbade two protocols fixing one domain string, but no spec
listed the domains. The §5 table now names each libid. operation domain,
its owner protocol and where its data encoding is fixed, and the prefix is
reserved for it. TEST-COMMON-02E checks the rule against the table.

Assisted-by: Claude Opus 5.5
Signed-off-by: SupremaLex <georglutsenko@gmail.com>
Anyone may submit a public entry first, and a batch that needs every call
to succeed then reverts on the spent digest. REQ-COMMON-01O makes the rule
an Application duty, names the EVM forms that meet it, and rules out only
an off-chain read of REQ-COMMON-01N. TEST-COMMON-02E exercises it.

Assisted-by: Claude Opus 5.5
Signed-off-by: SupremaLex <georglutsenko@gmail.com>
- REQ-COMMON-06A selects the handler after selecting the own entry under
  REQ-COMMON-01I; 01I's chain clause applies where the entry's data is
  decoded, as WalletRegistry does.
- REQ-CHAIN-07B states n = (length - 64) / 64 with the length checks of
  OperationList.select, so wrapping arithmetic cannot accept a huge n.
- TEST-COMMON-02C's trailing-byte clause names a Consumer whose call
  carries its entry's data; the bind Consumer carries none.
- TEST-COMMON-16A exercises REQ-COMMON-06.

Assisted-by: Claude Opus 5.5
Signed-off-by: SupremaLex <georglutsenko@gmail.com>
The spec lint reads only "The X" as an actor and flags two keywords in one
sentence. The Operation List rules (REQ-COMMON-01J-01N, 05, 06F, REQ-PLAT-08Q)
now name their actor in every normative sentence and state one duty per
sentence; no rule changes.

Assisted-by: Claude Opus 5.5
Signed-off-by: SupremaLex <georglutsenko@gmail.com>
- REQ-COMMON-01O names the EVM forms that meet the rule, not the read
  that fails it.
- REQ-COMMON-01L keeps the per-chain limit to one Consumer protocol.
- The operation domain table names the conformance-test Consumers as the
  owners of the vector domains.

Assisted-by: Claude Opus 5.5
Signed-off-by: SupremaLex <georglutsenko@gmail.com>
@SupremaLex

Copy link
Copy Markdown
Member Author

Pushed the fixes for your review (600b4c5…f140b87e). Each inline comment has a reply. Two more: every "It MUST" now names its actor, and REQ-COMMON-01L, 05, 06F and REQ-PLAT-08Q are split into one duty per sentence. The spec lint is back to exactly main's findings (108 errors, 147 warnings). The description now has the 01G/01I bullets fixed, adds 01O, and links #131, #138 and #140 under Implementation.

This branch has not been deployed

No deployments
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.

2 participants