@void-layer/codec 0.1.0 — pre-release: invoice codec, types & networks (Phase 1-3)

.changeset/config.json

@@ -0,0 +1,11 @@
+{
+  "$schema": "https://unpkg.com/@changesets/config@3.0.0/schema.json",
+  "changelog": "@changesets/cli/changelog",
+  "commit": false,
+  "fixed": [],
+  "linked": [],
+  "access": "public",
+  "baseBranch": "main",
+  "updateInternalDependencies": "patch",
+  "ignore": []
+}

.changeset/initial-release-0-1-0.md

@@ -0,0 +1,11 @@
+---
+"@void-layer/codec": minor
+"@void-layer/types": minor
+"@void-layer/networks": minor
+---
+
+Initial 0.1.0 release of the @void-layer monorepo.
+
+- `@void-layer/codec`: Canonical TLV + Brotli wire codec (WASM + JS shim). Includes `encodeInvoiceCanonical`, `decodeInvoiceCanonical`, `encodeInvoiceWire`, `decodeInvoiceWire`, and `receiptHash` (keccak-256 content hash). 18 golden vectors in v4-codec.json schema_version=1.
+- `@void-layer/types`: TypeScript type definitions for Invoice, InvoiceItem, InvoiceFrom, InvoiceClient, NetworkConfig, ChainId, FrameContext, FrameState, PaymentProof, PaymentRequiredResponse. Zero runtime dependencies.
+- `@void-layer/networks`: Chain configs for 5 EVM networks (Ethereum, Base, Arbitrum, Optimism, Polygon) with public RPC URLs. `SUPPORTED_TOKENS` is empty at 0.1.0 (@alpha — populated in a future release from Uniswap Token List).

.editorconfig

@@ -0,0 +1,15 @@
+root = true
+
+[*]
+end_of_line = lf
+charset = utf-8
+indent_style = space
+indent_size = 2
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[*.rs]
+indent_size = 4
+
+[*.md]
+trim_trailing_whitespace = false

.github/CODEOWNERS

@@ -0,0 +1,4 @@
+# Default owner for everything
+* @ignromanov
+
+# Phase 3+: add @void-layer/maintainers when team formed

.github/dependabot.yml

@@ -0,0 +1,21 @@
+version: 2
+updates:
+  - package-ecosystem: "npm"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 5
+    groups:
+      changesets:
+        patterns: ["@changesets/*"]
+      typescript:
+        patterns: ["typescript", "@types/*"]
+  - package-ecosystem: "cargo"
+    directory: "/packages/codec"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 3
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"

.github/workflows/ci.yml

