Skip to content

docs: add order discovery specification - #36

Open
mfw78 wants to merge 2 commits into
developfrom
docs/discovery-spec
Open

docs: add order discovery specification#36
mfw78 wants to merge 2 commits into
developfrom
docs/discovery-spec

Conversation

@mfw78

@mfw78 mfw78 commented Jul 11, 2026 •
edited
Loading

Copy link
Copy Markdown

The order discovery specification: handler descriptors (IOrderDescriptor), order modules (IOrderModule, digest-verified, auto-executable by monitoring services under sandbox and budget requirements), and merkle proof payloads as URI mirrors + EIP-4844 blob publication with in-transaction verification. Normative anchor for the five implementation slices stacked above.

Issues

Part of #15.
Advances #31, #32, #33, #34 and #35 - this is the normative spec those five implementation slices cite. It contains no code, so it closes none of them.

Part of #1.

This was referenced Jul 11, 2026
Draft
Open
@mfw78
mfw78 force-pushed the refactor/require-custom-errors branch from a43b42d to 8bcf0c3 Compare July 30, 2026 03:50
@mfw78
mfw78 force-pushed the docs/discovery-spec branch from aa95a18 to 87a44e4 Compare July 30, 2026 03:50
@mfw78
mfw78 force-pushed the refactor/require-custom-errors branch from 8bcf0c3 to 63c1004 Compare July 30, 2026 04:01
@mfw78
mfw78 force-pushed the docs/discovery-spec branch 2 times, most recently from 5f0e2c2 to 8c20956 Compare July 30, 2026 06:59
@mfw78
mfw78 force-pushed the refactor/require-custom-errors branch from 63c1004 to 596389a Compare July 30, 2026 06:59
@mfw78
mfw78 force-pushed the docs/discovery-spec branch 2 times, most recently from 314ad30 to b2df2c2 Compare July 30, 2026 07:07
@mfw78
mfw78 force-pushed the refactor/require-custom-errors branch 2 times, most recently from 35c75d4 to bf590b0 Compare July 30, 2026 07:09
@mfw78
mfw78 force-pushed the docs/discovery-spec branch from b2df2c2 to 1016b30 Compare July 30, 2026 07:09
@mfw78
mfw78 force-pushed the refactor/require-custom-errors branch from bf590b0 to f1eff7c Compare July 30, 2026 07:14
@mfw78
mfw78 force-pushed the docs/discovery-spec branch from 1016b30 to 7992c0c Compare July 30, 2026 07:14
@mfw78
mfw78 force-pushed the refactor/require-custom-errors branch from f1eff7c to 8a941c3 Compare July 30, 2026 07:18
@mfw78
mfw78 force-pushed the docs/discovery-spec branch 2 times, most recently from 250a23e to c186643 Compare July 30, 2026 07:22
@mfw78
mfw78 force-pushed the refactor/require-custom-errors branch 2 times, most recently from 7a85d84 to 9010b24 Compare July 30, 2026 07:26
@mfw78
mfw78 force-pushed the docs/discovery-spec branch 2 times, most recently from d8ab6f3 to 7e2d869 Compare July 30, 2026 07:33
@mfw78
mfw78 force-pushed the refactor/require-custom-errors branch from 9010b24 to 3445d39 Compare July 30, 2026 07:33
@mfw78 mfw78 mentioned this pull request Jul 30, 2026
Open
@mfw78
mfw78 force-pushed the docs/discovery-spec branch from 7e2d869 to 351371e Compare July 30, 2026 08:23
@mfw78
mfw78 force-pushed the refactor/require-custom-errors branch 2 times, most recently from 130e269 to dcd05f6 Compare July 30, 2026 08:42
@mfw78
mfw78 force-pushed the docs/discovery-spec branch from 351371e to 5f3c35a Compare July 30, 2026 08:42
@mfw78
mfw78 force-pushed the refactor/require-custom-errors branch from dcd05f6 to 92be3d4 Compare July 30, 2026 09:51
@mfw78
mfw78 force-pushed the docs/discovery-spec branch from 5f3c35a to 2e66088 Compare July 30, 2026 09:51
@mfw78
mfw78 force-pushed the refactor/require-custom-errors branch from 92be3d4 to 6cbc689 Compare July 30, 2026 09:54
@mfw78
mfw78 force-pushed the docs/discovery-spec branch 3 times, most recently from f1153c1 to f8277c5 Compare July 30, 2026 10:40
@mfw78
mfw78 force-pushed the refactor/require-custom-errors branch from 28428bd to c6c17be Compare July 30, 2026 10:40
@mfw78
mfw78 force-pushed the docs/discovery-spec branch from f8277c5 to c8591f7 Compare July 30, 2026 12:54
@mfw78
mfw78 force-pushed the refactor/require-custom-errors branch from c6c17be to fa42396 Compare July 30, 2026 12:54
@mfw78
mfw78 force-pushed the docs/discovery-spec branch from c8591f7 to c05bc70 Compare July 30, 2026 13:07
@mfw78
mfw78 force-pushed the refactor/require-custom-errors branch from fa42396 to 78626c2 Compare July 30, 2026 13:07
@mfw78
mfw78 force-pushed the docs/discovery-spec branch from c05bc70 to 9dea757 Compare July 30, 2026 13:19
@mfw78
mfw78 force-pushed the refactor/require-custom-errors branch from 78626c2 to 84e3886 Compare July 30, 2026 13:19
@mfw78
mfw78 force-pushed the docs/discovery-spec branch from 9dea757 to 53025d9 Compare July 30, 2026 13:55
@mfw78
mfw78 force-pushed the refactor/require-custom-errors branch 2 times, most recently from 37f6449 to 1507d96 Compare July 30, 2026 14:25
@mfw78
mfw78 force-pushed the docs/discovery-spec branch from 53025d9 to 038c02d Compare July 30, 2026 14:25
@mfw78
mfw78 force-pushed the refactor/require-custom-errors branch from 1507d96 to ff7debc Compare July 30, 2026 23:43
@mfw78
mfw78 force-pushed the docs/discovery-spec branch from 038c02d to 47f3559 Compare July 30, 2026 23:43
@mfw78
mfw78 force-pushed the refactor/require-custom-errors branch from ff7debc to 4c45245 Compare July 30, 2026 23:51
@mfw78
mfw78 force-pushed the docs/discovery-spec branch from 47f3559 to 1bf6da7 Compare July 30, 2026 23:51
@mfw78
mfw78 force-pushed the refactor/require-custom-errors branch from 4c45245 to 57dfdbc Compare July 31, 2026 00:06
@mfw78
mfw78 force-pushed the docs/discovery-spec branch from 1bf6da7 to 2fb1181 Compare July 31, 2026 00:06
@mfw78
mfw78 force-pushed the refactor/require-custom-errors branch from 57dfdbc to b9fdc2a Compare July 31, 2026 00:12
@mfw78
mfw78 force-pushed the docs/discovery-spec branch from 2fb1181 to 2c6b1bf Compare July 31, 2026 00:12
Base automatically changed from refactor/require-custom-errors to develop July 31, 2026 00:13
@mfw78
mfw78 force-pushed the docs/discovery-spec branch from 2c6b1bf to a5f50fd Compare July 31, 2026 00:14
@mfw78 mfw78 mentioned this pull request Jul 31, 2026
Open
@mfw78
docs: specify order modules as WASIP2 components
e70449b 
Replaces the single-file ES module contract with a WebAssembly component
targeting a WIT world, and reworks the commitment model that locates and
verifies it.

