feat(docs): add multichain contract reference drift check #160

.github/workflows/snippets.yml

@@ -70,6 +70,30 @@ jobs:
       - name: Check nav coverage
         run: pnpm run check:nav-coverage
 
+  contract-reference:
+    name: Contract reference drift check
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 10
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Verify contract references match the checked-in specs
+        run: pnpm run check:contract-reference
+
       - name: Check contract registry
         run: pnpm run check:contract-registry
 

contracts/ckb.mdx

@@ -5,6 +5,79 @@ description: "Lock script specs and the Cell model for stealth addresses on Nerv
 
 CKB scripts (smart contracts) for stealth address operations on the Nervos CKB network. Written in Rust and compiled to RISC-V binaries that run on CKB-VM.
 
+{/* ckb-reference:start */}
+
+<!-- Generated by scripts/generate-contract-reference.ts from contracts/specs. Do not edit by hand. -->
+
+- **Spec version:** 1
+- **API snapshot version:** 1
+- **Source:** `wraith-protocol/contracts/ckb/scripts` @ `0000000000000000000000000000000000000000`
+- **Contracts:** 3
+- **Removed in this version:** none
+
+## Generated contract reference
+
+### wraith-stealth-lock
+
+- **Code hash:** `0x0000000000000000000000000000000000000000000000000000000000000000`
+- **Type script:** `0x0000000000000000000000000000000000000000000000000000000000000000`
+
+- **Source kind:** `ckb-script`
+- **Public methods:** 1
+- **Errors:** 2
+
+| Method | Params | Returns | Auth required |
+|---|---|---|---|
+| `lock` | `amount: Amount`<br />`lock_args: Bytes` | `ScriptOutput` | No |
+
+| Type | Fields |
+|---|---|
+| `LockArgs` | `stealth_lock_hash: H256`<br />`scheme_id: Uint8`<br />`ephemeral_pubkey: Bytes`<br />`view_tag: Bytes` |
+
+```
+  AmountZero
+  InvalidArgs
+```
+
+### wraith-stealth-unlock
+
+- **Code hash:** `0x0000000000000000000000000000000000000000000000000000000000000000`
+- **Type script:** `0x0000000000000000000000000000000000000000000000000000000000000000`
+
+- **Source kind:** `ckb-script`
+- **Public methods:** 1
+- **Errors:** 2
+
+| Method | Params | Returns | Auth required |
+|---|---|---|---|
+| `unlock` | `unlock_args: Bytes` | `ScriptOutput` | Yes |
+
+| Type | Fields |
+|---|---|
+| `UnlockArgs` | `stealth_unlock_info: Bytes`<br />`amount: Amount` |
+
+```
+  InvalidArgs
+  LockNotFound
+```
+
+### wraith-stealth-scan
+
+- **Code hash:** `0x0000000000000000000000000000000000000000000000000000000000000000`
+- **Type script:** `0x0000000000000000000000000000000000000000000000000000000000000000`
+
+- **Source kind:** `ckb-script`
+- **Public methods:** 1
+- **Errors:** 0
+
+| Method | Params | Returns | Auth required |
+|---|---|---|---|
+| `scan` | `view_tag: Bytes` | `Option<CellData>` | No |
+
+No custom errors declared.
+
+{/* ckb-reference:end */}
+
 ## The Cell Model — Why CKB Is Different
 
 CKB uses a UTXO-based **Cell model**, not accounts. Every piece of on-chain state is a Cell:

contracts/evm.mdx

@@ -5,6 +5,111 @@ description: "Solidity contract specs and deployment"
 
 Solidity smart contracts for stealth address operations on EVM-compatible chains. Four contracts are deployed per chain.
 
