# Reference \[API reference for `@newton-xyz/vaultkit` 3.0.]

## Installation

```bash
pnpm add @newton-xyz/vaultkit @newton-xyz/policy-core viem zod
```

Node 22+ is required. `@newton-xyz/policy-core` (`^0.3.0`), `viem`, and `zod` are peer dependencies. Morpho packages are optional peer dependencies and are only needed for the Morpho vendor modules.

```typescript
import { VERSION } from '@newton-xyz/vaultkit'
```

`VERSION` matches the installed package version.

## Supported Chains

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

## `definePolicy`

```typescript
function definePolicy(config: {
  chainId: string
  env: GatewayEnv
}): PolicyDraft<readonly []>
```

A `PolicyDraft` is immutable:

```typescript
const policy = definePolicy({ chainId: '8453', env: 'prod' })
  .with(vaultsfyi)
  .with(chainalysis)
  .withPolicyParams(policyParamsSchema)
```

* `.with(module)` appends a published pack or custom oracle.
* `.withPolicyParams(schema)` declares the params schema of the `_policy` gate, a pure-Rego policy in the set. It requires `policies._policy` at `createShield(...)`.
* Chain reads are deferred until `createShield(...)`.

## `policyFromAddress`

```typescript
function policyFromAddress(config: {
  address: Address
  chainId: string
  env: GatewayEnv
  params?: ParamCodec
}): BarePolicy
```

Use this for one deployed policy, such as a calldata-only Rego or one Rego with its own WASM oracle. The Shield binds it as a one-entry policy set. `ParamCodec` can supply `encode` and `decode` to enable params methods and higher verification rungs.

## `createShield`

```typescript
function createShield(config: CreateShieldConfig): Promise<ShieldClient>
```

| Field | Type | Notes |
| --- | --- | --- |
| `apiKey` | `string` | Newton Gateway key for the selected environment. |
| `walletClient` | `WalletClient` | Curator signer; its chain selects the deployment slot. |
| `rpc` | `string` | RPC URL for reads and writes. |
| `policy` | `PolicyDraft \| BarePolicy` | Policy declaration or bare deployed policy. |
| `policies?` | `{ <shortId>: Address, _policy?: Address }` | `PolicyDraft` only, and required there: each module's deployed `NewtonPolicy`, keyed by short pack ID, plus the optional `_policy` gate. Forbidden for a `BarePolicy`. |
| `expectedWasmCids?` | `{ <shortId>?: string }` | `PolicyDraft` only: pin a module policy deployed against an earlier WASM of its pack. |
| `vault` | `Address` | Managed target used in deterministic addressing. |
| `publicClient?` | `PublicClient` | Reuse an existing client for reads. |
| `env?` | `GatewayEnv` | Must agree with `policy.env` when provided. |
| `gatewayUrl?` | `string` | Gateway override for testing. |
| `version?` | `bigint` | Addressing version; defaults to `0n`. |
| `deployment?` | `ShieldDeployment` | A Shield factory to use instead of the published `SHIELD_DEPLOYMENTS` slot. |
| `policyClientAddress?` | `Address` | Attach to a known address instead of predicting. |
| `expectedParams?` | `Record<string, unknown>` | Require canonical byte equality for every policy at attach time. |
| `attachWithoutVerify?` | `boolean` | Explicit recovery-only escape below verification rung 1. |
| `mustDeploy?` | `boolean` | Fail if an existing deployment would be attached. |
| `bypassDelaySeconds?` | `bigint` | Deployment configuration; default seven days, minimum one day. |
| `attestationExpiration?` | `bigint` | The `expireAfter`, in blocks, that `setParams` binds each policy with; default 50. |
| `wsRpcUrl?` | `string` | WebSocket RPC for subscription-based paths. |

VaultKit 3.0.0 publishes no Shield factory deployment: every `SHIELD_DEPLOYMENTS` slot is `null`. `createShield(...)` throws `ShieldDeploymentNotFoundError` unless you attach to an existing clone with `policyClientAddress` or pass `deployment`.

## `ShieldClient`

| Member | Purpose |
| --- | --- |
| `policy` | Resolved policy set: `policies` (`{ id, address }[]`, in set order), `modules`, `chainId`, `env`, and a bare policy's params codec. |
| `verification` | Attach-time `VerificationResult`. |
| `policyClientAddress` | Onchain client address. |
| `setParams(params)` | Bind the policy set through `setPolicies`, one entry per policy. |
| `encodeParams(params)` | Return the `PolicySpec[]` that `setParams` would write, without writing. |
| `setPolicies(specs)` | Replace the whole policy set with a `PolicySpec[]` you build, for sets outside the module model. |
| `uploadSecrets(secrets)` | Validate, encrypt, and upload one envelope per module, scoped to that module's policy. A bare policy uses the `BARE_POLICY_ID` key, `'policy'`. |
| `sendCall(args, mode?, timeoutMs?)` | Evaluate and execute a generic manager action. |
| `assertIntentBlocked(args, timeoutMs?)` | Confirm that a denied intent is rejected, without mining a transaction. |
| `prepareIntent(args)` | Build and sign an intent without submitting it. |
| `reverify()` | Refresh the verification result against current state. |
| `extend(vendorActions)` | Add a typed vendor namespace. |

