feat(deployments): require source commit provenance for first-party records

deployments/README.md

@@ -34,7 +34,8 @@ if the two disagree.
           "name": "ERC5564Announcer", // contract, crate or Anchor program name
           "id": "0x8AE6…", // address / contract ID / program ID / code hash
           "version": "0.1.0", // package or crate version, null if unknown
-          "sourceCommit": "…", // 40-hex git commit, null if unknown
+          "sourceCommit": "…", // full 40-hex git commit; null only when unverifiable
+          "provenance": { "status": "source-verified" }, // or { "status": "unverifiable", "reason": "…" }
           "artifactHash": { "algorithm": "keccak256", "value": "0x…" },
           "abi": { "path": "evm/subgraph/abis/ERC5564Announcer.json", "sha256": "0x…" },
           "deployment": {
@@ -69,9 +70,35 @@ so formatting does not matter). Solana programs carry `solana.programData` and
 `external: true` marks third-party scripts Wraith depends on (ckb-auth).
 
 `recordedBy: "chain-query"` means the record was reconstructed from chain state after
-the fact, so `sourceCommit` and `version` may be `null`. The current EVM, Solana and CKB
-records are of this kind: they predate the manifest. Records written by a deploy script
-must carry a source commit.
+the fact.
+
+### Source provenance
+
+Every first-party contract carries `provenance`:
+
+- `source-verified`: `sourceCommit` is a full 40-hex commit and building it reproduces
+  `artifactHash`. `npm run verify-source` rebuilds and checks this (EVM via Hardhat,
+  Stellar via the `stellar/deploy.sh` build; contracts with Solidity immutables are
+  compared against the deployed code everywhere except the immutable slots).
+- `unverifiable`: a historical record. `sourceCommit` is `null` and `reason` says why.
+  The current EVM, Solana and CKB records are of this kind, because they predate the
+  manifest and no build has been shown to reproduce them. Solana and CKB have no
+  reproducible build yet, so they cannot be source-verified.
+
+Records written by a deploy script must be `source-verified`: `record` rejects a missing
+or malformed `--source-commit` (only `HEAD` or a full hash), a working tree with
+uncommitted changes, and a commit whose build does not reproduce the artifact hash.
+Re-recording unchanged bytecode keeps its existing provenance; changed bytecode resets
+it to `unverifiable` unless a commit is supplied.
+
+To upgrade a historical record, prove the commit offline:
+
+```bash
+npm run attest -- evm --network horizen-testnet --contract ERC5564Announcer --search
+npm run attest -- evm --network horizen-testnet --contract ERC5564Announcer --commit <full sha>
+```
+
+A record is only changed when a build reproduces the recorded hash.
 
 ## Consumers
 
@@ -141,10 +168,12 @@ it names; `npm run deploy` and `npm run deploy-local` in `evm/subgraph` run it b
 
 ## Commands
 
-| Command            | What it does                                                                                    |
-| ------------------ | ----------------------------------------------------------------------------------------------- |
-| `npm run build`    | Validate records, write `manifest.json`, regenerate the generated consumers.                    |
-| `npm run check`    | Offline validation of records, manifest and consumers. Runs in CI.                              |
-| `npm run verify`   | Re-read every deployment from its chain and compare IDs, heights and hashes. Runs weekly in CI. |
-| `npm run subgraph` | Write `evm/subgraph/subgraph.yaml` for `--network <slug>`; `--check` verifies it.               |
-| `npm test`         | Unit and end-to-end tests for the tool.                                                         |
+| Command                 | What it does                                                                                    |
+| ----------------------- | ----------------------------------------------------------------------------------------------- |
+| `npm run build`         | Validate records, write `manifest.json`, regenerate the generated consumers.                    |
+| `npm run check`         | Offline validation of records, manifest and consumers. Runs in CI.                              |
+| `npm run verify-source` | Rebuild each source-verified contract from its commit and compare artifact hashes.              |
+| `npm run attest`        | Backfill: mark a historical record source-verified once a commit reproduces it.                 |
+| `npm run verify`        | Re-read every deployment from its chain and compare IDs, heights and hashes. Runs weekly in CI. |
+| `npm run subgraph`      | Write `evm/subgraph/subgraph.yaml` for `--network <slug>`; `--check` verifies it.               |
+| `npm test`              | Unit and end-to-end tests for the tool.                                                         |

deployments/ckb/ckb-testnet.json

@@ -10,6 +10,10 @@
       "id": "0x31f6ab9c7e7a26ecba980b838ac3b5bd6c3a2f1b945e75b7cf7e6a46cb19cb87",
       "version": null,
       "sourceCommit": null,