@@ -0,0 +1,152 @@
+name: CI
+on:
+  pull_request:
+  push:
+    branches: [main]
+permissions:
+  contents: read
+jobs:
+  lint-and-build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5      # v4
+      - uses: pnpm/action-setup@f40ffcd9367d9f12939873eb1018b921a783ffaa     # v4
+        with: { version: 10.24.0 }
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020    # v4
+        with: { node-version: 24, cache: pnpm }
+      - uses: actions-rust-lang/setup-rust-toolchain@46268bd060767258de96ed93c1251119784f2ab6  # v1
+        with: { rustflags: "" }
+      - uses: Swatinem/rust-cache@42dc69e1aa15d09112580998cf2ef0119e2e91ae   # v2
+      - run: rustup target add wasm32-unknown-unknown
+      - name: Install wasm-pack 0.14.0
+        run: cargo install wasm-pack --version 0.14.0 --locked
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm -r build
+      - run: pnpm -r lint
+      - run: pnpm -r test
+      - run: cargo build --manifest-path packages/codec/Cargo.toml --release
+      - run: cargo test --manifest-path packages/codec/Cargo.toml
+      - name: Assert size budgets
+        run: bash scripts/assert-size.sh
+        working-directory: packages/codec
+      - run: |
+          for dir in packages/codec packages/types packages/networks; do
+            (cd "$dir" && npm pack --dry-run)
+          done
+  vector-parity:
+    needs: [lint-and-build]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5      # v4
+      - uses: pnpm/action-setup@f40ffcd9367d9f12939873eb1018b921a783ffaa     # v4
+        with: { version: 10.24.0 }
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020    # v4
+        with: { node-version: 24, cache: pnpm }
+      - uses: actions-rust-lang/setup-rust-toolchain@46268bd060767258de96ed93c1251119784f2ab6  # v1
+        with: { rustflags: "" }
+      - uses: Swatinem/rust-cache@42dc69e1aa15d09112580998cf2ef0119e2e91ae   # v2
+      - run: rustup target add wasm32-unknown-unknown
+      - name: Install wasm-pack 0.14.0
+        run: cargo install wasm-pack --version 0.14.0 --locked
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm -r build
+      - name: TS/JS parity (vitest)
+        run: pnpm -C packages/codec exec vitest run tests/parity.test.ts --coverage.enabled=false
+      - name: Rust parity (cargo)
+        run: cargo test --manifest-path packages/codec/Cargo.toml --test parity_roundtrip --test parity_malformed
+  ts-rust-parity:
+    # Requires VOIDPAY_READ_TOKEN secret (fine-grained PAT: contents:read on ignromanov/voidpay).
+    # Skipped automatically on fork PRs where the secret is absent.
+    # To enable: set vars.TS_RUST_PARITY_ENABLED=true AND add secret VOIDPAY_READ_TOKEN in repo Settings.
+    needs: [lint-and-build]
+    runs-on: ubuntu-latest
+    if: ${{ vars.TS_RUST_PARITY_ENABLED == 'true' }}
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5      # v4
+      - name: Checkout vl/app at pinned SHA (sparse — codec files only)
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5      # v4
+        with:
+          repository: ignromanov/voidpay
+          ref: e4926b7f7b08ca4f72b707df8796bfd4a4b0a3b3
+          token: ${{ secrets.VOIDPAY_READ_TOKEN }}
+          path: vl-app
+          sparse-checkout: |
+            src/features/invoice-codec
+            src/shared/lib/tlv-codec
+      - uses: pnpm/action-setup@f40ffcd9367d9f12939873eb1018b921a783ffaa     # v4
+        with: { version: 10.24.0 }
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020    # v4
+        with: { node-version: 24, cache: pnpm }
+      - uses: actions-rust-lang/setup-rust-toolchain@46268bd060767258de96ed93c1251119784f2ab6  # v1
+        with: { rustflags: "" }
+      - uses: Swatinem/rust-cache@42dc69e1aa15d09112580998cf2ef0119e2e91ae   # v2
+      - run: rustup target add wasm32-unknown-unknown
+      - name: Install wasm-pack 0.14.0
+        run: cargo install wasm-pack --version 0.14.0 --locked
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm -r build
+      - name: Run cross-impl parity (Rust WASM vs TS reference)
+        run: VL_APP_PATH=${{ github.workspace }}/vl-app pnpm -C packages/codec run test:ts-rust-parity
+  macos-sanity:
+    runs-on: macos-latest
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5      # v4
+      - uses: actions-rust-lang/setup-rust-toolchain@46268bd060767258de96ed93c1251119784f2ab6  # v1
+      - uses: Swatinem/rust-cache@42dc69e1aa15d09112580998cf2ef0119e2e91ae   # v2
+      - run: cargo test --manifest-path packages/codec/Cargo.toml
+  test-wasm-node:
+    needs: [lint-and-build]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5      # v4
+      - uses: actions-rust-lang/setup-rust-toolchain@46268bd060767258de96ed93c1251119784f2ab6  # v1
+        with: { rustflags: "" }
+      - uses: Swatinem/rust-cache@42dc69e1aa15d09112580998cf2ef0119e2e91ae   # v2
+      - run: rustup target add wasm32-unknown-unknown
+      - name: Install wasm-pack 0.14.0
+        run: cargo install wasm-pack --version 0.14.0 --locked
+      - name: Run wasm-pack test --node (AC-9 boundary tests)
+        run: wasm-pack test --node packages/codec
+  ci-gate:
+    # Single required branch-protection check. All non-parity jobs must succeed;
+    # ts-rust-parity may be SKIPPED only when vars.TS_RUST_PARITY_ENABLED != 'true'
+    # (opt-out for forks or repos without VOIDPAY_READ_TOKEN secret).
+    needs: [lint-and-build, macos-sanity, vector-parity, test-wasm-node, ts-rust-parity]
+    if: always()
+    runs-on: ubuntu-latest
+    steps:
+      - name: Verify required jobs (parity opt-out aware)
+        run: |
+          fail=0
+
+          check() {
+            local name=$1 result=$2
+            if [ "$result" != "success" ]; then
+              echo "❌ $name: $result"
+              fail=1
+            else
+              echo "✅ $name: $result"
+            fi
+          }
+
+          check "lint-and-build" "${{ needs.lint-and-build.result }}"
+          check "macos-sanity"   "${{ needs.macos-sanity.result }}"
+          check "vector-parity"  "${{ needs.vector-parity.result }}"
+          check "test-wasm-node" "${{ needs.test-wasm-node.result }}"
+
+          parity_result="${{ needs.ts-rust-parity.result }}"
+          parity_enabled="${{ vars.TS_RUST_PARITY_ENABLED }}"
+
+          if [ "$parity_enabled" = "true" ]; then
+            check "ts-rust-parity (enabled)" "$parity_result"
+          else
+            # opt-out path: skipped or success both acceptable
+            if [ "$parity_result" = "skipped" ] || [ "$parity_result" = "success" ]; then
+              echo "✅ ts-rust-parity ($parity_result; disabled via vars.TS_RUST_PARITY_ENABLED)"
+            else
+              echo "❌ ts-rust-parity: $parity_result"
+              fail=1
+            fi
+          fi
+
+          exit $fail

