Skip to main content
PolicyData oracles often need access to API keys and credentials to fetch external data. Newton Protocol’s Privacy Layer encrypts these secrets client-side using HPKE (X25519 + HKDF-SHA256 + ChaCha20-Poly1305) so they are never exposed on-chain or to unauthorized parties.

Overview

The secret storage flow:
  1. Prepare your secrets as a JSON object matching your PolicyData’s schema
  2. Call storeEncryptedSecrets from the SDK — it encrypts the plaintext locally and uploads the HPKE envelope
  3. Operators decrypt the envelope during task evaluation to run your WASM oracle
Secrets are validated against the on-chain schema (secretsSchemaCid) defined on your PolicyData contract.

Secrets Format

Prepare a JSON object matching your PolicyData’s secrets schema:

Store via SDK

Use the storeEncryptedSecrets function from the SDK. It fetches the gateway’s HPKE public key automatically (or accepts one you’ve cached), encrypts the plaintext locally, and uploads the envelope in a single call.
Secrets are validated against the on-chain schema before storing.

Reference in PolicyData

Your WASM oracle reads secrets at runtime through the newton:provider/secrets host interface. Operators decrypt the stored envelope before execution; get() returns the decrypted secrets JSON as raw bytes, which you decode and parse.
For a full walkthrough of declaring, uploading, and reading secrets — plus per-oracle scoping in multi-oracle policies — see Uploading & Accessing Secrets in Oracles.

Secrets Schema

The secretsSchemaCid on your PolicyData contract points to a JSON Schema that defines the required shape of your secrets:
If your uploaded secrets do not match this schema, newt_storeEncryptedSecrets returns a validation error.

Security

  • Secrets are encrypted client-side before leaving your application — the HPKE envelope is what travels over the wire
  • The gateway decrypts the envelope in memory to validate against the schema, then stores the envelope (not the plaintext)
  • Only the on-chain owner of the PolicyClient can upload or update secrets
  • Operators decrypt the stored envelope locally during task evaluation — plaintext secrets are never persisted by operators and never sent over the network
  • Secrets are scoped per policy_data_address — redeploying a PolicyData contract produces a new address, so re-upload its secrets. In a multi-oracle policy, upload each oracle’s secrets to its own PolicyData address
  • Key rotation is supported — upload new secrets at any time via newt_storeEncryptedSecrets
For a deeper look at Newton’s encryption architecture, see the Privacy Layer.

Testing

Test your secrets work correctly before deploying:
  1. Test with inline secrets (no ownership required):
  2. Test with stored secrets (requires ownership):
See the RPC API for full parameter details.

Next Steps

Privacy Layer

Full privacy architecture overview

RPC API

newt_storeEncryptedSecrets and related methods