denniswon/gist:1c4602859835ded307eb4ddb402c2e9c

## gistfile1.txt
 ---
  Viem vs Newton SDK — Architecture Comparison

  Where Newton SDK Already Aligns with Viem

  ┌────────────────────┬────────────────────────┬──────────────────────────────────────┬───────────┐
  │        Area        │          Viem          │              Newton SDK              │  Status   │
  ├────────────────────┼────────────────────────┼──────────────────────────────────────┼───────────┤
  │ Linter/Formatter   │ Biome                  │ Biome 1.9.4                          │ Already   │
  │                    │                        │                                      │ aligned   │
  ├────────────────────┼────────────────────────┼──────────────────────────────────────┼───────────┤
  │ Test Framework     │ Vitest                 │ Vitest 3                             │ Already   │
  │                    │                        │                                      │ aligned   │
  ├────────────────────┼────────────────────────┼──────────────────────────────────────┼───────────┤
  │ TypeScript strict  │ strict: true           │ strict: true                         │ Already   │
  │                    │                        │                                      │ aligned   │
  ├────────────────────┼────────────────────────┼──────────────────────────────────────┼───────────┤
  │ Client extension   │ client.extend(actions) │ newtonWalletClientActions() /        │ Already   │
  │ pattern            │                        │ newtonPublicClientActions()          │ aligned   │
  ├────────────────────┼────────────────────────┼──────────────────────────────────────┼───────────┤
  │ Dual CJS/ESM       │ _cjs/ + _esm/          │ dist/cjs/ + dist/es/                 │ Already   │
  │ output             │                        │                                      │ aligned   │
  ├────────────────────┼────────────────────────┼──────────────────────────────────────┼───────────┤
  │ Pre-commit hooks   │ simple-git-hooks       │ simple-git-hooks                     │ Already   │
  │                    │                        │                                      │ aligned   │
  └────────────────────┴────────────────────────┴──────────────────────────────────────┴───────────┘

  ★ Insight ─────────────────────────────────────
  Newton SDK already follows viem's core architectural pattern — the "decorator" approach where
  standalone functions are bundled into a client via .extend(). This is the most important pattern to
  get right, and it's already in place. The gaps below are about engineering rigor, not fundamental
  architecture.
  ─────────────────────────────────────────────────

  ---
  Gaps & Adoption Opportunities

  Here's what viem does that Newton SDK should consider adopting, ordered by impact:

  1. Package Exports — Broken Entries (Critical Fix)

  Problem: Newton SDK's package.json declares ./viem and ./networks export paths that have no
  corresponding source files. These will fail at import time.

  Viem pattern: 32 subpath exports, each with types/import/default conditions, all verified by publint
  in CI.

  Recommendation: Remove the broken entries or create the source files. Add publint to CI to catch this
  automatically.

  2. Tests in CI Are Disabled (Critical Fix)

  Problem: The test.yml workflow has unit tests commented out. Only 1 test file exists (privacy module,
  9 tests). No tests run on PRs.

  Viem pattern: 3-way sharded test matrix, multi-transport, multi-runtime, with 3 retries. Tests gate
  every PR merge.

  Recommendation: Uncomment the test step in CI immediately. Add tests for the AVS module (the core of
  the SDK) and policy module. Co-locate tests with source (modules/avs/avs.test.ts).

  3. Bundle Size Enforcement (High Impact)

  Problem: No bundle size tracking. The SDK pulls in @hpke/core, @noble/curves, jose, viem — these are
  heavy. No visibility into how big the SDK is for consumers.

  Viem pattern: size-limit with hard caps (85 kB total, 6.6 kB for createClient). PR comments show size
  diff.

  Recommendation: Add size-limit with a reasonable cap. The privacy module target was already set at "<
  50 kB" in the NEWT-627 spec — enforce it.

  4. Type-Level Tests (Medium Impact)

  Problem: No type-level tests. The SDK exports complex generic types (SubmitEvaluationRequestParams,
  privacy types) that could regress silently.

  Viem pattern: *.test-d.ts files with expectTypeOf assertions. Run via vitest typecheck.

  Recommendation: Add *.test-d.ts for key exported types, especially the privacy module's
  CreateSecureEnvelopeParams and the task submission params.

  5. Stale Config Cleanup (Quick Win)

  Problem: .lintstagedrc.json references eslint --fix and prettier --write — neither is installed (Biome
   replaced them). Dead config confuses contributors.

  Recommendation: Update .lintstagedrc.json to use biome check --write instead, or remove it if
  simple-git-hooks already runs pnpm lint directly.

  6. Package Validation Tooling (Medium Impact)

  Problem: No validation that the published package works correctly across CJS/ESM/types resolution.

  Viem pattern: publint + @arethetypeswrong/cli in CI. Catches broken exports, missing types, CJS/ESM
  resolution issues.

  Recommendation: Add both as dev dependencies, run in CI after build.

  7. Unused Export Detection (Medium Impact)

  Problem: No dead export detection. As the SDK grows, unused exports accumulate.

  Viem pattern: knip detects unused files, exports, and dependencies.

  Recommendation: Add knip to CI. Low effort, high signal.

  8. Multi-Version TypeScript Testing (Low-Medium Impact)

  Problem: Tests run against a single TypeScript version (5.4). SDK consumers may use different TS
  versions.

  Viem pattern: CI runs type-checking against TS 5.8.2, 5.9.3, and latest.

  Recommendation: Add a matrix of TS versions to the CI type-check step. At minimum test against the
  version shipped and latest.

  9. Changesets for Versioning (Medium Impact)

  Problem: Newton SDK uses auto for releases. It works but has less community adoption and doesn't
  generate per-PR changelogs.

  Viem pattern: Changesets — contributors describe changes in .changeset/ files, automated version PRs
  aggregate them, CHANGELOG.md is auto-generated.

  Recommendation: This is a larger migration. Consider adopting when the team grows. auto is fine for
  now but changesets scale better for OSS.

  10. Canary Packages on PRs (Already Partially There)

  Problem: Newton SDK has a canary.yml workflow but it does a full npm publish. This pollutes the npm
  registry with canary versions.

  Viem pattern: Uses pkg-pr-new which publishes to a temporary CDN — reviewers get npm install
  https://pkg.pr.new/viem@<pr> without polluting the registry.

  Recommendation: Evaluate pkg-pr-new as a cleaner alternative to npm canary publishes.

  11. Debug Log in Production (Quick Fix)

  Problem: src/index.ts line 88 has console.log('idpUrl:', idpUrl) — a debug log left in production
  code.

  Recommendation: Remove it.

  ---
  Priority Action Items

  ┌──────────┬──────────────────────────────────────────────────┬──────────┐
  │ Priority │                       Item                       │  Effort  │
  ├──────────┼──────────────────────────────────────────────────┼──────────┤
  │ P0       │ Fix broken ./viem and ./networks package exports │ 10 min   │
  ├──────────┼──────────────────────────────────────────────────┼──────────┤
  │ P0       │ Remove debug console.log in src/index.ts         │ 1 min    │
  ├──────────┼──────────────────────────────────────────────────┼──────────┤
  │ P0       │ Uncomment tests in CI (test.yml)                 │ 5 min    │
  ├──────────┼──────────────────────────────────────────────────┼──────────┤
  │ P1       │ Update stale .lintstagedrc.json to use Biome     │ 5 min    │
  ├──────────┼──────────────────────────────────────────────────┼──────────┤
  │ P1       │ Add publint to CI                                │ 30 min   │
  ├──────────┼──────────────────────────────────────────────────┼──────────┤
  │ P1       │ Add size-limit with bundle size caps             │ 1-2 hr   │
  ├──────────┼──────────────────────────────────────────────────┼──────────┤
  │ P2       │ Add tests for AVS and policy modules             │ Half day │
  ├──────────┼──────────────────────────────────────────────────┼──────────┤
  │ P2       │ Add knip for unused export detection             │ 30 min   │
  ├──────────┼──────────────────────────────────────────────────┼──────────┤
  │ P2       │ Add @arethetypeswrong/cli to CI                  │ 30 min   │
  ├──────────┼──────────────────────────────────────────────────┼──────────┤
  │ P3       │ Add type-level tests (*.test-d.ts)               │ 2-3 hr   │
  ├──────────┼──────────────────────────────────────────────────┼──────────┤
  │ P3       │ Multi-version TS testing in CI                   │ 1 hr     │
  ├──────────┼──────────────────────────────────────────────────┼──────────┤
  │ P3       │ Evaluate pkg-pr-new vs npm canary                │ Research │
  ├──────────┼──────────────────────────────────────────────────┼──────────┤
  │ P4       │ Evaluate changesets vs auto                      │ Future   │
  └──────────┴──────────────────────────────────────────────────┴──────────┘

  ★ Insight ─────────────────────────────────────
  The biggest takeaway from viem isn't any single tool — it's the defense-in-depth quality pipeline:
  publint catches broken exports, size-limit catches bloat, knip catches dead code,
  @arethetypeswrong/cli catches type resolution bugs, and multi-version TS testing catches compatibility
   regressions. Each tool is cheap to add individually, but together they form a safety net that
  prevents the kind of issues that only surface when consumers try to use the SDK.
  ─────────────────────────────────────────────────
	---
	Viem vs Newton SDK — Architecture Comparison

	Where Newton SDK Already Aligns with Viem

	┌────────────────────┬────────────────────────┬──────────────────────────────────────┬───────────┐
	│ Area │ Viem │ Newton SDK │ Status │
	├────────────────────┼────────────────────────┼──────────────────────────────────────┼───────────┤
	│ Linter/Formatter │ Biome │ Biome 1.9.4 │ Already │
	│ │ │ │ aligned │
	├────────────────────┼────────────────────────┼──────────────────────────────────────┼───────────┤
	│ Test Framework │ Vitest │ Vitest 3 │ Already │
	│ │ │ │ aligned │
	├────────────────────┼────────────────────────┼──────────────────────────────────────┼───────────┤
	│ TypeScript strict │ strict: true │ strict: true │ Already │
	│ │ │ │ aligned │
	├────────────────────┼────────────────────────┼──────────────────────────────────────┼───────────┤
	│ Client extension │ client.extend(actions) │ newtonWalletClientActions() / │ Already │
	│ pattern │ │ newtonPublicClientActions() │ aligned │
	├────────────────────┼────────────────────────┼──────────────────────────────────────┼───────────┤
	│ Dual CJS/ESM │ _cjs/ + _esm/ │ dist/cjs/ + dist/es/ │ Already │
	│ output │ │ │ aligned │
	├────────────────────┼────────────────────────┼──────────────────────────────────────┼───────────┤
	│ Pre-commit hooks │ simple-git-hooks │ simple-git-hooks │ Already │
	│ │ │ │ aligned │
	└────────────────────┴────────────────────────┴──────────────────────────────────────┴───────────┘

	★ Insight ─────────────────────────────────────
	Newton SDK already follows viem's core architectural pattern — the "decorator" approach where
	standalone functions are bundled into a client via .extend(). This is the most important pattern to
	get right, and it's already in place. The gaps below are about engineering rigor, not fundamental
	architecture.
	─────────────────────────────────────────────────

	---
	Gaps & Adoption Opportunities

	Here's what viem does that Newton SDK should consider adopting, ordered by impact:

	1. Package Exports — Broken Entries (Critical Fix)

	Problem: Newton SDK's package.json declares ./viem and ./networks export paths that have no
	corresponding source files. These will fail at import time.

	Viem pattern: 32 subpath exports, each with types/import/default conditions, all verified by publint
	in CI.

	Recommendation: Remove the broken entries or create the source files. Add publint to CI to catch this
	automatically.

	2. Tests in CI Are Disabled (Critical Fix)

	Problem: The test.yml workflow has unit tests commented out. Only 1 test file exists (privacy module,
	9 tests). No tests run on PRs.

	Viem pattern: 3-way sharded test matrix, multi-transport, multi-runtime, with 3 retries. Tests gate
	every PR merge.

	Recommendation: Uncomment the test step in CI immediately. Add tests for the AVS module (the core of
	the SDK) and policy module. Co-locate tests with source (modules/avs/avs.test.ts).

	3. Bundle Size Enforcement (High Impact)

	Problem: No bundle size tracking. The SDK pulls in @hpke/core, @noble/curves, jose, viem — these are
	heavy. No visibility into how big the SDK is for consumers.

	Viem pattern: size-limit with hard caps (85 kB total, 6.6 kB for createClient). PR comments show size
	diff.

	Recommendation: Add size-limit with a reasonable cap. The privacy module target was already set at "<
	50 kB" in the NEWT-627 spec — enforce it.

	4. Type-Level Tests (Medium Impact)

	Problem: No type-level tests. The SDK exports complex generic types (SubmitEvaluationRequestParams,
	privacy types) that could regress silently.

	Viem pattern: *.test-d.ts files with expectTypeOf assertions. Run via vitest typecheck.

	Recommendation: Add *.test-d.ts for key exported types, especially the privacy module's
	CreateSecureEnvelopeParams and the task submission params.

	5. Stale Config Cleanup (Quick Win)

	Problem: .lintstagedrc.json references eslint --fix and prettier --write — neither is installed (Biome
	replaced them). Dead config confuses contributors.

	Recommendation: Update .lintstagedrc.json to use biome check --write instead, or remove it if
	simple-git-hooks already runs pnpm lint directly.

	6. Package Validation Tooling (Medium Impact)

	Problem: No validation that the published package works correctly across CJS/ESM/types resolution.

	Viem pattern: publint + @arethetypeswrong/cli in CI. Catches broken exports, missing types, CJS/ESM
	resolution issues.

	Recommendation: Add both as dev dependencies, run in CI after build.

	7. Unused Export Detection (Medium Impact)

	Problem: No dead export detection. As the SDK grows, unused exports accumulate.

	Viem pattern: knip detects unused files, exports, and dependencies.

	Recommendation: Add knip to CI. Low effort, high signal.

	8. Multi-Version TypeScript Testing (Low-Medium Impact)

	Problem: Tests run against a single TypeScript version (5.4). SDK consumers may use different TS
	versions.

	Viem pattern: CI runs type-checking against TS 5.8.2, 5.9.3, and latest.

	Recommendation: Add a matrix of TS versions to the CI type-check step. At minimum test against the
	version shipped and latest.

	9. Changesets for Versioning (Medium Impact)

	Problem: Newton SDK uses auto for releases. It works but has less community adoption and doesn't
	generate per-PR changelogs.

	Viem pattern: Changesets — contributors describe changes in .changeset/ files, automated version PRs
	aggregate them, CHANGELOG.md is auto-generated.

	Recommendation: This is a larger migration. Consider adopting when the team grows. auto is fine for
	now but changesets scale better for OSS.

	10. Canary Packages on PRs (Already Partially There)

	Problem: Newton SDK has a canary.yml workflow but it does a full npm publish. This pollutes the npm
	registry with canary versions.

	Viem pattern: Uses pkg-pr-new which publishes to a temporary CDN — reviewers get npm install
	https://pkg.pr.new/viem@<pr> without polluting the registry.

	Recommendation: Evaluate pkg-pr-new as a cleaner alternative to npm canary publishes.

	11. Debug Log in Production (Quick Fix)

	Problem: src/index.ts line 88 has console.log('idpUrl:', idpUrl) — a debug log left in production
	code.

	Recommendation: Remove it.

	---
	Priority Action Items

	┌──────────┬──────────────────────────────────────────────────┬──────────┐
	│ Priority │ Item │ Effort │
	├──────────┼──────────────────────────────────────────────────┼──────────┤
	│ P0 │ Fix broken ./viem and ./networks package exports │ 10 min │
	├──────────┼──────────────────────────────────────────────────┼──────────┤
	│ P0 │ Remove debug console.log in src/index.ts │ 1 min │
	├──────────┼──────────────────────────────────────────────────┼──────────┤
	│ P0 │ Uncomment tests in CI (test.yml) │ 5 min │
	├──────────┼──────────────────────────────────────────────────┼──────────┤
	│ P1 │ Update stale .lintstagedrc.json to use Biome │ 5 min │
	├──────────┼──────────────────────────────────────────────────┼──────────┤
	│ P1 │ Add publint to CI │ 30 min │
	├──────────┼──────────────────────────────────────────────────┼──────────┤
	│ P1 │ Add size-limit with bundle size caps │ 1-2 hr │
	├──────────┼──────────────────────────────────────────────────┼──────────┤
	│ P2 │ Add tests for AVS and policy modules │ Half day │
	├──────────┼──────────────────────────────────────────────────┼──────────┤
	│ P2 │ Add knip for unused export detection │ 30 min │
	├──────────┼──────────────────────────────────────────────────┼──────────┤
	│ P2 │ Add @arethetypeswrong/cli to CI │ 30 min │
	├──────────┼──────────────────────────────────────────────────┼──────────┤
	│ P3 │ Add type-level tests (*.test-d.ts) │ 2-3 hr │
	├──────────┼──────────────────────────────────────────────────┼──────────┤
	│ P3 │ Multi-version TS testing in CI │ 1 hr │
	├──────────┼──────────────────────────────────────────────────┼──────────┤
	│ P3 │ Evaluate pkg-pr-new vs npm canary │ Research │
	├──────────┼──────────────────────────────────────────────────┼──────────┤
	│ P4 │ Evaluate changesets vs auto │ Future │
	└──────────┴──────────────────────────────────────────────────┴──────────┘

	★ Insight ─────────────────────────────────────
	The biggest takeaway from viem isn't any single tool — it's the defense-in-depth quality pipeline:
	publint catches broken exports, size-limit catches bloat, knip catches dead code,
	@arethetypeswrong/cli catches type resolution bugs, and multi-version TS testing catches compatibility
	regressions. Each tool is cheap to add individually, but together they form a safety net that
	prevents the kind of issues that only surface when consumers try to use the SDK.
	─────────────────────────────────────────────────
No results found