Newton Protocol SDK Reference

Official TypeScript SDK for the Newton Protocol. This page provides a complete reference for all exported methods, types, interfaces, and utilities in the @newton-xyz/sdk package.

The SDK integrates with viem by extending PublicClient and WalletClient instances with Newton-specific actions. Make sure you are familiar with viem basics before proceeding.

Installation

npm install @newton-xyz/sdk

pnpm add @newton-xyz/sdk

yarn add @newton-xyz/sdk

Requirements:

Node.js >= 20
Package manager: pnpm >= 9 (recommended)

Dependencies:

Package	Version	Purpose
`viem`	^2.35.1	Ethereum client library
`jose`	^6.0.13	JWT / cryptographic operations
`eventemitter3`	^4.0.4	Event handling

Overview

The SDK is organized into two main client extensions:

Extension	Purpose	Client Type
`newtonPublicClientActions`	Read-only operations (query tasks, policy state)	`PublicClient`
`newtonWalletClientActions`	Write operations (submit evaluations, manage policies)	`WalletClient`

For a step-by-step walkthrough of integrating these into your application, see the Integration Guide. For the underlying JSON-RPC methods the SDK calls, see the RPC API Reference.

Setup & Initialization

Newton Protocol currently supports Ethereum Sepolia (chain ID 11155111), Base Sepolia (chain ID 84532), Ethereum Mainnet (chain ID 1), and Base (chain ID 8453). Pass the corresponding chain object from viem/chains when constructing your clients.

newtonPublicClientActions

Extends a viem PublicClient with Newton Protocol read methods.

import { createPublicClient, http } from 'viem';
import { sepolia, baseSepolia, base } from 'viem/chains';
import { newtonPublicClientActions } from '@newton-xyz/sdk';

const publicClient = createPublicClient({
  chain: sepolia,        // or baseSepolia, base, mainnet
  transport: http('<RPC_URL>'),
}).extend(
  newtonPublicClientActions({
    policyContractAddress: '0x...', // optional
  })
);

Signature:

function newtonPublicClientActions(
  options?: {
    policyContractAddress?: Address;
  },
  overrides?: SdkOverrides
): (publicClient: PublicClient) => NewtonPublicClientMethods;

Parameters:

Parameter	Type	Required	Description
`options.policyContractAddress`	`Address`	No	Scopes all policy read calls to this contract address
`overrides`	`SdkOverrides`	No	Override default SDK configuration

newtonWalletClientActions

Extends a viem WalletClient with Newton Protocol write methods.

import { createWalletClient, http } from 'viem';
import { sepolia, baseSepolia, base } from 'viem/chains';
import { newtonWalletClientActions } from '@newton-xyz/sdk';

const walletClient = createWalletClient({
  chain: sepolia,        // or baseSepolia, base, mainnet
  transport: http('<RPC_URL>'),
}).extend(
  newtonWalletClientActions({
    apiKey: '<YOUR_API_KEY>',
    policyContractAddress: '0x...', // optional
  })
);

Signature:

function newtonWalletClientActions(
  config: {
    apiKey: string;
    policyContractAddress?: Address;
  },
  overrides?: SdkOverrides
): (walletClient: WalletClient) => NewtonWalletClientMethods;

Parameters:

Parameter	Type	Required	Description
`config.apiKey`	`string`	Yes	Newton Protocol API key for gateway authentication
`config.policyContractAddress`	`Address`	No	Default policy contract address for write operations
`overrides`	`SdkOverrides`	No	Override default SDK configuration

Your API key authenticates requests to the Newton Gateway. Keep it secret and never expose it in client-side code.

SdkOverrides

Optional configuration to override default SDK endpoints and contract addresses.

interface SdkOverrides {
  gatewayApiUrl?: string;
  taskManagerAddress?: Address;
  attestationValidatorAddress?: Address;
  newtonIdpUrl?: string;
  identityRegistry?: Address;
}

Field	Type	Description
`gatewayApiUrl`	`string`	Custom Newton Gateway API URL
`taskManagerAddress`	`Address`	Custom TaskManager contract address
`attestationValidatorAddress`	`Address`	Custom AttestationValidator contract address
`newtonIdpUrl`	`string`	Custom Newton identity provider URL
`identityRegistry`	`Address`	Custom IdentityRegistry contract address

Wallet Client Methods (Write)

These methods are available after extending a WalletClient with newtonWalletClientActions.

submitEvaluationRequest

Submits an intent evaluation request to the Newton Protocol via the gateway. The task is created on-chain and operators evaluate the intent against the policy. Returns a PendingTaskBuilder that can be used to await the task response.

const { result, waitForTaskResponded } = await walletClient.submitEvaluationRequest({
  policyClient: '0x...',
  intent: {
    from: '0x...',
    to: '0x...',
    value: '0x0',
    data: '0x...',
    chainId: '0xaa36a7', // Ethereum Sepolia (11155111)
    functionSignature: '0x...',
  },
  timeout: 60000,
});

console.log(result.taskId);  // Hex
console.log(result.txHash);  // Hex

// Optionally wait for the on-chain response
const response = await waitForTaskResponded({ timeoutMs: 120000 });

Signature:

submitEvaluationRequest(
  args: SubmitEvaluationRequestParams
): Promise<{ result: { taskId: Hex; txHash: Hex } } & PendingTaskBuilder>

Parameters:

Parameter	Type	Required	Description
`policyClient`	`Address`	Yes	The policy client contract address
`intent`	`IntentFromParams`	Yes	The intent to evaluate
`timeout`	`number`	Yes	Request timeout in seconds
`proofCid`	`string`	No	IPFS CID of a TLSNotary presentation proof for zkTLS-backed evaluation
`includeValidateCalldata`	`boolean`	No	Include ABI-encoded `validateAttestationDirect` calldata in the response

Returns: An object containing:

result.taskId (Hex) — The unique task identifier
result.txHash (Hex) — The transaction hash
waitForTaskResponded({ timeoutMs? }) — A method to await the on-chain attestation result

The validate_calldata and operator_errors fields are available on the raw GatewayCreateTaskResult returned by the newt_createTask RPC method (see the RPC API Reference). These fields are not surfaced by the SDK’s submitEvaluationRequest or evaluateIntentDirect wrappers — call the gateway RPC directly when you need them.

evaluateIntentDirect

Evaluates an intent directly through the gateway without waiting for on-chain task response confirmation. Results are intended for use with validateAttestationDirect on NewtonPolicyClient (NewtonProverTaskManagerShared).

const domain = await readEip712Domain(policyClient, publicClient);
if (!domain) {
  throw new Error(
    "This policy client does not expose an EIP-712 domain, so the app cannot sign an intent for it.",
  );
}

const intent = {
  from: account.address,
  to: '0x...',
  value: '0x0',
  data: '0x',
  chainId: 11155111,
  functionSignature: '0x',
} as const;

const intentSignature = await walletClient.signTypedData({
  account,
  domain,
  types: {
    Intent: [
      { name: 'from', type: 'address' },
      { name: 'to', type: 'address' },
      { name: 'value', type: 'uint256' },
      { name: 'data', type: 'bytes' },
      { name: 'chainId', type: 'uint256' },
      { name: 'functionSignature', type: 'bytes' },
    ],
  },
  primaryType: 'Intent',
  message: {
    ...intent,
    value: BigInt(intent.value),
    chainId: BigInt(intent.chainId),
  },
});

const { result } = await walletClient.evaluateIntentDirect({
  policyClient,
  intent,
  intentSignature,
  timeout: 30000,
});

console.log(result.evaluationResult); // boolean
console.log(result.task);             // Task object
console.log(result.taskResponse);     // Raw task response
console.log(result.blsSignature);     // BLS signature data

Signature:

evaluateIntentDirect(
  args: SubmitEvaluationRequestParams
): Promise<{
  result: {
    evaluationResult: boolean;
    task: Task;
    taskResponse: unknown;
    blsSignature: unknown;
  };
}>

Parameters:

Parameter	Type	Required	Description
`policyClient`	`Address`	Yes	The policy client contract address
`intent`	`IntentFromParams`	Yes	The intent to evaluate. `chainId` must be `11155111` (Ethereum Sepolia), `84532` (Base Sepolia), or `8453` (Base).
`intentSignature`	`Hex`	No	EIP-712 signature of the exact intent. Optional in the SDK type, but required by policies and identity flows that read `input.intent_signature`.
`timeout`	`number`	No	Request timeout in milliseconds

Returns:

result.evaluationResult (boolean) — Whether the intent was allowed by the policy
result.task (Task) — The full task object
result.taskResponse — The raw task response from the operator
result.blsSignature — The BLS aggregate signature

Some policy clients and identity-backed flows require intentSignature even though it is optional in the base request type. If you omit it or pass "0x", the gateway can fail before policy evaluation with Failed to encode intent signature: 0x reason: expected exactly 65 bytes.

