@ixo/decision-oracle 0.2.25 → 0.2.27

package/docs/guide.md

@@ -1018,10 +1018,58 @@ Registration is one call with four gates, in this order:
    `company_unavailable` when the facilitator or the engine cannot say). Without one, the leg gate
    above stands, its refusal `402 no_review_billing` naming both ways in.
 
-Every refusal carries a stable machine code in `details.reason` (`collection_not_found`,
-`not_owner_or_grantee`, `not_hired`, `unsupported_protocol`, `evaluation_underpaid`,
-`no_review_billing`, `insufficient_credits`, `company_unavailable`, `credits_unavailable`, …), so a
-portal never matches a message.
+Every refusal carries a stable machine code in `details.reason` (`chain_lane_off`,
+`collection_not_found`, `not_owner_or_grantee`, `not_hired`, `unsupported_protocol`,
+`evaluation_underpaid`, `no_review_billing`, `insufficient_credits`, `company_unavailable`,
+`credits_unavailable`, …), so a portal never matches a message.
+
+### An API-only oracle: turning the chain lane off
+
+An oracle that serves only the Decision API (`API_LANE` on) still runs the chain lane by default,
+and that is a door you may not want open: your protocol is public on chain, so anyone can create a
+claim collection on it, grant your oracle, and register it — at no fee at all where your `pricing`
+charges none (a `byProtocol` `minAmount: "0"`, or an empty evaluation leg). From then on every claim
+there is pulled, its facts produced and the engine asked to decide, on **your** engine credits, and
+its reviews land in your organisation's inbox.
+
+Close it with one var in `wrangler.jsonc`, per env:
+
+```jsonc
+"CHAIN_LANE": "false", // needs "API_LANE": "true" — with no lane at all the worker refuses to start
+```
+
+Then:
+
+- `POST /v1/collections/register` (and the `registerCollection` runtime export) answers
+  `409 { reason: "chain_lane_off" }` before any of register's own reads, so nothing is stored;
+  `decision-oracle register` prints that answer as it is.
+- `POST /v1/collections/:id/scan` (`decision-oracle scan`, the `scanCollection` export), a
+  collection's resume (`POST /v1/collections/:id/resume` — a pause is still allowed), the
+  operator's `POST /v1/admin/claims/:claimId/redeliver` and the `rehireOpenhands` export answer the
+  same `409`, and so do the OpenHands webhooks (`{ error, reason: "chain_lane_off" }`).
+- The cron runs no chain job: no scan, no claims feed or replay, no chain-collection resume, no
+  OpenHands hire. Each tier logs one `cron.chain-lane.off` line at debug, never one per collection.
+  The Sentry monitors `oracle-scan` and `oracle-claims-feed` stop checking in, so close them if you
+  had them.
+- A chain claim's run already in flight when you flip it (or retrying, or restarted by hand) stops
+  before its pull: nothing is pulled, no AI is spent, the engine is not asked. The step retries on
+  its backoff, so the run carries on once the lane is back on — within its ~4 hours of retries;
+  past them it ends `failed` and is rerun like any failed claim. One that had already decided
+  keeps its decision and receipt.
+- The act lane signs no `MsgEvaluateClaim`; a decided row is left as it was (`pending`, or
+  `blocked`) for the owner to submit from the portal.
+- A reviewer's answer on a chain claim already waiting for review (`pending_review`) is still
+  folded: the engine is asked to complete the review, and a collection billed per review charges
+  its payer for it, so the decision is recorded for the owner. Only the signing is skipped.
+- `GET /v1/info` says `lanes: { chain: false, api: true }`, so a portal does not offer the oracle
+  for a chain hire (the listing is cached 5 minutes, so a flip shows up to 5 minutes late).
+
+The Decision API lane is untouched: sources, keys, submits, payments, payouts, reviews, webhooks
+and its cron share run exactly as before.
+
+Collections you already watch are not deleted or changed — they are simply not scanned. Set
+`CHAIN_LANE` back to `"true"` (or remove it) and redeploy, and the next minute tick scans them from
+their cursors, the claims submitted meanwhile included, and the resumes run again.
 
 ### Getting hired on OpenHands
 
@@ -1381,7 +1429,8 @@ write, a webhook retry job) is still reported, codes and ids only — answers, f
 API lane's personal fields are redacted there and in every log line. `SENTRY_TRACES_SAMPLE_RATE`
 (default `0.1`) and `SENTRY_ENVIRONMENT` (default `ENVIRONMENT`) tune it. The cron triggers check in
 to Sentry cron monitors: `oracle-scan` and — only with `API_LANE` on — `oracle-api-lane` every
-minute, `oracle-cron-five` every five minutes and `oracle-cron-hour` every hour; alert
+minute, `oracle-cron-five` every five minutes and `oracle-cron-hour` every hour (with `CHAIN_LANE`
+off, `oracle-scan` and `oracle-claims-feed` stop: §11, "An API-only oracle"); alert
 on a missed check-in and a stopped cron pages you. The conditions that need a person — a collection
 or API source paused (per reason), a webhook receiver that refused all 8 attempts, a paid claim whose
 settlement was lost or whose receipt the facilitator refused, a facilitator that refuses the
