1  # Assay Spec v0.1
  2  
  3  Status: Draft
  4  
  5  Assay turns narrow software checks into portable receipts.
  6  
  7  An assay is a small, named check of a narrow claim.
  8  
  9  A receipt records what was checked, which runner performed the check, which target was checked, under which conditions, and what result was produced.
 10  
 11  The first target is Nockchain wallet and infrastructure tooling.
 12  
 13  ## Objects
 14  
 15  Assay defines two objects:
 16  
 17  1. Assay Manifest
 18  2. Assay Receipt
 19  
 20  ## Assay Manifest
 21  
 22  An assay manifest defines a narrow software claim and the checks used to evaluate it.
 23  
 24  For v0, manifests are written as TOML files named `assay.toml`.
 25  
 26  Required fields:
 27  
 28  ```toml
 29  schema = "assay.manifest.v0"
 30  
 31  id = "nock-wallet-cli-smoke"
 32  version = "0.1.0"
 33  name = "Nockchain Wallet CLI Smoke Assay"
 34  author = "assay-core"
 35  
 36  target_type = "wallet-cli"
 37  runner = "assay-runner-v0.1.0"
 38  
 39  claim = "wallet CLI can perform basic expected operations against a configured local or fakenet Nockchain environment"
 40  
 41  hash_algorithm = "sha256"
 42  case_mode = "public"
 43  
 44  determinism_required = true
 45  network_mode = "local-or-fakenet"
 46  timeout_ms = 30000
 47  
 48  checks = [
 49    "binary_available",
 50    "version_or_help_available",
 51    "can_connect_to_configured_node",
 52    "can_query_notes_or_balance",
 53    "can_attempt_transaction_creation",
 54    "can_parse_transaction_artifact_when_available"
 55  ]
 56  
 57  non_goals = [
 58    "does_not_prove_wallet_security",
 59    "does_not_prove_key_management_safety",
 60    "does_not_prove_transaction_semantic_correctness_beyond_declared_checks",
 61    "does_not_replace_audits"
 62  ]
 63  ```
 64  
 65  ## Manifest Hash
 66  
 67  For v0, the manifest hash is the SHA-256 hash of the exact UTF-8 bytes of `assay.toml`.
 68  
 69  This means formatting changes change the manifest hash by design.
 70  
 71  Future versions may define a canonical noun representation, canonical JSON representation, or Nockchain-native hash.
 72  
 73  ## Assay Receipt
 74  
 75  An assay receipt records the result of running a target against an assay manifest.
 76  
 77  For v0, receipts are JSON objects.
 78  
 79  Required and reserved fields:
 80  
 81  ```json
 82  {
 83    "schema": "assay.receipt.v0",
 84    "assay_id": "nock-wallet-cli-smoke",
 85    "assay_version": "0.1.0",
 86    "manifest_hash": "sha256:...",
 87    "runner": "assay-runner-v0.1.0",
 88    "runner_hash": "sha256:...",
 89    "target": "nockchain-wallet",
 90    "target_version": "git:...",
 91    "target_hash": "sha256:...",
 92    "result": "pass",
 93    "passed": 0,
 94    "failed": 0,
 95    "timestamp": "2026-04-30T00:00:00Z",
 96    "issuer": null,
 97    "signature": null,
 98    "proof": null,
 99    "artifact_refs": [],
100    "nockchain": null,
101    "receipt_hash": "sha256:..."
102  }
103  ```
104  
105  ## Receipt Hash
106  
107  For v0, the receipt hash is the SHA-256 hash of the exact UTF-8 bytes of the receipt JSON file, excluding the `receipt_hash` field.
108  
109  This rule is provisional.
110  
111  Future versions should define canonical JSON or a canonical noun representation so equivalent receipts produce identical hashes.
112  
113  ## Field Definitions
114  
115  ### `schema`
116  
117  The schema version used by the object.
118  
119  Examples:
120  
121  ```text
122  assay.manifest.v0
123  assay.receipt.v0
124  ```
125  
126  ### `id`
127  
128  The stable identifier for the assay.
129  
130  Example:
131  
132  ```text
133  nock-wallet-cli-smoke
134  ```
135  
136  ### `version`
137  
138  The semantic version of the assay.
139  
140  Example:
141  
142  ```text
143  0.1.0
144  ```
145  
146  ### `name`
147  
148  A human-readable assay name.
149  
150  ### `author`
151  
152  The author or maintainer of the assay manifest.
153  
154  ### `target_type`
155  
156  The type of software being checked.
157  
158  Examples:
159  
160  ```text
161  wallet-cli
162  nockapp
163  sdk
164  bridge-adapter
165  explorer
166  miner
167  pool
168  prover
169  ```
170  
171  ### `runner`
172  
173  The assay runner expected to evaluate the target.
174  
175  Example:
176  
177  ```text
178  assay-runner-v0.1.0
179  ```
180  
181  ### `claim`
182  
183  The narrow claim being checked.
184  
185  A claim should be specific, limited, and falsifiable.
186  
187  Good:
188  
189  ```text
190  wallet CLI can perform basic expected operations against a configured local or fakenet Nockchain environment
191  ```
192  
193  Bad:
194  
195  ```text
196  wallet is safe
197  ```
198  
199  ### `hash_algorithm`
200  
201  The hash algorithm used for v0 manifest and artifact references.
202  
203  For v0, the default is:
204  
205  ```text
206  sha256
207  ```
208  
209  ### `case_mode`
210  
211  The case visibility and verification mode.
212  
213  Supported v0 values:
214  
215  ```text
216  public
217  commit-reveal
218  trusted-private
219  proof-backed
220  ```
221  
222  ### `determinism_required`
223  
224  Whether the assay expects deterministic behavior from the target and runner.
225  
226  ### `network_mode`
227  
228  The expected network environment.
229  
230  Examples:
231  
232  ```text
233  none
234  local
235  fakenet
236  local-or-fakenet
237  testnet
238  mainnet
239  ```
240  
241  ### `timeout_ms`
242  
243  The maximum wall-clock time allowed for the assay run.
244  
245  ### `checks`
246  
247  A list of named checks performed by the assay.
248  
249  ### `non_goals`
250  
251  A list of explicit things the assay does not claim to prove.
252  
253  ## Case Modes
254  
255  ### Public
256  
257  All checks and cases are public and reproducible.
258  
259  This is the default mode for v0.
260  
261  ### Commit-Reveal
262  
263  The assay operator commits to hidden cases before a round and reveals them after the round.
264  
265  This mode can reduce overfitting while preserving later auditability.
266  
267  ### Trusted-Private
268  
269  The assay operator keeps cases private and signs receipts.
270  
271  This mode requires trust in the operator.
272  
273  ### Proof-Backed
274  
275  The assay result is backed by a proof that the result followed from the committed manifest, committed cases, runner, and target output.
276  
277  Proof-backed mode is future work.
278  
279  ## Future-Proofing Fields
280  
281  The following receipt fields are optional in v0 but reserved for signed, proof-backed, and Nockchain-published receipts.
282  
283  ### `issuer`
284  
285  The identity that issued the receipt.
286  
287  In v0 this may be `null`.
288  
289  Future versions may use a public key, DID, Nockchain address, Urbit ship, or another explicit identity format.
290  
291  ### `signature`
292  
293  A signature by the issuer over the canonical receipt contents.
294  
295  In v0 this may be `null`.
296  
297  Future versions may require signatures for public registries or hosted assay runs.
298  
299  ### `proof`
300  
301  A proof object showing that the result followed from the declared manifest, runner, target output, and case set.
302  
303  In v0 this must be `null` unless an assay defines an experimental proof format.
304  
305  Future versions may support proof-backed receipts.
306  
307  Example future shape:
308  
309  ```json
310  {
311    "type": "nock-zkvm",
312    "statement_hash": "sha256:...",
313    "proof_hash": "sha256:...",
314    "verifier_hash": "sha256:...",
315    "public_inputs_hash": "sha256:..."
316  }
317  ```
318  
319  ### `artifact_refs`
320  
321  A list of external artifacts needed to inspect or reproduce the receipt.
322  
323  Examples include logs, case files, target binaries, source snapshots, generated transaction files, or proof files.
324  
325  In v0 this may be empty.
326  
327  Example:
328  
329  ```json
330  [
331    {
332      "name": "runner-log",
333      "media_type": "text/plain",
334      "hash": "sha256:...",
335      "uri": "file://logs/run.txt"
336    }
337  ]
338  ```
339  
340  ### `nockchain`
341  
342  Metadata for receipts registered by an Assay NockApp or published to Nockchain.
343  
344  In v0 this is usually `null`.
345  
346  Example future shape:
347  
348  ```json
349  {
350    "network": "fakenet",
351    "assay_app": "assay-registry-v0",
352    "state_root": "sha256:...",
353    "tx_id": "..."
354  }
355  ```
356  
357  ## Validity
358  
359  An assay manifest is valid if:
360  
361  1. It declares a supported schema.
362  2. It has a stable id.
363  3. It has a semantic version.
364  4. It declares a target type.
365  5. It declares a runner version.
366  6. It declares a narrow claim.
367  7. It declares a hash algorithm.
368  8. It declares a case mode.
369  9. It declares its checks.
370  10. It declares its non-goals.
371  
372  An assay receipt is valid if:
373  
374  1. It declares a supported schema.
375  2. It names the assay id and version.
376  3. It names the manifest hash.
377  4. It names the runner and runner hash.
378  5. It names the target and target version.
379  6. It reports a result.
380  7. It reports passed and failed counts.
381  8. Its receipt hash matches its canonical contents under the v0 receipt hash rule.
382  
383  For v0, `issuer`, `signature`, `proof`, and `nockchain` may be null.
384  
385  A proof-backed receipt is valid only if the proof verifies against the declared statement, verifier, public inputs, manifest hash, runner hash, and target hash.
386  
387  Proof-backed receipt validation is future work.
388  
389  A Nockchain-published receipt is valid only if the receipt hash or registry state commitment can be resolved against the declared Nockchain network and Assay NockApp state.
390  
391  Nockchain-published receipt validation is future work.
392  
393  ## Security Notes
394  
395  An assay receipt is not an audit.
396  
397  A receipt does not prove that software is safe.
398  
399  A receipt does not prove full correctness.
400  
401  A receipt means only:
402  
403  > This target version was checked against this assay version by this runner version under these declared conditions.
404  
405  Assay is complementary to audits, formal verification, monitoring, and production testing.
406  
407  ## Long-Term Direction
408  
409  Assay starts as local manifests and receipts.
410  
411  The intended path is:
412  
413  ```text
414  local receipt
415  → signed receipt
416  → public artifact mirrors
417  → commit-reveal checks
418  → Assay NockApp registry
419  → Nockchain-published commitments
420  → proof-backed receipts
421  ```
422  
423  The long-term implementation may include an Assay NockApp that registers assay manifests and receipts, maintains a public registry state, and publishes commitments to Nockchain.
424  
425  In that model:
426  
427  ```text
428  assay manifest
429  → local/off-chain runner
430  → receipt
431  → Assay NockApp
432  → Nockchain commitment
433  ```
434  
435  The NockApp should not need to store all artifacts directly on-chain.
436  
437  Large artifacts such as logs, case files, binaries, generated outputs, and proof files may be mirrored through Radicle, Urbit ships, IPFS, Arweave, ordinary HTTPS, local archives, or other storage systems.
438  
439  Validity should come from hashes, signatures, receipts, proofs, and Nockchain commitments rather than from any single centralized website.