Reference - Docs | Magic Newton Foundation

Package

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

viem, zod, and @newton-xyz/policy-pack-shared are peer dependencies. Vendor SDKs, such as @morpho-org/blue-sdk-viem, are optional peer dependencies so applications only install the vault integrations they use.

Supported Chains

Chain	Chain ID
Ethereum	`1`
Base	`8453`
Sepolia	`11155111`
Base Sepolia	`84532`

Calling createShield on an unsupported chain errors before sending a transaction.

`createShield`

Creates or attaches to a Shield for a curator and vault. A newly created Shield client normally requires setParams(...) and uploadSecrets(...) before it can evaluate the selected policy.

const shield = await createShield({
  apiKey,
  policyClientAddress?,
  walletClient,
  rpc,
  env?,
  gatewayUrl?,
  pack,
  vault,
  version?,
  expectedParams?,
  skipPolicyBindingCheck?,
  mustDeploy?,
  bypassDelaySeconds?,
  attestationExpiration?,
  wsRpcUrl?,
})

Parameters

Field	Description
`apiKey`	Newton Gateway API key. Create one for your project on the dashboard.
`policyClientAddress?`	Shield contract address when attaching to a known deployed clone. Leave empty to deploy or attach based on curator, vault, and version.
`walletClient`	Viem wallet client for the signer that will own the Shield and sign intents. The account address participates in deterministic Shield addressing.
`rpc`	RPC URL used for sending transactions, polling chain state, and public-client reads.
`env?`	Newton Gateway environment. Defaults to `prod`.
`gatewayUrl?`	Custom Newton Gateway URL for testing. Defaults to the protocol URL for `env`.
`pack`	`CompositePolicyPack` from `defineComposite(...)`. See Composite Policy Packs.
`vault`	The vault address to be managed. The vault address is one of the deploy params that determines the shield address.
`version?`	Addressing nonce. Defaults to `0`. Use a different version when the same curator and vault need another Shield clone.
`expectedParams?`	Typed policy params expected on an existing Shield. If onchain params differ, the SDK errors instead of attaching.
`skipPolicyBindingCheck?`	Skips the policy pack and contract compatibility check when attaching. Use only for recovery or diagnostics.
`mustDeploy?`	Errors if `createShield` would attach to an existing clone. Use when a fresh deployment is required.
`bypassDelaySeconds?`	Timelock for owner bypass execution. Default is one week; minimum is one day.
`attestationExpiration?`	Number of blocks an approved policy action remains valid. Default is 50 blocks.
`wsRpcUrl?`	Optional websocket RPC URL used for standard attestation-mode polling. This mode is slower but can save gas.

Return Value

Calling createShield returns a Shield client object with these properties.

Property	Description
`pack`	The policy pack object that it was configured with. Useful as the policy pack method functions help with the typing of params and secrets objects.
`policyClientAddress`	Shield contract address created or attached to by the client.
`encodeParams`	Helper for encoding policy params into hex. Useful when comparing against onchain configuration.
`setParams`	Writes the versioned onchain manifest envelope to the Shield’s bound policy.
`uploadSecrets`	Encrypts and uploads policy secrets to Newton Gateway.
`sendCall`	Generic entrypoint for policy evaluation and intent execution.
`prepareIntent`	Builds and signs the intent without submitting it.
`extend`	Attaches a typed vendor overlay such as `shield.morpho.*`.

`setParams`

Configures a newly created Shield contract or reconfigures an existing one with serialized policy params. Uses the attestationExpiration value from Shield client creation.

await shield.setParams({
  vaultsfyi: {
    apy_z_max: 3,
    risk_score_floor: 80,
    tvl_drawdown_24h_max_pct: 25,
    tvl_drawdown_7d_max_pct: 40,
    deny_on_allocation_change: true,
    deny_on_critical_flag: true,
    deny_on_corrupted: true,
  },
})

Parameters

Field	Description
`params`	Typed parameter object from the selected policy pack.

`uploadSecrets`

Uploads required API secrets used by the selected policy pack. Values are encrypted in the SDK and stored with Newton Gateway for policy evaluation.

await shield.uploadSecrets({
  vaultsfyi: {
    VAULTS_FYI_API_KEY: process.env.VAULTSFYI_API_KEY!,
  },
})

Parameters

Field	Description
`secrets`	Typed secrets object from the selected policy pack.

Shield Runtime

The Shield runtime turns a typed call into:

Intent construction
Newton AVS policy evaluation
Policy attestation retrieval
Onchain execution through the Shield contract

