feat(sdk): compatibility validation harness adapter-based integrations + documentations - v1

examples/compatibility-harness/.env.example

@@ -0,0 +1,122 @@
+# ══════════════════════════════════════════════════════════════════════════════
+#  Zama Compatibility Harness — Environment Configuration
+# ══════════════════════════════════════════════════════════════════════════════
+#
+#  Copy this file to .env and fill in the values for your adapter.
+#
+#  Only ONE section is needed depending on the adapter you run:
+#    • Built-in EOA adapter (default src/adapter/index.ts)  →  set PRIVATE_KEY
+#    • Crossmint adapter (SIGNER_MODULE=./examples/crossmint/signer.ts)
+#                                                         →  set CROSSMINT_* vars
+#    • Turnkey adapter (SIGNER_MODULE=./examples/turnkey/signer.ts)
+#                                                         →  set TURNKEY_* vars
+#    • Openfort baseline adapter (SIGNER_MODULE=./examples/openfort/signer.ts)
+#                                                         →  set OPENFORT_* vars
+#    • Custom adapter module                               →  set whatever it needs
+#
+
+# ── Built-in EOA Adapter ──────────────────────────────────────────────────────
+#
+#  Only needed when using the built-in adapter (default test path).
+#  Not required when using a custom module through SIGNER_MODULE.
+#
+#  The account must hold Sepolia ETH for the Transaction Execution test.
+#  Faucets: https://sepoliafaucet.com  |  https://faucet.alchemy.com/faucets/ethereum-sepolia
+#
+PRIVATE_KEY=0x
+
+# ── Crossmint MPC Adapter ─────────────────────────────────────────────────────
+#
+#  Only needed when running:
+#    SIGNER_MODULE=./examples/crossmint/signer.ts npm test
+#  See examples/crossmint/COMPATIBILITY.md for setup details.
+#
+# CROSSMINT_API_KEY=your_server_side_api_key
+#
+# Wallet locator — one of:
+#   email:alice@example.com:evm-smart-wallet
+#   userId:abc123:evm-smart-wallet
+#   phoneNumber:+1234567890:evm-smart-wallet
+# CROSSMINT_WALLET_LOCATOR=email:alice@example.com:evm-smart-wallet
+#
+# Optional: supply the wallet 0x address directly to skip the API lookup at startup.
+# If omitted, the address is resolved via GET /wallets/{locator} before tests run.
+# CROSSMINT_WALLET_ADDRESS=0x
+
+# ── Turnkey API Key Adapter ───────────────────────────────────────────────────
+#
+#  Only needed when running:
+#    SIGNER_MODULE=./examples/turnkey/signer.ts npm test
+#  See examples/turnkey/COMPATIBILITY.md for setup details.
+#
+# Required:
+# TURNKEY_ORG_ID=...
+# TURNKEY_PRIVATE_KEY_ID=...
+# TURNKEY_API_PUBLIC_KEY=...
+# TURNKEY_API_PRIVATE_KEY=...
+#
+# Optional:
+# TURNKEY_WALLET_ADDRESS=0x...
+# TURNKEY_BASE_URL=https://api.turnkey.com
+# TURNKEY_RPC_URL=https://eth-sepolia.g.alchemy.com/v2/YOUR_KEY
+
+# ── Openfort EOA Baseline Adapter ─────────────────────────────────────────────
+#
+#  Only needed when running:
+#    SIGNER_MODULE=./examples/openfort/signer.ts npm test
+#  See examples/openfort/COMPATIBILITY.md for scope and caveats.
+#
+# OPENFORT_TEST_PRIVATE_KEY=0x...
+#
+# Optional: adapter-specific RPC override (defaults to RPC_URL)
+# OPENFORT_RPC_URL=https://eth-sepolia.g.alchemy.com/v2/YOUR_KEY
+
+# ── Network ───────────────────────────────────────────────────────────────────
+#
+# Profile selector:
+# - sepolia (default)
+# - mainnet (requires explicit RELAYER_URL)
+#
+# NETWORK_PROFILE=sepolia
+#
+#  Sepolia JSON-RPC endpoint. Defaults to a public endpoint.
+#  Override with Infura / Alchemy for better reliability.
+#
+# RPC_URL=https://ethereum-sepolia-rpc.publicnode.com
+
+# ── Relayer ───────────────────────────────────────────────────────────────────
+#
+#  Zama relayer base URL. Defaults to the public Sepolia testnet relayer.
+#  Override for a private or mainnet relayer.
+#
+# RELAYER_URL=https://relayer.testnet.zama.org/v2
+#
+#  API key forwarded as x-api-key. Not required for the public Sepolia relayer.
+#  Required for mainnet or private relayers.
+#
+# RELAYER_API_KEY=
+
+# ── Reporting ─────────────────────────────────────────────────────────────────
+#
+# Optional machine-readable report artifact path.
+# Example:
+# REPORT_JSON_PATH=./reports/latest.json
+#
+# REPORT_JSON_PATH=
+
+# ── Harness Runtime ──────────────────────────────────────────────────────────
+#
+# Deterministic local mode:
+# - disables network/relayer/registry-dependent validations in the test suite
+# - marks those checks as UNTESTED with explicit rationale
+#
+# HARNESS_MOCK_MODE=1
+
+# ── Validation Gate Policy (optional) ────────────────────────────────────────
+#
+# Use with `npm run validate`:
+# - policy file path (JSON), see ./validation-policy.example.json
+# - optional env override to accept PARTIAL outcomes as pass
+#
+# VALIDATION_POLICY_PATH=./validation-policy.example.json
+# VALIDATION_ALLOW_PARTIAL=false

