Skip to content

Commit 474f8c6

Browse files
drewstonedrewstone
authored
docs(blueprints): remove product indexer claims
1 parent 21f8426 commit 474f8c6

14 files changed

Lines changed: 88 additions & 82 deletions

File tree

‎pages/blueprints/ai-agent-sandbox/_meta.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ const meta: Meta = {
44
index: "Overview",
55
"operator-requirements": "Operator Requirements",
66
"runtime-and-harnesses": "Runtime and Harnesses",
7-
"dapp-and-indexer": "Dapp and Indexer",
7+
"dapp-and-indexer": "Dapp Integration",
88
};
99

1010
export default meta;

‎pages/blueprints/ai-agent-sandbox/dapp-and-indexer.mdx‎

Lines changed: 14 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,16 @@
11
---
2-
title: AI Agent Sandbox Dapp and Indexer
3-
description: Dapp metadata, iframe policy, indexed state, and live health boundaries for AI Agent Sandbox.
2+
title: AI Agent Sandbox Dapp Integration
3+
description: Dapp metadata, iframe policy, protocol state, and live health boundaries for AI Agent Sandbox.
44
---
55

6-
# AI Agent Sandbox Dapp and Indexer
6+
# AI Agent Sandbox Dapp Integration
77

88
Tangle Cloud should launch the hosted sandbox app from metadata, then keep the raw protocol page one click away.
99

1010
The hosted app owns the sandbox UX. The protocol page owns raw state inspection.
1111

12+
The AI Agent Sandbox repo does not ship a dedicated indexer today. Treat protocol state as data the dapp can read from contracts or a shared protocol indexing layer when one is available. Do not make an indexer part of the blueprint operator path.
13+
1214
## Metadata the dapp should use
1315

1416
| Field | Current value in repo metadata |
@@ -21,7 +23,7 @@ The hosted app owns the sandbox UX. The protocol page owns raw state inspection.
2123

2224
The metadata also declares cloud, dedicated instance, and TEE instance modes. Use those records to route service creation to the right blueprint ID for the selected network.
2325

24-
## Indexed state
26+
## Protocol state
2527

2628
| State | Why the dapp needs it |
2729
| --------------------------------------- | ----------------------------------------------------------- |
@@ -33,11 +35,11 @@ The metadata also declares cloud, dedicated instance, and TEE instance modes. Us
3335
| Jobs | Show lifecycle and workflow commands. |
3436
| Heartbeats | Separate "not ready yet" from "operator stopped reporting." |
3537

36-
The indexer should preserve enough history to distinguish pending provisioning from operator failure. The hosted app should not have to guess.
38+
The dapp should preserve enough protocol history to distinguish pending provisioning from operator failure. That history can come from direct chain reads, a shared protocol indexer, or another canonical protocol-state service. It is not a separate component shipped by this blueprint.
3739

3840
## Live checks
3941

40-
Indexed state is not enough to open a terminal or inject a secret. Before showing a sandbox as usable, the app should check:
42+
Protocol state is not enough to open a terminal or inject a secret. Before showing a sandbox as usable, the app should check:
4143

4244
1. operator API reachability
4345
2. session auth challenge/session flow
@@ -51,12 +53,12 @@ For TEE mode, the app should also expose attestation status and avoid presenting
5153

5254
The sandbox app is iframe-first. The parent dapp should:
5355

54-
| Rule | Reason |
55-
| --------------------------------------------------------------- | --------------------------------------------------------------------------- |
56-
| Restrict iframe hosts to trusted suffixes and manifest entries. | Prevent arbitrary operator metadata from embedding a hostile app. |
57-
| Pass parent origin and chain context explicitly. | Lets the child app request wallet operations through the parent. |
58-
| Keep wallet approval in the parent. | Users should see the same wallet confirmation model across Tangle Cloud. |
59-
| Keep a link to raw protocol state. | Operators and support need chain/indexer state when the hosted app is down. |
56+
| Rule | Reason |
57+
| --------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
58+
| Restrict iframe hosts to trusted suffixes and manifest entries. | Prevent arbitrary operator metadata from embedding a hostile app. |
59+
| Pass parent origin and chain context explicitly. | Lets the child app request wallet operations through the parent. |
60+
| Keep wallet approval in the parent. | Users should see the same wallet confirmation model across Tangle Cloud. |
61+
| Keep a link to raw protocol state. | Operators and support need chain and service-instance state when the hosted app is down. |
6062