+      "provenance": {
+        "status": "unverifiable",
+        "reason": "Historical record reconstructed from chain state; no source commit has been shown to reproduce the artifact hash."
+      },
       "artifactHash": {
         "algorithm": "blake2b-256",
         "value": "0x31f6ab9c7e7a26ecba980b838ac3b5bd6c3a2f1b945e75b7cf7e6a46cb19cb87"
@@ -34,6 +38,10 @@
       "id": "0xc133817d433f72ea16a2404adaf961524e9572c8378829a21968710d6182e20d",
       "version": null,
       "sourceCommit": null,
+      "provenance": {
+        "status": "unverifiable",
+        "reason": "Historical record reconstructed from chain state; no source commit has been shown to reproduce the artifact hash."
+      },
       "artifactHash": {
         "algorithm": "blake2b-256",
         "value": "0xc133817d433f72ea16a2404adaf961524e9572c8378829a21968710d6182e20d"

deployments/evm/horizen-testnet.json

@@ -10,6 +10,10 @@
       "id": "0x8AE65c05E7eb48B9bA652781Bc0a3DBA09A484F3",
       "version": null,
       "sourceCommit": null,
+      "provenance": {
+        "status": "unverifiable",
+        "reason": "Historical record reconstructed from chain state; no source commit has been shown to reproduce the artifact hash."
+      },
       "artifactHash": {
         "algorithm": "keccak256",
         "value": "0x9b846a07b17d019277a06764e6d0281dac81741c9a64944ede50ddc23ef10be0"
@@ -30,6 +34,10 @@
       "id": "0x953E6cEdcdfAe321796e7637d33653F6Ce05c527",
       "version": null,
       "sourceCommit": null,
+      "provenance": {
+        "status": "unverifiable",
+        "reason": "Historical record reconstructed from chain state; no source commit has been shown to reproduce the artifact hash."
+      },
       "artifactHash": {
         "algorithm": "keccak256",
         "value": "0x81d5bdf8d1ccb3ced05fde681ae45ecd6ae51dde1e368fed331eeb1684a383e2"

deployments/manifest.json

@@ -14,6 +14,10 @@
           "id": "0x8AE65c05E7eb48B9bA652781Bc0a3DBA09A484F3",
           "version": null,
           "sourceCommit": null,
+          "provenance": {
+            "status": "unverifiable",
+            "reason": "Historical record reconstructed from chain state; no source commit has been shown to reproduce the artifact hash."
+          },
           "artifactHash": {
             "algorithm": "keccak256",
             "value": "0x9b846a07b17d019277a06764e6d0281dac81741c9a64944ede50ddc23ef10be0"
@@ -34,6 +38,10 @@
           "id": "0x953E6cEdcdfAe321796e7637d33653F6Ce05c527",
           "version": null,
           "sourceCommit": null,
+          "provenance": {
+            "status": "unverifiable",
+            "reason": "Historical record reconstructed from chain state; no source commit has been shown to reproduce the artifact hash."
+          },
           "artifactHash": {
             "algorithm": "keccak256",
             "value": "0x81d5bdf8d1ccb3ced05fde681ae45ecd6ae51dde1e368fed331eeb1684a383e2"
@@ -63,6 +71,10 @@
           "id": "9Ko7TuXHpLUH1ZsZWQEpeA9Tv7hX325ooWk5SD7Y9nuq",
           "version": null,
           "sourceCommit": null,
+          "provenance": {
+            "status": "unverifiable",
+            "reason": "Historical record reconstructed from chain state; no source commit has been shown to reproduce the artifact hash."
+          },
           "artifactHash": {
             "algorithm": "sha256",
             "value": "0x2be5d2b1e9d08926ab515829c7f72b16367f59a8b0fd4241318762dd184dec67"
@@ -83,6 +95,10 @@
           "id": "E6J7GBSTjKbYANWjfTo5HfnXZ4Tg3LAasN7NrvCwn5Dq",
           "version": null,
           "sourceCommit": null,
+          "provenance": {
+            "status": "unverifiable",
+            "reason": "Historical record reconstructed from chain state; no source commit has been shown to reproduce the artifact hash."
+          },
           "artifactHash": {
             "algorithm": "sha256",
             "value": "0xc77d61231a088a54ac6be18ea21b20f10d48c3b47e890bda517ee8e059a593b9"
@@ -103,6 +119,10 @@
           "id": "4JrrQh5aK7iLvx6MgtEQk7K7X3SsWfTLxVJu1jXEwNjD",
           "version": null,
           "sourceCommit": null,
+          "provenance": {
+            "status": "unverifiable",
+            "reason": "Historical record reconstructed from chain state; no source commit has been shown to reproduce the artifact hash."
+          },
           "artifactHash": {
             "algorithm": "sha256",
             "value": "0x2583b2cd9cfa7dafd4a1710f61654b34796ef1932bde1c4f44f706d3821a0ea4"
@@ -132,6 +152,10 @@
           "id": "0x31f6ab9c7e7a26ecba980b838ac3b5bd6c3a2f1b945e75b7cf7e6a46cb19cb87",
           "version": null,
           "sourceCommit": null,
+          "provenance": {
+            "status": "unverifiable",
+            "reason": "Historical record reconstructed from chain state; no source commit has been shown to reproduce the artifact hash."
+          },
           "artifactHash": {
             "algorithm": "blake2b-256",
             "value": "0x31f6ab9c7e7a26ecba980b838ac3b5bd6c3a2f1b945e75b7cf7e6a46cb19cb87"
@@ -156,6 +180,10 @@
           "id": "0xc133817d433f72ea16a2404adaf961524e9572c8378829a21968710d6182e20d",
           "version": null,
           "sourceCommit": null,
+          "provenance": {
+            "status": "unverifiable",
+            "reason": "Historical record reconstructed from chain state; no source commit has been shown to reproduce the artifact hash."
+          },
           "artifactHash": {
             "algorithm": "blake2b-256",
             "value": "0xc133817d433f72ea16a2404adaf961524e9572c8378829a21968710d6182e20d"

deployments/schema/v1.json

@@ -104,9 +104,19 @@
           "pattern": "^\\d+\\.\\d+\\.\\d+([-+][0-9A-Za-z.-]+)?$"
         },
         "sourceCommit": {
-          "description": "Git commit the artifact was built from, or null if unknown.",
+          "description": "Full 40-hex git commit the artifact was built from, or null if unknown. Non-null only together with provenance.status source-verified.",
           "oneOf": [{ "$ref": "#/$defs/commit" }, { "type": "null" }]
         },
+        "provenance": {
+          "description": "Whether sourceCommit is proven. source-verified: building sourceCommit reproduces artifactHash (checked by `verify-source`). unverifiable: a historical record whose source commit cannot be proven; sourceCommit is null and reason says why. Required on every first-party (non-external) contract; enforced by the manifest tool.",
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["status"],
+          "properties": {
+            "status": { "enum": ["source-verified", "unverifiable"] },
+            "reason": { "type": "string", "minLength": 1 }
+          }
+        },
         "external": {
           "description": "True for third-party code Wraith depends on but does not build (e.g. ckb-auth).",
           "type": "boolean"

deployments/solana/solana-devnet.json

@@ -10,6 +10,10 @@
       "id": "9Ko7TuXHpLUH1ZsZWQEpeA9Tv7hX325ooWk5SD7Y9nuq",
       "version": null,
       "sourceCommit": null,
+      "provenance": {
+        "status": "unverifiable",
+        "reason": "Historical record reconstructed from chain state; no source commit has been shown to reproduce the artifact hash."
+      },
       "artifactHash": {
         "algorithm": "sha256",
         "value": "0x2be5d2b1e9d08926ab515829c7f72b16367f59a8b0fd4241318762dd184dec67"
@@ -30,6 +34,10 @@
       "id": "E6J7GBSTjKbYANWjfTo5HfnXZ4Tg3LAasN7NrvCwn5Dq",
       "version": null,
       "sourceCommit": null,
+      "provenance": {
+        "status": "unverifiable",
+        "reason": "Historical record reconstructed from chain state; no source commit has been shown to reproduce the artifact hash."
+      },
       "artifactHash": {
         "algorithm": "sha256",
         "value": "0xc77d61231a088a54ac6be18ea21b20f10d48c3b47e890bda517ee8e059a593b9"
@@ -50,6 +58,10 @@
       "id": "4JrrQh5aK7iLvx6MgtEQk7K7X3SsWfTLxVJu1jXEwNjD",
       "version": null,
       "sourceCommit": null,
+      "provenance": {
+        "status": "unverifiable",
+        "reason": "Historical record reconstructed from chain state; no source commit has been shown to reproduce the artifact hash."
+      },
       "artifactHash": {
         "algorithm": "sha256",
         "value": "0x2583b2cd9cfa7dafd4a1710f61654b34796ef1932bde1c4f44f706d3821a0ea4"

scripts/deployment-manifest/package.json

@@ -12,6 +12,8 @@
     "check": "tsx src/cli.ts check",
     "verify": "tsx src/cli.ts verify",
     "record": "tsx src/cli.ts record",
+    "verify-source": "tsx src/cli.ts verify-source",
+    "attest": "tsx src/cli.ts attest",
     "subgraph": "tsx src/cli.ts subgraph",
     "typecheck": "tsc --noEmit",
     "test": "vitest run"