@@ -1548,7 +1597,8 @@ own retries, and a terminal failure clears it.
 | `401` from the claim bot, the UCAN Store or the VFS claims lane (`claim.store-denied`), on an invocation minted as `did:ixo:…` | That DID has no IID document, or the `SERVICE_ED25519_MNEMONIC` key is not a verification method on it — the resolver has nothing to check the signature against | Re-run `oracle init --protocol <protocol did> --kit-url https://<your host> --yes`: every step already done says `skip`, so only the missing `iid` / `key` writes anything. (`--protocol` and `--kit-url` are always required, and `--only <step>` without `--yes` is still just a dry run) |
 | `bunx @ixo/decision-oracle@<version>` says `No version matching … found (but package exists)` right after a release | bun's cached copy of the package list is older than the release | `bun pm cache rm`, then run it again — or `BUN_INSTALL_CACHE_DIR=$(mktemp -d) bunx @ixo/decision-oracle@<version> …` |
 | A protocol shows as "Unnamed" in the portal, the console or the Openhands app | It has no `#pro` profile: `publish-protocol` writes one only with `--name` | `publish-protocol --phase profile --entity <protocol did> --rubric <file> --form <file> --name "<name>" [--description "<text>"] --yes` |
-| A service or test account cannot sign in through a browser | `login` is a browser flow | `login --session-file <session.json> --network <n>` saves a session in the shape `login` writes |
+| A service or test account cannot sign in through a browser | `login` is a browser flow | `login --session-file <session.json> --network <n>` saves a session in the shape `login` writes. Without a `sessionAuthenticatorId` it is a plain key account: its `sessionMnemonic` must derive `address` (checked before saving) and every chain command signs standard transactions with it. An AuthHub smart-account session keeps its `sessionAuthenticatorId` and signs through that authenticator |
+| A chain command fails `AuthHub session has no sessionAuthenticatorId and its sessionMnemonic does not derive ixo1…` | The saved session names no authenticator, so it is signed as a plain key account, but its mnemonic is not that address's key | For a plain account, save the mnemonic that derives `address`; for an AuthHub smart account, run `login` again (or put its `sessionAuthenticatorId` back in the session file) |
 | `MsgEvaluateClaim` fails with `insufficient funds` | The oracle's own wallet was never funded; it pays its own gas, and the AuthHub session's balance is a different account | `oracle init --protocol <protocol did> --kit-url https://<your host> --only fund --yes` (tops it back up to 1 IXO). `chainStatus` on `GET /v1/claims/:claimId` names the failure |
 | `ORACLE_MATRIX_USER_ID (…) is not <network>'s MXID for did:ixo:…` | The MXID in `wrangler.jsonc` was hand-edited, or was derived for a different network's homeserver | Use the expected MXID the error prints — it is derived from `ORACLE_ADDRESS` and the network. Nothing is signed or written before this check |
 | `oracle init` says `.dev.vars`'s token belongs to someone else, or the homeserver did not answer for it | A stale or rotated `ORACLE_MATRIX_ACCESS_TOKEN`, or a homeserver blip — either way the answer is a fresh login | Let the `matrix` step run (or force it with `--relogin`); account creation underneath is idempotent, so the worst case is one extra Matrix device |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ixo/decision-oracle",