6163
## Bad copy to avoid
6264

‎pages/blueprints/ai-agent-sandbox/index.mdx‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -60,11 +60,11 @@ Every data endpoint requires a signed wallet session. Production operators must
6060

6161
## What to read next
6262

63-
| Page | Use it for |
64-
| --------------------------------------------------------------------------- | ------------------------------------------------------------------- |
65-
| [Operator Requirements](/blueprints/ai-agent-sandbox/operator-requirements) | Host setup, ports, Docker, Firecracker, TEE, state, and secrets. |
66-
| [Runtime and Harnesses](/blueprints/ai-agent-sandbox/runtime-and-harnesses) | Runtime backends, capability discovery, harnesses, and AI keys. |
67-
| [Dapp and Indexer](/blueprints/ai-agent-sandbox/dapp-and-indexer) | Metadata, iframe policy, indexed state, and live health boundaries. |
63+
| Page | Use it for |
64+
| --------------------------------------------------------------------------- | -------------------------------------------------------------------- |
65+
| [Operator Requirements](/blueprints/ai-agent-sandbox/operator-requirements) | Host setup, ports, Docker, Firecracker, TEE, state, and secrets. |
66+
| [Runtime and Harnesses](/blueprints/ai-agent-sandbox/runtime-and-harnesses) | Runtime backends, capability discovery, harnesses, and AI keys. |
67+
| [Dapp Integration](/blueprints/ai-agent-sandbox/dapp-and-indexer) | Metadata, iframe policy, protocol state, and live health boundaries. |
6868

6969
## Sources used
7070

‎pages/blueprints/ai-agent-sandbox/runtime-and-harnesses.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -91,4 +91,4 @@ Use these probes before routing users into a sandbox:
9191
| `/api/capabilities` | The runtime and harness features the operator says are available. |
9292
| Product operation probe | A real exec, prompt, terminal, port, or workflow call through the operator API. |
9393

94-
The indexer can tell the app that a service exists. It cannot tell the app that a sidecar is usable right now.
94+
Protocol state can tell the app that a service exists. It cannot tell the app that a sidecar is usable right now.

‎pages/blueprints/ai-trading/_meta.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ const meta: Meta = {
44
index: "Overview",
55
"operator-requirements": "Operator Requirements",
66
"runtime-and-risk": "Runtime and Risk",
7-
"dapp-and-indexer": "Dapp and Indexer",
7+
"dapp-and-indexer": "Dapp Integration",
88
};
99

1010
export default meta;

‎pages/blueprints/ai-trading/dapp-and-indexer.mdx‎

Lines changed: 8 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,14 @@
11
---
2-
title: AI Trading Dapp and Indexer
3-
description: Arena routing, operator discovery, and indexed state for AI Trading.
2+
title: AI Trading Dapp Integration
3+
description: Arena routing, operator discovery, protocol state, and live operator reads for AI Trading.
44
---
55

6-
# AI Trading Dapp and Indexer
6+
# AI Trading Dapp Integration
77

88
The Arena is the product app for AI Trading. Tangle Cloud should launch it from trusted metadata and preserve the protocol fallback route for raw service state.
99

10+
The AI Trading repo does not ship a dedicated indexer today. Its own improvement notes list vault event indexing as future work. Treat protocol state as data the Arena can read from contracts or a shared protocol indexing layer when one exists, not as a blueprint operator requirement.
11+
1012
## Metadata the dapp should use
1113

1214
| Field | Current value in repo metadata |
@@ -19,7 +21,7 @@ The Arena is the product app for AI Trading. Tangle Cloud should launch it from
1921

2022
The metadata also declares cloud, instance, and TEE modes. The Arena should use those mode records instead of hard-coding a single blueprint ID.
2123

