@ixo/decision-oracle 0.2.10 → 0.2.11

package/README.md

@@ -779,6 +779,6 @@ symlinks are not packed). CI diffs them — change one, copy it to the other.
 
 ## Status
 
-Published on npm: `@ixo/decision-oracle` 0.2.10 and `@ixo/decision-oracle-client` 0.1.1.
+Published on npm: `@ixo/decision-oracle` 0.2.11 and `@ixo/decision-oracle-client` 0.1.1.
 
 Apache License 2.0: `LICENSE` at the repo root and in each package.

package/docs/api.md

@@ -397,7 +397,7 @@ set, below) re-exports a fourth, `OpenhandsHire`, bound as `HIRE_WORKFLOW`.
 | `description` | `string` | any string | The listing blurb |
 | `supportedProtocols` | `string[]` | every entry must start with `did:ixo:entity:` | Register gate 3: a collection whose protocol is not listed is refused `409`. `[]` ⇒ **no restriction**. Convention: exactly one entry — one oracle, one protocol |
 | `pricing.evaluation.denom` | `string` | non-empty | The denom a collection's on-chain `Payments.evaluation` must be in |
-| `pricing.evaluation.minAmount` | `string` | `/^\d+$/` — an **integer base-unit string** | The minimum that payment must carry, compared with `BigInt`. Below it, register is refused `402`: the chain's 80/10/10 split of that coin is how the oracle earns. Both fields are replaced, per deployment, by the `EVALUATION_DENOM` / `EVALUATION_MIN_AMOUNT` vars when those are set (required on mainnet) — what register charges and `/v1/info` serves is the result (`effectivePricing`) |
+| `pricing.evaluation.minAmount` | `string` | `/^\d+$/` — an **integer base-unit string** | The minimum that payment must carry, compared with `BigInt`. Below it, register is refused `402`: the chain's split of that coin (80% to the oracle, 10% to the network, 10% to the relayer node — the x/claims `network_fee_percentage` / `node_fee_percentage` chain params, governance-set, 10/10 on mainnet today; rounding remainder to the oracle) is how the oracle earns. Both fields are replaced, per deployment, by the `EVALUATION_DENOM` / `EVALUATION_MIN_AMOUNT` vars when those are set (required on mainnet) — what register charges and `/v1/info` serves is the result (`effectivePricing`) |
 | `pricing.byProtocol` | `Record<protocolDid, { denom, minAmount }>` | optional; each entry the same shape/validation as `pricing.evaluation` | Per-protocol override, keyed by `did:ixo:entity:…`. Register's gate 4 resolves the collection's protocol against this map first, falling back to `pricing.evaluation` when unlisted. `minAmount: "0"` lets that protocol's collections register with an EMPTY `Payments.evaluation` leg — for an oracle whose income for it isn't the evaluation split. `GET /v1/info` advertises this map alongside `pricing.evaluation` |
 | `pricing.api.amountMicroUsd` | `number` | optional (`pricing.api` whole is optional); an integer ≥ 10 000 and a multiple of 10 000 (whole cents ≥ 1¢), micro-USD (1 upay = 1 µUSD; $1.20 = `1_200_000`) | The Decision API lane's price per decision — a separate thing from the chain fees above. Published at `GET /v1/api/protocols[/:did]` as `price` (public, `cache-control: public, max-age=300`), quoted in every 402, and checked by the facilitator against every offer (`price_mismatch` otherwise). A function of the protocol alone — there are no per-source prices; a partner who should not pay gets billing mode `none`. Every price is a whole number of cents, at least 1¢ (a multiple of 10 000 µUSD — anything else fails at startup), so `price.amountCents` and `price.amount` (upay) are both exact |
 | `payouts` | `Record<protocolDid, { amount: string; currency: string \| { path: string } \| { asset: string; decimals: number } }>` | optional; `amount` / `currency.path` are a path like `$.invoice.total` or `$.lines[0].amount` (`$` then `.key` / `[n]` only); `currency` an ISO 4217 code (`EUR`), or `{ asset: "eip155:<chain>/erc20:0x…", decimals }`; nothing else (a `payee` or `readers` key is refused); with a non-empty `supportedProtocols`, every key must be in it (refused at module evaluation) | S16 Decision Payouts: where a protocol's claims carry the amount to pay. The oracle sends it to the engine as the `payout` block (outside the facts) on the decide call and the fold of EVERY claim of the protocol; the engine reads the amount from the claim's answers and, when the claim is approved, binds the payment into the decision's one credential: `ClaimRecord.decision.receipt` is then also typed `DecisionToPayCredential` and carries the payment binding, public at the engine's `/v1/receipts/:cid` (contracts 1.13.0 removed the separate `decisionToPay`). The engine derives the payee — a chain claim's on-chain agent; an API claim's `submitter`, else the answer the source's company link names (`payeeField`) — and answers `decisionToPayRefused: "NO_PAYEE"` (a receipt with no binding, logged `payout.refused`) when there is none. Submitter ids must be **opaque** (never a name, email or phone), at most 256 characters: the public receipt names the payee by that id. Absent ⇒ no payout block, nothing changes |
