@ixo/openhands-sdk 0.2.0 → 0.4.0

package/dist/cjs/chain/orgReviewBillingSign.js

@@ -0,0 +1,166 @@
+"use strict";
+/**
+ * "Pay for reviews", the signing side (owner request 2026-10-14; eval-oracle contract 1.22.0). Only the org's
+ * chain OWNER signs, in the browser, with their AuthHub session's ed25519 key:
+ *
+ * - On / raise: one x402-ixo-pay payment delegation, built by S4's own `@ixo/x402-ixo-pay` (never by hand):
+ *   issuer the owner's did:ixo, audience the network's x402 facilitator, `billing/pay` on `billing:decision-api`
+ *   with `{maxAmount, denom: "upay", oracles: [<this oracle's did:web>]}`, ~100 years. PUT to the oracle for the
+ *   org's source (a re-PUT replaces: that is "raise"), then deposited in the UCAN store so it can be revoked later
+ *   by its CID (the oracle never gives the token back). A replaced one is revoked.
+ * - Off: DELETE at the oracle, then REVOKE the delegation in the UCAN store (the oracle's DELETE alone leaves it
+ *   valid until it expires).
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.billingHosts = exports.expiryFrom = void 0;
+exports.buildReviewBillingDelegation = buildReviewBillingDelegation;
+exports.revokeDelegation = revokeDelegation;
+exports.enableReviewBilling = enableReviewBilling;
+exports.turnOffReviewBilling = turnOffReviewBilling;
+const network_ts_1 = require("../network.js");
+const orgReviewBilling_ts_1 = require("./orgReviewBilling.js");
+/** now + 100 calendar years (owner ruling; same as the CLI): the cap, not the clock, is what limits it. */
+const expiryFrom = (nowSeconds) => {
+    const d = new Date(nowSeconds * 1000);
+    d.setUTCFullYear(d.getUTCFullYear() + 100);
+    return Math.floor(d.getTime() / 1000);
+};
+exports.expiryFrom = expiryFrom;
+const HOSTS = {
+    devnet: { facilitator: "did:web:facilitator.devnet.ixo.earth", store: "https://devnet.store.ucan.ixo.earth" },
+    testnet: { facilitator: "did:web:facilitator.testnet.ixo.earth", store: "https://testnet.store.ucan.ixo.earth" },
+    mainnet: { facilitator: "did:web:facilitator.ixo.earth", store: "https://store.ucan.ixo.earth" }
+};
+/** The x402 facilitator (the delegation's audience) and the UCAN store on this deployment's network. */
+const billingHosts = () => HOSTS[(0, network_ts_1.network)()];
+exports.billingHosts = billingHosts;
+const signerOf = async (owner) => {
+    const { signerFromMnemonic } = await Promise.resolve().then(() => __importStar(require("@ixo/ucan")));
+    return (await signerFromMnemonic(owner.mnemonic, `did:ixo:${owner.address}`)).signer;
+};
+/** The owner's payment delegation for this oracle alone: base64 CAR, as the facilitator verifies it. */
+async function buildReviewBillingDelegation(owner, oracleDid, maxAmount, options = {}) {
+    const { buildPaymentDelegation } = await Promise.resolve().then(() => __importStar(require("@ixo/x402-ixo-pay")));
+    return buildPaymentDelegation({
+        /* @ixo/ucan 2.1's signer; the package's 2.2 takes the same ucanto Signer. */
+        issuer: (await signerOf(owner)),
+        facilitatorDid: options.facilitatorDid ?? (0, exports.billingHosts)().facilitator,
+        maxAmount,
+        expiration: (0, exports.expiryFrom)(options.now ?? Math.floor(Date.now() / 1000)),
+        oracles: [oracleDid]
+    });
+}
+/** One self-signed call to the UCAN store as the owner (`with: ixo:ucan-store`). False on any failure. */
+async function storeCall(owner, can, path, body, options) {
+    const store = (options.storeUrl ?? (0, exports.billingHosts)().store).replace(/\/$/, "");
+    try {
+        const doc = await (options.fetch ?? fetch)(`${store}/.well-known/did.json`, { headers: { accept: "application/json" }, signal: AbortSignal.timeout(10_000) });
+        const audience = doc.ok ? (await doc.json().catch(() => null))?.id : null;
+        if (typeof audience !== "string")
+            return null;
+        const { createInvocation, serializeInvocation } = await Promise.resolve().then(() => __importStar(require("@ixo/ucan")));
+        const invocation = await createInvocation({
+            issuer: await signerOf(owner),
+            audience,
+            capability: { can, with: "ixo:ucan-store" },
+            expiration: Math.floor(Date.now() / 1000) + 300,
+            facts: [{ nonce: crypto.randomUUID() }]
+        });
+        const response = await (options.fetch ?? fetch)(`${store}${path}`, {
+            method: "POST",
+            headers: { "content-type": "application/json", authorization: `Bearer ${await serializeInvocation(invocation)}`, "x-auth-type": "ucan" },
+            body: JSON.stringify(body),
+            signal: AbortSignal.timeout(10_000)
+        });
+        return response.status;
+    }
+    catch {
+        return null;
+    }
+}
+/** Revokes a delegation the store holds, by its CID: true when it is revoked now (or was already). */
+async function revokeDelegation(owner, cid, options = {}) {
+    const status = await storeCall(owner, "store/revoke", "/api/revocations", { cid, reason: "OpenHands: Pay for reviews turned off or replaced" }, options);
+    return status === 200 || status === 201;
+}
+/**
+ * Turn on, or raise the cap (a re-PUT replaces the stored one): sign, PUT for the org's source, keep it in the UCAN
+ * store for a later revoke, and revoke the one it replaced. Only the PUT decides success.
+ */
+async function enableReviewBilling(input, options = {}) {
+    const audience = await (0, orgReviewBilling_ts_1.oracleAudience)(input.oracleUrl, options);
+    if (!audience)
+        return { ok: false, why: "The oracle did not answer. Nothing was signed." };
+    let delegation;
+    try {
+        delegation = await buildReviewBillingDelegation(input.owner, audience, input.maxAmount, options);
+    }
+    catch (error) {
+        return { ok: false, why: `The permission could not be signed: ${error instanceof Error ? error.message : "unknown error"}.` };
+    }
+    const mint = (0, orgReviewBilling_ts_1.sourceMint)(input.owner);
+    const answer = await (0, orgReviewBilling_ts_1.sourceCall)(input.oracleUrl, audience, mint, { method: "PUT", path: "/v1/api/source/review-billing", can: "review-billing/set", sourceId: input.sourceId, body: { delegation } }, options);
+    if (!answer)
+        return { ok: false, why: "The oracle did not answer. Nothing was stored; try again." };
+    if (answer.status !== 200)
+        return { ok: false, why: (0, orgReviewBilling_ts_1.refusalWords)(answer.status, answer.code, answer.reason, answer.message) };
+    const status = (0, orgReviewBilling_ts_1.parseReviewBilling)(answer.body);
+    if (!status)
+        return { ok: false, why: "The oracle stored it but answered in a form this page does not read. Reload to see it." };
+    /* Kept so Turn off can revoke it; a failure here only means a later revoke must be done where it was signed. */
+    await storeCall(input.owner, "store/add", "/api/delegations", { token: delegation, note: `openhands review billing ${input.sourceId}` }, options);
+    const old = input.replacing && input.replacing !== status.delegationCid ? input.replacing : null;
+    const revoked = old ? await revokeDelegation(input.owner, old, options) : true;
+    return { ok: true, value: status, ...(revoked ? {} : { note: "A new budget is signed. The permission it replaced could not be revoked from here; the oracle no longer holds it." }) };
+}
+/** Turn off: DELETE at the oracle, then revoke the delegation in the UCAN store. */
+async function turnOffReviewBilling(input, options = {}) {
+    const audience = await (0, orgReviewBilling_ts_1.oracleAudience)(input.oracleUrl, options);
+    if (!audience)
+        return { ok: false, why: "The oracle did not answer. Nothing was changed." };
+    const answer = await (0, orgReviewBilling_ts_1.sourceCall)(input.oracleUrl, audience, (0, orgReviewBilling_ts_1.sourceMint)(input.owner), { method: "DELETE", path: "/v1/api/source/review-billing", can: "review-billing/delete", sourceId: input.sourceId }, options);
+    if (!answer)
+        return { ok: false, why: "The oracle did not answer. Nothing was changed; try again." };
+    if (answer.status !== 200 && answer.status !== 204)
+        return { ok: false, why: (0, orgReviewBilling_ts_1.refusalWords)(answer.status, answer.code, answer.reason, answer.message) };
+    const revoked = await revokeDelegation(input.owner, input.delegationCid, options);
+    return {
+        ok: true,
+        value: { revoked },
+        ...(revoked ? {} : { note: "The oracle no longer charges it, but the signed permission could not be revoked from here (it was signed elsewhere). Revoke it where it was signed (the Decision Console) to stop it everywhere." })
+    };
+}
+//# sourceMappingURL=orgReviewBillingSign.js.map

