From e6c77c314a72e51754bf8e60d89d6bc5a95b1ec1 Mon Sep 17 00:00:00 2001 From: Drew Stone Date: Mon, 15 Jun 2026 10:17:22 -0600 Subject: [PATCH] docs(copy): ground claims and sandbox boundaries --- .../ai-agent-sandbox/dapp-and-indexer.mdx | 2 +- .../runtime-and-harnesses.mdx | 2 +- .../ai-trading/operator-requirements.mdx | 2 +- pages/blueprints/operator-matrix.mdx | 2 +- .../api/reference/ITangleServices.mdx | 8 +++--- .../reference/generated/ITangleServices.mdx | 8 +++--- .../blueprint-contexts/introduction.mdx | 2 +- pages/developers/blueprint-qos.mdx | 6 ++--- .../blueprint-runner/background-services.mdx | 4 +-- .../developers/blueprint-runner/building.mdx | 6 ++--- .../developers/blueprint-runner/consumers.mdx | 4 +-- pages/developers/blueprint-runner/jobs.mdx | 4 +-- .../developers/blueprint-runner/producers.mdx | 4 +-- pages/developers/blueprint-runner/routers.mdx | 4 +-- pages/developers/cli/keys.mdx | 4 +-- pages/developers/endpoints.mdx | 16 +++++++++++- pages/developers/key-contacts.mdx | 2 +- pages/developers/slashing.mdx | 2 +- pages/gateway/api-generation.mdx | 4 +-- pages/gateway/authentication.mdx | 2 +- pages/gateway/byok.mdx | 6 ++--- pages/gateway/enterprise-zdr.mdx | 2 +- pages/gateway/fallbacks.mdx | 6 ++--- pages/gateway/getting-started.mdx | 8 +++--- pages/gateway/index.mdx | 26 +++++++++---------- pages/gateway/migrate-openai.mdx | 2 +- pages/gateway/migrate-vercel.mdx | 26 +++++++++---------- pages/gateway/models.mdx | 4 +-- pages/gateway/operator-routing.mdx | 8 +++--- pages/gateway/pricing.mdx | 2 +- pages/gateway/provider-options.mdx | 12 ++++----- pages/gateway/routing-trace.mdx | 4 +-- pages/gateway/smart-routing.mdx | 6 ++--- pages/gateway/timeouts.mdx | 2 +- pages/infrastructure/architecture.mdx | 19 ++++++++++++++ pages/infrastructure/harnesses.mdx | 7 ++--- pages/infrastructure/orchestration.mdx | 14 ++++++++++ pages/infrastructure/sandboxing.mdx | 16 +++++++++++- pages/network/claim-airdrop.mdx | 2 +- pages/network/incentives-developers.mdx | 2 +- pages/network/incentives-stakers.mdx | 2 +- pages/network/points-mechanics.mdx | 6 ++--- pages/operators/manager/requirements.mdx | 2 +- pages/operators/quality-of-service.mdx | 2 +- pages/release-notes/0.13.0.mdx | 14 +++++----- pages/staking/how-staking-works.mdx | 4 +-- pages/staking/introduction.mdx | 19 ++++++++++++++ pages/staking/liquid-staking/introduction.mdx | 2 +- pages/vibe/integrations.mdx | 12 +++++++++ pages/vibe/introduction.mdx | 2 +- pages/vibe/profile-schema.mdx | 2 +- pages/vibe/profiles.mdx | 2 +- pages/vibe/simulations.mdx | 6 +++++ pages/vision/architecture.mdx | 4 +-- pages/vision/introduction.mdx | 2 +- pages/vision/use-cases.mdx | 2 +- 56 files changed, 222 insertions(+), 123 deletions(-) diff --git a/pages/blueprints/ai-agent-sandbox/dapp-and-indexer.mdx b/pages/blueprints/ai-agent-sandbox/dapp-and-indexer.mdx index 34306557..34da02ef 100644 --- a/pages/blueprints/ai-agent-sandbox/dapp-and-indexer.mdx +++ b/pages/blueprints/ai-agent-sandbox/dapp-and-indexer.mdx @@ -62,7 +62,7 @@ The sandbox app is iframe-first. The parent dapp should: ## Bad copy to avoid -Do not name the product after one harness. The Sandbox SDK supports OpenCode plus 12 peer backend types: Claude Code, Kimi Code, Codex, AMP, Factory Droids, Pi, Hermes, Forge, OpenClaw, ACP, Cursor, and CLI base. The current Sandbox UI picker exposes a subset plus NanoClaw. The AI Agent Sandbox blueprint's current all-harness sidecar advertises Claude Code, Codex, OpenCode, Kimi Code, and Gemini CLI. The product boundary is the sandbox service instance and operator API. +Do not name the product after one harness. The Sandbox SDK supports OpenCode plus 13 peer backend types: Claude Code, Kimi Code, Codex, AMP, Factory Droids, Pi, Hermes, Forge, OpenClaw, NanoClaw, ACP, Cursor, and CLI base. The current Sandbox UI picker exposes OpenClaw and NanoClaw while deferring Pi, Forge, ACP, and Cursor. The AI Agent Sandbox blueprint's current all-harness sidecar advertises Claude Code, Codex, OpenCode, Kimi Code, and Gemini CLI. The product boundary is the sandbox service instance and operator API. Use capability language instead: diff --git a/pages/blueprints/ai-agent-sandbox/runtime-and-harnesses.mdx b/pages/blueprints/ai-agent-sandbox/runtime-and-harnesses.mdx index 8e08a8a6..0108f292 100644 --- a/pages/blueprints/ai-agent-sandbox/runtime-and-harnesses.mdx +++ b/pages/blueprints/ai-agent-sandbox/runtime-and-harnesses.mdx @@ -7,7 +7,7 @@ description: Runtime backends, capability discovery, harnesses, and AI credentia The sandbox is the product. Harnesses are tools inside the sandbox. -Do not describe this blueprint as an OpenCode integration, a Codex integration, or a Claude integration. The Sandbox SDK supports OpenCode plus 12 peer backend types: Claude Code, Kimi Code, Codex, AMP, Factory Droids, Pi, Hermes, Forge, OpenClaw, ACP, Cursor, and CLI base. A blueprint service instance asks its operator for the live runtime set through `GET /api/capabilities`. +Do not describe this blueprint as an OpenCode integration, a Codex integration, or a Claude integration. The Sandbox SDK supports OpenCode plus 13 peer backend types: Claude Code, Kimi Code, Codex, AMP, Factory Droids, Pi, Hermes, Forge, OpenClaw, NanoClaw, ACP, Cursor, and CLI base. A blueprint service instance asks its operator for the live runtime set through `GET /api/capabilities`. ## Runtime backends diff --git a/pages/blueprints/ai-trading/operator-requirements.mdx b/pages/blueprints/ai-trading/operator-requirements.mdx index 1e7448c9..19af15b1 100644 --- a/pages/blueprints/ai-trading/operator-requirements.mdx +++ b/pages/blueprints/ai-trading/operator-requirements.mdx @@ -62,7 +62,7 @@ Public admission means public cost exposure. Every accepted bot can use CPU, dis The operator install path defaults new bots to paper trading. Paper mode uses live market data and simulated fills; it should not move capital. -AI keys are optional. If you set `ZAI_API_KEY`, `ANTHROPIC_API_KEY`, `TANGLE_API_KEY`, or OpenCode model/env settings, agentic activation and chat can use those settings when the selected sidecar advertises OpenCode. Treat OpenCode as one harness inside the same capability model as Claude Code, Kimi Code, Codex, AMP, Factory Droids, Pi, Hermes, Forge, OpenClaw, ACP, Cursor, CLI base, or a smaller blueprint sidecar subset. The operator docs are clear: there is no built-in per-bot, per-day, or total LLM spend cap today. Use provider-side billing limits. +AI keys are optional. If you set `ZAI_API_KEY`, `ANTHROPIC_API_KEY`, `TANGLE_API_KEY`, or OpenCode model/env settings, agentic activation and chat can use those settings when the selected sidecar advertises OpenCode. Treat OpenCode as one harness inside the same capability model as Claude Code, Kimi Code, Codex, AMP, Factory Droids, Pi, Hermes, Forge, OpenClaw, NanoClaw, ACP, Cursor, CLI base, or a smaller blueprint sidecar subset. The operator docs are clear: there is no built-in per-bot, per-day, or total LLM spend cap today. Use provider-side billing limits. ## Public endpoint diff --git a/pages/blueprints/operator-matrix.mdx b/pages/blueprints/operator-matrix.mdx index 9da19a71..086a9070 100644 --- a/pages/blueprints/operator-matrix.mdx +++ b/pages/blueprints/operator-matrix.mdx @@ -43,7 +43,7 @@ The three first-party blueprints do not fail the same way. A sandbox operator ru ## Harnesses are not the product boundary -The sandbox product is the sandbox service instance plus its operator API. The Sandbox SDK supports OpenCode, Claude Code, Kimi Code, Codex, AMP, Factory Droids, Pi, Hermes, Forge, OpenClaw, ACP, Cursor, and CLI base. The current all-harness sidecar in the sandbox blueprint advertises Claude Code, Codex, OpenCode, Kimi Code, and Gemini CLI through `GET /api/capabilities`. +The sandbox product is the sandbox service instance plus its operator API. The Sandbox SDK supports OpenCode, Claude Code, Kimi Code, Codex, AMP, Factory Droids, Pi, Hermes, Forge, OpenClaw, NanoClaw, ACP, Cursor, and CLI base. The current all-harness sidecar in the sandbox blueprint advertises Claude Code, Codex, OpenCode, Kimi Code, and Gemini CLI through `GET /api/capabilities`. That endpoint is the contract the app should read. Do not make docs or UI copy pretend OpenCode, Codex, or any one harness is the integration. Harness support can change by publishing a new sidecar image without changing the blueprint ABI. diff --git a/pages/developers/api/reference/ITangleServices.mdx b/pages/developers/api/reference/ITangleServices.mdx index 6ee10aff..dde30bdd 100644 --- a/pages/developers/api/reference/ITangleServices.mdx +++ b/pages/developers/api/reference/ITangleServices.mdx @@ -57,9 +57,9 @@ Approve a service request as one of its operators. _Single entrypoint covering every approval mode. Pass empty/zero fields on `ApprovalParams` to opt out of the corresponding capability:_ -- `securityCommitments == []` — no per-asset commitment supplied. Only valid when the request has no security requirements OR the only requirement is the protocol-default TNT requirement (auto-filled at min-exposure). -- `blsPubkey == [0,0,0,0]` — operator does NOT register a BLS pubkey for aggregated job-result signing. BLS is opt-in; the protocol accepts any operator. -- `teeCommitments == []` — operator does NOT bind to a TEE attestation profile. +- `securityCommitments == []` - no per-asset commitment supplied. Only valid when the request has no security requirements OR the only requirement is the protocol-default TNT requirement (auto-filled at min-exposure). +- `blsPubkey == [0,0,0,0]` - operator does NOT register a BLS pubkey for aggregated job-result signing. BLS is opt-in; the protocol accepts any operator. +- `teeCommitments == []` - operator does NOT bind to a TEE attestation profile. #### getTeeCommitmentRoot @@ -75,7 +75,7 @@ Returns `keccak256(abi.encode(commitments))` over an operator's `TeeAttestationC function teeNonceFor(uint64 requestId) external view returns (bytes32) ``` -Canonical TEE attestation nonce binding for `requestId` on this contract on this chain. Operators MUST submit this exact value as `nonceBinding` in any `TeeAttestationCommitment` for the request — it eliminates cross-request attestation replay at approval time. +Canonical TEE attestation nonce binding for `requestId` on this contract on this chain. Operators MUST submit this exact value as `nonceBinding` in any `TeeAttestationCommitment` for the request - it eliminates cross-request attestation replay at approval time. #### blsPopMessage diff --git a/pages/developers/api/reference/generated/ITangleServices.mdx b/pages/developers/api/reference/generated/ITangleServices.mdx index 6ee10aff..dde30bdd 100644 --- a/pages/developers/api/reference/generated/ITangleServices.mdx +++ b/pages/developers/api/reference/generated/ITangleServices.mdx @@ -57,9 +57,9 @@ Approve a service request as one of its operators. _Single entrypoint covering every approval mode. Pass empty/zero fields on `ApprovalParams` to opt out of the corresponding capability:_ -- `securityCommitments == []` — no per-asset commitment supplied. Only valid when the request has no security requirements OR the only requirement is the protocol-default TNT requirement (auto-filled at min-exposure). -- `blsPubkey == [0,0,0,0]` — operator does NOT register a BLS pubkey for aggregated job-result signing. BLS is opt-in; the protocol accepts any operator. -- `teeCommitments == []` — operator does NOT bind to a TEE attestation profile. +- `securityCommitments == []` - no per-asset commitment supplied. Only valid when the request has no security requirements OR the only requirement is the protocol-default TNT requirement (auto-filled at min-exposure). +- `blsPubkey == [0,0,0,0]` - operator does NOT register a BLS pubkey for aggregated job-result signing. BLS is opt-in; the protocol accepts any operator. +- `teeCommitments == []` - operator does NOT bind to a TEE attestation profile. #### getTeeCommitmentRoot @@ -75,7 +75,7 @@ Returns `keccak256(abi.encode(commitments))` over an operator's `TeeAttestationC function teeNonceFor(uint64 requestId) external view returns (bytes32) ``` -Canonical TEE attestation nonce binding for `requestId` on this contract on this chain. Operators MUST submit this exact value as `nonceBinding` in any `TeeAttestationCommitment` for the request — it eliminates cross-request attestation replay at approval time. +Canonical TEE attestation nonce binding for `requestId` on this contract on this chain. Operators MUST submit this exact value as `nonceBinding` in any `TeeAttestationCommitment` for the request - it eliminates cross-request attestation replay at approval time. #### blsPopMessage diff --git a/pages/developers/blueprint-contexts/introduction.mdx b/pages/developers/blueprint-contexts/introduction.mdx index de77e35d..deffa54f 100644 --- a/pages/developers/blueprint-contexts/introduction.mdx +++ b/pages/developers/blueprint-contexts/introduction.mdx @@ -27,7 +27,7 @@ The Context pattern offers several significant benefits in software design and d 1. **Decoupling**: By passing dependencies through a Context, we decouple the job implementation from the specific implementations of its dependencies. This makes the code more modular and easier to maintain. -2. **Testability**: With a Context, it's easier to mock or stub dependencies during unit testing, allowing for more comprehensive and isolated tests. +2. **Testability**: With a Context, tests can replace RPC clients, keystores, or service clients with mocks and fixtures. 3. **Flexibility**: Contexts allow for easy swapping of implementations, which is particularly useful when adapting to different environments (e.g., development, staging, production). diff --git a/pages/developers/blueprint-qos.mdx b/pages/developers/blueprint-qos.mdx index 93428366..845e3014 100644 --- a/pages/developers/blueprint-qos.mdx +++ b/pages/developers/blueprint-qos.mdx @@ -350,9 +350,9 @@ event MetricViolation( Violation reasons include: -- `"required metric missing"` — a required metric was not reported -- `"value below minimum"` — reported value < `minValue` -- `"value above maximum"` — reported value > `maxValue` +- `"required metric missing"` - a required metric was not reported +- `"value below minimum"` - reported value < `minValue` +- `"value above maximum"` - reported value > `maxValue` Slashing is intentionally decoupled from validation. Auto-slashing from metric violations is dangerous because transient spikes or network delays could trigger false positives. Instead: diff --git a/pages/developers/blueprint-runner/background-services.mdx b/pages/developers/blueprint-runner/background-services.mdx index ae6ded1f..f6e5cc97 100644 --- a/pages/developers/blueprint-runner/background-services.mdx +++ b/pages/developers/blueprint-runner/background-services.mdx @@ -86,6 +86,6 @@ Now that you understand background services, it might be helpful to take a look - [Consumers](/developers/blueprint-runner/consumers) - How to handle job results - [Building a Blueprint Runner](/developers/blueprint-runner/building) - Step-by-step guide to building your own Blueprint Runner -## Conclusion +## Before You Ship -Background services are powerful components that enhance the capabilities of your Blueprint Runner by providing continuous support operations. By implementing well-designed background services, you can build more robust, efficient, and feature-rich Blueprints. +Verify that each background service starts, reports failure, and shuts down cleanly. If the service owns a connection, lock, or local process, its shutdown handler should release that resource before the runner exits. diff --git a/pages/developers/blueprint-runner/building.mdx b/pages/developers/blueprint-runner/building.mdx index ef3aa868..29d3440f 100644 --- a/pages/developers/blueprint-runner/building.mdx +++ b/pages/developers/blueprint-runner/building.mdx @@ -165,7 +165,7 @@ let result = BlueprintRunner::builder(tangle_config, env) The `run` method starts the Blueprint Runner and returns a result indicating whether it ran successfully or encountered an error. -With this, the Blueprint Runner, the centerpoint of your Blueprint is ready to be used! +With this, the Blueprint Runner can start and serve the components you attached to the builder. ## Next Steps @@ -175,6 +175,6 @@ After building your Blueprint Runner, you might want to explore: - [Producer Patterns](/developers/blueprint-runner/producers#producer-patterns) - [Consumer Patterns](/developers/blueprint-runner/consumers#consumer-patterns) -## Conclusion +## Before You Ship -Building a Blueprint Runner involves setting up various components that work together to execute your Tangle Blueprint. By following this guide and adhering to best practices, you can create a robust and efficient Blueprint Runner for your blueprint service on the Tangle Network. +Run the runner against a local node or testnet, submit one real job, and keep the transaction hash plus runner logs. A runner is ready for operators only after it can start, receive a job, execute the handler, and return the expected result. diff --git a/pages/developers/blueprint-runner/consumers.mdx b/pages/developers/blueprint-runner/consumers.mdx index ea335eae..3f292c23 100644 --- a/pages/developers/blueprint-runner/consumers.mdx +++ b/pages/developers/blueprint-runner/consumers.mdx @@ -99,6 +99,6 @@ Now that you understand consumers, learn about: - [Producers](/developers/blueprint-runner/producers) - How to capture and process events - [Building a Blueprint Runner](/developers/blueprint-runner/building) - Step-by-step guide to building your own Blueprint Runner -## Conclusion +## Before You Ship -Consumers are essential components that translate job results into meaningful actions in your Blueprint Runner. By implementing robust and efficient consumers, you can ensure that your Blueprint operates reliably and effectively. +Check the consumer path with a successful result and a failed result. The runner should record the outcome, retry only when the action is safe to repeat, and surface enough context for an operator to debug the failure. diff --git a/pages/developers/blueprint-runner/jobs.mdx b/pages/developers/blueprint-runner/jobs.mdx index 112c15c4..74fbf028 100644 --- a/pages/developers/blueprint-runner/jobs.mdx +++ b/pages/developers/blueprint-runner/jobs.mdx @@ -101,6 +101,6 @@ Now that you understand jobs, it might be helpful to take a look at: - [Consumers](/developers/blueprint-runner/consumers) - How to handle job results - [Building a Blueprint Runner](/developers/blueprint-runner/building) - Step-by-step guide to building your own Blueprint Runner -## Conclusion +## Before You Ship -Jobs are the core building blocks of your Blueprint, encapsulating the business logic that processes events and produces meaningful results. By implementing well-designed jobs, you can create powerful and flexible Blueprints that can handle a wide range of use cases. +Test each job with valid input, invalid input, and an execution failure. The handler should reject malformed calls before doing work and return errors that let a consumer decide whether to retry, alert, or stop. diff --git a/pages/developers/blueprint-runner/producers.mdx b/pages/developers/blueprint-runner/producers.mdx index 7b8617e4..3c7afa98 100644 --- a/pages/developers/blueprint-runner/producers.mdx +++ b/pages/developers/blueprint-runner/producers.mdx @@ -97,6 +97,6 @@ Now that you understand producers, learn about: - [Consumers](/developers/blueprint-runner/consumers) - How to handle job results - [Building a Blueprint Runner](/developers/blueprint-runner/building) - Step-by-step guide to building your own Blueprint Runner -## Conclusion +## Before You Ship -Producers are essential components that capture and prepare events for processing in your Blueprint Runner. By implementing robust and efficient producers, you can ensure that your Blueprint reliably processes desired events. +Run the producer against the real event source or a recorded fixture. It should emit the same `JobCall` shape the router expects, preserve ordering where the service requires it, and stop cleanly when the runner shuts down. diff --git a/pages/developers/blueprint-runner/routers.mdx b/pages/developers/blueprint-runner/routers.mdx index 8cb45768..45037eb8 100644 --- a/pages/developers/blueprint-runner/routers.mdx +++ b/pages/developers/blueprint-runner/routers.mdx @@ -74,6 +74,6 @@ Now that you understand routers, check out: - [Consumers](/developers/blueprint-runner/consumers) - How to handle job results - [Building a Blueprint Runner](/developers/blueprint-runner/building) - Step-by-step guide to building your own Blueprint Runner -## Conclusion +## Before You Ship -Routers are a fundamental component of Blueprint Runners, enabling efficient job execution and management. By properly configuring and utilizing routers, you can build robust and performant Blueprints. +Submit at least one job per route and one unknown job ID. The router should dispatch known calls to the intended handler, reject unknown calls clearly, and preserve the error shape your consumers expect. diff --git a/pages/developers/cli/keys.mdx b/pages/developers/cli/keys.mdx index e9f51f10..c84274e8 100644 --- a/pages/developers/cli/keys.mdx +++ b/pages/developers/cli/keys.mdx @@ -158,7 +158,7 @@ The Tangle CLI supports the following key types: ## Best Practices -1. **Backup your keys**: Always keep a secure backup of your keys or mnemonic phrases. -2. **Secure your keystore**: Ensure your keystore directory has appropriate permissions. +1. **Back up recovery material**: Store mnemonic phrases offline and test recovery before funding an account. +2. **Lock down your keystore**: Restrict the keystore directory to the OS user that runs the CLI, for example with `chmod 700 ` on Linux/macOS. 3. **Use different keys for different environments**: Use separate keys for testnet and mainnet. 4. **Never share your private keys**: Keep your private keys confidential. diff --git a/pages/developers/endpoints.mdx b/pages/developers/endpoints.mdx index a09936eb..21de6421 100644 --- a/pages/developers/endpoints.mdx +++ b/pages/developers/endpoints.mdx @@ -1,5 +1,19 @@ import NetworkTabs from "../../components/NetworkResources.tsx" -# Resources +# Network Resources + +Use this page when you need the public dapp, chain endpoints, explorers, wallet metadata, or source repos for Tangle. + +## What to use + +| Need | Use | +| -------------------------------- | ----------------------------------------------------------------------- | +| Stake, delegate, or inspect apps | The Tangle dapp for the target network. | +| Read chain state | The public RPC or WSS endpoint for the target network. | +| Check transactions and contracts | The EVM explorer for the target network. | +| Build protocol integrations | The `tnt-core` contracts and generated bindings for the current branch. | +| Build or run Blueprint services | The Blueprint SDK and product-specific blueprint docs. | + +Public RPC endpoints are shared infrastructure. Production apps and operators should use their own RPC provider or a monitored endpoint when reliability matters. diff --git a/pages/developers/key-contacts.mdx b/pages/developers/key-contacts.mdx index 56fcb036..ce41370d 100644 --- a/pages/developers/key-contacts.mdx +++ b/pages/developers/key-contacts.mdx @@ -7,7 +7,7 @@ Primary points of contact for Tangle Network security, operations, and complianc | Founder and CEO | Drew Stone | drew@tangle.tools | | Security Contact | Drew Stone | drew@tangle.tools | | Compliance Contact | Drew Stone | drew@tangle.tools | -| General Inquiries | — | hello@tangle.tools | +| General Inquiries | - | hello@tangle.tools | ## Reporting Security Issues diff --git a/pages/developers/slashing.mdx b/pages/developers/slashing.mdx index 1530e7fd..505a6245 100644 --- a/pages/developers/slashing.mdx +++ b/pages/developers/slashing.mdx @@ -58,7 +58,7 @@ The operator must post `config.disputeBond` in native asset. `SLASH_ADMIN` posts A `SLASH_ADMIN_ROLE` holder that is also the `proposer` of a slash CANNOT dispute their own proposal. Without this, a single role-holder could propose, immediately self-dispute (no bond), -and freeze operator stake for the full `disputeResolutionDeadline` window — and (when +and freeze operator stake for the full `disputeResolutionDeadline` window - and (when `treasury == admin`) capture the operator's bond on auto-execution. To dispute as `SLASH_ADMIN`, route the dispute through a different admin-keyed account or the operator. diff --git a/pages/gateway/api-generation.mdx b/pages/gateway/api-generation.mdx index b86cf608..bc86a34a 100644 --- a/pages/gateway/api-generation.mdx +++ b/pages/gateway/api-generation.mdx @@ -50,6 +50,6 @@ Authorization: Bearer sk-tan-YOUR_KEY | Status | Code | Description | | ------ | ----------- | ----------------------------------------------- | -| 400 | — | Missing or invalid generation ID | -| 401 | — | Authentication required | +| 400 | - | Missing or invalid generation ID | +| 401 | - | Authentication required | | 404 | `not_found` | Generation not found or belongs to another user | diff --git a/pages/gateway/authentication.mdx b/pages/gateway/authentication.mdx index 5ce04f4e..d0da267d 100644 --- a/pages/gateway/authentication.mdx +++ b/pages/gateway/authentication.mdx @@ -38,7 +38,7 @@ POST /api/siwe/verify ## SpendAuth (On-Chain Payment) -EIP-712 signed payment authorization. No account needed — pay operators directly on-chain. +EIP-712 signed payment authorization. No account needed - pay operators directly on-chain. ```bash curl -H "X-Payment-Signature: {\"commitment\":\"0x...\",\"amount\":\"1000000\",...}" \ diff --git a/pages/gateway/byok.mdx b/pages/gateway/byok.mdx index 120af118..a28609b6 100644 --- a/pages/gateway/byok.mdx +++ b/pages/gateway/byok.mdx @@ -5,7 +5,7 @@ description: Use your own provider API keys with Tangle Gateway for zero-markup # Bring Your Own Key (BYOK) -Use your existing provider API keys with Tangle Gateway. BYOK requests have **zero platform markup** — you pay the provider's list price directly. +Use your existing provider API keys with Tangle Gateway. BYOK requests have **zero platform markup** - you pay the provider's list price directly. ## Per-request BYOK @@ -61,7 +61,7 @@ Specify multiple credentials per provider. The gateway tries them in order: ## Automatic fallback -If your BYOK credentials fail (401, 403, rate limit), the gateway automatically falls back to platform credentials. This fallback preserves all compliance filters — if you requested [ZDR](/gateway/zdr), the fallback will only use ZDR-compliant system credentials. +If your BYOK credentials fail (401, 403, rate limit), the gateway automatically falls back to platform credentials. This fallback preserves all compliance filters - if you requested [ZDR](/gateway/zdr), the fallback will only use ZDR-compliant system credentials. The `X-Tangle-BYOK` response header indicates whether the request used your credentials: @@ -75,7 +75,7 @@ If the header is absent, platform credentials were used (possibly via fallback). | Credential type | Markup | | -------------------- | ---------------------------- | -| BYOK | **0%** — provider list price | +| BYOK | **0%** - provider list price | | Platform credentials | 20% markup (configurable) | ## Security diff --git a/pages/gateway/enterprise-zdr.mdx b/pages/gateway/enterprise-zdr.mdx index c1d157ae..a22fdfc1 100644 --- a/pages/gateway/enterprise-zdr.mdx +++ b/pages/gateway/enterprise-zdr.mdx @@ -20,7 +20,7 @@ Read the [ZDR trust model](/gateway/zdr#trust-model) first. Key points: ### Option A: Team-wide ZDR (recommended) -Enable ZDR for all requests from your team. No code changes needed — every request is automatically filtered. +Enable ZDR for all requests from your team. No code changes needed - every request is automatically filtered. Contact your admin to set `zdrEnabled: true` on your team record via the admin API: diff --git a/pages/gateway/fallbacks.mdx b/pages/gateway/fallbacks.mdx index bd01e96f..626b36db 100644 --- a/pages/gateway/fallbacks.mdx +++ b/pages/gateway/fallbacks.mdx @@ -35,9 +35,9 @@ The response comes from the first model that succeeds. For each model in the list, the gateway runs the full routing chain: -1. **Operators** — try operators serving this model (if available) -2. **LiteLLM** — try the proxy with built-in retries -3. **Direct provider** — call the provider API directly +1. **Operators** - try operators serving this model (if available) +2. **LiteLLM** - try the proxy with built-in retries +3. **Direct provider** - call the provider API directly If all tiers fail for a model, the gateway moves to the next model in the list. diff --git a/pages/gateway/getting-started.mdx b/pages/gateway/getting-started.mdx index 30d1edd2..0c399abe 100644 --- a/pages/gateway/getting-started.mdx +++ b/pages/gateway/getting-started.mdx @@ -85,10 +85,10 @@ deepseek/deepseek-chat mistral/mistral-large-latest ``` -You can also use bare model names (`gpt-4o-mini`, `claude-sonnet-4-6`) — the gateway resolves the provider automatically. +You can also use bare model names (`gpt-4o-mini`, `claude-sonnet-4-6`) - the gateway resolves the provider automatically. ## What's next -- [Bring Your Own Key](/gateway/byok) — use your existing provider API keys for zero markup -- [Model Fallbacks](/gateway/fallbacks) — configure backup models -- [Zero Data Retention](/gateway/zdr) — compliance for sensitive workloads +- [Bring Your Own Key](/gateway/byok) - use your existing provider API keys for zero markup +- [Model Fallbacks](/gateway/fallbacks) - configure backup models +- [Zero Data Retention](/gateway/zdr) - compliance for sensitive workloads diff --git a/pages/gateway/index.mdx b/pages/gateway/index.mdx index 57c7630a..00db1542 100644 --- a/pages/gateway/index.mdx +++ b/pages/gateway/index.mdx @@ -5,15 +5,15 @@ description: Unified API for hundreds of AI models with built-in routing, compli # Tangle Gateway -Tangle Gateway is a unified inference API. One endpoint, hundreds of models, automatic routing across centralized providers and decentralized operators. +Tangle Gateway is a unified inference API. One endpoint, hundreds of models, and routing across provider APIs and registered Tangle operators. ## What it does - **One key, any model.** Access OpenAI, Anthropic, Google, Groq, Mistral, and 20+ providers through a single API key. -- **Operator network.** Route to decentralized operators running [Blueprints](/developers/blueprints/introduction) on the Tangle network who compete on price, latency, and reputation. +- **Operator network.** Route to operators registered for [Blueprints](/developers/blueprints/introduction); the gateway selects from their advertised endpoint, model support, price, latency, and reputation data. - **Compliance routing.** Zero Data Retention and no-train filtering with verified provider agreements. - **BYOK.** Bring your own provider keys for zero-markup access. -- **On-chain payments.** Pay operators directly via SpendAuth — no credit card required. +- **On-chain payments.** Pay operators directly via SpendAuth - no credit card required. ## Quick example @@ -34,13 +34,13 @@ Works with any OpenAI-compatible SDK. Change the base URL and you're done. The gateway routes through three tiers, in order: -| Tier | What | When | -| ------------- | ---------------------------------------------------------- | -------------------------------------------------------------- | -| **Operators** | Decentralized inference providers on Tangle | Default for operator-pinned requests and SpendAuth | -| **LiteLLM** | Proxy with 100+ provider integrations and built-in retries | Default for standard requests | -| **Direct** | Straight to provider API (OpenAI, Anthropic, etc.) | Fallback when LiteLLM unavailable, or when compliance required | +| Tier | What | When | +| ------------- | --------------------------------------------------------------- | -------------------------------------------------------------- | +| **Operators** | Tangle-registered inference operators with advertised endpoints | Default for operator-pinned requests and SpendAuth | +| **LiteLLM** | Proxy with 100+ provider integrations and built-in retries | Default for standard requests | +| **Direct** | Straight to provider API (OpenAI, Anthropic, etc.) | Fallback when LiteLLM unavailable, or when compliance required | -When [Zero Data Retention](/gateway/zdr) or [no-train](/gateway/no-train) is requested, operators and LiteLLM are skipped — the gateway routes directly to verified providers only. +When [Zero Data Retention](/gateway/zdr) or [no-train](/gateway/no-train) is requested, operators and LiteLLM are skipped - the gateway routes directly to verified providers only. ## How it fits @@ -52,7 +52,7 @@ The gateway sits between the [Workbench](/vibe/introduction) where agents run an ## Next steps -- [Getting Started](/gateway/getting-started) — make your first request in 2 minutes -- [Supported Models](/gateway/models) — browse the model catalog -- [How Routing Works](/gateway/how-routing-works) — understand the 3-tier architecture -- [Zero Data Retention](/gateway/zdr) — compliance for regulated industries +- [Getting Started](/gateway/getting-started) - make your first request in 2 minutes +- [Supported Models](/gateway/models) - browse the model catalog +- [How Routing Works](/gateway/how-routing-works) - understand the 3-tier architecture +- [Zero Data Retention](/gateway/zdr) - compliance for regulated industries diff --git a/pages/gateway/migrate-openai.mdx b/pages/gateway/migrate-openai.mdx index c27336f5..f9f2902a 100644 --- a/pages/gateway/migrate-openai.mdx +++ b/pages/gateway/migrate-openai.mdx @@ -20,7 +20,7 @@ Tangle Gateway is OpenAI-compatible. Change two lines and you're done. response = client.chat.completions.create( - model="gpt-4o", -+ model="openai/gpt-4o", # or just "gpt-4o" — auto-resolved ++ model="openai/gpt-4o", # or just "gpt-4o" - auto-resolved messages=[{"role": "user", "content": "Hello"}] ) ``` diff --git a/pages/gateway/migrate-vercel.mdx b/pages/gateway/migrate-vercel.mdx index abad708f..e217783f 100644 --- a/pages/gateway/migrate-vercel.mdx +++ b/pages/gateway/migrate-vercel.mdx @@ -23,16 +23,16 @@ Tangle Gateway supports the same `providerOptions.gateway` schema as Vercel AI G ## What's different -| Feature | Vercel | Tangle | -| --------------------- | ------------------------------------- | -------------------------------------------------------- | -| **Base URL** | `ai-gateway.vercel.sh/v1` | `router.tangle.tools/v1` | -| **Auth** | API key or OIDC token | API key, session, SIWE (wallet), or SpendAuth (on-chain) | -| **Pricing** | Zero markup | 20% markup (0% with BYOK) | -| **Operator network** | None | Decentralized operators compete on price/latency | -| **On-chain payments** | None | SpendAuth (EIP-712) — pay without a credit card | -| **Guardrails** | None | PII + injection detection built-in | -| **Web search tools** | Perplexity, Parallel, provider-native | Not yet (planned) | -| **OIDC auth** | Vercel-only | Not applicable | +| Feature | Vercel | Tangle | +| --------------------- | ------------------------------------- | --------------------------------------------------------------------- | +| **Base URL** | `ai-gateway.vercel.sh/v1` | `router.tangle.tools/v1` | +| **Auth** | API key or OIDC token | API key, session, SIWE (wallet), or SpendAuth (on-chain) | +| **Pricing** | Zero markup | 20% markup (0% with BYOK) | +| **Operator network** | None | Registered Tangle operators expose endpoints, prices, and health data | +| **On-chain payments** | None | SpendAuth (EIP-712) - pay without a credit card | +| **Guardrails** | None | PII + injection detection built-in | +| **Web search tools** | Perplexity, Parallel, provider-native | Not available through Tangle Gateway today | +| **OIDC auth** | Vercel-only | Not applicable | ## Code change @@ -73,8 +73,8 @@ Tangle Gateway supports the same `providerOptions.gateway` schema as Vercel AI G ## What you gain -- **Operator network.** Access decentralized inference providers who compete on price and latency. -- **On-chain payments.** Pay with crypto via SpendAuth — no Stripe/credit card required. +- **Operator network.** Access registered Tangle operators selected by endpoint health, model support, price, latency, and reputation data. +- **On-chain payments.** Pay with crypto via SpendAuth - no Stripe/credit card required. - **Wallet auth.** Sign in with Ethereum (SIWE) for web3-native access. - **Guardrails.** Built-in PII and prompt injection detection on every request. -- **Self-hostable.** Deploy your own gateway instance — it's open source. +- **Self-hostable.** Deploy your own gateway instance - it's open source. diff --git a/pages/gateway/models.mdx b/pages/gateway/models.mdx index 4c058018..4c5ec071 100644 --- a/pages/gateway/models.mdx +++ b/pages/gateway/models.mdx @@ -28,7 +28,7 @@ Tangle Gateway provides access to models from 20+ providers through a single API | Z.ai | `zai` | GLM-4.7, GLM-5 | | Moonshot | `moonshot` | Kimi | -Plus decentralized operators on the Tangle network running [Blueprints](/developers/blueprints/introduction): +Plus operators registered on Tangle and running [Blueprints](/developers/blueprints/introduction): | Blueprint | Models | How to route | | -------------------------------------------------------------------------- | ----------------------------------------------- | ------------------------------------- | @@ -48,7 +48,7 @@ openai/gpt-4o-mini groq/llama-3.1-70b-versatile ``` -Or use bare names — the gateway resolves the provider by prefix: +Or use bare names - the gateway resolves the provider by prefix: | Prefix | Resolves to | | --------------------------- | ----------- | diff --git a/pages/gateway/operator-routing.mdx b/pages/gateway/operator-routing.mdx index 89bba309..fb02946d 100644 --- a/pages/gateway/operator-routing.mdx +++ b/pages/gateway/operator-routing.mdx @@ -1,6 +1,6 @@ --- title: Operator Routing -description: Route inference through decentralized operators on the Tangle network. +description: Route inference through registered operators on the Tangle network. --- # Operator Routing @@ -17,7 +17,7 @@ Operators run **Blueprints**: service templates that define what software an ope | **Vector Store** | Embedding storage and retrieval for RAG | Operator-deployed | | **Custom** | Any model/pipeline an operator chooses to serve | [Build your own](/developers/blueprints/introduction) | -The LLM Inference Blueprint uses [tangle-inference-core](https://github.com/tangle-network/tangle-inference-core) — a shared Rust crate for EIP-712 signature verification, nonce management, and on-chain settlement. Operators compile it into a binary (`operator-lite`) that runs alongside their model server. +The LLM Inference Blueprint uses [tangle-inference-core](https://github.com/tangle-network/tangle-inference-core) - a shared Rust crate for EIP-712 signature verification, nonce management, and on-chain settlement. Operators compile it into a binary (`operator-lite`) that runs alongside their model server. To build and deploy your own inference Blueprint, see the [Blueprint SDK docs](/developers/blueprints/introduction) and the [Blueprint Runner](/developers/blueprint-runner/introduction). @@ -85,5 +85,5 @@ Because endpoint URL and backing provider are self-reported, operator routing is Operator requests can be paid two ways: -1. **Platform credits** — deducted from your credit balance at the operator's listed price -2. **SpendAuth (on-chain)** — direct EIP-712 signed payment to the operator. No credit card needed. See [SpendAuth](/gateway/spend-auth). +1. **Platform credits** - deducted from your credit balance at the operator's listed price +2. **SpendAuth (on-chain)** - direct EIP-712 signed payment to the operator. No credit card needed. See [SpendAuth](/gateway/spend-auth). diff --git a/pages/gateway/pricing.mdx b/pages/gateway/pricing.mdx index 6634f841..c95640c2 100644 --- a/pages/gateway/pricing.mdx +++ b/pages/gateway/pricing.mdx @@ -10,7 +10,7 @@ description: How billing works on Tangle Gateway. | Credential type | Markup | | -------------------------------- | ------------------------------------------- | | Platform credentials | 20% above provider list price | -| [BYOK](/gateway/byok) | **0%** — provider list price, no markup | +| [BYOK](/gateway/byok) | **0%** - provider list price, no markup | | [SpendAuth](/gateway/spend-auth) | Operator-set prices (typically competitive) | The 20% platform markup on non-BYOK requests funds operator payouts and platform infrastructure. Operators earn a share of every request routed through them. diff --git a/pages/gateway/provider-options.mdx b/pages/gateway/provider-options.mdx index ccb49797..f471ef07 100644 --- a/pages/gateway/provider-options.mdx +++ b/pages/gateway/provider-options.mdx @@ -38,14 +38,14 @@ interface GatewayOptions { | Option | Type | Default | Description | | ------------------------ | ---------------------------------- | ------- | -------------------------------------------------------------- | -| `byok` | `Record>` | — | Per-request provider credentials. [Details](/gateway/byok) | +| `byok` | `Record>` | - | Per-request provider credentials. [Details](/gateway/byok) | | `zeroDataRetention` | `boolean` | `false` | Route only to ZDR-verified providers. [Details](/gateway/zdr) | | `disallowPromptTraining` | `boolean` | `false` | Route only to no-train providers. [Details](/gateway/no-train) | -| `caching` | `'auto'` | — | Auto-inject prompt cache markers. [Details](/gateway/caching) | -| `cache` | `false` | — | Set `false` to skip response cache for this request. | -| `order` | `string[]` | — | Provider priority order. [Details](/gateway/smart-routing) | -| `only` | `string[]` | — | Restrict to these providers only. | -| `models` | `string[]` | — | Fallback model list. [Details](/gateway/fallbacks) | +| `caching` | `'auto'` | - | Auto-inject prompt cache markers. [Details](/gateway/caching) | +| `cache` | `false` | - | Set `false` to skip response cache for this request. | +| `order` | `string[]` | - | Provider priority order. [Details](/gateway/smart-routing) | +| `only` | `string[]` | - | Restrict to these providers only. | +| `models` | `string[]` | - | Fallback model list. [Details](/gateway/fallbacks) | | `timeout` | `number \| Record` | `30000` | Timeout in ms. [Details](/gateway/timeouts) | ## Example: everything at once diff --git a/pages/gateway/routing-trace.mdx b/pages/gateway/routing-trace.mdx index 9e23653d..cfb9a197 100644 --- a/pages/gateway/routing-trace.mdx +++ b/pages/gateway/routing-trace.mdx @@ -5,7 +5,7 @@ description: See exactly which providers were tried for every request. # Routing Trace -Every response includes an `X-Tangle-Routing-Trace` header showing the routing path — which providers were tried, whether they succeeded, and how long each took. +Every response includes an `X-Tangle-Routing-Trace` header showing the routing path - which providers were tried, whether they succeeded, and how long each took. ## Header format @@ -29,7 +29,7 @@ The trace header is sanitized for safety: - Error messages are not included (only status codes) - Internal URLs and hostnames are never leaked -For the full unredacted trace including error messages, use the [generation lookup API](/gateway/generation-lookup) — the `routing_trace` field in the response contains the complete history. +For the full unredacted trace including error messages, use the [generation lookup API](/gateway/generation-lookup) - the `routing_trace` field in the response contains the complete history. ## Disabling diff --git a/pages/gateway/smart-routing.mdx b/pages/gateway/smart-routing.mdx index 9521f60f..cebfd8f5 100644 --- a/pages/gateway/smart-routing.mdx +++ b/pages/gateway/smart-routing.mdx @@ -33,9 +33,9 @@ If a preferred operator is specified (via `X-Tangle-Operator`), it's moved to th The gateway tracks operator health via: -- **Health checks** — periodic probes stored in `OperatorHealthCheck` -- **Request outcomes** — success/failure recorded per request -- **Latency tracking** — rolling average updated per request +- **Health checks** - periodic probes stored in `OperatorHealthCheck` +- **Request outcomes** - success/failure recorded per request +- **Latency tracking** - rolling average updated per request Operators that consistently fail are automatically deprioritized by their dropping reputation and rising latency scores. diff --git a/pages/gateway/timeouts.mdx b/pages/gateway/timeouts.mdx index 6c49cc18..8b10a979 100644 --- a/pages/gateway/timeouts.mdx +++ b/pages/gateway/timeouts.mdx @@ -54,4 +54,4 @@ Values outside this range are silently clamped to the nearest bound. ## Interaction with fallbacks -When a provider times out, it counts as a failure in the [routing trace](/gateway/routing-trace) and the gateway moves to the next option — either a different provider for the same model, or the next [fallback model](/gateway/fallbacks). +When a provider times out, it counts as a failure in the [routing trace](/gateway/routing-trace) and the gateway moves to the next option - either a different provider for the same model, or the next [fallback model](/gateway/fallbacks). diff --git a/pages/infrastructure/architecture.mdx b/pages/infrastructure/architecture.mdx index 5816bb11..a5f5b6e5 100644 --- a/pages/infrastructure/architecture.mdx +++ b/pages/infrastructure/architecture.mdx @@ -2,6 +2,15 @@ The runtime is split into an orchestrator and execution sidecars so workloads stay isolated while coordination stays flexible. +The runtime has two operating modes: + +| Mode | Source of truth | +| ----------------------- | -------------------------------------------------------------------------------------------------- | +| Tangle-managed API mode | Product access, profiles, API keys, and hosted orchestration state. | +| Onchain service mode | Blueprint registration, service instances, operator commitments, and payment settlement on Tangle. | + +Both modes isolate work, stream events, and keep execution reviewable. The app should show which mode a user is entering before it asks them to trust an operator endpoint. + ## Core Components - **Orchestrator**: Accepts run requests, validates policy, selects hosts, and manages sidecar lifecycle. @@ -19,3 +28,13 @@ This architecture keeps workloads portable while maintaining consistent safety g - **Capacity-aware placement**: Allocate based on host health and resource limits. - **Resilient streams**: Event buffering and replay support intermittent connections. - **Policy-first execution**: Every task is validated before it runs. + +## Readiness Checks + +Before routing a user into a runtime, the app should verify: + +1. The session API is reachable from the client or server path that will use it. +2. The selected host has capacity for the requested CPU, memory, disk, and timeout. +3. The profile allows the requested tools, domains, files, secrets, and model provider. +4. The runtime emits events for start, tool calls, file changes, completion, and failure. +5. For protocol-backed services, the service instance and operator endpoint match the chain state the app is displaying. diff --git a/pages/infrastructure/harnesses.mdx b/pages/infrastructure/harnesses.mdx index fd1e8585..e0571aca 100644 --- a/pages/infrastructure/harnesses.mdx +++ b/pages/infrastructure/harnesses.mdx @@ -11,7 +11,7 @@ There are three related surfaces: | Surface | Source of truth | Current harness set | | ---------------------------------- | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Published Sandbox SDK | `@tangle-network/sandbox` `BackendType` | OpenCode, Claude Code, Kimi Code, Codex, AMP, Factory Droids, Pi, Hermes, Forge, OpenClaw, ACP, Cursor, and CLI base. | +| Published Sandbox SDK | `@tangle-network/sandbox` `BackendType` | OpenCode, Claude Code, Kimi Code, Codex, AMP, Factory Droids, Pi, Hermes, Forge, OpenClaw, NanoClaw, ACP, Cursor, and CLI base. | | Current Sandbox UI picker | `sandbox-ui` harness picker | OpenCode, Claude Code, Codex, AMP, Factory Droids, Kimi Code, OpenClaw, NanoClaw, Hermes, and CLI base. The picker defers SDK backends such as Pi, Forge, ACP, and Cursor until copy and compatibility policy land. | | AI Agent Sandbox blueprint sidecar | The operator's `/api/capabilities` response | Claude Code, Codex, OpenCode, Kimi Code, and Gemini CLI in the current `ghcr.io/tangle-network/blueprint-sidecar:all-harness` image. | @@ -35,11 +35,12 @@ The published SDK accepts these backend types: | Hermes | Hermes coding harness. | | Forge | SDK backend type; not surfaced in the current Sandbox UI picker. | | OpenClaw | Dispatcher path for Claude, Codex, and Gemini CLIs. | +| NanoClaw | Local socket-bridge agent backend. | | ACP | Agent Client Protocol bridge for ACP-compliant agent binaries. | | Cursor | Cursor Agent SDK backend. | | CLI base | Shell and workflow tools without a coding harness. | -The current Sandbox UI picker also surfaces NanoClaw, a local socket-bridge agent backend, while deferring Pi, Forge, ACP, and Cursor. Product docs should say which surface they mean. +The current Sandbox UI picker exposes OpenClaw and NanoClaw while deferring Pi, Forge, ACP, and Cursor. Product docs should say which surface they mean and should prefer `/api/capabilities` for live operator surfaces. These are execution harnesses, not routing categories. Every coding harness runs inside the sandbox. Unless a profile, user setting, or operator config points elsewhere, model calls go through Tangle Router. Do not describe routing as a property of one harness. @@ -60,7 +61,7 @@ Read `GET /api/capabilities` before rendering a harness choice. The image tag is Any public copy that names OpenCode must name the peer harnesses or link to this page. The correct framing is: -> The sandbox supports multiple harnesses. OpenCode is one adapter beside Claude Code, Kimi Code, Codex, AMP, Factory Droids, Pi, Hermes, Forge, OpenClaw, ACP, Cursor, CLI base, and blueprint sidecar images that may advertise a smaller set through `/api/capabilities`. +> The sandbox supports multiple harnesses. OpenCode is one adapter beside Claude Code, Kimi Code, Codex, AMP, Factory Droids, Pi, Hermes, Forge, OpenClaw, NanoClaw, ACP, Cursor, CLI base, and blueprint sidecar images that may advertise a smaller set through `/api/capabilities`. The wrong framing is: diff --git a/pages/infrastructure/orchestration.mdx b/pages/infrastructure/orchestration.mdx index 42ea3dc4..50da900f 100644 --- a/pages/infrastructure/orchestration.mdx +++ b/pages/infrastructure/orchestration.mdx @@ -10,6 +10,8 @@ Orchestration turns workbench intent into sandboxed execution. It coordinates si 4. Events stream to clients with buffering and replay support. 5. Completion, failure, or cancellation updates metrics and metadata. +The orchestrator should fail before allocation when policy or capacity is invalid. Once a sidecar starts, failures should be visible as session events and metrics, not hidden as missing output. + ## What Orchestration Covers - **Placement and capacity**: Host health, resource-aware limits, and pool membership. @@ -19,3 +21,15 @@ Orchestration turns workbench intent into sandboxed execution. It coordinates si - **Observability hooks**: Health endpoints and metrics for fleet visibility. This is how the workbench and protocol workloads remain predictable even when the compute layer is distributed. + +## Operator Preflight + +For a hosted pool or protocol-backed operator endpoint, check these before accepting traffic: + +| Check | Why it matters | +| -------------------------------------------------- | ----------------------------------------------------------------------- | +| `/health` or equivalent host probe returns healthy | The process and required dependencies are up. | +| A new session can be created and cancelled | Lifecycle control works before customer work starts. | +| A short command or prompt emits events | Streaming and execution are wired through the same path users will hit. | +| Capacity counters move after the run | Placement decisions are using live resource state. | +| Failure events include a reason | Operators can debug without guessing which subsystem failed. | diff --git a/pages/infrastructure/sandboxing.mdx b/pages/infrastructure/sandboxing.mdx index 2fe98585..bceeea86 100644 --- a/pages/infrastructure/sandboxing.mdx +++ b/pages/infrastructure/sandboxing.mdx @@ -2,6 +2,8 @@ Every workload runs inside an isolated sandbox. This protects the host, the operator, and the customer while making agent behavior reviewable. +Isolation is enforced by the runtime. Slashing applies only when an onchain Blueprint service defines the fault, the evidence path, and the slashable collateral. Tangle-managed API incidents still need operational response even when no onchain slashing rule applies. + ## Isolation Technologies Operators choose isolation based on security requirements and workload type: @@ -23,7 +25,7 @@ Regardless of technology, these guarantees must hold: - **Network isolation**: Restricted external access per policy. - **Resource limits**: Bounded CPU, memory, and I/O consumption. -Operators who fail to maintain isolation guarantees are subject to slashing. +For onchain services, slashing depends on the Blueprint's rules and evidence path. For Tangle-managed API mode, isolation failures are handled as product security incidents. ## Policy Enforcement @@ -36,6 +38,8 @@ Each sandbox enforces: Policies are defined in workbench profiles and enforced at the runtime level. +For protocol-backed services, the app should also check the service instance policy and operator endpoint before launching a session. A chain record proves the service exists; it does not prove the sandbox is currently ready. + ## Auditability Every session produces: @@ -45,3 +49,13 @@ Every session produces: - **File snapshots**: State of the workspace at key points. This makes execution reviewable and supports dispute resolution when issues arise. + +## Operator Checklist + +Before exposing a sandbox endpoint: + +1. Run the selected isolation backend locally with the same kernel, container runtime, or microVM assets used in production. +2. Confirm the sandbox cannot read host files, sibling session files, or unapproved secrets. +3. Confirm network policy blocks non-allowlisted destinations. +4. Set CPU, memory, disk, and timeout limits and verify they trigger controlled failures. +5. Capture one successful run and one blocked-policy run in logs that an operator can inspect later. diff --git a/pages/network/claim-airdrop.mdx b/pages/network/claim-airdrop.mdx index ac33a20d..3db23af0 100644 --- a/pages/network/claim-airdrop.mdx +++ b/pages/network/claim-airdrop.mdx @@ -5,7 +5,7 @@ import { Callout } from "nextra/components"; TNT migration moves eligible legacy Substrate balances into the canonical TNT token on EVM. Claims are verified using a Merkle tree and an SP1 zero-knowledge proof, then distributed with a vesting schedule. - The claim window and unlock parameters are defined by the on-chain migration contract. The claims portal shows the current deadline and vesting configuration. + The on-chain migration contract defines when eligible balances can migrate and how tokens are released. The portal shows the current deadline, immediately available amount, and release schedule. Contract sources (GitHub): diff --git a/pages/network/incentives-developers.mdx b/pages/network/incentives-developers.mdx index e48f0f0b..34f63948 100644 --- a/pages/network/incentives-developers.mdx +++ b/pages/network/incentives-developers.mdx @@ -26,7 +26,7 @@ For a readable breakdown and links to contracts, see [Rewards Architecture](/dev ## Design Tips - Be explicit about slashing conditions and the evidence you expect to be submitted on-chain. -- Use security requirements and operator commitments to express what “secure enough” means for your service. +- Use asset requirements, operator commitments, and slashing evidence rules to define the risk threshold for your service. - Provide observability where possible (heartbeats and optional QoS metrics) to help operators and customers assess performance. See [Metrics and Scoring](/network/metrics-and-scoring). diff --git a/pages/network/incentives-stakers.mdx b/pages/network/incentives-stakers.mdx index e2df3524..781e4e51 100644 --- a/pages/network/incentives-stakers.mdx +++ b/pages/network/incentives-stakers.mdx @@ -2,7 +2,7 @@ Stakers (delegators) earn two types of rewards on Tangle: -1. **Service fee revenue** from blueprint services they help secure (paid in the service’s payment token). +1. **Service fee revenue** from blueprint services backed by their delegated stake (paid in the service’s payment token). 2. **Optional TNT incentives** for delegating assets (pre-funded by governance). ## How You Participate diff --git a/pages/network/points-mechanics.mdx b/pages/network/points-mechanics.mdx index a2e78f0e..12954147 100644 --- a/pages/network/points-mechanics.mdx +++ b/pages/network/points-mechanics.mdx @@ -1,8 +1,8 @@ # Participation Credits -Tangle uses a credits system to recognize contributions and make participation auditable. Credits are computed off-chain, published as a Merkle root, and claimed on-chain through a dedicated contract. +Tangle uses a credits system to recognize contributions. Credits are computed off-chain, published as a Merkle root, and claimed on-chain through a dedicated contract. -Credits are not token transfers. They are a verifiable record of participation that can be used for programs, access, or distributions over time. +Credits are not token transfers. A user proves inclusion by submitting the claim data and Merkle proof accepted by the `Credits` contract. ## How Credits Work @@ -10,7 +10,7 @@ Credits are not token transfers. They are a verifiable record of participation t 2. A Merkle root for the epoch is published on-chain. 3. Users claim credits for that epoch via a single transaction. -This approach keeps the system lightweight while preserving verifiability. +This approach keeps on-chain storage small while still giving the contract a deterministic proof to check. ## Example Credit Sources diff --git a/pages/operators/manager/requirements.mdx b/pages/operators/manager/requirements.mdx index 8c133797..179576dc 100644 --- a/pages/operators/manager/requirements.mdx +++ b/pages/operators/manager/requirements.mdx @@ -29,7 +29,7 @@ No extra dependencies, the blueprint will run as a normal host process. - This can be done by running `setcap cap_net_admin+eip /path/to/blueprint-manager` - **_or_** simply running the `blueprint-manager` as root (**not recommended**) -For secure production deployments, see [Sandboxing and Security](/operators/manager/security). +For production deployments that need stronger workload isolation, see [Sandboxing and Security](/operators/manager/security). ## Container Sources diff --git a/pages/operators/quality-of-service.mdx b/pages/operators/quality-of-service.mdx index 779778b8..abd97986 100644 --- a/pages/operators/quality-of-service.mdx +++ b/pages/operators/quality-of-service.mdx @@ -99,7 +99,7 @@ cast call $REGISTRY "isHeartbeatCurrent(uint64,address)" $SERVICE_ID $YOUR_ADDRE | `QOS_HEARTBEAT_INTERVAL_SECS` | `300` | Heartbeat interval in seconds | | `QOS_METRICS_INTERVAL_SECS` | `60` | Metrics collection interval in seconds | | `QOS_DRY_RUN` | `true` | Skip on-chain submissions (for testing) | -| `BLUEPRINT_KEYSTORE_URI` | — | Path to keystore for signing heartbeats | +| `BLUEPRINT_KEYSTORE_URI` | - | Path to keystore for signing heartbeats | ## Security Notes diff --git a/pages/release-notes/0.13.0.mdx b/pages/release-notes/0.13.0.mdx index e82f70a7..63a6d9f3 100644 --- a/pages/release-notes/0.13.0.mdx +++ b/pages/release-notes/0.13.0.mdx @@ -41,7 +41,7 @@ typehash level. - Add `requester` to the `QuoteDetails` typed-data hash as the first member. - Add `requester` to the `JobQuoteDetails` typed-data hash as the first member. -- Sign per-caller quotes; do **not** emit wildcard quotes — they are rejected on-chain. +- Sign per-caller quotes; do **not** emit wildcard quotes - they are rejected on-chain. - Pre-fix signatures fail signature recovery against the new typehash and must be regenerated. See [pricing & payments](/developers/blueprints/pricing-and-payments) for the updated @@ -62,8 +62,8 @@ any slash event because the interface declared smaller, legacy shapes. | Event | Old fields | New fields | | -------------------- | -------------- | --------------------------------------------------------------------------------------------------------------- | -| `SlashProposed` | 4 | 8 — `slashId`, `serviceId`, `operator`, `proposer`, `slashBps`, `effectiveSlashBps`, `evidence`, `executeAfter` | -| `SlashExecuted` | 3 | 4 — `slashId`, `serviceId`, `operator`, `actualSlashed` | +| `SlashProposed` | 4 | 8 - `slashId`, `serviceId`, `operator`, `proposer`, `slashBps`, `effectiveSlashBps`, `evidence`, `executeAfter` | +| `SlashExecuted` | 3 | 4 - `slashId`, `serviceId`, `operator`, `actualSlashed` | | `SlashDisputed` | (not declared) | `slashId`, `disputer`, `reason` | | `SlashCancelled` | (not declared) | `slashId`, `canceller`, `reason` | | `SlashConfigUpdated` | (not declared) | full `SlashConfig` tuple (6 fields) | @@ -86,7 +86,7 @@ See [`ITangleSlashing`](/developers/api/reference/ITangleSlashing) and function forceRemoveAllowsBelowMin(uint64 serviceId) external view returns (bool ok); ``` -Default in `BlueprintServiceManagerBase` is `false` — the protocol enforces +Default in `BlueprintServiceManagerBase` is `false` - the protocol enforces `operatorCount > minOperators` on `forceRemoveOperator`. Custom BSMs that do **not** inherit `BlueprintServiceManagerBase` MUST implement this hook explicitly; an unimplemented or reverting view fails closed and the eviction reverts as soon as it @@ -146,8 +146,8 @@ the configured floor and bias the operator set toward sybils. little-endian byte-swap on SSZ-packed `uint64` fields. EigenPod-CLI fixtures decode correctly out of the box; hand-rolled proof builders that pack values into the low 8 bytes of the chunk (or use big-endian) will be rejected. Real EigenPod proofs would -silently mis-account every `uint64` field — every effective balance, exit epoch, and -validator balance — under the previous code. +silently mis-account every `uint64` field - every effective balance, exit epoch, and +validator balance - under the previous code. If you maintain a proof builder, regenerate fixtures with the canonical SSZ packing and pin the 32-ETH leaf regression test that ships with v0.13.0. @@ -178,7 +178,7 @@ and pin the 32-ETH leaf regression test that ships with v0.13.0. `forceRemoveAllowsBelowMin(uint64) -> bool` (return `false` unless you genuinely need emergency-eviction-below-min). 4. **MBSM operators**: do not pin a blueprint to a revision that is in the deprecation - grace window — `pinBlueprint` will revert. Wait until the deprecation completes or + grace window - `pinBlueprint` will revert. Wait until the deprecation completes or pick a different revision. 5. **L2 slashing receiver operators**: budget for two-step rotations of `messenger` and `slasher`. Queue with `setMessenger` / `setSlasher`, then schedule diff --git a/pages/staking/how-staking-works.mdx b/pages/staking/how-staking-works.mdx index ff1b98f0..5b035060 100644 --- a/pages/staking/how-staking-works.mdx +++ b/pages/staking/how-staking-works.mdx @@ -11,7 +11,7 @@ Tangle provides permissionless, asset-configurable staking for Blueprint service - Increased efficiency of staked capital by sharing it across instances - Additional revenue streams for stakers and operators - Boosted security for protocols leveraging new assets as security capital -- Innovation in new blockchain services by harnessing decentralized resources +- New service markets that use registered operators and delegated stake ## How Staking Works on Tangle @@ -21,7 +21,7 @@ Tangle provides permissionless, asset-configurable staking for Blueprint service 4. Customers instantiate services and select operators based on pricing and commitments. 5. Operators execute services and earn service fees; stakers share in rewards. -Staking aligns operators, developers, and stakers around service reliability and makes it possible to secure on-demand services without a consensus-layer dependency. +Staking aligns operators, developers, and stakers around service reliability. A service instance can require delegated assets, operator commitments, and slashing conditions without adding a new validator set to the base chain. ## Liquid Staking Option diff --git a/pages/staking/introduction.mdx b/pages/staking/introduction.mdx index 837b92a3..fcc112e6 100644 --- a/pages/staking/introduction.mdx +++ b/pages/staking/introduction.mdx @@ -21,8 +21,27 @@ Tangle's economic security stack centers on staking for Blueprint services. Tangle uses economic security to back operators who run Blueprint services. Operators register for services and provide compute. Assets can be staked to operators as collateral, aligning incentives and enabling slashing where policies require it. +The protocol does not make every workload safe by default. Each Blueprint defines the assets it accepts, the operators it needs, the service rules, and the evidence path for slashing. Staking gives the service an economic bond; the Blueprint still has to define what counts as a fault. + ## Staking Tangle provides permissionless and asset-configurable staking for Blueprints. Assets can be staked to operators as collateral for service instances, and participants earn rewards based on service usage and incentives. Staking aligns operators, developers, and stakers around service reliability and performance. If an operator violates service requirements, delegated assets can be slashed under the protocol’s rules. + +## Start by Role + +| Role | First question | Next page | +| ------------------- | ----------------------------------------------------------- | ----------------------------------------------------------------------------- | +| Staker | Which operator and asset should I delegate to? | [How Staking Works](/staking/how-staking-works) | +| Integrator | Do I need transferable staking positions? | [Liquid Staking Vaults](/staking/liquid-staking/introduction) | +| Blueprint developer | What collateral and slashing rules does my service need? | [Blueprint Pricing and Payments](/developers/blueprints/pricing-and-payments) | +| Operator | Which services am I registered for and what can be slashed? | [Operator onboarding](/operators/introduction) | + +## Protocol Surfaces + +| Surface | What it controls | +| ---------------------- | ------------------------------------------------------------------------------- | +| `MultiAssetDelegation` | Delegation, operator stake, unstaking, and vault-backed positions. | +| `ServiceManager` | Blueprint registration, service requests, approvals, jobs, and lifecycle state. | +| Reward contracts | Service fee distribution and optional TNT incentives. | diff --git a/pages/staking/liquid-staking/introduction.mdx b/pages/staking/liquid-staking/introduction.mdx index c47f212e..a98bc0db 100644 --- a/pages/staking/liquid-staking/introduction.mdx +++ b/pages/staking/liquid-staking/introduction.mdx @@ -1,6 +1,6 @@ # Liquid Staking (Liquid Delegation Vaults) -Liquid staking on Tangle lets stakers keep a transferable position while their assets secure operator-run services. It is implemented as ERC-7540 liquid delegation vaults that wrap the standard staking flow in `MultiAssetDelegation`. +Liquid staking on Tangle lets stakers keep a transferable position while their assets remain delegated to operator-run services. It is implemented as ERC-7540 liquid delegation vaults that wrap the standard staking flow in `MultiAssetDelegation`. Each vault is tied to one operator, one asset, and one blueprint selection mode. Deposits are immediate, while redemptions are asynchronous and follow protocol exit delays. diff --git a/pages/vibe/integrations.mdx b/pages/vibe/integrations.mdx index b2616971..5189fce7 100644 --- a/pages/vibe/integrations.mdx +++ b/pages/vibe/integrations.mdx @@ -11,6 +11,16 @@ The workbench is built to work with existing company systems. You can connect in Integrations are governed by profiles and policies, so the agent only has access to what it needs. +## What a Profile Should Specify + +| Area | Examples | +| ----------- | -------------------------------------------------------------------------------------------- | +| Identity | Which user, service account, or team owns the run. | +| Tools | Repositories, ticket queues, data stores, browser access, shell commands, and internal APIs. | +| Secrets | Provider keys, app tokens, SSH keys, and environment variables available to the sandbox. | +| Network | Domains or private endpoints the session can reach. | +| Review gate | Whether the agent can only draft, can open a PR, or can take a production action. | + ## Tool Servers And Gateways Advanced integrations can be exposed as tool servers. Profiles can allowlist local or remote servers, attach headers or environment variables, and set timeouts. Sensitive systems stay behind explicit gates, and approved workflows still get the tools they need. @@ -18,3 +28,5 @@ Advanced integrations can be exposed as tool servers. Profiles can allowlist loc ## Design Principle Integrations should be explicit and scoped. If a tool is not required for a workflow, it should not be enabled. + +Start with read-only tools, add write access only for a named workflow, and keep production credentials out of general-purpose profiles. diff --git a/pages/vibe/introduction.mdx b/pages/vibe/introduction.mdx index a07ed166..1e587d72 100644 --- a/pages/vibe/introduction.mdx +++ b/pages/vibe/introduction.mdx @@ -23,7 +23,7 @@ The workbench sends execution to the sandbox runtime. Hosted runs use product/AP ## Profiles Power The Runtime -Workbench profiles configure the selected agent harness, model routing, per-agent prompts, and tool permissions. OpenCode sits beside 12 other Sandbox SDK backend types: Claude Code, Kimi Code, Codex, AMP, Factory Droids, Pi, Hermes, Forge, OpenClaw, ACP, Cursor, and CLI base. Protocol-backed service instances must still read their own `/api/capabilities` response. +Workbench profiles configure the selected agent harness, model routing, per-agent prompts, and tool permissions. OpenCode sits beside 13 other Sandbox SDK backend types: Claude Code, Kimi Code, Codex, AMP, Factory Droids, Pi, Hermes, Forge, OpenClaw, NanoClaw, ACP, Cursor, and CLI base. Protocol-backed service instances must still read their own `/api/capabilities` response. ## Start Here (By Role) diff --git a/pages/vibe/profile-schema.mdx b/pages/vibe/profile-schema.mdx index b83432f9..d175a103 100644 --- a/pages/vibe/profile-schema.mdx +++ b/pages/vibe/profile-schema.mdx @@ -4,7 +4,7 @@ This page documents the profile schema used to configure sidecar agents. The sch ## Current Support -- **Sandbox SDK backends**: OpenCode, Claude Code, Kimi Code, Codex, AMP, Factory Droids, Pi, Hermes, Forge, OpenClaw, ACP, Cursor, and CLI base. +- **Sandbox SDK backends**: OpenCode, Claude Code, Kimi Code, Codex, AMP, Factory Droids, Pi, Hermes, Forge, OpenClaw, NanoClaw, ACP, Cursor, and CLI base. - **Sandbox UI picker**: the current picker exposes OpenCode, Claude Code, Codex, AMP, Factory Droids, Kimi Code, OpenClaw, NanoClaw, Hermes, and CLI base while deferring Pi, Forge, ACP, and Cursor. - **Blueprint sidecar**: the AI Agent Sandbox blueprint's current all-harness sidecar advertises Claude Code, Codex, OpenCode, Kimi Code, and Gemini CLI through `/api/capabilities`. diff --git a/pages/vibe/profiles.mdx b/pages/vibe/profiles.mdx index 7a5fbbe8..2cfa47b6 100644 --- a/pages/vibe/profiles.mdx +++ b/pages/vibe/profiles.mdx @@ -4,7 +4,7 @@ Profiles define how an agent behaves end to end. They package model choice, tool ## What A Profile Controls -- **Harness selection**: OpenCode, Claude Code, Kimi Code, Codex, AMP, Factory Droids, Pi, Hermes, Forge, OpenClaw, ACP, Cursor, or CLI base when the product exposes them. The current Sandbox UI picker also surfaces NanoClaw and defers Pi, Forge, ACP, and Cursor until product policy lands. +- **Harness selection**: OpenCode, Claude Code, Kimi Code, Codex, AMP, Factory Droids, Pi, Hermes, Forge, OpenClaw, NanoClaw, ACP, Cursor, or CLI base when the product exposes them. The current Sandbox UI picker defers Pi, Forge, ACP, and Cursor until product policy lands. - **Model selection**: primary and small model routing per profile. - **Per-agent tuning**: distinct configs for plan/build/explore (prompt, temperature, max steps). - **Tool access**: enable or disable individual tools. diff --git a/pages/vibe/simulations.mdx b/pages/vibe/simulations.mdx index 4c9bda70..9f7be400 100644 --- a/pages/vibe/simulations.mdx +++ b/pages/vibe/simulations.mdx @@ -12,6 +12,8 @@ Simulations are how you evaluate agent performance before shipping. Instead of a Each simulation produces a structured record of inputs, outputs, and logs. This makes it easier to score results, audit failures, and tune workflows based on evidence instead of anecdotes. +Useful simulation output should include the task input, selected profile, model or harness, tool calls, final output, score, cost, duration, and failure reason. Without those fields, a failed run is hard to reproduce and a passing run is hard to trust. + ## The Evaluation Loop Every execution generates traces: what agents did, inputs received, outputs produced, timing. These traces feed evaluation systems: @@ -27,3 +29,7 @@ This creates a flywheel: more usage generates more traces, better traces improve - Before shipping a new workflow. - After changing tools, models, or policies. - When outcomes start drifting or costs spike. + +## Minimum Comparison + +Run the current workflow and the proposed workflow on the same task set. Compare success rate, review burden, cost, latency, and failure categories. Ship the change only when it improves the target metric without creating a new failure mode that operators or reviewers cannot see. diff --git a/pages/vision/architecture.mdx b/pages/vision/architecture.mdx index 47f5f080..7d55be07 100644 --- a/pages/vision/architecture.mdx +++ b/pages/vision/architecture.mdx @@ -30,7 +30,7 @@ Tangle ties together three layers most platforms separate: the workbench where w Sandboxed runtimes with isolation, resource limits, and audit logs. This is where tasks actually run. **2) Inference Layer** -The [Gateway](/gateway) routes inference requests across centralized providers and decentralized operators. It handles model selection, compliance filtering ([ZDR](/gateway/zdr), [no-train](/gateway/no-train)), [BYOK](/gateway/byok) credential management, and billing. +The [Gateway](/gateway) routes inference requests across provider APIs and registered operators. It handles model selection, compliance filtering ([ZDR](/gateway/zdr), [no-train](/gateway/no-train)), [BYOK](/gateway/byok) credential management, and billing. **3) Protocol Layer** The coordination plane. It handles operator discovery, payment routing, and incentive enforcement. @@ -66,7 +66,7 @@ Autonomous work only scales when delegation is safe. Tangle enforces policy gate ## Design Pillars - **Isolation first**: Every workload runs inside a sandbox with explicit permissions. -- **Verifiable outcomes**: Logs, metadata, and evaluations make results auditable. +- **Reviewable outcomes**: Logs, metadata, and evaluations give reviewers evidence about what ran and how it performed. - **Composable services**: Blueprints define reusable services that can be instantiated on demand. - **Economic alignment**: Operators and developers earn based on usage and reliability. - **Developer speed**: Workflows are testable, repeatable, and easy to ship. diff --git a/pages/vision/introduction.mdx b/pages/vision/introduction.mdx index 6968ffbd..f697b58d 100644 --- a/pages/vision/introduction.mdx +++ b/pages/vision/introduction.mdx @@ -23,7 +23,7 @@ Autonomous work today is brittle: tasks run outside policy, results lack evidenc ## Where It Goes -- **Operator marketplace**: runtime hosting becomes decentralized and paid through the protocol. +- **Operator marketplace**: runtime hosting moves to registered operators paid through protocol settlement. - **Protocol-native coordination**: payments, reliability, and service discovery move on-chain. ## What Tangle Is diff --git a/pages/vision/use-cases.mdx b/pages/vision/use-cases.mdx index 55bb9027..1ecd88b7 100644 --- a/pages/vision/use-cases.mdx +++ b/pages/vision/use-cases.mdx @@ -16,7 +16,7 @@ Layers: workbench + runtime. ## Regulated and Sensitive Workflows -Deploy AI workflows on protected data with strict isolation, resource limits, and audit logs. Outputs are verifiable and reviewable. +Deploy AI workflows on protected data with strict isolation, resource limits, and audit logs. Outputs are linked to run metadata so reviewers can inspect what happened. Good for: regulated teams that require strong isolation and auditability. Layers: runtime + protocol (for paid operators).