## `SendCallArgs`

```typescript
interface SendCallArgs<TModules> {
  to: Address
  data: Hex
  value?: bigint
  functionSignature: string
  prepareQueryOptions?: PrepareQueryOptions<TModules>
}
```

`prepareQueryOptions` is keyed by short pack ID, and each value is typed to that module's own options. There is no per-call `wasmArgs` field; see [Per-Call Inputs](/developers/vaults/sdk/policies#per-call-inputs).

```typescript
interface PolicySpec {
  policy: Address
  config: {
    policyParams: Hex
    expireAfter: number
  }
}
```

```typescript
type SubmissionMode = 'ATTESTATION' | 'DIRECT'

interface SendCallResult {
  transactionHash: Hex
  taskId: Hex
  evaluationResult: boolean
}
```

Only `'DIRECT'` works in VaultKit 3.0. The type still lists `'ATTESTATION'`, but that path throws `unimplemented, waiting for merge`.

## `assertIntentBlocked`

```typescript
interface PolicyBlockedResult {
  blocked: true
  taskId: Hex
  reason: string
}
```

The method expects a denial, simulates the denied direct execution with `eth_call`, and resolves only if the revert is `InvalidAttestation`.

It can throw:

* `PolicyNotDeniedError` when the supplied action was allowed.
* `NotApprovedDelegateError` when the wallet is not authorized to call the client.
* `PolicyDeniedError` when the gateway denial cannot be submitted as the negative assertion requires.
* The decoded error for any unrelated revert.

## Verification

```typescript
interface VerificationResult {
  achievedRung: 0 | 1 | 2 | 3 | 4
  addressChecked: boolean
  oracleSetChecked: boolean
  paramsChecked: boolean
  byteEqualChecked: boolean
  skippedReason?: 'attachWithoutVerify' | 'freshDeploy'
}
```

A bare policy's empty oracle set satisfies the structural check vacuously. Check `client.policy.modules.length > 0` before presenting "oracle set verified" in a UI.

## Gateway Client

```typescript
function createGatewayClient(config: GatewayClientConfig): GatewayClient
function resolveGatewayUrl(
  chainId: SupportedChainId,
  env: GatewayEnv,
): string
```

Construct a gateway client directly only for lower-level calls such as task creation, policy simulation, or encrypted-secret storage.

## Deployment Utilities

```typescript
const SHIELD_DEPLOYMENTS: ShieldDeploymentRegistry
const SUPPORTED_CHAINS: readonly SupportedChainId[]
const GATEWAY_API_URLS: Record<string, string>

function predictShieldAddress(args: PredictShieldAddressArgs): Address
function resolveShieldDeployment(
  chainId: number,
  env?: GatewayEnv,
  registry?: ShieldDeploymentRegistry,
): ShieldDeployment
function isSupportedChainId(value: unknown): value is SupportedChainId
function isGatewayEnv(value: unknown): value is GatewayEnv
```

## Vendor Subpaths

```typescript
import { morphoActions } from '@newton-xyz/vaultkit/vendors/morpho'
import { morphoBlueActions } from '@newton-xyz/vaultkit/vendors/morpho-blue'
import { eulerActions } from '@newton-xyz/vaultkit/vendors/euler'
import { eulerVaultActions } from '@newton-xyz/vaultkit/vendors/euler-vault'
import { superformActions } from '@newton-xyz/vaultkit/vendors/superform'
```

Each extension adds its own namespace. `extend(...)` throws `ExtendCollisionError` if an extension would overwrite an existing member.

## Policy Core

Import these directly from `@newton-xyz/policy-core`:

* `defineOracle`
* `defineComposite`
* `encodeCompositePolicyPack`
* `generateCompositeParamsSchema`
* `introspectComposite`
* `getPolicyManifest`
* `classifyProvenance`

VaultKit re-exports common policy types, `classifyProvenance`, and the composite error classes, but authoring and inspection utilities such as `defineOracle` and `defineComposite` come directly from `policy-core`.

## Error Guard

```typescript
function isShieldError(error: unknown): error is ShieldError
```

VaultKit's own errors extend `ShieldError`. `NewtonShieldError` remains a deprecated compatibility alias. The re-exported `policy-core` errors, such as `PolicyWasmCidMismatchError` and `CompositeModuleSetMismatchError`, extend plain `Error`, so code that calls both layers needs both catch arms.

## Related

* [Policies](/developers/vaults/sdk/policies)
* [Custom Oracles](/developers/vaults/sdk/custom-oracles)
* [Errors](/developers/vaults/sdk/errors)