-  "version": "0.2.25",
+  "version": "0.2.27",
   "license": "Apache-2.0",
   "description": "Run an IXO evaluation oracle: pull claims, produce facts with your handlers, let the decision engine decide, sign on chain",
   "keywords": [

package/skills/decision-api-oracle/SKILL.md

@@ -148,6 +148,14 @@ courier page answer (`curl -s https://shipment-delivery-oracle.devnet.ixo.earth/
 Later deploys: `bunx wrangler deploy --env <env>` (secrets persist); one secret: `bunx wrangler
 secret put <NAME> --env <env>`. The did.json `id` must be `did:web:<host>`.
 
+**API-only? Close the chain lane.** An oracle that serves only this lane still takes chain hires by
+default — its protocol is public, so anyone can create a collection on it, hire the oracle (free
+where `pricing` charges nothing) and spend the owner's engine credits. Ask the owner; if they want
+API-only, set `"CHAIN_LANE": "false"` in that env's `vars` (needs `"API_LANE": "true"`), redeploy,
+and check `curl -s https://<host>/v1/info` shows `"lanes":{"chain":false,"api":true}`. Register,
+scan and the OpenHands webhooks then answer `409 chain_lane_off`; the API lane is untouched; setting
+it back to `"true"` resumes any collections already watched (guide §11, "An API-only oracle").
+
 ### 6. Engine registration — payable at once
 
 ```bash
@@ -315,6 +323,8 @@ Decision Console shows the price and card eligibility read-only.
 | --- | --- |
 | Console / CLI 401 `UNAUTHORIZED` on a UCAN call | audience mismatch: the invocation names the did:web read from `<host>/.well-known/did.json` — `ORACLE_HOSTNAME` must equal the host the env is served from (its Custom Domain, or its `workers.dev` host), and `--kit` must be that host |
 | Worker 500s on every request after deploy; logs say `WEBHOOK_ENCRYPTION_KEY: required when API_LANE is on` | the secret is missing in that env — `bunx wrangler secret put WEBHOOK_ENCRYPTION_KEY --env <env>` (for a new deployment only; never replace an existing one) |
+| Worker 500s on every request; logs say `CHAIN_LANE is off and API_LANE is not on` | an oracle with no lane — set `"API_LANE": "true"` in that env's `vars` (with its secrets), or remove `CHAIN_LANE` |
+| `register` / `scan` / an OpenHands webhook answers 409 `chain_lane_off` | the oracle is API-only (`CHAIN_LANE` `"false"`) — by design; set it back to `"true"` and redeploy to take chain hires again |
 | `PROTOCOL_NOT_ALLOWED` on submit | the source's allow-list lacks it — empty means NONE; `api admin protocols <src> <did> --yes` |
 | 503 `SOURCE_PAUSED` `payments-disabled` | `API_PAYMENTS` is off and the source bills `x402` — turn payments on, or `api admin billing-mode <src> none` |
 | 402 again after a `PAYMENT-SIGNATURE` | the facilitator refused the payer: no deed / no `SendAuthorization` / not enough PAY — the fresh 402's error says which |

package/templates/project/.dev.vars.example

@@ -52,6 +52,10 @@ UNIQUE_HMAC_KEY="change-me-to-a-long-random-string"
 #   openssl rand -base64 32
 # (deployed: wrangler secret put WEBHOOK_ENCRYPTION_KEY [--env testnet|production])
 # WEBHOOK_ENCRYPTION_KEY="change-me-to-a-long-random-string"
+# An oracle that serves ONLY this lane turns the chain lane off with CHAIN_LANE "false" in
+# wrangler.jsonc (on by default): nobody can then hire it on chain and spend your engine credits.
+# Needs API_LANE on. Not a secret; for `wrangler dev` only:
+# CHAIN_LANE="false"
 # Where your earnings land is NOT a secret: EARNINGS_ADDRESS (ixo1…, PAY and USDC on IXO) and
 # EARNINGS_BASE_WALLET (0x…, USDC on Base) live in wrangler.jsonc `vars`, per env. Each offer names
 # them as its payTo; a way to pay whose address is unset is not offered. For `wrangler dev` only:

package/templates/project/wrangler.jsonc

@@ -193,6 +193,11 @@
     // Sign `MsgEvaluateClaim` on a terminal verdict automatically. "false" ⇒ decisions are
     // recorded and receipted, but a human submits them from the portal.
     "AUTO_SIGN": "true",
+    // The chain lane (collections hired on chain) is ON unless this says "false". Turn it off only
+    // for an oracle that serves the Decision API alone: your protocol is public on chain, so anyone
+    // could hire this oracle on a collection of their own and spend YOUR engine credits. Off ⇒
+    // register, scan and the hire webhooks answer 409 chain_lane_off; needs API_LANE "true".
+    // "CHAIN_LANE": "false",
 
     // The Decision API lane: paid, off-chain claims over HTTP at /v1/api. Dormant until API_LANE is
     // "true"; with API_PAYMENTS "false" new submits answer 503 payments-disabled, so nothing is
@@ -261,6 +266,7 @@
         // "AI_GATEWAY_ID": "<your gateway>",
         "C2PA_IMAGE_CHECK": "true",
         "AUTO_SIGN": "true",
+        // "CHAIN_LANE": "false", // API-only oracle: no chain hires (needs API_LANE "true")
         "API_LANE": "false",
         "API_PAYMENTS": "false"
         // "API_PRICE_USD_CENTS": "120",
@@ -371,6 +377,7 @@
         // "AI_GATEWAY_ID": "<your gateway>",
         "C2PA_IMAGE_CHECK": "true",
         "AUTO_SIGN": "true",
+        // "CHAIN_LANE": "false", // API-only oracle: no chain hires (needs API_LANE "true")
         "API_LANE": "false",
         "API_PAYMENTS": "false"
         // "API_PRICE_USD_CENTS": "120",
@@ -481,6 +488,7 @@
         // "AI_GATEWAY_ID": "<your gateway>",
         "C2PA_IMAGE_CHECK": "true",
         "AUTO_SIGN": "true",
+        // "CHAIN_LANE": "false", // API-only oracle: no chain hires (needs API_LANE "true")
         "API_LANE": "false",
         "API_PAYMENTS": "false"
         // "API_PRICE_USD_CENTS": "120",