Viem vs Newton SDK — Architecture Comparison

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.
  ─────────────────────────────────────────────────

About page (about.mdx)

Problem: It's all prose. No code. No action. A developer reads 46 lines of
marketing-adjacent text ("new foundation for trust, compliance, and safety in
autonomous systems") and has to decide whether to click to the next page.

Fixes:

• Cut the "Summary" section — it literally restates paragraph 1
• Replace "Why Newton" bullet list with a 10-line code snippet showing the SDK in
  action (the "show, don't tell" moment)
• Move the video walkthrough higher — above the bullet list. Video is your best
  conversion tool and it's buried below the fold.
• The demo Card link is good but should be more prominent — put it at the very top, not
  after 2 paragraphs of explanation.

Quickstart page (quickstart.mdx)

This is where you're losing people. Several problems:

1. Hardcoded SDK version 0.3.15 in the install command. Current version is 0.3.18. A
   developer who copies this gets an older version, which may not match the docs. Remove
   the version pin — just use @magicnewton/newton-protocol-sdk.
2. The prerequisites are a wall of friction:
   - Need a Newton API key (email-based, not self-serve)
   - Need Sepolia ETH
   - Need an Alchemy RPC URL

That's 3 external accounts before writing a single line of code. By contrast, the
quickstart uses simulateTask which is a read-only simulation — does it actually need
Sepolia ETH? If not, remove that prerequisite. If the simulation endpoint doesn't need
auth, remove the API key requirement too.
3. The code is split across two steps — Step 2 creates a file, Step 3 adds to it. This
means the developer can't copy-paste a single working file. Combine them into one
complete, runnable script.
4. The hex values are opaque:
policyId: '0x27b7c88f...',
policyAddress: '0x5FeaeBfB...',
wasmArgs: '0x7b22626173...',
4. A developer has no idea what these mean. Add inline comments: // OFAC sanctions
screening policy on Sepolia, // BTC price oracle args ({"base_symbol":"BTC"}).
5. The "AI-assisted build" accordion at the bottom is misplaced. It's a completely
different workflow (download context files, use Claude). It doesn't belong on the
quickstart page — it should be its own guide or in resources.
6. Next steps links go to Core Concepts first — wrong order. After the quickstart, the
developer wants to build something real, not read more theory. Lead with Integration
Guide.

Core Concepts page (core-concepts.mdx)

Decent page, wrong position in the funnel. It's linked from the quickstart as "next
step" but it's a glossary page. Developers who just ran a simulation don't need a
dictionary — they need the next building block.

Fix: This page is fine as reference but should not be the primary "next step" from the
quickstart. The quickstart should link to the integration guide first, with core
concepts as a sidebar reference.

Integration Guide (integration-guide.mdx)

Problem: It's a table of contents, not a guide. It lists 5 steps, each linking to a
separate page. A developer arrives here and sees another set of prerequisites (Rust,
Cargo, Foundry, newton-cli, Pinata account, Sepolia ETH) — that's 6 more tools to
install before they can do anything.

This is why 60% of people leave after the quickstart. The quickstart says "you can
simulate in 5 minutes," then the integration guide says "now install Rust, Cargo,
Foundry, and get a Pinata account." The cliff is too steep.

Fix: The integration guide needs an inline, end-to-end example that works — not just
links to 5 other pages. Or better: the quickstart should progress to a real task
submission (not just simulation) so developers see the full loop before being asked to
install heavy tooling.

Concrete Action Items

┌──────────┬─────────────────────────────────────────┬─────────────────────────────┐
│ Priority │ Change │ Impact │
├──────────┼─────────────────────────────────────────┼─────────────────────────────┤
│ P0 │ Remove hardcoded @0.3.15 from │ Prevents broken first │
│ │ quickstart install │ experience │
├──────────┼─────────────────────────────────────────┼─────────────────────────────┤
│ P0 │ Remove Sepolia ETH prerequisite if │ Reduces friction to first │
│ │ simulation doesn't need it │ run │
├──────────┼─────────────────────────────────────────┼─────────────────────────────┤
│ P0 │ Merge quickstart Steps 2+3 into one │ Copy-paste-run experience │
│ │ complete, runnable file │ │
├──────────┼─────────────────────────────────────────┼─────────────────────────────┤
│ P1 │ Add inline comments to all hex values │ Comprehension │
│ │ in quickstart │ │
├──────────┼─────────────────────────────────────────┼─────────────────────────────┤
│ │ Reorder quickstart "Next steps" — │ │
│ P1 │ Integration Guide first, Core Concepts │ Conversion │
│ │ second │ │
├──────────┼─────────────────────────────────────────┼─────────────────────────────┤
│ P1 │ Add a 10-line SDK code snippet to the │ Show don't tell │
│ │ about page │ │
├──────────┼─────────────────────────────────────────┼─────────────────────────────┤
│ P1 │ Move the AI-assisted accordion to a │ Declutter quickstart │
│ │ separate guide or resources page │ │
├──────────┼─────────────────────────────────────────┼─────────────────────────────┤
│ │ Add a "light" integration path after │ Bridge the │
│ P2 │ quickstart — submit a real task, get │ simulation-to-production │
│ │ attestation — before the heavy tooling │ gap │
│ │ guide │ │
├──────────┼─────────────────────────────────────────┼─────────────────────────────┤
│ P2 │ Consider merging About + Core Concepts │ Fewer clicks to code │
│ │ into one page │ │
└──────────┴─────────────────────────────────────────┴─────────────────────────────┘

Completed

P0 (Critical) — PR #122, merged

• about.mdx: Tightened prose, cut redundant Summary section, added code snippet within
  2 scrolls, added quickstart CTA
• quickstart.mdx: Removed hardcoded @0.3.15, merged split steps into single copy-paste
  file, annotated all opaque hex values, added sequence diagram to "What just happened?",
  reordered next-step cards (integration guide first)
• docs.json: Reordered nav: about → quickstart → core-concepts (hands-on before theory)

P1 (High) — PR #122, merged

• integration-guide.mdx: Added tabbed entry point ("Use existing policy" vs "Build from
  scratch"), added per-step prerequisites column, collapsed full toolchain install into
  accordion
• core-concepts.mdx: Repositioned as reference page, updated intro and next-step cards

P2 (Medium) — PR #123, merged

• Removed 3 remaining hardcoded SDK version pins (frontend-sdk-integration,
  sdk-reference, agent.md)
• Added "Try the demo" card to quickstart next-steps

Auth standardization — PR #124, open

• SDK source: X-API-Key → Authorization: Bearer (RFC 6750)
• Local .claude/ rules updated to match

---

Remaining Items

Content improvements (not yet started)

1. frontend-sdk-integration.mdx — still exposes NEXT_PUBLIC_SIGNER_PRIVATE_KEY in the
   env example (line 42). This is a security anti-pattern for docs. Should show a safer
   approach or add a prominent warning.
2. Combine about + quickstart flow — originally a P2 idea. The about page now has a
   code snippet and links to quickstart, which may be sufficient. Worth revisiting after
   seeing analytics post-merge. Not urgent.
3. Inline "Try it" sandbox embeds — P2 idea to add interactive code sandboxes (e.g.,
   StackBlitz). Higher effort, unclear ROI until we see if the current changes improve the
   funnel.
4. Sub-guide pages quality pass — The integration guide links to 5 sub-guides
   (writing-data-oracles, writing-policies, deploying-with-cli,
   smart-contract-integration, frontend-sdk-integration). These haven't been audited for
   the same issues (opaque hex, split steps, missing annotations). Could have similar
   drop-off problems.

Structural / SEO

5. SDK reference page — still says "v0.3.15" was removed, but the page content itself
   may be stale vs current exports. Worth a full audit against src/index.ts exports.
6. Cross-page link consistency — dashboard-api-keys "Use the API key" step (line 83-89)
   shows a raw curl example but doesn't link to the quickstart or SDK reference for the
   programmatic approach.

Measurement

7. Track analytics post-merge — The whole point is reducing the 60% quickstart →
   integration-guide drop-off. Need to check Mintlify analytics in 1-2 weeks after PR #122
   deploys to see if the changes moved the needle.

---

Priority recommendation for next session

┌──────────┬───────────────────────────────────────────┬───────────────────────────┐
│ Priority │ Item │ Effort │
├──────────┼───────────────────────────────────────────┼───────────────────────────┤
│ High │ #4 — Audit the 5 sub-guide pages │ Medium (read + fix each) │
├──────────┼───────────────────────────────────────────┼───────────────────────────┤
│ High │ #5 — SDK reference audit vs actual │ Medium │
│ │ exports │ │
├──────────┼───────────────────────────────────────────┼───────────────────────────┤
│ Medium │ #1 — Fix private key in frontend guide │ Small │
│ │ env │ │
├──────────┼───────────────────────────────────────────┼───────────────────────────┤
│ Low │ #7 — Check analytics in 1-2 weeks │ None (just look) │
├──────────┼───────────────────────────────────────────┼───────────────────────────┤
│ Low │ #2, #3 — Combine pages / sandbox embeds │ Defer until analytics │
│ │ │ data │
└──────────┴───────────────────────────────────────────┴───────────────────────────┘

---

SEO Audit & Optimization Plan for docs.newt.foundation

Current State

What's working:

• All 34+ pages have title and description frontmatter
• GA4 tracking is active (G-JFG7Z812VK)
• Global OG/Twitter meta tags are set in docs.json
• Redirects are properly configured for legacy URLs
• Mintlify auto-generates sitemap.xml and robots.txt

What's broken or missing:

┌────────────────────────────────────┬─────────────────────────────┬──────────┐
│ Issue │ Impact │ Severity │
├────────────────────────────────────┼─────────────────────────────┼──────────┤
│ Only 16 Google referral views out │ Organic search is nearly │ Critical │
│ of ~1,400 total │ zero │ │
├────────────────────────────────────┼─────────────────────────────┼──────────┤
│ 46% of traffic is $direct (no │ Real external traffic is │ Critical │
│ referrer) — likely internal/team │ tiny │ │
├────────────────────────────────────┼─────────────────────────────┼──────────┤
│ twitter:card set to a URL instead │ Twitter previews are broken │ High │
│ of summary_large_image │ │ │
├────────────────────────────────────┼─────────────────────────────┼──────────┤
│ og:url points to │ Canonical confusion between │ │
│ https://newt.foundation not │ landing page and docs │ High │
│ https://docs.newt.foundation │ │ │
├────────────────────────────────────┼─────────────────────────────┼──────────┤
│ Zero per-page keywords frontmatter │ Pages aren't targeting │ Medium │
│ │ specific search queries │ │
├────────────────────────────────────┼─────────────────────────────┼──────────┤
│ Generic titles like "Quickstart", │ No brand or topic signal │ Medium │
│ "Architecture", "Introduction" │ for search engines │ │
├────────────────────────────────────┼─────────────────────────────┼──────────┤
│ │ Potential duplicate content │ │
│ No canonical set at global or page │ issues between │ Medium │
│ level │ docs.newt.foundation and │ │
│ │ newton.xyz │ │
├────────────────────────────────────┼─────────────────────────────┼──────────┤
│ No structured data / article │ Missing rich snippets │ Low │
│ metadata │ opportunity │ │
└────────────────────────────────────┴─────────────────────────────┴──────────┘

---

Strategy 1: Fix Critical Meta Tag Errors

In docs.json:

"seo": {
"metatags": {
"og:url": "https://docs.newt.foundation",
"twitter:card": "summary_large_image",
"canonical": "https://docs.newt.foundation"
}
}

The twitter:card value must be one of summary, summary_large_image, app, or player
— not a URL. This is currently broken, meaning every share on X has no preview
card.

Strategy 2: SEO-Optimized Page Titles

Generic titles like "Quickstart" or "Architecture" compete with millions of other
docs sites. Rewrite titles to include the product name and target keyword:

┌─────────────────────────────┬───────────────────────────────────────────────┐
│ Current Title │ Proposed Title │
├─────────────────────────────┼───────────────────────────────────────────────┤
│ "Quickstart" │ "Quickstart — Newton Protocol" │
├─────────────────────────────┼───────────────────────────────────────────────┤
│ "Architecture" │ "Architecture — Newton Protocol" │
├─────────────────────────────┼───────────────────────────────────────────────┤
│ "Core Concepts" │ "Core Concepts — Newton Protocol" │
├─────────────────────────────┼───────────────────────────────────────────────┤
│ "Writing Policies" │ "Writing Rego Policies — Newton Protocol" │
├─────────────────────────────┼───────────────────────────────────────────────┤
│ "SDK Reference" │ "TypeScript SDK Reference — Newton Protocol" │
├─────────────────────────────┼───────────────────────────────────────────────┤
│ "RPC API" │ "JSON-RPC API Reference — Newton Protocol" │
├─────────────────────────────┼───────────────────────────────────────────────┤
│ "Introduction" │ "Technical Whitepaper — Newton Protocol" │
├─────────────────────────────┼───────────────────────────────────────────────┤
│ "Smart Contract │ "Smart Contract Integration — Newton │
│ Integration" │ Protocol" │
└─────────────────────────────┴───────────────────────────────────────────────┘

Mintlify uses the title frontmatter for both the page heading and <title> tag.
Adding "— Newton Protocol" as a suffix gives every page brand + topic signal.

Strategy 3: Per-Page Keywords

Add keywords frontmatter targeting long-tail search queries developers actually
search for. Examples:

┌────────────────────────────┬─────────────────────────────────────────────────┐
│ Page │ Keywords │
├────────────────────────────┼─────────────────────────────────────────────────┤
│ quickstart │ "newton protocol quickstart, policy evaluation │
│ │ tutorial, eigenlayer avs sdk" │
├────────────────────────────┼─────────────────────────────────────────────────┤
│ writing-policies │ "rego policy examples, blockchain transaction │
│ │ policy, onchain compliance rules" │
├────────────────────────────┼─────────────────────────────────────────────────┤
│ sdk-reference │ "newton sdk, viem client extension, typescript │
│ │ blockchain sdk" │
├────────────────────────────┼─────────────────────────────────────────────────┤
│ rpc-api │ "newton rpc api, policy evaluation api, │
│ │ eigenlayer json-rpc" │
├────────────────────────────┼─────────────────────────────────────────────────┤
│ smart-contract-integration │ "solidity policy client, onchain attestation │
│ │ verification, eigenlayer smart contract" │
├────────────────────────────┼─────────────────────────────────────────────────┤
│ architecture │ "newton protocol architecture, avs policy │
│ │ engine, eigenlayer avs design" │
└────────────────────────────┴─────────────────────────────────────────────────┘

Strategy 4: Cross-Linking Between docs.newt.foundation and newton.xyz

The referral data shows newton.xyz sends 319 views to docs — but Google sends only
16. To improve:

1. Add structured links from newton.xyz landing page — "Developer Docs" CTA should
   link to /developers/overview/quickstart, not just the docs root
2. Add a docs backlink in newton.xyz footer — permanent crawlable link
3. Blog cross-links — blog.newt.foundation (5 referrals currently) should link to
   specific docs pages, not just the homepage. Every blog post about a feature should
   deep-link to the relevant guide

Strategy 5: Content Gaps for Organic Search

Developers search for problems, not product names. Pages that answer specific
questions rank well. Consider adding:

┌──────────────────────────────┬──────────────────────────────────────────────┐
│ Target Query │ Proposed Page │
├──────────────────────────────┼──────────────────────────────────────────────┤
│ "how to add transaction │ Covered by integration-guide, but │
│ policies to smart contracts" │ title/description don't match this query │
├──────────────────────────────┼──────────────────────────────────────────────┤
│ "eigenlayer avs tutorial" │ No page targets this — add an "EigenLayer │
│ │ AVS" section to about.mdx │
├──────────────────────────────┼──────────────────────────────────────────────┤
│ "rego policy blockchain" │ writing-policies covers this but the │
│ │ description doesn't mention "blockchain" │
├──────────────────────────────┼──────────────────────────────────────────────┤
│ "onchain compliance │ No page targets this keyword cluster │
│ automation" │ │
├──────────────────────────────┼──────────────────────────────────────────────┤
│ "wasm data oracle web3" │ writing-data-oracles covers this but isn't │
│ │ framed for search │
└──────────────────────────────┴──────────────────────────────────────────────┘

Strategy 6: Improve Internal Linking

The 60% drop-off after quickstart (from your earlier analytics) means pages don't
guide users forward. Every page should:

1. End with a "Next steps" section linking to 2-3 related pages
2. First mention of any Newton concept should link to its reference page
3. Add navigation blocks at the bottom of guide pages

Strategy 7: Social Preview Images

Create per-section OG images rather than one generic image. Mintlify supports
per-page og:image in frontmatter. At minimum, create distinct images for:

• Developers section
• Whitepaper section
• Protocol section

---

Implementation Priority

┌──────────┬───────────────────────────────┬────────┬─────────────────────────┐
│ Priority │ Action │ Effort │ Impact │
├──────────┼───────────────────────────────┼────────┼─────────────────────────┤
│ P0 │ Fix twitter:card and og:url │ 5 min │ Fixes broken social │
│ │ in docs.json │ │ previews │
├──────────┼───────────────────────────────┼────────┼─────────────────────────┤
│ P0 │ Add canonical to docs.json │ 5 min │ Prevents duplicate │
│ │ │ │ indexing │
├──────────┼───────────────────────────────┼────────┼─────────────────────────┤
│ P1 │ Rewrite all page titles with │ 1 hr │ Brand signal in every │
│ │ "— Newton Protocol" suffix │ │ SERP result │
├──────────┼───────────────────────────────┼────────┼─────────────────────────┤
│ P1 │ Add keywords to top 10 pages │ 30 min │ Targets specific search │
│ │ │ │ queries │
├──────────┼───────────────────────────────┼────────┼─────────────────────────┤
│ P2 │ Cross-link newton.xyz → │ 30 min │ Boosts referral + link │
│ │ specific docs pages │ │ equity │
├──────────┼───────────────────────────────┼────────┼─────────────────────────┤
│ P2 │ Add "Next steps" sections to │ 2 hr │ Reduces drop-off, │
│ │ guide pages │ │ improves crawl depth │
├──────────┼───────────────────────────────┼────────┼─────────────────────────┤
│ P3 │ Blog-to-docs deep linking │ 1 hr │ Long-tail organic │
│ │ │ │ traffic │
├──────────┼───────────────────────────────┼────────┼─────────────────────────┤
│ P3 │ Per-section OG images │ 2 hr │ Better social │
│ │ │ │ click-through │
└──────────┴───────────────────────────────┴────────┴─────────────────────────┘

Want me to start implementing the P0 and P1 changes now?

NEWT-176 (Threshold Decryption with Feldman VSS) is now complete. The dkg module implements the full threshold
HPKE decryption pipeline:

1. dealer.rs — Feldman VSS: trusted dealer generates polynomial, evaluates shares at operator indices, publishes
   commitments for verification. Horner's method for polynomial evaluation.
2. dleq.rs — Non-interactive DLEQ proofs via Fiat-Shamir with SHA-256. Each operator proves log_G(pk_i) ==
   log_{enc}(D_i) — same secret share used for both their public key and partial decryption. This is the foundation
   for slashing (NEWT-629): a bad DLEQ proof is cryptographic evidence of misbehavior.
3. combine.rs — Lagrange interpolation in the exponent. The gateway combines t valid partial decryptions D_i = s_i

• enc into the full DH output sk * enc without ever reconstructing the master secret. This feeds into
  decrypt_with_precomputed_dh (NEWT-638) to complete the post-DH HPKE pipeline.
  ─────────────────────────────────────────────────

Here's the status of the critical path:

┌──────────┬────────────────────────────────────┬─────────────────┐
│ Ticket │ Description │ Status │
├──────────┼────────────────────────────────────┼─────────────────┤
│ NEWT-638 │ HPKE decrypt_with_precomputed_dh │ Done (10 tests) │
├──────────┼────────────────────────────────────┼─────────────────┤
│ NEWT-176 │ Threshold Decryption (Feldman VSS) │ Done (28 tests) │
├──────────┼────────────────────────────────────┼─────────────────┤
│ NEWT-178 │ Two-Phase Consensus Integration │ Next │
├──────────┼────────────────────────────────────┼─────────────────┤
│ NEWT-630 │ On-chain Aggregation Commitments │ Pending │
├──────────┼────────────────────────────────────┼─────────────────┤
│ NEWT-629 │ Privacy-specific Operator Slashing │ Pending │
└──────────┴────────────────────────────────────┴─────────────────┘

Next step is NEWT-178: integrating threshold decryption into the Two-Phase Consensus Prepare phase. This involves
modifying the gateway to distribute key shares to operators, collect partial decryptions during the Prepare phase,
combine them via Lagrange interpolation, and then decrypt the HPKE ciphertext before broadcasting plaintext in
the Commit phase. Want me to proceed?

Done (code changes):

┌─────┬─────────────────────┬──────────────────────────────────────────────────────┐
│ # │ Item │ Status │
├─────┼─────────────────────┼──────────────────────────────────────────────────────┤
│ │ Google Search │ │
│ 1 │ Console │ Added to docs.json │
│ │ verification tag │ │
├─────┼─────────────────────┼──────────────────────────────────────────────────────┤
│ 2 │ Image alt text │ Fixed iframe title (about.mdx) + 3 token chart │
│ │ audit │ images │
├─────┼─────────────────────┼──────────────────────────────────────────────────────┤
│ │ │ Already correct (Mintlify auto-generates FAQPage │
│ 3 │ FAQ page schema │ JSON-LD from Accordion pattern). Fixed stale mainnet │
│ │ │ reference, added keywords. │
├─────┼─────────────────────┼──────────────────────────────────────────────────────┤
│ │ │ Design task — frontmatter ready, needs image assets │
│ 4 │ Per-page OG images │ created (1200x630px) for quickstart, about, │
│ │ │ core-concepts, integration-guide │
├─────┼─────────────────────┼──────────────────────────────────────────────────────┤
│ 5 │ External backlinks │ Added Documentation section with 4 links to │
│ │ — README │ docs.newton.xyz │
├─────┼─────────────────────┼──────────────────────────────────────────────────────┤
│ 5b │ External backlinks │ Action item for you — add links from newton.xyz to │
│ │ — landing page │ use-case pages and quickstart │
├─────┼─────────────────────┼──────────────────────────────────────────────────────┤
│ 6 │ Content gap │ Pending — needs Search Console data (available ~1 │
│ │ analysis │ week after verification) │
├─────┼─────────────────────┼──────────────────────────────────────────────────────┤
│ 7 │ Old domain │ Already handled — 301 from docs.newt.foundation → │
│ │ redirects │ docs.newton.xyz confirmed │
└─────┴─────────────────────┴──────────────────────────────────────────────────────┘

Your next steps:

1. Complete Search Console setup — go to search.google.com/search-console, add
   https://docs.newton.xyz, verify with the meta tag (will deploy with this PR), then
   submit sitemap https://docs.newton.xyz/sitemap.xml
2. Create per-page OG images for the 4 high-traffic pages (or delegate to design)
3. Add backlinks from newton.xyz landing page to docs use-case pages
4. In ~1 week, check Search Console for content gap opportunities

⏺ That's the most effective method. Google will fetch and index the sitemap within the
next few hours. You can check back in Search Console tomorrow — the sitemap status
should update to "Success" and you'll start seeing pages in the index.

In the meantime, everything on our end is done. Here's the final status:

Completed:

• Per-page SEO metadata (titles, descriptions, keywords) across all pages
• 3 new use-case pages (institutional DeFi, stablecoins, agent security)
• Content flow optimization on 4 high-traffic pages
• Internal cross-linking throughout docs
• Google Search Console verified + sitemap submitted
• Image alt text fixed
• FAQ page keywords + stale content fixed
• README backlinks to docs.newton.xyz
• Domain redirect (docs.newt.foundation → docs.newton.xyz) confirmed

Follow-ups (non-code):

• Recheck sitemap status tomorrow in Search Console
• Per-page OG images (design task)
• Landing page backlinks to docs use-case pages
• Content gap analysis (~1 week, once Search Console has data)

---

1. Stale URLs — docs.newt.foundation should be docs.newton.xyz

The domain has migrated (301 redirect confirmed), but the landing page still hardcodes
the old domain in 5 places in site.config.ts:

┌─────────────────────┬────────────────────────────────────────────┬───────────────┐
│ Location │ Current URL │ Should be │
├─────────────────────┼────────────────────────────────────────────┼───────────────┤
│ nav.items[0] (Quick │ docs.newt.foundation/developers/overview/q │ docs.newton.x │
│ Start) │ uickstart │ yz/... │
├─────────────────────┼────────────────────────────────────────────┼───────────────┤
│ nav.items[0] │ docs.newt.foundation/developers/overview/a │ docs.newton.x │
│ (Documentation) │ bout │ yz/... │
├─────────────────────┼────────────────────────────────────────────┼───────────────┤
│ trustModel.ctas[1] │ docs.newt.foundation/developers/overview/a │ docs.newton.x │
│ (Learn more) │ bout │ yz/... │
├─────────────────────┼────────────────────────────────────────────┼───────────────┤
│ policyCapabilities. │ docs.newt.foundation/developers/advanced/p │ docs.newton.x │
│ ctas[1] (Learn │ olicy-data-oracles │ yz/... │
│ more) │ │ │
├─────────────────────┼────────────────────────────────────────────┼───────────────┤
│ footer.columns.Deve │ docs.newt.foundation/ │ docs.newton.x │
│ loper[0] (Docs) │ │ yz/ │
└─────────────────────┴────────────────────────────────────────────┴───────────────┘

The 301 redirect works, but this hurts SEO (redirect chains lose link equity) and adds
latency.

2. Missing backlinks to docs use-case pages

The UseCases section has 5 items but none link to the corresponding docs pages. These
are the backlinks we discussed:

┌───────────────────┬───────────────────────────────────────────────────────────────┐
│ Use Case │ Should link to │
├───────────────────┼───────────────────────────────────────────────────────────────┤
│ Stablecoins & │ docs.newton.xyz/developers/use-cases/stablecoins-and-payments │
│ RWAs │ │
├───────────────────┼───────────────────────────────────────────────────────────────┤
│ Institutional │ docs.newton.xyz/developers/use-cases/institutional-defi │
│ DeFi & Vaults │ │
├───────────────────┼───────────────────────────────────────────────────────────────┤
│ AI Agent Commerce │ docs.newton.xyz/developers/use-cases/agent-security │
└───────────────────┴───────────────────────────────────────────────────────────────┘

3. "Trusted By" includes Magic Labs

logos.items lists Magic Labs alongside EigenLayer, Base, and M0. Magic Labs is the
parent company — listing it as "Trusted By" is self-referential. Consider replacing
with an actual customer/partner, or changing the heading to "Ecosystem" or "Built
With".

4. No developer CTA on the main page

The page is entirely enterprise/business oriented. The "Build" dropdown links to docs,
but there's no visible developer section or code snippet on the landing page itself.
The docs site about page has a code snippet — a similar one on the landing page could
attract developer traffic directly.

5. CTA buttons don't include docs quickstart

Both CTA groups (ValueProp and CTABanner) offer "Talk to an expert" + "Download
Whitepaper". There's no "Start Building" or "Try Quickstart" CTA anywhere on the page
body. The "Try Demo" is only in the header nav. For developers landing on newton.xyz,
the path to getting started is buried in a dropdown.

6. Market stats may be stale

The marketStats.items values ($298B+ stablecoin cap, $700B+ monthly volume, $21B+ RWA,
$206B compliance costs) are static. These are likely from when the page was built.
Worth verifying they're still accurate — stablecoin market cap has been growing
rapidly.

7. Missing narratives

• No mainnet mention — if mainnet is live (per the docs update), the landing page
  doesn't call this out. A "Live on Mainnet" badge or announcement could build
  credibility.
• No usage/traction metrics — no numbers about tasks evaluated, policies deployed, or
  operators active. Even testnet metrics would add social proof.
• No NEWT token section — the token is only mentioned in the announcement banner. For a
  protocol with a live token, this feels like a gap. Even a brief section or footer
  reference to tokenomics/staking would help.
• No regulatory framework detail — the "Why Now" section mentions GENIUS Act, MiCA,
  FATF Travel Rule but doesn't explain what Newton does for each. A brief mapping
  (regulation → Newton capability) would strengthen the narrative.

8. Minor content issues

• howItWorks.steps[1].description: "Adding a lightweight snippet" — should be "Add a
  lightweight snippet" (imperative, consistent with other step titles)
• announcement.text: "Staking $NEWT? Looking for Newton agents?" — two unrelated
  questions in one banner. Could be clearer.
• explorer.newt.foundation links (trustModel, footer) — should these also migrate to
  explorer.newton.xyz?

---

Want me to start fixing these? The URL migration (#1) is the most impactful and
quickest to execute.

✻ Sautéed for 1m 18s

❯ Note that @/projects/landing-page/ also has its own agent files in
@/projects/landing-page/.claude folder and @/projects/landing-page/CLAUDE.md,
following the same agent file management structure/rules as in this repo or other newton
project repos like @/projects/newton-prover-avs/ or
@~/projects/newton-prover-avs-deploy/, etc.
⎿  Listed directory ../landing-page/
⎿  Listed directory ../landing-page/.claude/
⎿  Read ../landing-page/CLAUDE.md (121 lines)
⎿  Listed directory ../newton-prover-avs/
⎿  Listed directory ../newton-prover-avs-deploy/
⎿  Async hook Stop completed

⏺ Understood — the landing-page repo has its own fully set up agent files. Since the most
impactful fix is the URL migration (#1 from my review), and those changes would be in
the landing-page repo, do you want me to switch over to ~/projects/landing-page/ and
start fixing those stale docs.newt.foundation URLs in site.config.ts? That's a quick
win that improves SEO link equity and eliminates redirect latency.

Or would you prefer to tackle these in a specific order / prioritize certain items from
the review?

❯ First, draft and present a full plan with your in-depth analysis on what we should do
to improve the landing page (landing-page repo) or the developer docs (this repo). And
if all task items are for the landing page, then yes lets switch over to
~/projects/landing-page/ and start fixing those stale docs.newt.foundation URLs in
site.config.ts
⎿  Async hook Stop completed

⏺ Here's the full plan, split by repo:

---

Newton SDK repo (this repo) — No remaining items

All docs site work is complete. SEO metadata, content flow, cross-linking, Search
Console, image alt text, README backlinks — all shipped in PRs #128 and #129.

---

Landing Page repo (~/projects/landing-page/) — All items below

Critical (SEO/functionality impact)

┌─────┬────────────────────────────────┬────────────────┬──────────────────────────┐
│ # │ Item │ File │ Impact │
├─────┼────────────────────────────────┼────────────────┼──────────────────────────┤
│ │ Migrate all │ │ 5 links forcing 301 │
│ 1 │ docs.newt.foundation URLs to │ site.config.ts │ redirects — hurts SEO │
│ │ docs.newton.xyz │ │ link equity, adds ~100ms │
│ │ │ │ latency per click │
├─────┼────────────────────────────────┼────────────────┼──────────────────────────┤
│ │ Check if │ │ 2 links (trustModel CTA, │
│ 2 │ explorer.newt.foundation │ site.config.ts │ footer) — same redirect │
│ │ should also migrate │ │ concern │
└─────┴────────────────────────────────┴────────────────┴──────────────────────────┘

High (content/narrative gaps)

#: 3
Item: Add backlinks from use-case cards to docs use-case pages
File: site.config.ts (useCases items)
Impact: Direct SEO backlinks to new docs pages; gives users a "learn more" path from
each use case
────────────────────────────────────────
#: 4
Item: Add a developer-oriented CTA in CTA sections
File: site.config.ts (valueProp.ctas or ctaBanner.ctas)
Impact: Currently both CTA groups are enterprise-only ("Talk to expert" +
"Whitepaper").
Adding "Start Building" → quickstart would serve developer traffic
────────────────────────────────────────
#: 5
Item: Fix "Trusted By" — remove or reposition Magic Labs
File: site.config.ts (logos.items)
Impact: Self-referential — Magic Labs is the parent company, not an external trust
signal. Move to "Built By" section or replace with an actual partner

Medium (content accuracy/freshness)

#: 6
Item: Fix grammar: "Adding a lightweight snippet" → "Add a lightweight snippet"
File: site.config.ts (howItWorks.steps[1])
Impact: Inconsistent with imperative voice in other steps
────────────────────────────────────────
#: 7
Item: Verify market stats are current
File: site.config.ts (marketStats.items)
Impact: $298B stablecoin cap, $700B monthly volume, $21B RWA, $206B compliance — need
to
verify these haven't shifted significantly
────────────────────────────────────────
#: 8
Item: Add "Live on Mainnet" signal
File: site.config.ts (announcement or hero)
Impact: If mainnet is live, the landing page should say so. Currently no mention
anywhere.

Low (nice-to-have improvements)

#: 9
Item: Add regulation → capability mapping to "Why Now" section
File: Section component or site.config.ts
Impact: GENIUS Act, MiCA, FATF Travel Rule are mentioned but not mapped to what Newton
does for each
────────────────────────────────────────
#: 10
Item: Add NEWT token section or reference
File: site.config.ts
Impact: Token only appears in announcement banner. A brief staking/tokenomics mention
could help with token-related search traffic
────────────────────────────────────────
#: 11
Item: Clarify announcement banner
File: site.config.ts (announcement.text)
Impact: "Staking $NEWT? Looking for Newton agents?" — two unrelated questions. Could be

more focused

---

All 11 items are in the landing-page repo. Items 1-2 are pure site.config.ts URL
changes I can fix immediately. Items 3-6 are also site.config.ts content changes. Items
7-11 need your input on content/direction.

Want me to switch to ~/projects/landing-page/ and start executing items 1 through 6?

Committed and pushed to main: 789d87a.

Changes in this commit:

• Updated 3 market stats (stablecoin cap $313B+, monthly volume $4T+, RWA $25B+)
• Softened "FATF Travel Rule" → "FATF sanctions screening"
• Simplified banner to demo-focused CTA

All landing page items are resolved. Remaining follow-ups:

┌─────┬─────────────────────────────────────┬──────────────────────────────────┐
│ # │ Item │ Status │
├─────┼─────────────────────────────────────┼──────────────────────────────────┤
│ 8 │ "Live on Mainnet" signal │ Follow up after launch next week │
├─────┼─────────────────────────────────────┼──────────────────────────────────┤
│ 10 │ NEWT token prominence │ Hold — tokenomics TBD │
├─────┼─────────────────────────────────────┼──────────────────────────────────┤
│ — │ Per-page OG images │ Design task │
├─────┼─────────────────────────────────────┼──────────────────────────────────┤
│ — │ Search Console content gap analysis │ Check in ~1 week │
├─────┼─────────────────────────────────────┼──────────────────────────────────┤
│ — │ Recheck sitemap indexing │ Check in ~1 week │
└─────┴─────────────────────────────────────┴──────────────────────────────────┘

Committed and pushed: 7fbc267 — 12 files changed, 80 insertions, 251 deletions.

Changes included:

• SDK reference: removed fake exports, fixed error enums, corrected constructor
  signatures
• Gateway URLs: migrated all newt.foundation → newton.xyz across 6 docs pages
• License: MIT → Apache-2.0 in package.json
• README: fixed evaluateIntent → evaluateIntentDirect, added missing apiKey param
• Explorer URL: explorer.newt.foundation → explorer.newton.xyz

Remaining follow-ups:

• Mainnet signal — add "Live on Mainnet" after launch (this week)
• NEWT token prominence — hold until tokenomics finalized
• Dependabot alerts — 11 vulnerabilities flagged by GitHub (7 high, 3 moderate, 1 low)
• Search Console — recheck sitemap indexing in ~1 week