Read the EIP-712 domain from the policy client whenever possible. Dashboard-deployed clients expose EIP-5267 eip712Domain(), which binds the signature to the correct name, version, chainId, and verifyingContract.

import type { Address } from 'viem';

const EIP712_DOMAIN_ABI = [
  {
    type: 'function',
    name: 'eip712Domain',
    stateMutability: 'view',
    inputs: [],
    outputs: [
      { name: 'fields', type: 'bytes1' },
      { name: 'name', type: 'string' },
      { name: 'version', type: 'string' },
      { name: 'chainId', type: 'uint256' },
      { name: 'verifyingContract', type: 'address' },
      { name: 'salt', type: 'bytes32' },
      { name: 'extensions', type: 'uint256[]' },
    ],
  },
] as const;

export async function readEip712Domain(
  policyClient: Address,
  publicClient,
) {
  try {
    const [, name, version, chainId, verifyingContract] =
      await publicClient.readContract({
        address: policyClient,
        abi: EIP712_DOMAIN_ABI,
        functionName: 'eip712Domain',
      });

    return {
      name,
      version,
      chainId: Number(chainId),
      verifyingContract,
    };
  } catch {
    return null;
  }
}

If you deploy a custom policy client that does not implement EIP-5267, hardcoded signing domains must match the contract’s EIP712(name, version) constructor values and the deployed policy client address.

submitIntentAndSubscribe

Submits a task via newt_sendTask and opens a WebSocket connection to receive the evaluation result. Results are intended for use with validateAttestation on NewtonProverTaskManager (the on-chain task verification path).

const { result, ws } = await walletClient.submitIntentAndSubscribe({
  policyClient: '0x...',
  intent: {
    from: '0x...',
    to: '0x...',
    value: '0x0',
    data: '0x...',
    chainId: 11155111,
    functionSignature: '0x...',
  },
  timeout: 30,
});

console.log(result.task_id);             // Hex task identifier
console.log(result.subscription_topic);  // WebSocket topic

// Listen for the task response
ws.onmessage = (event) => {
  const taskResponse = JSON.parse(event.data);
  console.log(taskResponse);
};

Signature:

submitIntentAndSubscribe(
  args: SubmitEvaluationRequestParams
): Promise<{
  result: SubmitIntentResult;
  ws: WebSocket;
}>

Parameters:

Parameter	Type	Required	Description
`policyClient`	`Address`	Yes	The policy client contract address
`intent`	`IntentFromParams`	Yes	The intent to evaluate. `chainId` must be `11155111` (Ethereum Sepolia), `84532` (Base Sepolia), or `8453` (Base).
`timeout`	`number`	No	Request timeout in seconds

Returns:

result.message (string) — Status message from the gateway
result.subscription_topic (string) — WebSocket topic to subscribe to for task updates
result.task_id (Hex) — 32-byte task identifier
result.timestamp (number) — Task creation timestamp
ws (WebSocket) — Active WebSocket connection subscribed to the task topic

SubmitIntentResult type:

interface SubmitIntentResult {
  message: string;
  subscription_topic: string;
  task_id: Hex;
  timestamp: number;
}

Use submitIntentAndSubscribe when you need on-chain task verification via NewtonProverTaskManager.validateAttestation. Use evaluateIntentDirect for the simpler direct validation path via PolicyClient.validateAttestationDirect.

simulateTask

Simulates task evaluation (newt_simulateTask). Forwards the task to an operator and returns an allow/deny result without executing on-chain. See the RPC API Reference for the underlying JSON-RPC method.

const result = await walletClient.simulateTask({
  intent: {
    from: '0x...',
    to: '0x...',
    value: '0x0',
    data: '0x...',
    chainId: 11155111, // Ethereum Sepolia; use 84532 for Base Sepolia or 8453 for Base
    functionSignature: '0x...',
  },
  policyTaskData: {
    policyId: '0x...',
    policyAddress: '0x...',
    policy: '0x...',
    policyData: [
      {
        wasmArgs: '0x',
        data: '0x...',
        attestation: '0x...',
        policyDataAddress: '0x...',
        expireBlock: 999999,
      },
    ],
  },
});

console.log(result.success);
console.log(result.result?.allow);
console.log(result.result?.reason);
console.log(result.error);

Signature:

simulateTask(args: SimulateTaskParams): Promise<SimulateTaskResult>

simulatePolicy

Simulates full Rego policy evaluation (newt_simulatePolicy). Tests a policy with a sample intent and policy data. May require ownership if PolicyData uses stored secrets.

const result = await walletClient.simulatePolicy({
  policyClient: '0x...',
  policy: '<rego-policy-string>',
  intent: {
    from: '0x...',
    to: '0x...',
    value: '0x0',
    data: '0x...',
    chainId: 11155111, // Ethereum Sepolia; use 84532 for Base Sepolia or 8453 for Base
    functionSignature: '0x...',
  },
  policyData: [
    { policyDataAddress: '0x...' },
  ],
  policyParams: { max_amount: 1000 },
  entrypoint: 'newton/policy/allow',
});

console.log(result.success);
console.log(result.evaluation_result);
console.log(result.error);

Signature:

simulatePolicy(args: SimulatePolicyParams): Promise<SimulatePolicyResult>

simulatePolicyData

Simulates PolicyData WASM execution (newt_simulatePolicyData) with caller-provided secrets. No ownership verification is required.

const result = await walletClient.simulatePolicyData({
  policyDataAddress: '0x...',
  secrets: '<secrets-json-string>',
  wasmArgs: '0x...',
  chainId: 11155111, // required
});

console.log(result.success);
console.log(result.policy_data?.specifier);
console.log(result.policy_data?.data);

Signature:

simulatePolicyData(
  args: SimulatePolicyDataParams
): Promise<SimulatePolicyDataResult>

simulatePolicyDataWithClient

Simulates PolicyData WASM execution (newt_simulatePolicyDataWithClient) using stored secrets for a policy client. Requires ownership of the policy client.

const result = await walletClient.simulatePolicyDataWithClient({
  policyDataAddress: '0x...',
  policyClient: '0x...',
  wasmArgs: '0x...',
});

console.log(result.success);
console.log(result.policy_data?.specifier);

Signature:

simulatePolicyDataWithClient(
  args: SimulatePolicyDataWithClientParams
): Promise<SimulatePolicyDataWithClientResult>

initialize

Initializes a Newton Policy contract with the given configuration. This is a one-time setup call. The contract requires keccak256 of the Rego policy bytes as _policyCodeHash so the on-chain hash matches the policy referenced by policyCid. Provide it one of two ways:

policyCodeHash — pre-computed hex hash (from policy_cids.json or another out-of-band source). Takes precedence when both are set.
policyBytes — the raw Rego policy bytes; the SDK computes keccak256 for you. Useful when fetching from IPFS via policyCid, reading a local file, or any other transport.

const txHash = await walletClient.initialize({
  factory: '0x...',
  entrypoint: 'newton/policy/allow',
  policyCid: 'bafyrei...',
  schemaCid: 'bafyrei...',
  policyData: ['0x...', '0x...'],
  metadataCid: 'bafyrei...',
  owner: '0x...',
  policyBytes: await fetchPolicyBytes(policyCid),
});

Signature:

type InitializePolicyArgs = {
  factory: Address;
  entrypoint: string;
  policyCid: string;
  schemaCid: string;
  policyData: Address[];
  metadataCid: string;
  owner: Address;
} & ({ policyCodeHash: Hex } | { policyBytes: Uint8Array });

initialize(args: InitializePolicyArgs): Promise<`0x${string}`>

Parameters:

Parameter	Type	Required	Description
`factory`	`Address`	Yes	Address of the deploying factory contract
`entrypoint`	`string`	Yes	Policy entrypoint path (e.g., `"newton/policy/allow"`)
`policyCid`	`string`	Yes	Content identifier (CID) of the policy WASM
`schemaCid`	`string`	Yes	Content identifier (CID) of the policy schema
`policyData`	`Address[]`	Yes	Array of PolicyData contract addresses
`metadataCid`	`string`	Yes	Content identifier (CID) of the policy metadata
`owner`	`Address`	Yes	Owner address of the policy contract
`policyCodeHash`	`Hex`	One of these two	Pre-computed `keccak256` of the Rego policy bytes
`policyBytes`	`Uint8Array`	One of these two	Raw Rego policy bytes; SDK computes `keccak256(policyBytes)` for you

Returns: `0x${string}` — The transaction hash.

renounceOwnership

Renounces ownership of the policy contract. After calling this, no one will be able to perform owner-restricted actions.

This action is irreversible. Once ownership is renounced, administrative operations on the policy contract can never be performed again.

const txHash = await walletClient.renounceOwnership();

Signature:

renounceOwnership(): Promise<`0x${string}`>

transferOwnership

Transfers ownership of the policy contract to a new address.

const txHash = await walletClient.transferOwnership({
  newOwner: '0x...',
});

Signature:

transferOwnership(args: {
  newOwner: Address;
}): Promise<`0x${string}`>