package/dist/cjs/chain/orgReviewBillingSign.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"orgReviewBillingSign.js","sourceRoot":"","sources":["../../../src/chain/orgReviewBillingSign.ts"],"names":[],"mappings":"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"}

package/dist/cjs/chain/payoutSettings.d.ts

@@ -0,0 +1,97 @@
+import { type PayoutRail } from "./payoutTerms.ts";
+/** "chain" is today's on-chain escrow; the others are paid off chain by the facilitator. */
+export type SettingsRail = "chain" | PayoutRail;
+export declare const SETTINGS_RAILS: readonly SettingsRail[];
+export interface PayoutSettings {
+    v: 1;
+    /** The company's facilitator, as a canonical did:web. Absent when the company pays on chain only. */
+    facilitator?: string;
+    /** The rails the company pays on, in its own order. */
+    rails: SettingsRail[];
+    /** The oracles the company allows; the first is the default. */
+    oracles: string[];
+    /** What off-chain amounts are quoted in. Absent: USD. */
+    currency?: "USD" | "USDC";
+}
+export interface SettingsInput {
+    /** Needed only for the off-chain rails (usdc_base, stripe); blank or absent for a chain-only company. */
+    facilitator?: string;
+    rails: string[];
+    oracles: string[];
+    currency?: string;
+}
+export declare function buildPayoutSettings(input: SettingsInput): PayoutSettings;
+/** The document as stored, believed field by field; anything else is null. */
+export declare function readPayoutSettings(doc: unknown): PayoutSettings | null;
+/** The exact bytes that are published and hashed. */
+export declare const payoutSettingsJson: (settings: PayoutSettings) => string;
+export declare const payoutSettingsCid: (settings: PayoutSettings) => Promise<string>;
+/** The linked resource on the org's IID; the endpoint is the https address its store gave, as `#payoutTerms`. */
+export declare const payoutSettingsResource: (ref: {
+    cid: string;
+    url?: string;
+    uri?: string;
+}) => {
+    type: string;
+    id: string;
+    description: string;
+    mediaType: string;
+    serviceEndpoint: string;
+    proof: string;
+    encrypted: string;
+    right: string;
+};
+/** Where an org's settings are, found by id suffix. */
+export declare function payoutSettingsRef(linked: {
+    id?: string | null;
+    proof?: string | null;
+}[] | null | undefined): {
+    id: string;
+    cid: string;
+} | null;
+/** The fetched bytes, believed only when they hash to the anchored CID. */
+export declare function verifiedPayoutSettings(text: string | null, cid: string): Promise<PayoutSettings | null>;
+/**
+ * Whether `address` may edit this IID: a key in its `authentication` with that
+ * account (a `controller` entry is not enough — the chain answers code 1106).
+ * The org-admin check of OpenHands HQ, shared with the worker's shaped post.
+ * shortcut: matches on blockchainAccountID only, as every key minted by createIidVerificationMethods has one; upgrade if an org authenticates by bare public key.
+ */
+export declare function canEditIid(doc: {
+    verificationMethod?: {
+        id?: string;
+        blockchainAccountID?: string;
+    }[] | null;
+    authentication?: string[] | null;
+} | null | undefined, address: string): boolean;
+/** The settings edit, as one transaction's IID messages: the old resource out (when there is one) and the new one in. */
+export declare function replaceSettingsMsgs(org: string, signer: string, stored: {
+    cid: string;
+    url: string;
+}, oldId: string | null): ({
+    typeUrl: "/ixo.iid.v1beta1.MsgDeleteLinkedResource";
+    value: {
+        id: string;
+        resourceId: string;
+        signer: string;
+        linkedResource?: undefined;
+    };
+} | {
+    typeUrl: "/ixo.iid.v1beta1.MsgAddLinkedResource";
+    value: {
+        id: string;
+        signer: string;
+        linkedResource: {
+            type: string;
+            id: string;
+            description: string;
+            mediaType: string;
+            serviceEndpoint: string;
+            proof: string;
+            encrypted: string;
+            right: string;
+        };
+        resourceId?: undefined;
+    };
+})[];
+//# sourceMappingURL=payoutSettings.d.ts.map