@@ -2518,7 +2518,7 @@ than a suppressed one.
   found through the `OWNER_DELEGATION_CAR` you posted at register. An exhausted balance is the `402`
   above: the owner tops up at the portal URL the engine names, and the cron resumes everything.
 - **The chain pays you.** The collection's on-chain `Payments.evaluation` — the coin your
-  `pricing.evaluation` gate insists on — is split 80/10/10 by the chain on every `MsgEvaluateClaim`
+  `pricing.evaluation` gate insists on — is split by the chain (80% to the oracle, 10% to the network, 10% to the relayer node — the x/claims `network_fee_percentage` / `node_fee_percentage` chain params, governance-set, 10/10 on mainnet today; rounding remainder to the oracle) on every `MsgEvaluateClaim`
   you sign. That split is the oracle's income, which is why registering a collection that pays less
   than your minimum is refused.
 - **The collection's admin account pays the evaluation leg**, on every evaluation, approve or reject

package/docs/guide.md

@@ -1047,7 +1047,7 @@ Three things to decide:
 ### Third-party oracle fees
 
 An oracle that IXO does not run is paid on chain claims by the collection's on-chain **evaluation
-fee**: the `Payments.evaluation` coin, split 80/10/10 by the chain on every `MsgEvaluateClaim`. Gate 4
+fee**: the `Payments.evaluation` coin, split by the chain (80% to the oracle, 10% to the network, 10% to the relayer node — the x/claims `network_fee_percentage` / `node_fee_percentage` chain params, governance-set, 10/10 on mainnet today; rounding remainder to the oracle) on every `MsgEvaluateClaim`. Gate 4
 holds a collection to your fee, matching the denom exactly. The coin differs per network:
 
 - **mainnet** — real USDC: USDC.inj, native Circle USDC on Injective over IBC (the USDC IXO's

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ixo/decision-oracle",
-  "version": "0.2.10",
+  "version": "0.2.11",
   "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/add-openhands-support/SKILL.md

@@ -51,7 +51,9 @@ The engine bills every decision to the account that registered the oracle. Pick
   `ibc/77C12480BD8C29BF0ACEC2143736C15BAF8CD232CA27BAE09336677B828955E6`). Never PAY (`upay`): it
   is only for oracles IXO runs, and register refuses it on yours. The app escrows each ask in your
   coin and amount (read from your `/v1/info`); an ask escrowing less is refused 402 and never
-  judged. Price above the engine's per-decision cost, which is billed to you.
+  judged. You keep 80% of it (on mainnet today the chain pays 10% to the network and 10% to the
+  relayer node — chain parameters governance can change), so
+  price that 80% above the engine's per-decision cost, which is billed to you.
 - **Or free, bounded** — `minAmount: "0"` and an `openhands.admit` hook that refuses asks you will
   not pay for (an allow-list of admins, a daily budget):
 

package/skills/create-oracle/SKILL.md

@@ -119,7 +119,9 @@ it; no handler stands in). Then fill in `src/index.ts` with the provider's answe
 table below):
 `supportedProtocols: ["<protocol did>"]`, the evaluation fee, and `policies`.
 
-The fee is the on-chain evaluation payment a collection must carry, or register refuses it. Set it
+The fee is the on-chain evaluation payment a collection must carry, or register refuses it. The
+chain splits each payment: 80% to the oracle, 10% to the network, 10% to the relayer node (chain
+parameters, 10/10 on mainnet today). Set it
 per wrangler env with the `EVALUATION_DENOM` / `EVALUATION_MIN_AMOUNT` vars (both or neither; the
 minimum in integer base units) — they replace `pricing.evaluation` from `defineOracle`, and they
 are REQUIRED on mainnet: the worker refuses to start without them. A third-party oracle charges