Identity Methods

These methods interact with the Newton Identity Provider for verified credential flows. They open a popup window for user interaction.

connectIdentityWithNewton

Connects the user’s identity with Newton via the identity provider popup.

await walletClient.connectIdentityWithNewton({
  appWalletAddress: '0x...',
  appClientAddress: '0x...',
});

Signature:

connectIdentityWithNewton(args: {
  appWalletAddress: Address;
  appClientAddress: Address;
}): Promise<unknown>

registerUserData

Registers KYC user data through the identity provider popup.

await walletClient.registerUserData({
  userData: {
    status: 'approved',
    selected_country_code: 'US',
    address_subdivision: 'CA',
    address_country_code: 'US',
    birthdate: '1990-01-15',
    expiration_date: '2030-01-15',
    issue_date: '2020-01-15',
    issuing_authority: 'US_DL',
  },
  appIdentityDomain: '0x...',
  policyClient: '0xYourPolicyClientAddress',
});

Signature:

registerUserData(args: {
  userData: KycUserData;
  appIdentityDomain: Hex;
  policyClient: Address;
}): Promise<unknown>

linkApp

Links an application to the user’s Newton identity.

await walletClient.linkApp({
  appWalletAddress: '0x...',
  appClientAddress: '0x...',
  appIdentityDomain: '0x...',
});

Signature:

linkApp(args: {
  appWalletAddress: Address;
  appClientAddress: Address;
  appIdentityDomain: Hex;
}): Promise<unknown>

unlinkApp

Unlinks an application from the user’s Newton identity.

await walletClient.unlinkApp({
  appWalletAddress: '0x...',
  appClientAddress: '0x...',
  appIdentityDomain: '0x...',
});

Signature:

unlinkApp(args: {
  appWalletAddress: Address;
  appClientAddress: Address;
  appIdentityDomain: Hex;
}): Promise<unknown>

Privacy Methods

These methods are available on the wallet client for privacy-preserving policy evaluation using client-side HPKE encryption. They are also exported as standalone functions from the package.

getPrivacyPublicKey

Fetches the Newton Gateway’s X25519 HPKE public key for encrypting data.

const { public_key, key_type, encryption_suite } = await walletClient.getPrivacyPublicKey();

Signature:

getPrivacyPublicKey(): Promise<PrivacyPublicKeyResponse>

Returns:

public_key (string) — The gateway’s X25519 public key (hex-encoded)
key_type (string) — Key type identifier
encryption_suite (string) — HPKE suite identifier

createSecureEnvelope

Creates an HPKE-encrypted envelope from plaintext. Runs entirely offline with zero network calls.

const signingKeyPair = walletClient.generateSigningKeyPair();
const { envelope, signature, senderPublicKey } = await walletClient.createSecureEnvelope(
  {
    plaintext: { secret: 'value' },
    policyClient: '0x...',
    chainId: 11155111,
    recipientPublicKey: '<gateway-public-key>',
  },
  signingKeyPair.privateKey // Uint8Array from generateSigningKeyPair()
);

Signature:

createSecureEnvelope(
  args: CreateSecureEnvelopeParams,
  signingKey: Uint8Array
): Promise<SecureEnvelopeResult>

Parameters:

Parameter	Type	Required	Description
`args.plaintext`	`Uint8Array \| string \| Record<string, unknown>`	Yes	Data to encrypt (objects are JSON-stringified)
`args.policyClient`	`Address`	Yes	PolicyClient address (bound via AAD)
`args.chainId`	`number`	Yes	Chain ID (bound via AAD)
`args.recipientPublicKey`	`string`	Yes	Gateway’s X25519 public key
`signingKey`	`Uint8Array`	Yes	Ed25519 private key seed (32 bytes)

getSecretsPublicKey

Fetches the Newton Gateway’s X25519 HPKE public key for encrypting WASM secrets. In threshold DKG mode, this returns a different key than getPrivacyPublicKey.

const { public_key, key_type, encryption_suite } = await walletClient.getSecretsPublicKey();

Signature:

getSecretsPublicKey(): Promise<SecretsPublicKeyResponse>

Returns:

public_key (string) — The gateway’s X25519 public key (hex-encoded)
key_type (string) — Key type identifier
encryption_suite (string) — HPKE suite identifier

uploadIdentityEncrypted

Uploads HPKE-encrypted identity data to the Newton Gateway. The caller must provide a pre-built SecureEnvelope (via createSecureEnvelope) and an EIP-712 signature of the envelope JSON from the identity owner. The gateway stores the envelope and returns a data_ref_id + gateway signature for the on-chain registerIdentityData call.

const { data_ref_id, gateway_signature, deadline } = await walletClient.uploadIdentityEncrypted({
  identityOwner: '0x...',
  identityOwnerSig: '0x...', // EIP-712 signature of the envelope JSON
  envelope: JSON.stringify(envelope),
  identityDomain: identityDomainHash('kyc'),
  chainId: 11155111,
});

Signature:

uploadIdentityEncrypted(
  args: UploadIdentityEncryptedParams
): Promise<UploadIdentityEncryptedResponse>

Returns:

data_ref_id (string) — Content-hash data reference ID: keccak256(envelope_json_bytes)
gateway_signature (string) — Gateway EIP-712 signature for registerIdentityData on-chain call
deadline (number) — Signature expiration (unix timestamp)

getIdentityEncrypted

Fetches encrypted identity data by its content-hash reference ID. Used to resolve a data_ref_id (stored on-chain in IdentityRegistry) back to the encrypted data blob (stored off-chain in the gateway).

const { envelope, identity_domain, identity_owner } = await walletClient.getIdentityEncrypted({
  dataRefId: 'abc123...',
});

Signature:

getIdentityEncrypted(
  args: { dataRefId: string }
): Promise<GetIdentityEncryptedResult>

Returns:

envelope (string) — The HPKE-encrypted identity data as a SecureEnvelope JSON string
identity_domain (string) — The identity domain this data was registered under
identity_owner (string) — The identity owner address

generateSigningKeyPair

Generates a random Ed25519 key pair for privacy authorization signatures.

const { privateKey, publicKey } = walletClient.generateSigningKeyPair();
// Both are 32-byte hex strings without 0x prefix

Signature:

generateSigningKeyPair(): Ed25519KeyPair

This is a synchronous method. Keys are generated locally and never sent to any server.

storeEncryptedSecrets

Encrypts plaintext secrets client-side with HPKE and uploads the envelope to the gateway for a PolicyClient’s PolicyData oracle. The gateway’s X25519 public key is fetched automatically if not provided.

const { success } = await walletClient.storeEncryptedSecrets({
  policyClient: '0x...',
  policyDataAddress: '0x...',
  plaintext: { API_KEY: 'sk-...', ENDPOINT: 'https://api.example.com' },
  chainId: 11155111,
});

Signature:

storeEncryptedSecrets(
  args: StoreEncryptedSecretsParams
): Promise<StoreEncryptedSecretsResponse>

signPrivacyAuthorization

Computes dual Ed25519 signatures (user + app) for privacy-enabled task creation. Runs entirely offline.

const { userSignature, appSignature, userPublicKey, appPublicKey } =
  walletClient.signPrivacyAuthorization({
    policyClient: '0x...',
    intentHash: '0x...',
    encryptedDataRefs: ['ref-id-1', 'ref-id-2'],
    userSigningKey: '<user-ed25519-private-key>',
    appSigningKey: '<app-ed25519-private-key>',
  });

Signature:

signPrivacyAuthorization(
  args: SignPrivacyAuthorizationParams
): PrivacyAuthorizationResult

This is a synchronous method. Signatures are computed locally.

Webhook Methods

registerWebhook

Registers a webhook URL to receive task failure notifications. The gateway sends HMAC-SHA256 signed payloads to the registered URL when tasks fail.

const { success, message } = await walletClient.registerWebhook({
  url: 'https://example.com/newton-webhook',
  secret: 'my-hmac-secret',
  timeoutSeconds: 10,
  maxRetries: 3,
  failureTypes: ['timeout', 'quorum_not_reached'],
});

Signature:

registerWebhook(args: RegisterWebhookParams): Promise<RegisterWebhookResult>

Parameters:

Parameter	Type	Required	Description
`url`	`string`	Yes	Webhook URL (must be HTTPS, or `http://localhost` for testing)
`secret`	`string`	No	HMAC secret for payload signing (recommended)
`timeoutSeconds`	`number`	No	Request timeout in seconds (default: 10)
`maxRetries`	`number`	No	Maximum retry attempts (default: 3)
`failureTypes`	`TaskFailureType[]`	No	Failure types to notify about (default: all)

unregisterWebhook

Removes the registered webhook for the current API key.

const { success, message } = await walletClient.unregisterWebhook();

Signature:

unregisterWebhook(): Promise<UnregisterWebhookResult>

Identity Methods