The export contract (`ccow:module`) is normative here and versions with
`IOrderModule`: the commitment and the WIT are two halves of one agreement,
where the chain says a module exists and the WIT says what a module is. The
import surface (`videre:ccow`) is the environment and versions with the
runtime instead. `local-store` is deliberately absent, which makes the
idempotence requirement structural rather than a rule to enforce.

Commitments become `(bytes32 digest, PackageKind kind)`, hoisted into a new
section shared by descriptors and modules. Two kinds, trading the same pair of
properties against each other so a publisher picks which one it wants:

- `BZZ_MANIFEST` is a hash over a structure, so only Swarm can recompute it.
  That is what buys per-entry verification and partial fetch, and what costs
  cross-scheme mirroring. It also locates itself, so no URI is published and no
  gateway operator is written into a deployed contract.
- `TAR_ZST` is a hash over bytes, so any transport can be checked by hashing
  what it delivered. That is what buys mirroring across bzz, ipfs and https,
  and what costs verifying nothing until the whole archive is in hand.
- No per-entry digests are declared off-chain. A manifest already carries the
  root of each entry, and an archive digest covers every byte, so restating
  them would create a second source of truth and a disagreement to specify
  around without adding a check. What an archive does need, and a manifest does
  not, is extraction hardening: duplicate paths, traversal, symlinks, and
  decompression bombs.
- A UnixFS CID is not usable as a commitment: it depends on chunker and DAG
  layout, which are publisher settings rather than properties of the content,
  so it cannot be recomputed from bytes fetched elsewhere. `ipfs://` remains a
  location.

Modules are no longer required to be deterministic given a block. A module may
fetch, so repeated calls may legitimately differ; what is required is
idempotence. Determinism was never achievable here and is not needed, because
output is verified on-chain rather than trusted.

Interface changes land with the interfaces themselves.
@mfw78
mfw78 force-pushed the docs/discovery-spec branch from d164df6 to e70449b Compare July 31, 2026 05:26
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@mfw78