@newton-xyz/newton-shield-sdk

TypeScript SDK for vault curators on Morpho. Wraps every vault-management action behind a Newton Protocol policy attestation, so the curator's manager role is structurally incapable of executing actions that violate the policy.

Curators don't write calldata by hand and don't integrate a new vault product. They use the vendor's existing SDK (@morpho-org/blue-sdk-viem) to produce calldata, and the SDK plus on-chain Shield contract handle the policy gating.

Status: pre-release. The SDK is 0.4.0-alpha.0. The public surface described below is the target shape; not all modules are exported yet. Track release-by-release additions in CHANGELOG.md once published.

Highlights (target shape)

• createShield({ apiKey, walletClient, rpc, policyClientAddress, pack, vault }) — pairs a deployed Shield clone address with a CompositePolicyPack (from await defineComposite({ modules, chainId, env, publicClient, policyAddress })), deploying the clone if necessary. Single-pack curators wrap their one pack: defineComposite({ modules: [vaultsfyi], chainId, env, publicClient, policyAddress }). Returns a ShieldClient with setup functions (.setParams(paramsByShortId) and .uploadSecrets(secretsByShortId)) for configuring the Shield contract and the execution entrypoint .sendCall({ to, data, functionSignature, prepareQueryOptions }) that runs the composite's aggregated prepareQuery → wasmArgsSchema → newt_createTask → shield.executeDirect on every call.
• Deployment process Configuration order: defineComposite → createShield → setParams → uploadSecrets → sendCall is needed for first-time configuration ONLY. By passing a configured Newton Shield contract, the client detects, validates, and binds to the existing deployment. Functions setParams and uploadSecrets can be called later to update configuration. Use param mustDeploy to ensure not binding to existing contracts that you didn't deploy. Use param expectedParams with skipPolicyBindingCheck: false to ensure that the configuration is expected. Increment version to replace unusable or abandoned shield deployments. For testing on a non-production network where a pack's external data source has no coverage (e.g. vaults.fyi indexes mainnets only), a pack may expose its own data-source override in sendCall's prepareQueryOptions (e.g. { vaultsfyi: { network, vaultAddress } }) to point its lookup at a real mainnet target while the Shield executes on a testnet — a testing affordance only; leave it unset in production so the policy describes the same vault it gates.
• NewtonShield — lower-level runtime exposed via .guardedCall({ to, data, functionSignature, wasmArgs }). Use this when you want to drive intent submission yourself.
• Policy packs ship as separate npm packages. Install only the ones you integrate, e.g. pnpm add @newton-xyz/policy-pack-vaultsfyi. The SDK declares @newton-xyz/policy-pack-shared as a peer dep. Build a composite with defineComposite from @newton-xyz/policy-pack-shared, then pass it to createShield as the pack argument.
• A typed error hierarchy (PolicyDeniedError, GatewayHttpError, GatewayRpcError, GatewayTimeoutError, NewtonTaskEvaluationError, TransactionFailedError, InvalidConfigurationError, ConcurrentIntentError, UnsupportedChainError).
• Browser-safe core. No node:* imports.

Install

pnpm add @newton-xyz/newton-shield-sdk @newton-xyz/policy-pack-shared viem zod

# Plus one or more policy packs:
pnpm add @newton-xyz/policy-pack-vaultsfyi

@newton-xyz/policy-pack-shared, viem, and zod are peer dependencies — the SDK uses whatever versions your application has installed. Per-pack packages (@newton-xyz/policy-pack-vaultsfyi, @newton-xyz/policy-pack-blockaid, …) are independent: install only the packs you integrate. Vendor SDKs (@morpho-org/blue-sdk-viem, etc.) are also peer deps; install only the ones you use.

Supported chains

SUPPORTED_CHAINS (in sdk/src/chains.ts) covers the two testnets today; both are deployed on stagef and prod:

| Chain | Chain id | Network | Status | | ------------- | ----------- | ------- | ----------------------------------------------- | | Sepolia | 11155111 | Testnet | Deployed | | Base Sepolia | 84532 | Testnet | Deployed | | Ethereum | 1 | Mainnet | Reserved — not in SUPPORTED_CHAINS yet | | Base | 8453 | Mainnet | Reserved — not in SUPPORTED_CHAINS yet |

The mainnet rows are placeholder slots: their audit-trail JSON exists at deployments/{1,8453}-{env}.json, but they are not in SUPPORTED_CHAINS, so createShield raises UnsupportedChainError for them today. See docs/deployment/chains.md for the add-a-chain procedure.

The SDK's per-chain registry lives in sdk/src/deployments.ts (SHIELD_DEPLOYMENTS, keyed by (chainId, env)). The audit trail per (chainId, env) slot lives in deployments/{chainId}-{env}.json at the repo root — those JSON files travel with the source repo and are not loaded at SDK runtime. Calling createShield on an unsupported chain throws UnsupportedChainError; calling against a supported chain with no deployment recorded yet throws ShieldDeploymentNotFoundError. Either way, the SDK fails before any tx is sent.

Repository structure

sdk/
├── src/
│   ├── index.ts            ← top-level exports
│   ├── builder.ts          ← `createShield(...)` factory
│   ├── pack-runtime.ts     ← `buildIntentArgs` / `encodePackParams` helpers
│   ├── shield.ts           ← `NewtonShield` low-level runtime
│   ├── factory.ts          ← `predictShieldAddress` (CREATE2 derivation)
│   ├── gateway.ts          ← Newton Gateway HTTP/JSON-RPC client
│   └── vendors/<name>/     ← vendor module subpath modules
├── test/
├── package.json
├── tsconfig.json
├── tsup.config.ts          ← ESM + CJS + .d.ts build
├── vitest.config.ts
└── README.md

Pack code lives in newton-policy-packs; each pack publishes as its own @newton-xyz/policy-pack-<name> npm package on its own release cadence.

Local development

Requires Node ≥22 and pnpm ≥10. The SDK lives in a pnpm monorepo at the repo root.

# from repo root
pnpm install
pnpm --filter @newton-xyz/newton-shield-sdk build
pnpm --filter @newton-xyz/newton-shield-sdk typecheck
pnpm --filter @newton-xyz/newton-shield-sdk test

To test against a consumer app without publishing:

"@newton-xyz/newton-shield-sdk": "link:../newton-shield/sdk"

Versioning

Changesets for semver bumps. Public-surface changes get a .changeset/*.md entry per PR via pnpm changeset.

Vendor SDK breaking changes cascade through. Peer-dep versions are tracked, and any vendor-side breaking change is treated as a Shield SDK semver-major.

License

Apache-2.0