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

## Installation

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

Node 22+ is required. `@newton-xyz/policy-core`, `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 reserved `_policy` params object.
* Chain reads are deferred until `createShield(...)`.

## `policyFromAddress`

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

Use this for a deployed monolithic or calldata-only policy. `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. |
| `policyAddress?` | `Address` | Required for `PolicyDraft`; omit for `BarePolicy`. |
| `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`. |
| `policyClientAddress?` | `Address` | Attach to a known address instead of predicting. |
| `expectedParams?` | `Record<string, unknown>` | Require canonical byte equality 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` | Per-call expiration override. |
| `wsRpcUrl?` | `string` | WebSocket RPC for subscription-based paths. |

## `ShieldClient`

| Member | Purpose |
| --- | --- |
| `policy` | Resolved policy address, chain, environment, params codec, and modules. |
| `verification` | Attach-time `VerificationResult`. |
| `policyClientAddress` | Onchain client address. |
| `setParams(params)` | Encode and store policy configuration. |
| `encodeParams(params)` | Return the exact encoded bytes without writing. |
| `uploadSecrets(secrets)` | Validate, encrypt, and upload per-module secrets. |
| `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 {
  to: Address
  data: Hex
  value?: bigint
  functionSignature: string
  prepareQueryOptions?: Record<string, unknown>
}
```

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

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

## `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`
* `introspectComposite`
* `classifyProvenance`
* Manifest encoders and decoders
* Composite params-schema derivation

VaultKit re-exports common policy types and `classifyProvenance`, 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
```

All SDK errors extend `ShieldError`. `NewtonShieldError` remains a deprecated compatibility alias.

## Related

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