22-
## Indexed state
24+
## Protocol state
2325

2426
| State | Why the dapp needs it |
2527
| ----------------------------------- | ----------------------------------------------------------------- |
@@ -30,7 +32,7 @@ The metadata also declares cloud, instance, and TEE modes. The Arena should use
3032
| Pricing pointers | Show quote or subscription information when available. |
3133
| Heartbeats | Distinguish dead operators from missing data. |
3234

33-
The indexer should make operator discovery reliable. It should not be treated as proof that a bot is healthy or that a trade was safe.
35+
Protocol state should make operator discovery reliable. It should not be treated as proof that a bot is healthy or that a trade was safe.
3436

3537
## Live operator reads
3638

@@ -46,7 +48,7 @@ The Arena still needs operator APIs for:
4648
- terminal or sidecar logs
4749
- health
4850

49-
If an operator endpoint is unreachable, say that. Do not replace it with stale indexed state unless the UI labels it as stale.
51+
If an operator endpoint is unreachable, say that. Do not replace it with stale protocol state unless the UI labels it as stale.
5052

5153
## User-facing states
5254

‎pages/blueprints/ai-trading/index.mdx‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -56,11 +56,11 @@ On-chain guards live in contracts such as `PolicyEngine`, `TradeValidator`, vaul
5656

5757
## What to read next
5858

59-
| Page | Use it for |
60-
| --------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
61-
| [Operator Requirements](/blueprints/ai-trading/operator-requirements) | VPS sizing, install flow, service IDs, ports, env, admission, and upgrade rules. |
62-
| [Runtime and Risk](/blueprints/ai-trading/runtime-and-risk) | Paper mode, agent keys, runtime backend, risk gates, and validation trust. |
63-
| [Dapp and Indexer](/blueprints/ai-trading/dapp-and-indexer) | Arena iframe metadata, operator discovery, and indexed service state. |
59+
| Page | Use it for |
60+
| --------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
61+
| [Operator Requirements](/blueprints/ai-trading/operator-requirements) | VPS sizing, install flow, service IDs, ports, env, admission, and upgrade rules. |
62+
| [Runtime and Risk](/blueprints/ai-trading/runtime-and-risk) | Paper mode, agent keys, runtime backend, risk gates, and validation trust. |
63+
| [Dapp Integration](/blueprints/ai-trading/dapp-and-indexer) | Arena iframe metadata, operator discovery, protocol state, and live operator reads. |
6464

6565
## Sources used
6666

‎pages/blueprints/dapp-integration.mdx‎

Lines changed: 12 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
title: Dapp Integration
3-
description: How Tangle Cloud should route blueprint apps, use indexed state, and prove local staking flows.
3+
description: How the dapp should route blueprint apps, show service state, and prove local staking flows.
44
---
55

66
# Dapp Integration
@@ -37,14 +37,14 @@ Do not build around one agent harness, one venue, or one operator URL. Route fro
3737

3838
| State | Source |
3939
| ----------------------------- | ---------------------------------------------------------------------------------------------------------- |
40-
| Blueprint exists | Indexer over blueprint creation and metadata updates. |
40+
| Blueprint exists | Contract reads or shared protocol indexing over blueprint creation and metadata updates. |
4141
| Operator can serve it | Operator registration and endpoint metadata. |
4242
| Service instance exists | Service request, approval, and activation events. |
43-
| Job was submitted | Indexed job events. |
43+
| Job was submitted | Protocol job events. |
4444
| Product is healthy | Operator API, app-level probe, or blueprint-specific proof path. |
4545
| Product result is trustworthy | Contract state, attestation, settlement receipt, SP1 proof, signed report, or product-specific validation. |
4646

47-
The indexer is discovery infrastructure. It tells the dapp what the protocol saw. It does not replace runtime health checks.
47+
Shared protocol indexing is discovery infrastructure when it exists. It tells the dapp what the protocol saw. It is not shipped by these product blueprint repos, and it does not replace runtime health checks.
4848

4949
## Failure states worth showing
5050