package/dist/cjs/chain/payoutSettings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"payoutSettings.d.ts","sourceRoot":"","sources":["../../../src/chain/payoutSettings.ts"],"names":[],"mappings":"AAYA,OAAO,EAA+B,KAAK,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEhF,4FAA4F;AAC5F,MAAM,MAAM,YAAY,GAAG,OAAO,GAAG,UAAU,CAAC;AAChD,eAAO,MAAM,cAAc,EAAE,SAAS,YAAY,EAAqC,CAAC;AAMxF,MAAM,WAAW,cAAc;IAC7B,CAAC,EAAE,CAAC,CAAC;IACL,qGAAqG;IACrG,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,uDAAuD;IACvD,KAAK,EAAE,YAAY,EAAE,CAAC;IACtB,gEAAgE;IAChE,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,yDAAyD;IACzD,QAAQ,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,aAAa;IAC5B,yGAAyG;IACzG,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,aAAa,GAAG,cAAc,CAexE;AAED,8EAA8E;AAC9E,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,OAAO,GAAG,cAAc,GAAG,IAAI,CAatE;AAED,qDAAqD;AACrD,eAAO,MAAM,kBAAkB,GAAI,UAAU,cAAc,KAAG,MAAkC,CAAC;AAEjG,eAAO,MAAM,iBAAiB,GAAI,UAAU,cAAc,KAAG,OAAO,CAAC,MAAM,CAA4C,CAAC;AAExH,iHAAiH;AACjH,eAAO,MAAM,sBAAsB,GAAI,KAAK;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE;;;;;;;;;CASrF,CAAC;AAEH,uDAAuD;AACvD,wBAAgB,iBAAiB,CAAC,MAAM,EAAE;IAAE,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,EAAE,GAAG,IAAI,GAAG,SAAS,GAAG;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAGhJ;AAED,2EAA2E;AAC3E,wBAAsB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAO7G;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE;IAAE,kBAAkB,CAAC,EAAE;QAAE,EAAE,CAAC,EAAE,MAAM,CAAC;QAAC,mBAAmB,CAAC,EAAE,MAAM,CAAA;KAAE,EAAE,GAAG,IAAI,CAAC;IAAC,cAAc,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,CAAA;CAAE,GAAG,IAAI,GAAG,SAAS,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAI9L;AAED,yHAAyH;AACzH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;;;;;;;;;;;;;;;;;;;;;;;;;KAK1H"}