The Shield client uses typed vendor overlays for supported protocols and keeps sendCall(...) as the escape hatch for unwrapped vendors.

import { createShield } from '@newton-xyz/vaultkit'
import { morphoActions } from '@newton-xyz/vaultkit/vendors/morpho'

const shield = (await createShield(config)).extend(morphoActions)

Morpho Module

The Morpho module exposes manager actions under shield.morpho.*. reallocate is positional in the published module:

await shield.morpho.reallocate(
  vault,
  [{ marketParams, assets: 1_000_000n }],
  { prepareQueryOptions: { vaultsfyi: { previousAllocationHash: '0x...' } } },
)

The overlay wraps MetaMorpho manager and allocator actions such as setCurator, setIsAllocator, submitCap, acceptCap, setSupplyQueue, updateWithdrawQueue, and reallocate. End-user deposit, mint, withdraw, and redeem flows are not wrapped.

`sendCall`

For vendors or actions without a first-class module, use sendCall. This function requires you to encode calldata for the delegated contract call yourself. Pack-specific prepareQueryOptions tell the composite policy what must be evaluated for this call.

await shield.sendCall({
  to: '0xTargetAddress',
  data: '0xCalldata',
  functionSignature: 'reallocate((bytes32,uint256)[])',
  prepareQueryOptions: {
    redstone: {
      symbol: 'USDC',
      rpcUrl: 'https://base.example',
      onchainOracle: {
        address: '0xOracleAddress',
        selector: 'latestAnswer()',
      },
    },
  },
}, 'DIRECT', 30_000)

When using sendCall, the integration owns intent integrity for the target call. Use 'DIRECT' for the current curator path. The lower-level runtime also has an attestation mode path for deployments that support it.

Composite Manifest

shield.setParams(...) writes a versioned UTF-8 JSON manifest into NewtonPolicy.PolicyConfig.policyParams. The manifest is the shape operators read and the AVS validates:

{
  "_manifest": { "magic": "NPM1", "version": 1 },
  "modules": [
    {
      "id": "vaultsfyi/risk-envelope/v1",
      "policyDataAddress": "0xVAULTSFYI_PD...",
      "wasmCid": "bafybei..."
    }
  ],
  "params": {
    "vaultsfyi": {
      "risk_score_floor": 80,
      "tvl_drawdown_24h_max_pct": 25
    }
  }
}

For the full verifier path and introspectComposite(...), see Composite Policy Packs.

Policy Packs

Policy packs are developed in newt-foundation/newton-policy-packs and are available as subpath imports:

import { vaultsfyi } from '@newton-xyz/policy-pack-vaultsfyi'

Each pack provides typed params and helper logic for freshness-bound policy inputs.

Errors

The SDK error hierarchy includes:

Error	When it occurs
`InvalidConfigurationError`	Error for when a parameter for `createShield` is invalid.
`IntentConfigurationError`	Intent submission parameters are malformed before network or chain submission.
`ParamMismatchError`	The expected params or param typing does not match the configuration of an attached Shield contract.
`PolicyMismatchError`	The expected policy from the pack does not match the configuration of an attached Shield contract.
`ShieldExecutionError`	The execution of the intent on chain encounters an error.
`PolicyDeniedError`	Newton evaluates the policy and denies the action.
`NewtonTaskEvaluationError`	Newton evaluation fails to evaluate the policy correctly.
`AttestationTimeoutError`	The SDK does not receive an attestation in time.
`GatewayError` / `GatewayHttpError` / `GatewayRpcError` / `GatewayTimeoutError`	The request fails to reach Newton Gateway or Gateway returns a protocol error.
`ConcurrentIntentError`	A second gated call was started against the same clone while another is in flight.
`ExtendCollisionError`	A vendor overlay would overwrite an existing client member.
`TransactionFailedError`	An onchain transaction failed outside the Shield-specific decode path.
`IntentMismatchError`	The task and task-response intents differ in direct execution.
`ShieldDeploymentNotFoundError`	ShieldClient creation tries to use a chain without Shield deployments.
`UnsupportedChainError`	ShieldClient creation tries to use a chain that is unsupported by the Newton Protocol.

​Package

​Supported Chains

​createShield

​Parameters

​Return Value

​setParams

​Parameters

​uploadSecrets

​Parameters

​Shield Runtime

​Morpho Module

​sendCall

​Composite Manifest

​Policy Packs

​Errors

​See Also

Package

Supported Chains

`createShield`

Parameters

Return Value

`setParams`

Parameters

`uploadSecrets`

Parameters

Shield Runtime

Morpho Module

`sendCall`

Composite Manifest

Policy Packs

Errors

See Also