@@ -89,14 +89,14 @@ The direct local staking gate must exercise real contract calls for:
8989
6. schedule withdraw
9090
7. execute withdraw
9191

92-
The browser gate should prove the same actions through the UI. If local GraphQL/indexer noise blocks the browser run, say that plainly and keep the direct contract gate as the hard proof. Do not claim the browser gate passed unless it did.
92+
The browser gate should prove the same actions through the UI. If local GraphQL or protocol-state noise blocks the browser run, say that plainly and keep the direct contract gate as the hard proof. Do not claim the browser gate passed unless it did.
9393

9494
## Implementation rules
9595

96-
| Rule | Reason |
97-
| ------------------------------------------------------------- | ------------------------------------------------------------------------------- |
98-
| Prefer metadata and iframe policy over bespoke React modules. | New first-party apps should not require a dapp redeploy for every route change. |
99-
| Keep the generic protocol route. | Operators and auditors need raw chain/indexer state. |
100-
| Use operator APIs for live product state. | The indexer cannot tell whether a bot, sandbox, or venue is healthy right now. |
101-
| Keep jobs for commands, not reads. | Job history should mean work was requested. |
102-
| Show unavailable, pending, failed, and healthy separately. | Each state has a different fix. |
96+
| Rule | Reason |
97+
| ------------------------------------------------------------- | --------------------------------------------------------------------------------- |
98+
| Prefer metadata and iframe policy over bespoke React modules. | New first-party apps should not require a dapp redeploy for every route change. |
99+
| Keep the generic protocol route. | Operators and auditors need raw chain and service-instance state. |
100+
| Use operator APIs for live product state. | Protocol state cannot tell whether a bot, sandbox, or venue is healthy right now. |
101+
| Keep jobs for commands, not reads. | Job history should mean work was requested. |
102+
| Show unavailable, pending, failed, and healthy separately. | Each state has a different fix. |

‎pages/blueprints/index.mdx‎

Lines changed: 10 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -13,16 +13,16 @@ The live unit is a service instance. A user requests it, picks registered operat
1313

1414
If you only remember one model, use this:
1515

16-
| Layer | Plain meaning |
17-
| --------------------- | ---------------------------------------------------------------------------------------------- |
18-
| Blueprint | The recipe: jobs, metadata, binaries, contracts, and app policy. |
19-
| Operator registration | An operator says, on-chain, "I can run this recipe." |
20-
| Service request | A user chooses parameters and the operators that should serve them. |
21-
| Service instance | The running service created from that request. |
22-
| Job | A command against one service instance. Jobs change state or ask operators to do work. |
23-
| Query | A read from contracts, the indexer, or an operator API. Queries should not be modeled as jobs. |
24-
25-
The indexer turns protocol events into app state. It can tell the dapp which blueprints exist, which operators registered, which service instances were created, which jobs landed, and which endpoints operators advertised. It does not prove that an endpoint is healthy, honest, or serving the right model. Product pages still need operator API checks, contract reads, attestations, settlement receipts, or proof systems.
16+
| Layer | Plain meaning |
17+
| --------------------- | --------------------------------------------------------------------------------------------------------------------------- |
18+
| Blueprint | The recipe: jobs, metadata, binaries, contracts, and app policy. |
19+
| Operator registration | An operator says, on-chain, "I can run this recipe." |
20+
| Service request | A user chooses parameters and the operators that should serve them. |
21+
| Service instance | The running service created from that request. |
22+
| Job | A command against one service instance. Jobs change state or ask operators to do work. |
23+
| Query | A read from contracts, a shared protocol indexer when available, or an operator API. Queries should not be modeled as jobs. |
24+
25+
A shared protocol indexer can turn protocol events into app state. It can tell the dapp which blueprints exist, which operators registered, which service instances were created, which jobs landed, and which endpoints operators advertised. It is not part of the three product blueprint repos documented here, and it does not prove that an endpoint is healthy, honest, or serving the right model. Product pages still need operator API checks, contract reads, attestations, settlement receipts, or proof systems.
2626

2727
## First-party blueprint products
2828

0 commit comments

Comments
 (0)