feat(withdrawal): add canonical Base-to-Nockchain codec

.github/workflows/ci.yml

@@ -17,7 +17,7 @@ jobs:
       - name: Setup Node.js
         uses: actions/setup-node@v4
         with:
-          node-version: '20'
+          node-version: '22'
           cache: 'npm'
 
       - name: Install dependencies
@@ -26,6 +26,9 @@ jobs:
       - name: TypeScript compilation check
         run: npm run typecheck
 
+      - name: Withdrawal protocol vectors
+        run: npm test
+
       - name: Format check
         run: npm run format:check
 

README.md

@@ -23,3 +23,49 @@ The current provider API is version 1. Legacy API 0 transaction signing remains
 supported through the compatibility mapper. Optional transaction notes remain in
 the request type so existing dApps and API 0 wallets can interoperate, but their
 security status is explicitly advisory.
+
+## Base to Nockchain withdrawals
+
+Version 0.3 adds the canonical retained-contract `WithdrawalWireV1` codec.
+Official clients must use this codec instead of calling
+`burn(uint256,bytes32)` through a generated ABI helper.
+
+```ts
+import { encodeWithdrawalWireV1, validateWithdrawalWireV1 } from '@nockbox/iris-sdk';
+
+const encoded = encodeWithdrawalWireV1({
+  nockTokenAddress: '0x1111111111111111111111111111111111111111',
+  burnerAddress: connectedAccount,
+  amountBaseUnits: 1_000_000_000_000_000_000_000n,
+  lockRootLimbs: [1n, 2n, 3n, 4n, 5n],
+});
+
+// Use encoded.calldata unchanged for simulation, gas estimation, and sending.
+validateWithdrawalWireV1(encoded.calldata, {
+  nockTokenAddress: encoded.nockTokenAddress,
+  burnerAddress: encoded.burnerAddress,
+  amountBaseUnits: encoded.amountBaseUnits,
+  lockRootLimbs: encoded.lockRootLimbs,
+});
+```
+
+The codec:
+
+- returns exactly 116 calldata bytes
+- binds token, connected burner, exact bigint amount, and five Tip5 limbs
+- locally decodes and validates the final bytes before returning
+- enforces `withdrawal-policy-v1` amount divisibility and inclusive
+  100,000-NOCK minimum
+- throws typed `WithdrawalWireError` values for malformed or stale requests
+
+Changing account, chain, token, amount, or destination invalidates previously
+constructed calldata. The application must rebuild before simulation or
+submission.
+
+An ordinary 68-byte generated-ABI burn is unsupported even though the retained
+contract accepts it. It omits the full destination and can burn funds without a
+processable withdrawal.
+
+The published package includes
+`test-fixtures/withdrawal_wire_v1_vectors.json`, sourced from the canonical Rust
+bridge fixture. SDK consumers can use it to verify byte-for-byte compatibility.