package/dist/cjs/chain/payoutSettings.js

@@ -0,0 +1,123 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.payoutSettingsResource = exports.payoutSettingsCid = exports.payoutSettingsJson = exports.SETTINGS_RAILS = void 0;
+exports.buildPayoutSettings = buildPayoutSettings;
+exports.readPayoutSettings = readPayoutSettings;
+exports.payoutSettingsRef = payoutSettingsRef;
+exports.verifiedPayoutSettings = verifiedPayoutSettings;
+exports.canEditIid = canEditIid;
+exports.replaceSettingsMsgs = replaceSettingsMsgs;
+/**
+ * A company's payout settings (OpenHands HQ), on the org's own chain record.
+ *
+ * One linked resource on the org's IID, `{orgDid}#payoutSettings`, points at
+ * this small JSON document by the https address its store gave (Vault or
+ * gateway) with the CID as its proof — stored
+ * and anchored exactly as `#payoutTerms` is (payoutTerms.ts). An ask posted for
+ * the org builds its `#payoutTerms` from these plus the poster's per-ask
+ * choices. Strict: unknown fields, a bad value or a CID that is not the bytes'
+ * own read as no settings at all.
+ */
+const cid_ts_1 = require("../udid/cid.js");
+const payoutTerms_ts_1 = require("./payoutTerms.js");
+exports.SETTINGS_RAILS = ["chain", "usdc_base", "stripe"];
+const KEYS = ["v", "facilitator", "rails", "oracles", "currency"];
+const MAX_ORACLES = 10;
+// An oracle the company allows: its did:web (IXO's and hosted oracles) or its on-chain entity.
+const ORACLE = /^(did:web:[a-z0-9.-]+(%3A\d+)?(:[A-Za-z0-9._~-]+)*|did:ixo:entity:[0-9a-f]{32})$/;
+function buildPayoutSettings(input) {
+    const rails = [...new Set(input.rails)];
+    if (rails.length === 0 || !rails.every((rail) => exports.SETTINGS_RAILS.includes(rail)))
+        throw new Error(`rails are some of ${exports.SETTINGS_RAILS.join(", ")}, at least one`);
+    const oracles = [...new Set(input.oracles.map((one) => one.trim()).filter(Boolean))];
+    if (oracles.length === 0)
+        throw new Error("name at least one oracle");
+    if (oracles.length > MAX_ORACLES)
+        throw new Error(`at most ${MAX_ORACLES} oracles`);
+    const bad = oracles.find((one) => !ORACLE.test(one));
+    if (bad)
+        throw new Error(`an oracle is a did:web or a did:ixo:entity, not ${bad}`);
+    if (input.currency !== undefined && input.currency !== "USD" && input.currency !== "USDC")
+        throw new Error(`currency is USD or USDC, not ${input.currency}`);
+    if (input.currency === "USDC" && rails.includes("stripe"))
+        throw new Error("Stripe pays in USD");
+    const facilitator = input.facilitator?.trim();
+    const offChain = rails.filter((rail) => rail !== "chain");
+    if (!facilitator && offChain.length)
+        throw new Error(`${offChain.join(" and ")} ${offChain.length === 1 ? "is" : "are"} paid by the company's facilitator: name one`);
+    /* Key order is the stored bytes' (and so the CID's): a doc with a facilitator reads exactly as it was written. */
+    return { v: 1, ...(facilitator ? { facilitator: (0, payoutTerms_ts_1.facilitatorDid)(facilitator) } : {}), rails, oracles, ...(input.currency ? { currency: input.currency } : {}) };
+}
+/** The document as stored, believed field by field; anything else is null. */
+function readPayoutSettings(doc) {
+    if (!doc || typeof doc !== "object" || Array.isArray(doc))
+        return null;
+    if (Object.keys(doc).some((key) => !KEYS.includes(key)))
+        return null;
+    const d = doc;
+    if (d.v !== 1 || !Array.isArray(d.rails) || !Array.isArray(d.oracles) || (d.facilitator !== undefined && typeof d.facilitator !== "string"))
+        return null;
+    if (!d.rails.every((rail) => typeof rail === "string") || !d.oracles.every((one) => typeof one === "string"))
+        return null;
+    try {
+        const built = buildPayoutSettings({ ...(d.facilitator !== undefined ? { facilitator: d.facilitator } : {}), rails: d.rails, oracles: d.oracles, ...(d.currency !== undefined ? { currency: d.currency } : {}) });
+        // Canonical only: what was stored must be what the builder writes, or a reader and the facilitator could disagree.
+        return (0, exports.payoutSettingsJson)(built) === JSON.stringify(doc) ? built : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** The exact bytes that are published and hashed. */
+const payoutSettingsJson = (settings) => JSON.stringify(settings);
+exports.payoutSettingsJson = payoutSettingsJson;
+const payoutSettingsCid = (settings) => (0, cid_ts_1.cidOfText)((0, exports.payoutSettingsJson)(settings));
+exports.payoutSettingsCid = payoutSettingsCid;
+/** The linked resource on the org's IID; the endpoint is the https address its store gave, as `#payoutTerms`. */
+const payoutSettingsResource = (ref) => ({
+    type: "PayoutSettings",
+    id: "{id}#payoutSettings",
+    description: "How this organisation pays for answers",
+    mediaType: "application/json",
+    serviceEndpoint: (0, payoutTerms_ts_1.storedHttps)(ref, "#payoutSettings"),
+    proof: ref.cid,
+    encrypted: "false",
+    right: ""
+});
+exports.payoutSettingsResource = payoutSettingsResource;
+/** Where an org's settings are, found by id suffix. */
+function payoutSettingsRef(linked) {
+    const found = (linked ?? []).find((one) => typeof one?.id === "string" && one.id.endsWith("#payoutSettings"));
+    return found?.id && found.proof ? { id: found.id, cid: found.proof } : null;
+}
+/** The fetched bytes, believed only when they hash to the anchored CID. */
+async function verifiedPayoutSettings(text, cid) {
+    if (text === null || (await (0, cid_ts_1.cidOfText)(text)) !== cid)
+        return null;
+    try {
+        return readPayoutSettings(JSON.parse(text));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Whether `address` may edit this IID: a key in its `authentication` with that
+ * account (a `controller` entry is not enough — the chain answers code 1106).
+ * The org-admin check of OpenHands HQ, shared with the worker's shaped post.
+ * shortcut: matches on blockchainAccountID only, as every key minted by createIidVerificationMethods has one; upgrade if an org authenticates by bare public key.
+ */
+function canEditIid(doc, address) {
+    if (!doc || !address)
+        return false;
+    const authn = new Set(doc.authentication ?? []);
+    return (doc.verificationMethod ?? []).some((method) => authn.has(method.id ?? "") && (method.blockchainAccountID ?? "").split(":").pop() === address);
+}
+/** The settings edit, as one transaction's IID messages: the old resource out (when there is one) and the new one in. */
+function replaceSettingsMsgs(org, signer, stored, oldId) {
+    return [
+        ...(oldId ? [{ typeUrl: "/ixo.iid.v1beta1.MsgDeleteLinkedResource", value: { id: org, resourceId: oldId, signer } }] : []),
+        { typeUrl: "/ixo.iid.v1beta1.MsgAddLinkedResource", value: { id: org, signer, linkedResource: (0, exports.payoutSettingsResource)(stored) } }
+    ];
+}
+//# sourceMappingURL=payoutSettings.js.map

package/dist/cjs/chain/payoutSettings.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"payoutSettings.js","sourceRoot":"","sources":["../../../src/chain/payoutSettings.ts"],"names":[],"mappings":"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"}

package/dist/cjs/chain/payoutTerms.d.ts

@@ -0,0 +1,72 @@
+export type PayoutRail = "usdc_base" | "stripe";
+export interface PayoutTerms {
+    v: 1;
+    /** The organisation that pays: its did:ixo:entity, the collection's `entity`. */
+    org: string;
+    /** The org's facilitator, as a canonical did:web. */
+    facilitator: string;
+    rails: PayoutRail[];
+    /** Per approved answer, a decimal string: two decimals for USD, up to six for USDC. */
+    amount: string;
+    /** USD when the rails include stripe; USDC only with usdc_base alone (which also pays USD 1:1). */
+    currency: "USD" | "USDC";
+    payee: "submitter";
+    /** A hint, not authority: the org's trusted-oracle list decides. */
+    oracle?: string;
+}
+export interface PayoutInput {
+    org: string;
+    facilitator: string;
+    rail: PayoutRail;
+    amount: number;
+    currency: string;
+    oracle?: string;
+}
+/** `https://host/any/path` or `did:web:host[:path]` → `did:web:host`, a port as `%3A`. */
+export declare function facilitatorDid(facilitator: string): string;
+/** The facilitator's https origin, from either form. */
+export declare const facilitatorOrigin: (facilitator: string) => string;
+export declare function buildPayoutTerms(input: PayoutInput): PayoutTerms;
+/** The document as stored, believed field by field; anything else is null. */
+export declare function readPayoutTerms(doc: unknown): PayoutTerms | null;
+/** The exact bytes that are published and hashed. */
+export declare const payoutTermsJson: (terms: PayoutTerms) => string;
+/** CIDv1 raw sha256 of those bytes: the facilitator recomputes it and refuses a mismatch. */
+export declare const payoutTermsCid: (terms: PayoutTerms) => Promise<string>;
+/** The https address the store gave (`url` from the browser's store, `uri` from the worker's); an extra resource is never `ipfs:`. */
+export declare function storedHttps(ref: {
+    url?: string;
+    uri?: string;
+}, what: string): string;
+/** The linked resource on the ask entity. Wrap in `ixo.iid.v1beta1.LinkedResource.fromPartial` at the call site. The proof is the CID the facilitator recomputes. */
+export declare const payoutTermsResource: (ref: {
+    cid: string;
+    url?: string;
+    uri?: string;
+}) => {
+    type: string;
+    id: string;
+    description: string;
+    mediaType: string;
+    serviceEndpoint: string;
+    proof: string;
+    encrypted: string;
+    right: string;
+};
+/** Where an entity's payout terms are, found by id suffix as the engine finds `#vct`. */
+export declare function payoutTermsRef(linked: {
+    id?: string | null;
+    serviceEndpoint?: string | null;
+    proof?: string | null;
+}[]): {
+    cid: string;
+    url: string;
+} | null;
+/** What the ask's own `#done` terms carry for the board: no org, no facilitator, those are this document's. */
+export declare const payoutSummary: (terms: PayoutTerms) => {
+    rail: PayoutRail;
+    amount: string;
+    currency: "USD" | "USDC";
+};
+export declare const railWords: (rail: PayoutRail) => string;
+//# sourceMappingURL=payoutTerms.d.ts.map

package/dist/cjs/chain/payoutTerms.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"payoutTerms.d.ts","sourceRoot":"","sources":["../../../src/chain/payoutTerms.ts"],"names":[],"mappings":"AAYA,MAAM,MAAM,UAAU,GAAG,WAAW,GAAG,QAAQ,CAAC;AAIhD,MAAM,WAAW,WAAW;IAC1B,CAAC,EAAE,CAAC,CAAC;IACL,iFAAiF;IACjF,GAAG,EAAE,MAAM,CAAC;IACZ,qDAAqD;IACrD,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,UAAU,EAAE,CAAC;IACpB,uFAAuF;IACvF,MAAM,EAAE,MAAM,CAAC;IACf,mGAAmG;IACnG,QAAQ,EAAE,KAAK,GAAG,MAAM,CAAC;IACzB,KAAK,EAAE,WAAW,CAAC;IACnB,oEAAoE;IACpE,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,UAAU,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAQD,0FAA0F;AAC1F,wBAAgB,cAAc,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAU1D;AAED,wDAAwD;AACxD,eAAO,MAAM,iBAAiB,GAAI,aAAa,MAAM,KAAG,MAAgG,CAAC;AAEzJ,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,WAAW,GAAG,WAAW,CAuBhE;AAED,8EAA8E;AAC9E,wBAAgB,eAAe,CAAC,GAAG,EAAE,OAAO,GAAG,WAAW,GAAG,IAAI,CAkBhE;AAED,qDAAqD;AACrD,eAAO,MAAM,eAAe,GAAI,OAAO,WAAW,KAAG,MAA+B,CAAC;AAErF,6FAA6F;AAC7F,eAAO,MAAM,cAAc,GAAI,OAAO,WAAW,KAAG,OAAO,CAAC,MAAM,CAAsC,CAAC;AAEzG,sIAAsI;AACtI,wBAAgB,WAAW,CAAC,GAAG,EAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAIrF;AAED,qKAAqK;AACrK,eAAO,MAAM,mBAAmB,GAAI,KAAK;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE;;;;;;;;;CASlF,CAAC;AAEH,yFAAyF;AACzF,wBAAgB,cAAc,CAAC,MAAM,EAAE;IAAE,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,EAAE,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAG5J;AAED,+GAA+G;AAC/G,eAAO,MAAM,aAAa,GAAI,OAAO,WAAW;;;;CAAgF,CAAC;AAEjI,eAAO,MAAM,SAAS,GAAI,MAAM,UAAU,KAAG,MAAyE,CAAC"}

package/dist/cjs/chain/payoutTerms.js

@@ -0,0 +1,141 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.railWords = exports.payoutSummary = exports.payoutTermsResource = exports.payoutTermsCid = exports.payoutTermsJson = exports.facilitatorOrigin = void 0;
+exports.facilitatorDid = facilitatorDid;
+exports.buildPayoutTerms = buildPayoutTerms;
+exports.readPayoutTerms = readPayoutTerms;
+exports.storedHttps = storedHttps;
+exports.payoutTermsRef = payoutTermsRef;
+/**
+ * How an ask paid off chain pays (OpenHands HQ, ways B and C).
+ *
+ * The approval leg of such an ask is empty, so the chain pays nobody; the
+ * organisation's facilitator reads this document at `{askDid}#payoutTerms`
+ * and pays the submitter on USDC on Base or Stripe once an approved oracle
+ * approves. **The shape is S4's #payoutTerms v1 contract (confirmed
+ * 2026-10-13); strict, unknown fields are refused.** This file is the only
+ * writer and reader, so a change to it is a change here.
+ */
+const cid_ts_1 = require("../udid/cid.js");
+const RAILS = ["usdc_base", "stripe"];
+const KEYS = ["v", "org", "facilitator", "rails", "amount", "currency", "payee", "oracle"];
+const ORG = /^did:ixo:entity:[0-9a-f]{32}$/;
+const HOST = /^[a-z0-9.-]+(%3a\d+)?$/i;
+// The facilitator verifies the oracle by did:web or did:key; an on-chain entity DID is not one.
+const WEB_OR_KEY = (did) => did.startsWith("did:web:") || did.startsWith("did:key:");
+const MAX_DECIMALS = { USD: 2, USDC: 6 };
+/** `https://host/any/path` or `did:web:host[:path]` → `did:web:host`, a port as `%3A`. */
+function facilitatorDid(facilitator) {
+    const value = facilitator.trim();
+    if (value.toLowerCase().startsWith("did:web:")) {
+        const host = value.slice("did:web:".length).split(":")[0] ?? "";
+        if (!host || !HOST.test(host))
+            throw new Error(`not a facilitator did:web: ${facilitator}`);
+        return `did:web:${host.toLowerCase().replace(/%3a/, "%3A")}`;
+    }
+    const url = URL.canParse(value) ? new URL(value) : null;
+    if (url?.protocol !== "https:" || !url.hostname)
+        throw new Error(`a facilitator is a did:web or an https URL, not ${facilitator}`);
+    return `did:web:${url.host.toLowerCase().replace(/:/g, "%3A")}`;
+}
+/** The facilitator's https origin, from either form. */
+const facilitatorOrigin = (facilitator) => `https://${facilitatorDid(facilitator).slice("did:web:".length).replace(/%3A/g, ":")}`;
+exports.facilitatorOrigin = facilitatorOrigin;
+function buildPayoutTerms(input) {
+    if (!ORG.test(input.org))
+        throw new Error(`org must be the organisation's did:ixo:entity, not ${input.org}`);
+    if (!RAILS.includes(input.rail))
+        throw new Error(`rail must be usdc_base or stripe, not ${input.rail}`);
+    // USDC on Base pays USD 1:1, so usdc_base takes either; Stripe only USD.
+    if (input.currency !== "USD" && !(input.rail === "usdc_base" && input.currency === "USDC"))
+        throw new Error(`${input.rail === "stripe" ? "Stripe pays in USD" : "USDC on Base pays in USDC or USD"}, not ${input.currency}`);
+    const currency = input.currency;
+    if (!Number.isFinite(input.amount) || input.amount <= 0)
+        throw new Error("the payout amount must be more than 0");
+    if (input.amount > 1_000_000)
+        throw new Error("the payout amount is at most 1,000,000");
+    const places = MAX_DECIMALS[currency];
+    const scaled = input.amount * 10 ** places;
+    if (Math.abs(Math.round(scaled) - scaled) > 1e-6)
+        throw new Error(`a ${currency} payout amount has at most ${places} decimals (${places === 2 ? "cents" : "micro-dollars"})`);
+    // Two decimals when that is exact, else the shortest exact form (USDC only gets here).
+    const amount = Math.abs(Math.round(input.amount * 100) - input.amount * 100) <= 1e-6 ? input.amount.toFixed(2) : input.amount.toFixed(places).replace(/0+$/, "");
+    return {
+        v: 1,
+        org: input.org,
+        facilitator: facilitatorDid(input.facilitator),
+        rails: [input.rail],
+        amount,
+        currency,
+        payee: "submitter",
+        ...(input.oracle !== undefined && WEB_OR_KEY(input.oracle) && { oracle: input.oracle })
+    };
+}
+/** The document as stored, believed field by field; anything else is null. */
+function readPayoutTerms(doc) {
+    if (!doc || typeof doc !== "object" || Array.isArray(doc))
+        return null;
+    if (Object.keys(doc).some((key) => !KEYS.includes(key)))
+        return null;
+    const d = doc;
+    if (d.v !== 1 || d.payee !== "submitter")
+        return null;
+    if (typeof d.org !== "string" || !ORG.test(d.org))
+        return null;
+    if (d.oracle !== undefined && (typeof d.oracle !== "string" || !WEB_OR_KEY(d.oracle)))
+        return null;
+    if (!Array.isArray(d.rails) || d.rails.length === 0 || !d.rails.every((rail) => RAILS.includes(rail)) || new Set(d.rails).size !== d.rails.length)
+        return null;
+    if (d.currency !== "USD" && d.currency !== "USDC")
+        return null;
+    if (d.rails.includes("stripe") && d.currency !== "USD")
+        return null; // no stripe means usdc_base alone (rails are unique): USD or USDC
+    if (typeof d.amount !== "string" || !/^\d+(\.\d+)?$/.test(d.amount) || Number(d.amount) <= 0)
+        return null;
+    if ((d.amount.split(".")[1]?.length ?? 0) > MAX_DECIMALS[d.currency])
+        return null;
+    try {
+        if (typeof d.facilitator !== "string" || facilitatorDid(d.facilitator) !== d.facilitator)
+            return null;
+    }
+    catch {
+        return null;
+    }
+    return { v: 1, org: d.org, facilitator: d.facilitator, rails: [...d.rails], amount: d.amount, currency: d.currency, payee: "submitter", ...(d.oracle !== undefined && { oracle: d.oracle }) };
+}
+/** The exact bytes that are published and hashed. */
+const payoutTermsJson = (terms) => JSON.stringify(terms);
+exports.payoutTermsJson = payoutTermsJson;
+/** CIDv1 raw sha256 of those bytes: the facilitator recomputes it and refuses a mismatch. */
+const payoutTermsCid = (terms) => (0, cid_ts_1.cidOfText)((0, exports.payoutTermsJson)(terms));
+exports.payoutTermsCid = payoutTermsCid;
+/** The https address the store gave (`url` from the browser's store, `uri` from the worker's); an extra resource is never `ipfs:`. */
+function storedHttps(ref, what) {
+    const url = (ref.url ?? ref.uri ?? "").trim();
+    if (!/^https:\/\/\S+$/.test(url))
+        throw new Error(`${what} needs the https address its store gave, got ${JSON.stringify(url)}`);
+    return url;
+}
+/** The linked resource on the ask entity. Wrap in `ixo.iid.v1beta1.LinkedResource.fromPartial` at the call site. The proof is the CID the facilitator recomputes. */
+const payoutTermsResource = (ref) => ({
+    type: "PayoutTerms",
+    id: "{id}#payoutTerms",
+    description: "How an approved answer is paid, off chain",
+    mediaType: "application/json",
+    serviceEndpoint: storedHttps(ref, "#payoutTerms"),
+    proof: ref.cid,
+    encrypted: "false",
+    right: ""
+});
+exports.payoutTermsResource = payoutTermsResource;
+/** Where an entity's payout terms are, found by id suffix as the engine finds `#vct`. */
+function payoutTermsRef(linked) {
+    const found = linked.find((one) => typeof one?.id === "string" && one.id.endsWith("#payoutTerms"));
+    return found?.proof && found.serviceEndpoint ? { cid: found.proof, url: found.serviceEndpoint } : null;
+}
+/** What the ask's own `#done` terms carry for the board: no org, no facilitator, those are this document's. */
+const payoutSummary = (terms) => ({ rail: terms.rails[0], amount: terms.amount, currency: terms.currency });
+exports.payoutSummary = payoutSummary;
+const railWords = (rail) => (rail === "stripe" ? "Paid by Stripe" : "Paid in USDC on Base");
+exports.railWords = railWords;
+//# sourceMappingURL=payoutTerms.js.map