.github/workflows/release.yml

@@ -0,0 +1,26 @@
+name: Release
+on:
+  workflow_dispatch:
+permissions:
+  contents: write
+  id-token: write
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5      # v4
+      - uses: pnpm/action-setup@f40ffcd9367d9f12939873eb1018b921a783ffaa     # v4
+        with: { version: 10.24.0 }
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020    # v4
+        with: { node-version: 24, cache: pnpm, registry-url: 'https://registry.npmjs.org' }
+      - uses: actions-rust-lang/setup-rust-toolchain@46268bd060767258de96ed93c1251119784f2ab6  # v1
+        with: { rustflags: "" }
+      - uses: Swatinem/rust-cache@42dc69e1aa15d09112580998cf2ef0119e2e91ae   # v2
+      - run: rustup target add wasm32-unknown-unknown
+      - name: Install wasm-pack 0.14.0
+        run: cargo install wasm-pack --version 0.14.0 --locked
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm -r build
+      - run: pnpm changeset publish
+        env:
+          NPM_CONFIG_PROVENANCE: true

.gitignore

@@ -1,6 +1,8 @@
 node_modules/
 target/
 pkg/
+pkg-node/
+pkg-web/
 dist/
 .DS_Store
 *.log

.npmrc

@@ -0,0 +1,2 @@
+save-exact=true
+engine-strict=true

.prettierignore

@@ -0,0 +1,8 @@
+node_modules/
+dist/
+pkg/
+target/
+.changeset/
+pnpm-lock.yaml
+Cargo.lock
+*.md

.prettierrc.json

@@ -0,0 +1,10 @@
+{
+  "semi": true,
+  "singleQuote": true,
+  "trailingComma": "all",
+  "printWidth": 100,
+  "tabWidth": 2,
+  "useTabs": false,
+  "arrowParens": "always",
+  "endOfLine": "lf"
+}

CODE_OF_CONDUCT.md

@@ -0,0 +1,23 @@
+# Code of Conduct
+
+This project adopts the [Contributor Covenant version 2.1](https://www.contributor-covenant.org/version/2/1/code_of_conduct/) as its Code of Conduct.
+
+Please read the full text at the link above before contributing.
+
+## Reporting
+
+Report unacceptable behavior to **ign.romanov@gmail.com** with subject prefix `[code-of-conduct][@void-layer/codec]`.
+
+Reports are reviewed within 72 hours. Confidentiality is maintained for reporters.
+
+## Scope
+
+This Code of Conduct applies within all project spaces — GitHub issues, pull requests, discussions, and any official communication channels — and when an individual is officially representing the project.
+
+## Enforcement
+
+Maintainers may take any action deemed appropriate, including warning, temporary ban, or permanent ban from the project.
+
+## Attribution
+
+This document is a pointer to the [Contributor Covenant v2.1](https://www.contributor-covenant.org/version/2/1/code_of_conduct/), which is licensed under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/).

CONTRIBUTING.md

@@ -0,0 +1,49 @@
+# Contributing to @void-layer/codec
+
+## Dev Setup
+
+```bash
+# Requires Node >=24 and pnpm >=10
+pnpm install
+```
+
+## Making Changes
+
+Build all packages:
+```bash
+pnpm build
+```
+
+Run tests:
+```bash
+pnpm test
+```
+
+Run lint:
+```bash
+pnpm lint
+```
+
+## Releasing
+
+This repo uses [Changesets](https://github.com/changesets/changesets) for versioning.
+
+Add a changeset for any user-facing change:
+```bash
+pnpm changeset
+```
+
+Then commit the generated `.changeset/*.md` file with your PR.
+
+Maintainers run `pnpm version` to bump versions and `pnpm release` to publish.
+
+## Design Rationale
+
+See [spec 056](https://github.com/ignromanov/voidpay-ai/blob/master/ops/specs/056-void-layer-codec-extraction/spec.md).
+
+The decision to rewrite the codec from TypeScript to Rust+WASM is documented in:
+`voidpay-ai/agent-memory/advisors/decisions/2026-05-09-kai-cto-codec-rust-supersedes-ts-first.md`
+
+## Schema
+
+v1 schema is LOCKED. Old invoice URLs must decode forever. Never break existing field assignments.