+{/* evm-reference:start */}
+
+<!-- Generated by scripts/generate-contract-reference.ts from contracts/specs. Do not edit by hand. -->
+
+- **Spec version:** 1
+- **API snapshot version:** 1
+- **Source:** `wraith-protocol/contracts/evm/src` @ `0000000000000000000000000000000000000000`
+- **Contracts:** 5
+- **Removed in this version:** none
+
+## Generated contract reference
+
+### ERC5564Announcer
+
+- **Source kind:** `solidity`
+- **Public methods:** 1
+- **Errors:** 0
+
+| Method | Params | Returns | Auth required |
+|---|---|---|---|
+| `announce` | `schemeId: uint256`<br />`stealthAddress: address`<br />`ephemeralPubKey: bytes`<br />`metadata: bytes` | None | No |
+
+| Event | Fields |
+|---|---|
+| `Announcement` | `schemeId: uint256 (indexed)`<br />`stealthAddress: address (indexed)`<br />`caller: address (indexed)`<br />`ephemeralPubKey: bytes`<br />`metadata: bytes` |
+
+No custom errors declared.
+
+### ERC6538Registry
+
+- **Source kind:** `solidity`
+- **Public methods:** 4
+- **Errors:** 3
+
+| Method | Params | Returns | Auth required |
+|---|---|---|---|
+| `register` | `_uint160: uint160`<br />`keys: bytes32[2]`<br />`prefix: uint8` | None | Yes |
+| `stealthMetaAddressOf` | `stealthAddress: uint160` | `_: uint160` | No |
+| `keysOf` | `metaAddress: uint160` | `_: bytes32[2]` | No |
+| `prefixOf` | `metaAddress: uint160` | `_: uint8` | No |
+
+| Event | Fields |
+|---|---|
+| `Registered` | `uint160: uint160 (indexed)`<br />`keys: bytes32[2]`<br />`prefix: uint8` |
+| `Updated` | `uint160: uint160 (indexed)`<br />`keys: bytes32[2]`<br />`prefix: uint8` |
+
+```
+  DuplicateEntry()
+  IndexOutOfBounds()
+  ZeroIndex()
+```
+
+### WraithSender
+
+- **Source kind:** `solidity`
+- **Public methods:** 2
+- **Errors:** 4
+
+| Method | Params | Returns | Auth required |
+|---|---|---|---|
+| `sendAndAnnounce` | `schemeId: uint256`<br />`recipient: address`<br />`amount: uint256`<br />`token: address`<br />`ephemeralPubKey: bytes`<br />`metadata: bytes` | None | Yes |
+| `batchSendAndAnnounce` | `schemeId: uint256`<br />`recipients: address[]`<br />`amounts: uint256[]`<br />`token: address`<br />`ephemeralPubKeys: bytes[]`<br />`metadatas: bytes[]` | None | Yes |
+
+```
+  LengthMismatch()
+  AmountZero()
+  InsufficientBalance()
+  TransferFailed()
+```
+
+### WraithNames
+
+- **Source kind:** `solidity`
+- **Public methods:** 3
+- **Errors:** 3
+
+| Method | Params | Returns | Auth required |
+|---|---|---|---|
+| `register` | `name: string`<br />`keyX: bytes32`<br />`keyY: bytes32` | None | Yes |
+| `resolve` | `name: string` | `_: bytes32[2]` | No |
+| `transfer` | `name: string`<br />`to: address` | None | Yes |
+
+```
+  AlreadyRegistered()
+  NotFound()
+  Unauthorized()
+```
+
+### WraithWithdrawer
+
+- **Source kind:** `solidity`
+- **Public methods:** 1
+- **Errors:** 2
+
+| Method | Params | Returns | Auth required |
+|---|---|---|---|
+| `withdraw` | `stealthAddress: address`<br />`amount: uint256`<br />`token: address` | None | Yes |
+
+```
+  NotAuthorized()
+  TransferFailed()
+```
+
+{/* evm-reference:end */}
+
 ## Contract Set
 
 | Contract | Purpose |

contracts/solana.mdx

@@ -5,6 +5,72 @@ description: "Anchor program specs and deployment"
 
 Solana programs (smart contracts) for stealth address operations, written in Rust with the Anchor framework.
 
+{/* solana-reference:start */}
+
+<!-- Generated by scripts/generate-contract-reference.ts from contracts/specs. Do not edit by hand. -->
+
+- **Spec version:** 1
+- **API snapshot version:** 1
+- **Source:** `wraith-protocol/contracts/solana/programs` @ `0000000000000000000000000000000000000000`
+- **Contracts:** 3
+- **Removed in this version:** none
+
+## Generated contract reference
+
+### wraith-announcer
+
+- **Source kind:** `anchor`
+- **Public methods:** 1
+- **Errors:** 0
+
+| Method | Params | Returns | Auth required |
+|---|---|---|---|
+| `announce` | `scheme_id: u32`<br />`stealth_address: Pubkey`<br />`ephemeral_pub_key: [u8; 32]`<br />`metadata: Vec<u8>` | `()` | Yes |
+
+| Event | Fields |
+|---|---|
+| `AnnouncementEvent` | `scheme_id: u32`<br />`stealth_address: Pubkey`<br />`caller: Pubkey`<br />`ephemeral_pub_key: [u8; 32]`<br />`metadata: Vec<u8>` |
+
+No custom errors declared.
+
+### wraith-sender
+
+- **Source kind:** `anchor`
+- **Public methods:** 2
+- **Errors:** 4
+
+| Method | Params | Returns | Auth required |
+|---|---|---|---|
+| `send_and_announce` | `scheme_id: u32`<br />`stealth_address: Pubkey`<br />`amount: u64`<br />`ephemeral_pub_key: [u8; 32]`<br />`metadata: Vec<u8>` | `()` | Yes |
+| `batch_send_and_announce` | `scheme_id: u32`<br />`stealth_addresses: Vec<Pubkey>`<br />`amounts: Vec<u64>`<br />`ephemeral_pub_keys: Vec<[u8; 32]>`<br />`metadatas: Vec<Vec<u8>>` | `()` | Yes |
+
+```
+  LengthMismatch
+  AmountZero
+  InsufficientBalance
+  TransferFailed
+```
+
+### wraith-names
+
+- **Source kind:** `anchor`
+- **Public methods:** 3
+- **Errors:** 3
+
+| Method | Params | Returns | Auth required |
+|---|---|---|---|
+| `register` | `name: String`<br />`key_x: [u8; 32]`<br />`key_y: [u8; 32]` | `()` | Yes |
+| `resolve` | `name: String` | `[u8; 64]` | No |
+| `transfer` | `name: String`<br />`to: Pubkey` | `()` | Yes |
+
+```
+  AlreadyRegistered
+  NotFound
+  Unauthorized
+```
+
+{/* solana-reference:end */}
+
 ## Program Set
 
 | Program | Purpose |