These methods handle identity data registration and identity-to-PolicyClient linking via direct contract calls to the IdentityRegistry. They are also exported as standalone functions from the package.

registerIdentityData

Register an identity data reference on-chain. The identity owner (caller) submits a data_ref_id obtained from the gateway’s newt_uploadIdentityEncrypted RPC, along with the gateway’s co-signature and deadline.

await walletClient.registerIdentityData({
  identityDomain: identityDomainHash('kyc'),
  dataRefId: 'QmEncryptedDataRef...',
  gatewaySignature: '0x...', // from newt_uploadIdentityEncrypted response
  deadline: 1700000000n,      // from newt_uploadIdentityEncrypted response
})

Signature:

registerIdentityData(args: RegisterIdentityDataParams): Promise<Hex>

The contract verifies the gateway signature against REGISTER_IDENTITY_TYPEHASH and checks that the signer is a registered task generator via isTaskGenerator(). Overwrites are allowed — users can update their identity data reference by calling this again.

linkIdentityAsSignerAndUser

Link identity data when the caller is both the identity owner and the client user. The simplest linking flow — no counterparty signatures needed.

await walletClient.linkIdentityAsSignerAndUser({
  policyClient: '0xPolicyClientAddress',
  identityDomains: [identityDomainHash('kyc')],
});

Signature:

linkIdentityAsSignerAndUser(args: LinkIdentityAsSignerAndUserParams): Promise<Hex>

Parameters:

Parameter	Type	Description
`policyClient`	`Address`	PolicyClient contract address
`identityDomains`	`Hex[]`	Array of domain hashes (use `identityDomainHash()`)

Returns: Transaction hash (Hex).

linkIdentityAsSigner

Link identity data as the identity owner (signer). Requires a counterparty EIP-712 signature from the client user.

await walletClient.linkIdentityAsSigner({
  policyClient: '0xPolicyClientAddress',
  identityDomains: [identityDomainHash('kyc')],
  clientUser: '0xClientUserAddress',
  clientUserSignature: '0x...',
  clientUserNonce: 0n,
  clientUserDeadline: BigInt(Math.floor(Date.now() / 1000) + 3600),
});

Signature:

linkIdentityAsSigner(args: LinkIdentityAsSignerParams): Promise<Hex>

Parameters:

Parameter	Type	Description
`policyClient`	`Address`	PolicyClient contract address
`identityDomains`	`Hex[]`	Array of domain hashes
`clientUser`	`Address`	The client user’s address
`clientUserSignature`	`Hex`	EIP-712 signature from the client user
`clientUserNonce`	`bigint`	Nonce for the client user’s signature
`clientUserDeadline`	`bigint`	Deadline timestamp for the signature

Returns: Transaction hash (Hex).

linkIdentityAsUser

Link identity data as the client user. Requires a counterparty EIP-712 signature from the identity owner.

await walletClient.linkIdentityAsUser({
  identityOwner: '0xIdentityOwnerAddress',
  policyClient: '0xPolicyClientAddress',
  identityDomains: [identityDomainHash('kyc')],
  identityOwnerSignature: '0x...',
  identityOwnerNonce: 0n,
  identityOwnerDeadline: BigInt(Math.floor(Date.now() / 1000) + 3600),
});

Signature:

linkIdentityAsUser(args: LinkIdentityAsUserParams): Promise<Hex>

Parameters:

Parameter	Type	Description
`identityOwner`	`Address`	The identity owner’s address
`policyClient`	`Address`	PolicyClient contract address
`identityDomains`	`Hex[]`	Array of domain hashes
`identityOwnerSignature`	`Hex`	EIP-712 signature from the identity owner
`identityOwnerNonce`	`bigint`	Nonce for the identity owner’s signature
`identityOwnerDeadline`	`bigint`	Deadline timestamp for the signature

Returns: Transaction hash (Hex).

linkIdentity

Link identity data as a 3rd party with EIP-712 signatures from both the identity owner and the client user. Signature:

linkIdentity(args: LinkIdentityParams): Promise<Hex>

Parameters:

Parameter	Type	Description
`identityOwner`	`Address`	The identity owner’s address
`clientUser`	`Address`	The client user’s address
`policyClient`	`Address`	PolicyClient contract address
`identityDomains`	`Hex[]`	Array of domain hashes
`identityOwnerSignature`	`Hex`	EIP-712 signature from the identity owner
`identityOwnerNonce`	`bigint`	Nonce for the identity owner’s signature
`identityOwnerDeadline`	`bigint`	Deadline timestamp for the owner signature
`clientUserSignature`	`Hex`	EIP-712 signature from the client user
`clientUserNonce`	`bigint`	Nonce for the client user’s signature
`clientUserDeadline`	`bigint`	Deadline timestamp for the user signature

Returns: Transaction hash (Hex).

unlinkIdentityAsSigner

Unlink identity data as the identity owner (signer). Only the identity owner who created the link can call this.

await walletClient.unlinkIdentityAsSigner({
  clientUser: '0xClientUserAddress',
  policyClient: '0xPolicyClientAddress',
  identityDomains: [identityDomainHash('kyc')],
});

Signature:

unlinkIdentityAsSigner(args: UnlinkIdentityAsSignerParams): Promise<Hex>

Parameters:

Parameter	Type	Description
`clientUser`	`Address`	The client user whose link to remove
`policyClient`	`Address`	PolicyClient contract address
`identityDomains`	`Hex[]`	Array of domain hashes to unlink

Returns: Transaction hash (Hex).

unlinkIdentityAsUser

Unlink identity data as the client user. Allows users to revoke links to their own account.

await walletClient.unlinkIdentityAsUser({
  policyClient: '0xPolicyClientAddress',
  identityDomains: [identityDomainHash('kyc')],
});

Signature:

unlinkIdentityAsUser(args: UnlinkIdentityAsUserParams): Promise<Hex>

Parameters:

Parameter	Type	Description
`policyClient`	`Address`	PolicyClient contract address
`identityDomains`	`Hex[]`	Array of domain hashes to unlink

Returns: Transaction hash (Hex).

Public Client Methods (Read)

These methods are available after extending a PublicClient with newtonPublicClientActions.

Task Methods

waitForTaskResponded

Polls the on-chain TaskManager contract for a TaskResponded event for the given task ID.

const result = await publicClient.waitForTaskResponded({
  taskId: '0x...',
  timeoutMs: 120000,
});

console.log(result.taskResponse.evaluationResult);
console.log(result.attestation.expiration);

Signature:

waitForTaskResponded(args: {
  taskId: TaskId;
  timeoutMs?: number;
  abortSignal?: AbortSignal;
}): Promise<TaskResponseResult>

Parameters:

Parameter	Type	Required	Description
`taskId`	`TaskId` (`Hex`)	Yes	The task identifier to monitor
`timeoutMs`	`number`	No	Maximum wait time in milliseconds
`abortSignal`	`AbortSignal`	No	Signal to abort the polling

getTaskStatus

Queries the current status of a task from the on-chain contracts.

const status = await publicClient.getTaskStatus({ taskId: '0x...' });
// status: 'Created' | 'Responded' | 'AttestationSpent'
//       | 'AttestationExpired' | 'SuccessfullyChallenged'

Signature:

getTaskStatus(args: {
  taskId: TaskId;
}): Promise<TaskStatus>

getTaskResponseHash

Retrieves the response hash for a given task from the on-chain contract.

const hash = await publicClient.getTaskResponseHash({ taskId: '0x...' });
// hash: '0x...' | null

Signature:

getTaskResponseHash(args: {
  taskId: TaskId;
}): Promise<Hex | null>

Policy Methods

getPolicyId

Returns the policy ID associated with a given client address.

const policyId = await publicClient.getPolicyId({ client: '0x...' });

Signature:

getPolicyId(args: { client: Address }): Promise<`0x${string}`>

getPolicyConfig

Returns the full policy configuration for a given policy ID, including parameters and expiration settings.

const config = await publicClient.getPolicyConfig({ policyId: '0x...' });
console.log(config.policyParams);
console.log(config.policyParamsHex);
console.log(config.expireAfter);

Signature:

getPolicyConfig(args: {
  policyId: `0x${string}`;
}): Promise<{
  policyParams: string | object;
  policyParamsHex: `0x${string}`;
  expireAfter: number;
}>

getPolicyCid

Returns the content identifier (CID) of the policy WASM stored in the contract.

const cid = await publicClient.getPolicyCid();

Signature:

getPolicyCid(): Promise<string>

getSchemaCid

Returns the content identifier (CID) of the policy schema.

const cid = await publicClient.getSchemaCid();

Signature:

getSchemaCid(): Promise<string>

getMetadataCid

Returns the content identifier (CID) of the policy metadata.

const cid = await publicClient.getMetadataCid();

Signature:

getMetadataCid(): Promise<string>

getEntrypoint

Returns the policy entrypoint string (e.g., "newton/policy/allow").

const entrypoint = await publicClient.getEntrypoint();

Signature:

getEntrypoint(): Promise<string>

getPolicyData

Returns the array of PolicyData contract addresses associated with the policy.

const addresses = await publicClient.getPolicyData();

Signature:

getPolicyData(): Promise<Address[]>

isPolicyVerified

Returns whether the policy contract has been verified.

const verified = await publicClient.isPolicyVerified();

Signature:

isPolicyVerified(): Promise<boolean>

precomputePolicyId

Synchronously computes a policy ID from its constituent parts without making an on-chain call.

const policyId = publicClient.precomputePolicyId({
  policyContract: '0x...',
  policyData: ['0x...'],
  params: {
    admin: '0x...',
    allowed_actions: {},
    token_whitelist: {},
  },
  client: '0x...',
  policyUri: 'ipfs://...',
  schemaUri: 'ipfs://...',
  entrypoint: 'newton/policy/allow',
  expireAfter: 3600,
});

Signature:

precomputePolicyId(args: {
  policyContract: Address;
  policyData: Address[];
  params: Record<string, any>;
  client: Address;
  policyUri: string;
  schemaUri: string;
  entrypoint: string;
  expireAfter?: number;
  blockTimestamp?: bigint;
}): `0x${string}`

This is a synchronous method. It does not make any network or contract calls.

Additional Policy Contract Readers

The following methods read individual fields from the policy contract. They all require a policyContractAddress to have been set during initialization (or passed via overrides).

