# FAQ & Troubleshooting \[Frequently asked questions and solutions to common issues with Newton Protocol — API keys, policy evaluation, chain support, error codes, and debugging.]

## General FAQ

:::details[What is Newton Protocol?]
Newton Protocol is a decentralized policy engine for onchain transaction authorization, built as an EigenLayer Actively Validated Service (AVS). It lets you encode, verify, and enforce rules — such as spend limits, sanctions screening, or KYC gates — directly within smart contracts. See [What is Newton?](/developers/overview/about) for a full overview.
:::

:::details[What chains does Newton support?]
Newton currently supports **Ethereum Sepolia** (`11155111`) as both a source and destination chain, plus policy execution on **Base** (`8453`) and **Base Sepolia** (`84532`). See [Supported Networks](/developers/concepts/multichain#supported-networks).
:::

:::details[How do I get an API key?]
Go to [dashboard.newton.xyz](https://dashboard.newton.xyz/), sign in, and click **API Keys** in the left navigation — your key is already generated. See [Getting an API Key](/developers/overview/dashboard-api-keys).
:::

:::details[What programming languages can I use for data oracles?]
Newton data oracles compile to WebAssembly (WASM) components. You can write them in:

* [JavaScript](/developers/advanced/javascript-wasm-guide) (using ComponentizeJS)
* [Python](/developers/advanced/python-wasm-guide) (using componentize-py)
* [Rust](/developers/advanced/rust-wasm-guide) (using cargo-component)

Any language that compiles to WASM and supports the WIT interface can be used.
:::

:::details[What is the difference between Standard and Direct validation?]
**Standard validation** (`_validateAttestation`) uses the PolicyClientRegistry to automatically resolve your contract's policy configuration. It costs more gas but is simpler to use.

**Direct validation** (`_validateAttestationDirect`) bypasses the registry. It uses less gas but requires your contract to manage its own policy reference.

See [Validation Methods](/developers/overview/core-concepts#validation-methods) for details.
:::

:::details[How long does policy evaluation take?]
Two-phase consensus (Prepare-Commit) takes approximately **4 seconds**. See [Consensus & Security](/developers/concepts/consensus-security).
:::

:::details[Can I test policies without deploying on-chain?]
Yes. Use `newt_simulateTask` via the SDK or Gateway RPC to simulate a full policy evaluation without any on-chain interaction. You can also test individual components:

* `newt_simulatePolicy` — test Rego policy logic with provided inputs
* `newt_simulatePolicyData` — test a WASM data oracle
* `newton-cli regorus eval` — evaluate Rego locally with Newton crypto extensions

See [Testing & Debugging](/developers/resources/testing-debugging).
:::

:::details[What is the difference between a Policy and a PolicyClient?]
A **Policy** is a reusable Rego program that defines evaluation logic (e.g., "block transactions over $10,000"). A **PolicyClient** is a smart contract that references a specific policy and its configuration parameters (thresholds, allowlists). Multiple PolicyClients can use the same Policy with different parameters. See [Core Concepts](/developers/overview/core-concepts).
:::

## Common Errors

:::details[TaskAlreadyExists — duplicate task submission]
**Cause:** You submitted a task with the same intent hash that is already being evaluated.

**Fix:** Wait for the existing task to complete, or modify the intent (e.g., change the nonce or timestamp) to produce a different hash.
:::

:::details[InvalidAttestation — on-chain verification failed]
**Cause:** The attestation proof failed BLS signature verification on-chain.

**Common reasons:**

* The attestation has expired (check `expiration` field)
* The operator set has rotated since the attestation was produced
* The attestation was produced for a different chain

**Fix:** Request a fresh attestation and submit it before expiration. Ensure the `chainId` in your intent matches the chain where the PolicyClient is deployed.
:::

:::details[PolicyNotFound (-32617) — policy not found]
**Cause:** The Gateway could not find the policy associated with the provided PolicyClient address.

**Fix:** Verify:

1. The PolicyClient address is correct and deployed on the expected chain
2. The PolicyClient has a policy set (use `newton-cli policy-client status`)
3. The PolicyClient is registered with the PolicyClientRegistry
:::

:::details[Unauthorized (-32615) — authentication failed]
**Cause:** Your API key is missing, invalid, or lacks the required permission.

**Fix:**

* Ensure your `Authorization: Bearer <key>` header is present
* Check that your key has the required permission level (`rpc_read` for simulations, `rpc_write` for secret storage)
* Verify the key has not been revoked
:::

:::details[IncompatiblePolicyVersion — version mismatch]
**Cause:** Your PolicyClient contract was deployed with an older SDK version that is incompatible with the current protocol.

**Fix:** Run `newton-cli version check-compatibility` to identify the issue, then `newton-cli version migrate` for automated migration.
:::

:::details[WASM oracle returns empty or unexpected data]
**Cause:** The WASM component's `run` function is not returning valid JSON, or the HTTP fetch is failing silently.

**Fix:**

1. Test locally: `newton-cli --chain-id 11155111 policy-data simulate --wasm-file policy.wasm --input-json '{}'`
2. Verify your `run` function returns a JSON string (not an object)
3. Check that HTTP requests use the correct URL and headers
4. Ensure secrets are stored if your oracle requires API keys
:::

For a complete list of error codes, see the [Error Reference](/developers/reference/error-reference).

## Getting Help

* **GitHub Issues:** [github.com/newt-foundation](https://github.com/newt-foundation)
* **Email:** `support@newton.xyz`
* **Blog:** [blog.newton.xyz](https://blog.newton.xyz)