examples/compatibility-harness/.github/workflows/compatibility-harness-ci.yml

@@ -0,0 +1,46 @@
+name: Compatibility Harness CI
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Typecheck
+        run: npm run typecheck
+
+      - name: Test (deterministic mock mode)
+        env:
+          HARNESS_MOCK_MODE: "1"
+        run: npm test
+
+      - name: Validate gate (deterministic mock mode)
+        env:
+          HARNESS_MOCK_MODE: "1"
+        run: |
+          set +e
+          npm run validate
+          status=$?
+          echo "validate exit code: $status"
+          # In deterministic mock mode, authorization is untested by design.
+          # Accept PASS(0), PARTIAL(10), INCONCLUSIVE(30) as non-regression outcomes.
+          if [ "$status" -eq 0 ] || [ "$status" -eq 10 ] || [ "$status" -eq 30 ]; then
+            exit 0
+          fi
+          exit "$status"

examples/compatibility-harness/.github/workflows/compatibility-harness-live.yml

@@ -0,0 +1,79 @@
+name: Compatibility Harness Live (Optional)
+
+on:
+  workflow_dispatch:
+    inputs:
+      signer_module:
+        description: "Adapter module path (optional)"
+        required: false
+        type: string
+      validation_target:
+        description: "Validation target"
+        required: false
+        default: AUTHORIZATION_AND_WRITE
+        type: choice
+        options:
+          - AUTHORIZATION
+          - AUTHORIZATION_AND_WRITE
+  schedule:
+    - cron: "0 3 * * *"
+
+jobs:
+  live-validate:
+    name: Live Validate (Non-Blocking)
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    continue-on-error: true
+    env:
+      PRIVATE_KEY: ${{ secrets.HARNESS_PRIVATE_KEY }}
+      RPC_URL: ${{ secrets.HARNESS_RPC_URL }}
+      RELAYER_URL: ${{ secrets.HARNESS_RELAYER_URL }}
+      RELAYER_API_KEY: ${{ secrets.HARNESS_RELAYER_API_KEY }}
+      NETWORK_PROFILE: ${{ secrets.HARNESS_NETWORK_PROFILE }}
+      REPORT_JSON_PATH: reports/live/latest-report.json
+      VALIDATION_TARGET: ${{ github.event.inputs.validation_target || 'AUTHORIZATION_AND_WRITE' }}
+      SIGNER_MODULE: ${{ github.event.inputs.signer_module }}
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Typecheck
+        run: npm run typecheck
+
+      - name: Run live validation (capture exit code)
+        id: live_validate
+        run: |
+          mkdir -p reports/live
+          set +e
+          npm run validate 2>&1 | tee reports/live/validate.log
+          status=${PIPESTATUS[0]}
+          echo "$status" > reports/live/validate.exitcode
+          echo "exit_code=$status" >> "$GITHUB_OUTPUT"
+          exit 0
+
+      - name: Upload live artifacts
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: compatibility-harness-live-${{ github.run_id }}
+          path: reports/live
+          if-no-files-found: warn
+
+      - name: Publish run summary
+        if: always()
+        run: |
+          echo "## Compatibility Harness Live Run" >> "$GITHUB_STEP_SUMMARY"
+          echo "" >> "$GITHUB_STEP_SUMMARY"
+          echo "- Non-blocking: yes (continue-on-error job)" >> "$GITHUB_STEP_SUMMARY"
+          echo "- validate exit code: ${{ steps.live_validate.outputs.exit_code }}" >> "$GITHUB_STEP_SUMMARY"
+          echo "- Artifact: compatibility-harness-live-${{ github.run_id }}" >> "$GITHUB_STEP_SUMMARY"

examples/compatibility-harness/.gitignore

@@ -0,0 +1,4 @@
+node_modules/
+dist/
+.env
+reports/