Method	Return Type	Description
`owner()`	`Promise<Address>`	Returns the owner address of the policy contract
`factory()`	`Promise<Address>`	Returns the factory address that deployed the contract
`entrypoint()`	`Promise<string>`	Returns the policy entrypoint path
`clientToPolicyId({ client })`	`Promise<\`0x$string`>`	Maps a client address to its policy ID
`policyData({ index })`	`Promise<Address>`	Returns the PolicyData contract address at the given index
`policyCid()`	`Promise<string>`	Returns the policy CID
`schemaCid()`	`Promise<string>`	Returns the schema CID
`metadataCid()`	`Promise<string>`	Returns the metadata CID
`supportsInterface({ interfaceId })`	`Promise<boolean>`	EIP-165 interface support check

Privacy Methods

Client-side HPKE encryption for privacy-preserving policy evaluation. These methods are available as wallet client actions and as standalone exports.

The privacy module uses X25519 KEM + HKDF-SHA256 + ChaCha20-Poly1305 (RFC 9180, Base mode) and is compatible with the Rust gateway implementation.

`createSecureEnvelope`

Encrypt plaintext into a SecureEnvelope using HPKE. This is a pure offline function — zero network calls. The ephemeral HPKE key is generated internally and zeroed after use. Standalone signature:

createSecureEnvelope(
  params: CreateSecureEnvelopeParams,
  signingKey: Uint8Array
): Promise<SecureEnvelopeResult>

Wallet client signature:

client.createSecureEnvelope(params: CreateSecureEnvelopeParams, signingKey: Uint8Array): Promise<SecureEnvelopeResult>

Parameters:

Parameter	Type	Description
`params.plaintext`	`Uint8Array \| string \| Record<string, unknown>`	Data to encrypt
`params.policyClient`	`Address`	Policy client address this data is scoped to
`params.chainId`	`number`	Chain ID for AAD context binding
`params.recipientPublicKey`	`string`	Gateway’s X25519 public key (hex, no 0x prefix)
`signingKey`	`Uint8Array`	Ed25519 private key seed (32 bytes). Caller owns the buffer lifecycle.

Returns: SecureEnvelopeResult containing the encrypted envelope, Ed25519 signature, and sender public key.

The caller is responsible for zeroing the signingKey buffer when done. The function copies the key internally and zeroes the copy after signing, but the original buffer remains in the caller’s control.

`getPrivacyPublicKey`

Fetch the gateway’s X25519 HPKE public key. Call this once and cache the result — the key only changes on gateway restart or key rotation. Standalone signature:

getPrivacyPublicKey(
  chainId: number,
  apiKey: string,
  gatewayApiUrlOverride?: string
): Promise<PrivacyPublicKeyResponse>

Wallet client signature:

client.getPrivacyPublicKey(): Promise<PrivacyPublicKeyResponse>

Returns:

Field	Type	Description
`public_key`	`string`	X25519 public key (hex, no 0x prefix)
`key_type`	`string`	Always `"x25519"`
`encryption_suite`	`string`	Encryption suite identifier

`getSecretsPublicKey`

Fetch the gateway’s X25519 HPKE public key for WASM secrets encryption. In threshold DKG mode, this returns a different key than getPrivacyPublicKey. Use this key when encrypting secrets via storeEncryptedSecrets. Standalone signature:

getSecretsPublicKey(
  chainId: number,
  apiKey: string,
  gatewayApiUrlOverride?: string
): Promise<SecretsPublicKeyResponse>

Wallet client signature:

client.getSecretsPublicKey(): Promise<SecretsPublicKeyResponse>

Returns:

Field	Type	Description
`public_key`	`string`	X25519 public key (hex, no 0x prefix)
`key_type`	`string`	Always `"x25519"`
`encryption_suite`	`string`	Encryption suite identifier

`uploadIdentityEncrypted`

Upload HPKE-encrypted identity data to the gateway. The caller must provide a pre-built SecureEnvelope (via createSecureEnvelope) and an EIP-712 signature of the envelope JSON from the identity owner. The gateway stores the envelope and returns a data_ref_id + gateway signature for the on-chain registerIdentityData call. Standalone signature:

uploadIdentityEncrypted(
  chainId: number,
  apiKey: string,
  params: UploadIdentityEncryptedParams,
  gatewayApiUrlOverride?: string
): Promise<UploadIdentityEncryptedResponse>

Wallet client signature:

client.uploadIdentityEncrypted(params: UploadIdentityEncryptedParams): Promise<UploadIdentityEncryptedResponse>

Parameters:

Parameter	Type	Description
`params.identityOwner`	`Address`	EVM address of the identity owner
`params.identityOwnerSig`	`string`	EIP-712 signature of the SecureEnvelope JSON by the identity owner
`params.envelope`	`string`	JSON-serialized SecureEnvelope (from `createSecureEnvelope`)
`params.identityDomain`	`0x${string}`	Identity domain as 0x-prefixed bytes32 hex (e.g., `keccak256("kyc")`)
`params.chainId`	`number`	Chain ID the identity registry lives on

Returns:

Field	Type	Description
`data_ref_id`	`string`	Content-hash data reference ID: `keccak256(envelope_json_bytes)`
`gateway_signature`	`string`	Gateway EIP-712 signature for `registerIdentityData` on-chain call
`deadline`	`number`	Signature expiration (unix timestamp)

`getIdentityEncrypted`

Fetch encrypted identity data by its content-hash reference ID. Used to resolve a data_ref_id (stored on-chain in IdentityRegistry) back to the encrypted data blob (stored off-chain in the gateway). Standalone signature:

getIdentityEncrypted(
  chainId: number,
  apiKey: string,
  dataRefId: string,
  gatewayApiUrlOverride?: string
): Promise<GetIdentityEncryptedResult>

Wallet client signature:

client.getIdentityEncrypted(args: { dataRefId: string }): Promise<GetIdentityEncryptedResult>

Parameters:

Parameter	Type	Description
`dataRefId`	`string`	Content-hash data reference ID (keccak256 of the encrypted data)

Returns:

Field	Type	Description
`envelope`	`string`	HPKE-encrypted identity data as a SecureEnvelope JSON string
`identity_domain`	`string`	Identity domain this data was registered under
`identity_owner`	`string`	Identity owner address

`uploadConfidentialData`

Encrypt confidential data (blacklists, allowlists, sanctions lists, etc.) client-side with HPKE and upload the envelope to the gateway. The gateway stores it and returns a content-hash data_ref_id. The provider then calls ConfidentialDataRegistry.publishData(domain, dataRefId) on-chain. The gateway validates provider registration via on-chain lookup — no Ed25519 signing key required. Standalone signature:

uploadConfidentialData(
  chainId: number,
  apiKey: string,
  params: UploadConfidentialDataParams,
  gatewayApiUrlOverride?: string
): Promise<UploadConfidentialDataResult>

Wallet client signature:

client.uploadConfidentialData(params: UploadConfidentialDataParams): Promise<UploadConfidentialDataResult>

Parameters:

Parameter	Type	Description
`params.provider`	`string`	Provider address (must be registered on-chain with ConfidentialDataRegistry)
`params.domain`	`string`	Confidential domain as 0x-prefixed bytes32 hex (e.g., `keccak256("newton.privacy.blacklist")`)
`params.plaintext`	`Uint8Array \| string \| Record<string, unknown>`	Data to encrypt and upload
`params.chainId`	`number`	Chain ID for AAD context binding
`params.recipientPublicKey`	`string?`	Gateway’s X25519 key (hex, no 0x prefix). If omitted, fetched via RPC.

Returns:

Field	Type	Description
`data_ref_id`	`string`	Content-hash data reference ID

`getConfidentialData`

Retrieve an HPKE-encrypted confidential data envelope by its data reference ID. The caller is responsible for decryption using their HPKE private key. Standalone signature:

getConfidentialData(
  chainId: number,
  apiKey: string,
  dataRefId: string,
  gatewayApiUrlOverride?: string
): Promise<GetConfidentialDataResult>

Wallet client signature:

client.getConfidentialData(args: { dataRefId: string }): Promise<GetConfidentialDataResult>

Parameters:

Parameter	Type	Description
`dataRefId`	`string`	Content-hash data reference ID returned from `uploadConfidentialData`

Returns:

Field	Type	Description
`envelope`	`string`	JSON-serialized HPKE SecureEnvelope
`domain`	`string`	Confidential domain as 0x-prefixed bytes32 hex
`provider`	`string`	Provider address

Identity Methods

EIP-712 signed identity data submission to the on-chain IdentityRegistry. These methods are available as wallet client actions and as standalone exports.

The identity module uses a single EncryptedIdentityData { string data } EIP-712 struct across all identity domains. The identity_domain field (bytes32 hash of the domain name) tells the gateway how to interpret the encrypted blob.

`identityDomainHash`

Compute the bytes32 identity domain hash from a human-readable domain name. Matches the Rust convention: keccak256(toBytes(domainName)). Signature:

identityDomainHash(domainName: string): Hex

Example:

import { identityDomainHash } from '@newton-xyz/sdk';

const kycDomain = identityDomainHash('kyc');
// Returns keccak256 of "kyc" as 0x-prefixed bytes32

`linkIdentityAsSignerAndUser`

Link identity data when the caller is both the identity owner and the client user. Calls the IdentityRegistry contract directly via writeContract. Standalone signature:

linkIdentityAsSignerAndUser(
  walletClient: WalletClient,
  params: LinkIdentityAsSignerAndUserParams
): Promise<Hex>

Parameters:

Parameter	Type	Description
`policyClient`	`Address`	PolicyClient contract address
`identityDomains`	`Hex[]`	Array of domain hashes (use `identityDomainHash()`)

Returns: Transaction hash (Hex).

`linkIdentityAsSigner`

Link identity data as the identity owner (signer). Requires a counterparty EIP-712 signature from the client user. Standalone signature:

linkIdentityAsSigner(
  walletClient: WalletClient,
  params: LinkIdentityAsSignerParams
): Promise<Hex>

Parameters:

Parameter	Type	Description
`policyClient`	`Address`	PolicyClient contract address
`identityDomains`	`Hex[]`	Array of domain hashes
`clientUser`	`Address`	The client user’s address
`clientUserSignature`	`Hex`	EIP-712 signature from the client user
`clientUserNonce`	`bigint`	Nonce for the client user’s signature
`clientUserDeadline`	`bigint`	Deadline timestamp for the signature

Returns: Transaction hash (Hex).

`linkIdentityAsUser`

Link identity data as the client user. Requires a counterparty EIP-712 signature from the identity owner. Standalone signature:

linkIdentityAsUser(
  walletClient: WalletClient,
  params: LinkIdentityAsUserParams
): Promise<Hex>

Parameters:

Parameter	Type	Description
`identityOwner`	`Address`	The identity owner’s address
`policyClient`	`Address`	PolicyClient contract address
`identityDomains`	`Hex[]`	Array of domain hashes
`identityOwnerSignature`	`Hex`	EIP-712 signature from the identity owner
`identityOwnerNonce`	`bigint`	Nonce for the identity owner’s signature
`identityOwnerDeadline`	`bigint`	Deadline timestamp for the signature

Returns: Transaction hash (Hex).

`linkIdentity`

Link identity data as a 3rd party with EIP-712 signatures from both the identity owner and the client user. Standalone signature:

linkIdentity(
  walletClient: WalletClient,
  params: LinkIdentityParams
): Promise<Hex>

Parameters:

Parameter	Type	Description
`identityOwner`	`Address`	The identity owner’s address
`clientUser`	`Address`	The client user’s address
`policyClient`	`Address`	PolicyClient contract address
`identityDomains`	`Hex[]`	Array of domain hashes
`identityOwnerSignature`	`Hex`	EIP-712 signature from the identity owner
`identityOwnerNonce`	`bigint`	Nonce for the identity owner’s signature
`identityOwnerDeadline`	`bigint`	Deadline timestamp for the owner signature
`clientUserSignature`	`Hex`	EIP-712 signature from the client user
`clientUserNonce`	`bigint`	Nonce for the client user’s signature
`clientUserDeadline`	`bigint`	Deadline timestamp for the user signature

Returns: Transaction hash (Hex).

`unlinkIdentityAsSigner`

Unlink identity data as the identity owner (signer). Only the identity owner who created the link can call this. Standalone signature:

unlinkIdentityAsSigner(
  walletClient: WalletClient,
  params: UnlinkIdentityAsSignerParams
): Promise<Hex>

Parameters:

Parameter	Type	Description
`clientUser`	`Address`	The client user whose link to remove
`policyClient`	`Address`	PolicyClient contract address
`identityDomains`	`Hex[]`	Array of domain hashes to unlink

Returns: Transaction hash (Hex).

`unlinkIdentityAsUser`

Unlink identity data as the client user. Allows users to revoke links to their own account. Standalone signature:

unlinkIdentityAsUser(
  walletClient: WalletClient,
  params: UnlinkIdentityAsUserParams
): Promise<Hex>

Parameters:

Parameter	Type	Description
`policyClient`	`Address`	PolicyClient contract address
`identityDomains`	`Hex[]`	Array of domain hashes to unlink

Returns: Transaction hash (Hex).

Types & Interfaces

Intent Types

Show IntentFromParams

The intent shape accepted by SDK methods before normalization.

interface IntentFromParams {
  from: string;
  to: string;
  value: string;
  data: string;
  chainId: string | number;
  functionSignature: string;
}

Show NormalizedIntent

The intent after internal normalization, with all fields as consistent types.

interface NormalizedIntent {
  from: Address;
  to: Address;
  value: Hex;
  data: Hex;
  chainId: number;
  functionSignature: Hex;
}

Show HexlifiedIntent

The intent with all fields encoded as hex strings for on-chain use.

interface HexlifiedIntent {
  from: Hex;
  to: Hex;
  value: Hex;
  data: Hex;
  chainId: Hex;
  functionSignature: Hex;
}

Task Types

Show TaskId

type TaskId = Hex;

A hex-encoded unique identifier for a task.

Show TaskStatus

type TaskStatus =
  | 'Created'
  | 'Responded'
  | 'AttestationSpent'
  | 'AttestationExpired'
  | 'SuccessfullyChallenged';

Represents the lifecycle state of a task on-chain.

Show Task

interface Task {
  taskId: TaskId;
  intent: NormalizedIntent;
  policyId: Hex;
  taskCreatedBlock: number;
  // Additional operator-specific fields
}

The full task object returned by evaluation methods.

Show TaskResponse

interface TaskResponse {
  evaluationResult: boolean;
  referenceTaskId: TaskId;
  // Additional response metadata
}

The operator’s response to a task evaluation.

Show TaskResponseResult

interface TaskResponseResult {
  taskResponse: TaskResponse;
  attestation: {
    expiration: number;
    // Additional attestation fields
  };
}

The combined result returned by waitForTaskResponded.

Show SubmitEvaluationRequestParams

interface SubmitEvaluationRequestParams {
  policyClient: Address;
  intent: IntentFromParams;
  timeout: number;
  proofCid?: string;
  includeValidateCalldata?: boolean;
  encryptedDataRefs?: string[];
  userSignature?: string;
  appSignature?: string;
  userPublicKey?: string;
  appPublicKey?: string;
}

Field	Type	Required	Description
`policyClient`	`Address`	Yes	The policy client contract address
`intent`	`IntentFromParams`	Yes	The intent to evaluate
`timeout`	`number`	Yes	Request timeout in seconds
`proofCid`	`string`	No	IPFS CID of a TLSNotary presentation proof for zkTLS-backed evaluation
`includeValidateCalldata`	`boolean`	No	Include ABI-encoded `validateAttestationDirect` calldata in the response
`encryptedDataRefs`	`string[]`	No	Encrypted data reference UUIDs for privacy-preserving evaluation
`userSignature`	`string`	No	User Ed25519 signature for privacy authorization (hex-encoded)
`appSignature`	`string`	No	Application Ed25519 signature for privacy authorization (hex-encoded)
`userPublicKey`	`string`	No	User Ed25519 public key (hex-encoded, 32 bytes)
`appPublicKey`	`string`	No	Application Ed25519 public key (hex-encoded, 32 bytes)

Simulation Types

Show SimulateTaskParams & SimulateTaskResult

interface SimulateTaskParams {
  intent: IntentFromParams;
  policyTaskData: SimulateTaskPolicyTaskData;
}

interface SimulateTaskPolicyTaskData {
  policyId: Hex;
  policyAddress: Address;
  policy: Hex;
  policyData: SimulateTaskPolicyData[];
}

interface SimulateTaskPolicyData {
  wasmArgs: Hex;
  data: Hex;
  attestation: Hex;
  policyDataAddress: Address;
  expireBlock: number;
}

interface SimulateTaskResult {
  success: boolean;
  result?: {
    allow: boolean;
    reason?: string;
  };
  error?: string;
}

Show SimulatePolicyParams & SimulatePolicyResult

interface SimulatePolicyParams {
  policyClient: Address;
  policy: string;
  intent: IntentFromParams;
  policyData: Array<{ policyDataAddress: Address }>;
  policyParams?: Record<string, any>;
  entrypoint?: string;
}

interface SimulatePolicyResult {
  success: boolean;
  evaluation_result?: SimulatePolicyEvaluationResult;
  error?: string;
}

interface SimulatePolicyEvaluationResult {
  allow: boolean;
  reason?: string;
}

Show SimulatePolicyDataParams & SimulatePolicyDataResult

interface SimulatePolicyDataParams {
  policyDataAddress: Address;
  secrets?: string;
  wasmArgs?: Hex;
  chainId: number; // required
}

interface SimulatePolicyDataResult {
  success: boolean;
  policy_data: {
    specifier: string;
    data: unknown;
    timestamp: number;
  } | null;
  error: string | null;
}

Show SimulatePolicyDataWithClientParams & SimulatePolicyDataWithClientResult

interface SimulatePolicyDataWithClientParams {
  policyDataAddress: Address;
  policyClient: Address;
  wasmArgs?: Hex;
}

interface SimulatePolicyDataWithClientResult {
  success: boolean;
  policy_data: {
    specifier: string;
    data: unknown;
    timestamp: number;
  } | null;
  error: string | null;
}

Policy Types

Show PolicyId, PolicyInfo, PolicyCodeInfo, PolicyDataInfo

type PolicyId = `0x${string}`;

interface PolicyInfo {
  policyId: PolicyId;
  policyParams: string | object;
  policyParamsHex: `0x${string}`;
  expireAfter: number;
}

interface PolicyCodeInfo {
  policyCid: string;
  schemaCid: string;
  metadataCid: string;
  entrypoint: string;
}

interface PolicyDataInfo {
  addresses: Address[];
}

Show PolicyParamsJson, SetPolicyInput, SetPolicyResult, PolicyDataInput

type PolicyParamsJson = Record<string, any>;

interface SetPolicyInput {
  client: Address;
  policyUri: string;
  schemaUri: string;
  entrypoint: string;
  params: PolicyParamsJson;
  policyData: Address[];
  expireAfter: number;
}

interface SetPolicyResult {
  txHash: `0x${string}`;
  policyId: PolicyId;
}

interface PolicyDataInput {
  policyDataAddress: Address;
}

Gateway Types

Show GatewayCreateTaskResult & AggregationResponse

interface GatewayCreateTaskResult {
  task_id: Hex;
  task: Task;
  task_response: unknown;
  aggregation_response: AggregationResponse;
  status: 'success' | 'failed';
  error: string | null;
  expiration: number;
  reference_block: number;
  signature_data: Hex;
  timestamp: number;
  /** ABI-encoded calldata for validateAttestationDirect (present when include_validate_calldata was true) */
  validate_calldata?: string;
  /** Per-operator error details when quorum fails */
  operator_errors?: OperatorError[];
}

interface AggregationResponse {
  non_signer_quorum_bitmap_indices: number[];
  non_signer_stake_indices: number[][];
  non_signers_pub_keys_g1: number[][];
  quorum_apk_indices: number[];
  quorum_apks_g1: number[][];
  signers_agg_sig_g1: { g1_point: number[] };
  signers_apk_g2: number[];
  total_stake_indices: number[];
  task_created_block: number;
}

interface OperatorError {
  operator_address: Address;
  operator_id: Hex;
  error_code: number;
  message: string;
  timestamp: string;
  retryable: boolean;
}

JSON-RPC Types

Show JsonRpcRequestPayload, JsonRpcResponsePayload, JsonRpcError, NewtonWalletPayloadMethod

interface JsonRpcRequestPayload {
  jsonrpc: '2.0';
  id: number | string;
  method: NewtonWalletPayloadMethod;
  params: any[];
}

interface JsonRpcResponsePayload<T = any> {
  jsonrpc: '2.0';
  id: number | string;
  result?: T;
  error?: JsonRpcError;
}

interface JsonRpcError {
  code: number;
  message: string;
  data?: any;
}

enum NewtonWalletPayloadMethod {
  ShowUI = 'newton_wallet_wallet',
  Receive = 'newton_wallet_wallet_receive',
  PersonalSign = 'personal_sign',
  SendUserOperation = 'eth_sendUserOperation',
  Connect = 'newton_wallet_user_connect',
  Disconnect = 'newton_wallet_user_disconnect',
  IsConnected = 'newton_wallet_user_is_connected',
  GetConnectedProfile = 'newton_wallet_user_get_connected_profile',
}

Builder Types

Show PendingTaskBuilder

interface PendingTaskBuilder {
  readonly taskId?: TaskId;
  waitForTaskResponded(args: {
    timeoutMs?: number;
  }): Promise<TaskResponseResult>;
}

Returned by submitEvaluationRequest. Call waitForTaskResponded() to poll for the on-chain attestation.

Privacy Types

Show SecureEnvelope & CreateSecureEnvelopeParams

interface SecureEnvelope {
  enc: string;
  ciphertext: string;
  policy_client: string;
  chain_id: number;
  recipient_pubkey: string;
}

interface CreateSecureEnvelopeParams {
  plaintext: Uint8Array | string | Record<string, unknown>;
  policyClient: Address;
  chainId: number;
  recipientPublicKey: string;
}

interface SecureEnvelopeResult {
  envelope: SecureEnvelope;
  signature: string;
  senderPublicKey: string;
}

Show Ed25519KeyPair

interface Ed25519KeyPair {
  privateKey: string;  // 32-byte hex, no 0x prefix
  publicKey: string;   // 32-byte hex, no 0x prefix
}

Show UploadIdentityEncryptedParams & Response

interface UploadIdentityEncryptedParams {
  identityOwner: Address;
  identityOwnerSig: string;
  envelope: string;
  identityDomain: `0x${string}`;
  chainId: number;
}

interface UploadIdentityEncryptedResponse {
  data_ref_id: string;
  gateway_signature: string;
  deadline: number;
}

Show GetIdentityEncryptedResult

interface GetIdentityEncryptedResult {
  envelope: string;
  identity_domain: string;
  identity_owner: string;
}

Show SecretsPublicKeyResponse

interface SecretsPublicKeyResponse {
  public_key: string;
  key_type: string;
  encryption_suite: string;
}

Show StoreEncryptedSecretsParams & Response

interface StoreEncryptedSecretsParams {
  policyClient: Address;
  policyDataAddress: Address;
  /** Plaintext secrets as a JSON object (e.g., { "API_KEY": "...", "ENDPOINT": "..." }) */
  plaintext: Record<string, unknown>;
  chainId: number;
  /** Gateway's X25519 public key (hex, no 0x prefix). Fetched automatically if omitted. */
  recipientPublicKey?: string;
}

interface StoreEncryptedSecretsResponse {
  success: boolean;
  schema: Record<string, unknown> | null;
  error: string | null;
}

Show SignPrivacyAuthorizationParams & PrivacyAuthorizationResult

interface SignPrivacyAuthorizationParams {
  policyClient: Address;
  intentHash: Hex;
  encryptedDataRefs: string[];
  userSigningKey: string;
  appSigningKey: string;
}

interface PrivacyAuthorizationResult {
  userSignature: string;
  appSignature: string;
  userPublicKey: string;
  appPublicKey: string;
}

Show PrivacyPublicKeyResponse

interface PrivacyPublicKeyResponse {
  public_key: string;
  key_type: string;
  encryption_suite: string;
}

Webhook Types

Show RegisterWebhookParams & RegisterWebhookResult

interface RegisterWebhookParams {
  url: string;
  secret?: string;
  timeoutSeconds?: number;
  maxRetries?: number;
  failureTypes?: TaskFailureType[];
}

interface RegisterWebhookResult {
  success: boolean;
  message: string;
}

Show UnregisterWebhookResult

interface UnregisterWebhookResult {
  success: boolean;
  message: string;
}

Show TaskFailureType

type TaskFailureType =
  | 'channel_error'
  | 'timeout'
  | 'quorum_not_reached'
  | 'onchain_submission_failed'
  | 'policy_evaluation_failed'
  | 'signature_verification_failed'
  | 'internal_error';

Identity Types

Show LinkIdentityAsSignerAndUserParams

interface LinkIdentityAsSignerAndUserParams {
  policyClient: Address;
  identityDomains: Hex[];
}

Show LinkIdentityAsSignerParams

interface LinkIdentityAsSignerParams {
  policyClient: Address;
  identityDomains: Hex[];
  clientUser: Address;
  clientUserSignature: Hex;
  clientUserNonce: bigint;
  clientUserDeadline: bigint;
}

Show LinkIdentityAsUserParams

interface LinkIdentityAsUserParams {
  identityOwner: Address;
  policyClient: Address;
  identityDomains: Hex[];
  identityOwnerSignature: Hex;
  identityOwnerNonce: bigint;
  identityOwnerDeadline: bigint;
}

Show LinkIdentityParams

interface LinkIdentityParams {
  identityOwner: Address;
  clientUser: Address;
  policyClient: Address;
  identityDomains: Hex[];
  identityOwnerSignature: Hex;
  identityOwnerNonce: bigint;
  identityOwnerDeadline: bigint;
  clientUserSignature: Hex;
  clientUserNonce: bigint;
  clientUserDeadline: bigint;
}

Show UnlinkIdentityAsSignerParams

interface UnlinkIdentityAsSignerParams {
  clientUser: Address;
  policyClient: Address;
  identityDomains: Hex[];
}

Show UnlinkIdentityAsUserParams

interface UnlinkIdentityAsUserParams {
  policyClient: Address;
  identityDomains: Hex[];
}

Show RegisterIdentityDataParams

interface RegisterIdentityDataParams {
  identityDomain: Hex;
  dataRefId: string;
  gatewaySignature: Hex;
  deadline: bigint;
}

Error Handling

The SDK provides structured error classes with typed error codes for precise error handling.

SDKError

Thrown when an SDK-level error occurs (e.g., missing API key, invalid arguments).

class SDKError extends Error {
  code: SDKErrorCode;
  rawMessage: string;

  constructor(code: SDKErrorCode, rawMessage: string);
}

MagicRPCError

Thrown when the Newton Gateway returns a JSON-RPC error.

class MagicRPCError extends Error {
  code: RPCErrorCode | number;
  rawMessage: string;
  data: unknown;

  constructor(sourceError?: JsonRpcError | null);
}

SDKErrorCode

Show SDKErrorCode enum values

enum SDKErrorCode {
  MissingApiKey = 'MISSING_API_KEY',
  PopupAlreadyExists = 'POPUP_ALREADY_EXISTS',
  MalformedResponse = 'MALFORMED_RESPONSE',
  InvalidArgument = 'INVALID_ARGUMENT',
  ExtensionNotInitialized = 'EXTENSION_NOT_INITIALIZED',
  IncompatibleExtensions = 'INCOMPATIBLE_EXTENSIONS',
  FailedToOpenPopup = 'FAILED_TO_OPEN_POPUP',
  FailedToRetrieveNativeTokenBalance = 'FAILED_TO_RETRIEVE_NATIVE_TOKEN_BALANCE',
  MissingChain = 'MISSING_CHAIN',
  MissingAccount = 'MISSING_ACCOUNT',
  InvalidAddress = 'INVALID_ADDRESS',
}

RPCErrorCode

Show RPCErrorCode enum values

enum RPCErrorCode {
  // Standard JSON-RPC 2.0 error codes
  ParseError = -32700,
  InvalidRequest = -32600,
  MethodNotFound = -32601,
  InvalidParams = -32602,
  InternalError = -32603,

  // Custom Newton error codes
  MagicLinkRateLimited = -10002,
  UserAlreadyLoggedIn = -10003,
  AccessDeniedToUser = -10011,
  UserRejectedAction = -10012,
  RequestCancelled = -10014,
  RedirectLoginComplete = -10015,
  NewtonWalletSessionTerminated = -10016,
  PopupRequestOverriden = -10017,
}

SDKWarningCode

Show SDKWarningCode enum values

enum SDKWarningCode {
  SyncWeb3Method = 'SYNC_WEB3_METHOD',
  ReactNativeEndpointConfiguration = 'REACT_NATIVE_ENDPOINT_CONFIGURATION',
  DeprecationNotice = 'DEPRECATION_NOTICE',
  ProductAnnouncement = 'ANNOUNCEMENT',
}

SDKError, MagicRPCError, and the error code enums are currently internal types. They are not exported from the package’s public API. You can catch errors generically using instanceof Error and inspect the message property.

Subpath Exports

The SDK provides multiple entry points for tree-shaking and targeted imports.

Import Path	Description
`@newton-xyz/sdk`	Full SDK — all methods, types, utilities, and constants
`@newton-xyz/sdk/types`	Type definitions and interfaces only

Use subpath exports to minimize bundle size when you only need a subset of SDK functionality.

Integration Guide — Step-by-step guide to building with the Newton Protocol SDK
RPC API Reference — Underlying JSON-RPC methods called by the SDK

RPC APINewton Gateway JSON-RPC API reference for policy-based transaction authorization

⌘I

​Newton Protocol SDK Reference

​Installation

​Overview

​Setup & Initialization

​newtonPublicClientActions

​newtonWalletClientActions

​SdkOverrides

​Wallet Client Methods (Write)

​submitEvaluationRequest

​evaluateIntentDirect

​submitIntentAndSubscribe

​simulateTask

​simulatePolicy

​simulatePolicyData

​simulatePolicyDataWithClient

​initialize

​renounceOwnership

​transferOwnership

​Identity Methods

​connectIdentityWithNewton

​registerUserData

​linkApp

​unlinkApp

​Privacy Methods

​getPrivacyPublicKey

​createSecureEnvelope

​getSecretsPublicKey

​uploadIdentityEncrypted

​getIdentityEncrypted

​generateSigningKeyPair

​storeEncryptedSecrets

​signPrivacyAuthorization

​Webhook Methods

​registerWebhook

​unregisterWebhook

​Identity Methods

​registerIdentityData

​linkIdentityAsSignerAndUser

​linkIdentityAsSigner

​linkIdentityAsUser

​linkIdentity

​unlinkIdentityAsSigner

​unlinkIdentityAsUser

​Public Client Methods (Read)

​Task Methods

​waitForTaskResponded

​getTaskStatus

​getTaskResponseHash

​Policy Methods

​getPolicyId

​getPolicyConfig

​getPolicyCid

​getSchemaCid

​getMetadataCid

​getEntrypoint

​getPolicyData

​isPolicyVerified

​precomputePolicyId

​Additional Policy Contract Readers

​Privacy Methods

​createSecureEnvelope

​getPrivacyPublicKey

​getSecretsPublicKey

​uploadIdentityEncrypted

​getIdentityEncrypted

​uploadConfidentialData

​getConfidentialData

​Identity Methods

​identityDomainHash

​linkIdentityAsSignerAndUser

​linkIdentityAsSigner

​linkIdentityAsUser

​linkIdentity

​unlinkIdentityAsSigner

​unlinkIdentityAsUser

​Types & Interfaces

​Intent Types

​Task Types

​Simulation Types

​Policy Types

Newton Protocol SDK Reference

Installation

Overview

Setup & Initialization

newtonPublicClientActions

newtonWalletClientActions

SdkOverrides

Wallet Client Methods (Write)

submitEvaluationRequest

evaluateIntentDirect

submitIntentAndSubscribe

simulateTask

simulatePolicy

simulatePolicyData

simulatePolicyDataWithClient

initialize

renounceOwnership

transferOwnership

Identity Methods

connectIdentityWithNewton

registerUserData

linkApp

unlinkApp

Privacy Methods

getPrivacyPublicKey

createSecureEnvelope

getSecretsPublicKey

uploadIdentityEncrypted

getIdentityEncrypted

generateSigningKeyPair

storeEncryptedSecrets

signPrivacyAuthorization

Webhook Methods

registerWebhook

unregisterWebhook

Identity Methods

registerIdentityData

linkIdentityAsSignerAndUser

linkIdentityAsSigner

linkIdentityAsUser

linkIdentity

unlinkIdentityAsSigner

unlinkIdentityAsUser

Public Client Methods (Read)

Task Methods

waitForTaskResponded

getTaskStatus

getTaskResponseHash

Policy Methods

getPolicyId

getPolicyConfig

getPolicyCid

getSchemaCid

getMetadataCid

getEntrypoint

getPolicyData

isPolicyVerified

precomputePolicyId

Additional Policy Contract Readers

Privacy Methods

`createSecureEnvelope`

`getPrivacyPublicKey`

`getSecretsPublicKey`

`uploadIdentityEncrypted`

`getIdentityEncrypted`

`uploadConfidentialData`

`getConfidentialData`

Identity Methods

`identityDomainHash`

`linkIdentityAsSignerAndUser`

`linkIdentityAsSigner`

`linkIdentityAsUser`

`linkIdentity`

`unlinkIdentityAsSigner`

`unlinkIdentityAsUser`

Types & Interfaces

Intent Types

Task Types

Simulation Types

Policy Types