@multiagency/sdk 0.3.1 → 0.4.0

package/dist/contract/treasury-proposals.d.ts

@@ -0,0 +1,193 @@
+import { z } from "zod";
+/**
+ * Treasury proposals (docs/enforcement.md, "Treasury proposals"): an app proposes swaps now; the owner approves their
+ * exact terms later by signing `proposalText` (NEP-413, recipient the platform host); the platform executes them once,
+ * through the same plan execution as any saved plan, under the owner's policy. Pure schemas and the text builder,
+ * shared by the platform and apps, so an app can show and check the text it relays.
+ */
+/** At most this long between proposing and expiry: Sputnik's default `proposal_period`. */
+export declare const MAX_PROPOSAL_MS: number;
+/** Proposals per agent neither claimed nor closed; another is refused. */
+export declare const MAX_OPEN_PROPOSALS = 32;
+export declare const MAX_PROPOSAL_LEGS = 8;
+/** The platform's assets as the owner's text names them. */
+export declare const PROPOSAL_TOKENS: Record<string, {
+    symbol: string;
+    decimals: number;
+}>;
+export declare const proposalId: z.ZodString;
+/** A swap an app chooses: what it spends, buys, and optionally the least it accepts (raised to the quote's floor). */
+export declare const proposalSwap: z.ZodObject<{
+    from: z.ZodEnum<{
+        [x: string]: string;
+    }>;
+    to: z.ZodEnum<{
+        [x: string]: string;
+    }>;
+    amount: z.ZodString;
+    minAmountOut: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+/**
+ * `legs`: the app's chosen swaps, in order, or `"strategy"` for the legs a rebalance toward the owner's strategy picks.
+ * `expiresAt`: at most `MAX_PROPOSAL_MS` ahead; the proposal may be approved and executed until then.
+ */
+export declare const proposalCreateInput: z.ZodObject<{
+    requestId: z.ZodString;
+    legs: z.ZodUnion<readonly [z.ZodArray<z.ZodObject<{
+        from: z.ZodEnum<{
+            [x: string]: string;
+        }>;
+        to: z.ZodEnum<{
+            [x: string]: string;
+        }>;
+        amount: z.ZodString;
+        minAmountOut: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>, z.ZodLiteral<"strategy">]>;
+    expiresAt: z.ZodISODateTime;
+    note: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+/** The owner's NEP-413 signature over the proposal's text, as the app relays it. */
+export declare const proposalSignature: z.ZodObject<{
+    message: z.ZodString;
+    nonce: z.ZodString;
+    publicKey: z.ZodString;
+    signature: z.ZodString;
+}, z.core.$strict>;
+export declare const proposalSigned: z.ZodObject<{
+    id: z.ZodString;
+    signed: z.ZodObject<{
+        message: z.ZodString;
+        nonce: z.ZodString;
+        publicKey: z.ZodString;
+        signature: z.ZodString;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export declare const proposalRef: z.ZodObject<{
+    id: z.ZodString;
+}, z.core.$strict>;
+export declare const ProposalState: z.ZodEnum<{
+    approved: "approved";
+    executed: "executed";
+    executing: "executing";
+    expired: "expired";
+    invalidated: "invalidated";
+    proposed: "proposed";
+    rejected: "rejected";
+    stopped: "stopped";
+    unknown: "unknown";
+    withdrawn: "withdrawn";
+}>;
+export type ProposalState = z.infer<typeof ProposalState>;
+/** A proposal as the platform shows it: its signed terms, its state, and what the journal holds for its execution. */
+export declare const proposalView: z.ZodObject<{
+    id: z.ZodString;
+    requestId: z.ZodString;
+    agentId: z.ZodString;
+    deployment: z.ZodString;
+    organization: z.ZodString;
+    source: z.ZodEnum<{
+        external: "external";
+        rebalance: "rebalance";
+    }>;
+    legs: z.ZodArray<z.ZodObject<{
+        from: z.ZodString;
+        to: z.ZodString;
+        amount: z.ZodString;
+        minAmountOut: z.ZodString;
+    }, z.core.$loose>>;
+    quoted: z.ZodArray<z.ZodObject<{
+        amountOut: z.ZodString;
+        costBps: z.ZodNumber;
+        usdIn: z.ZodNumber;
+    }, z.core.$loose>>;
+    policyRevision: z.ZodNullable<z.ZodNumber>;
+    policyDigest: z.ZodNullable<z.ZodString>;
+    strategyDigest: z.ZodString;
+    createdAt: z.ZodString;
+    expiresAt: z.ZodString;
+    note: z.ZodNullable<z.ZodString>;
+    sha256: z.ZodString;
+    state: z.ZodEnum<{
+        approved: "approved";
+        executed: "executed";
+        executing: "executing";
+        expired: "expired";
+        invalidated: "invalidated";
+        proposed: "proposed";
+        rejected: "rejected";
+        stopped: "stopped";
+        unknown: "unknown";
+        withdrawn: "withdrawn";
+    }>;
+    reason: z.ZodNullable<z.ZodString>;
+    approvedAt: z.ZodNullable<z.ZodString>;
+    planId: z.ZodNullable<z.ZodString>;
+    operations: z.ZodArray<z.ZodObject<{
+        method: z.ZodOptional<z.ZodString>;
+        status: z.ZodNullable<z.ZodString>;
+        correlationId: z.ZodNullable<z.ZodString>;
+        refused: z.ZodNullable<z.ZodString>;
+    }, z.core.$loose>>;
+}, z.core.$loose>;
+export type ProposalView = z.infer<typeof proposalView>;
+export declare const proposalList: z.ZodObject<{
+    proposals: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        requestId: z.ZodString;
+        agentId: z.ZodString;
+        deployment: z.ZodString;
+        organization: z.ZodString;
+        source: z.ZodEnum<{
+            external: "external";
+            rebalance: "rebalance";
+        }>;
+        legs: z.ZodArray<z.ZodObject<{
+            from: z.ZodString;
+            to: z.ZodString;
+            amount: z.ZodString;
+            minAmountOut: z.ZodString;
+        }, z.core.$loose>>;
+        quoted: z.ZodArray<z.ZodObject<{
+            amountOut: z.ZodString;
+            costBps: z.ZodNumber;
+            usdIn: z.ZodNumber;
+        }, z.core.$loose>>;
+        policyRevision: z.ZodNullable<z.ZodNumber>;
+        policyDigest: z.ZodNullable<z.ZodString>;
+        strategyDigest: z.ZodString;
+        createdAt: z.ZodString;
+        expiresAt: z.ZodString;
+        note: z.ZodNullable<z.ZodString>;
+        sha256: z.ZodString;
+        state: z.ZodEnum<{
+            approved: "approved";
+            executed: "executed";
+            executing: "executing";
+            expired: "expired";
+            invalidated: "invalidated";
+            proposed: "proposed";
+            rejected: "rejected";
+            stopped: "stopped";
+            unknown: "unknown";
+            withdrawn: "withdrawn";
+        }>;
+        reason: z.ZodNullable<z.ZodString>;
+        approvedAt: z.ZodNullable<z.ZodString>;
+        planId: z.ZodNullable<z.ZodString>;
+        operations: z.ZodArray<z.ZodObject<{
+            method: z.ZodOptional<z.ZodString>;
+            status: z.ZodNullable<z.ZodString>;
+            correlationId: z.ZodNullable<z.ZodString>;
+            refused: z.ZodNullable<z.ZodString>;
+        }, z.core.$loose>>;
+    }, z.core.$loose>>;
+}, z.core.$loose>;
+/** A raw amount in whole units, exact, without trailing zeros. */
+export declare function tokenAmount(raw: string, decimals: number): string;
+type Terms = Pick<ProposalView, "id" | "agentId" | "deployment" | "organization" | "legs" | "policyRevision" | "policyDigest" | "strategyDigest" | "expiresAt" | "sha256">;
+/**
+ * The exact text the owner signs to approve (or reject) a proposal: the platform accepts only these bytes. The host is
+ * the NEP-413 recipient, so it isn't repeated here.
+ */
+export declare function proposalText(proposal: Terms, verdict: "approve" | "reject"): string;
+export {};

package/dist/contract/treasury-proposals.js

@@ -0,0 +1,102 @@
+import { z } from "zod";
+import { ASSETS } from "./assets.js";
+import { payoutRequestId } from "./inputs.js";
+/**
+ * Treasury proposals (docs/enforcement.md, "Treasury proposals"): an app proposes swaps now; the owner approves their
+ * exact terms later by signing `proposalText` (NEP-413, recipient the platform host); the platform executes them once,
+ * through the same plan execution as any saved plan, under the owner's policy. Pure schemas and the text builder,
+ * shared by the platform and apps, so an app can show and check the text it relays.
+ */
+/** At most this long between proposing and expiry: Sputnik's default `proposal_period`. */
+export const MAX_PROPOSAL_MS = 7 * 86_400_000;
+/** Proposals per agent neither claimed nor closed; another is refused. */
+export const MAX_OPEN_PROPOSALS = 32;
+export const MAX_PROPOSAL_LEGS = 8;
+/** The platform's assets as the owner's text names them. */
+export const PROPOSAL_TOKENS = {
+    [ASSETS.USDC]: { symbol: "USDC", decimals: 6 },
+    [ASSETS.wNEAR]: { symbol: "wNEAR", decimals: 24 },
+    [ASSETS.ETH]: { symbol: "ETH", decimals: 18 },
+};
+const asset = z.enum(Object.values(ASSETS));
+const amount = z.string().regex(/^[0-9]{1,40}$/).refine(value => BigInt(value) > 0n, "Amount must be positive");
+export const proposalId = z.string().regex(/^[a-f0-9]{32}$/);
+/** A swap an app chooses: what it spends, buys, and optionally the least it accepts (raised to the quote's floor). */
+export const proposalSwap = z.strictObject({ from: asset, to: asset, amount, minAmountOut: amount.optional() })
+    .refine(swap => swap.from !== swap.to, "Swap assets must differ");
+/**
+ * `legs`: the app's chosen swaps, in order, or `"strategy"` for the legs a rebalance toward the owner's strategy picks.
+ * `expiresAt`: at most `MAX_PROPOSAL_MS` ahead; the proposal may be approved and executed until then.
+ */
+export const proposalCreateInput = z.strictObject({
+    requestId: payoutRequestId,
+    legs: z.union([z.array(proposalSwap).min(1).max(MAX_PROPOSAL_LEGS), z.literal("strategy")]),
+    expiresAt: z.iso.datetime(),
+    note: z.string().max(280).optional(),
+});
+/** The owner's NEP-413 signature over the proposal's text, as the app relays it. */
+export const proposalSignature = z.strictObject({
+    message: z.string().min(1).max(4_096),
+    nonce: z.string().min(1).max(64),
+    publicKey: z.string().regex(/^ed25519:[1-9A-HJ-NP-Za-km-z]{32,64}$/),
+    signature: z.string().min(1).max(200),
+});
+export const proposalSigned = z.strictObject({ id: proposalId, signed: proposalSignature });
+export const proposalRef = z.strictObject({ id: proposalId });
+export const ProposalState = z.enum(["proposed", "approved", "executing", "executed", "stopped", "unknown", "rejected", "withdrawn", "expired", "invalidated"]);
+const leg = z.looseObject({ from: z.string(), to: z.string(), amount: z.string(), minAmountOut: z.string() });
+/** A proposal as the platform shows it: its signed terms, its state, and what the journal holds for its execution. */
+export const proposalView = z.looseObject({
+    id: z.string(),
+    requestId: z.string(),
+    agentId: z.string(),
+    deployment: z.string(),
+    organization: z.string(),
+    source: z.enum(["external", "rebalance"]),
+    /** The terms the owner signs: each leg's floor is the least it may return. */
+    legs: z.array(leg),
+    /** Quotes when proposed: shown, never relied on. */
+    quoted: z.array(z.looseObject({ amountOut: z.string(), costBps: z.number(), usdIn: z.number() })),
+    policyRevision: z.number().nullable(),
+    policyDigest: z.string().nullable(),
+    strategyDigest: z.string(),
+    createdAt: z.string(),
+    expiresAt: z.string(),
+    note: z.string().nullable(),
+    /** sha256 of the canonical record: named in the owner's text. */
+    sha256: z.string(),
+    state: ProposalState,
+    /** Why it was closed (rejected, withdrawn, expired, invalidated), or null. */
+    reason: z.string().nullable(),
+    approvedAt: z.string().nullable(),
+    /** The plan its execution ran, once claimed. */
+    planId: z.string().nullable(),
+    /** Its plan's operations in the journal, oldest first. */
+    operations: z.array(z.looseObject({ method: z.string().optional(), status: z.string().nullable(), correlationId: z.string().nullable(), refused: z.string().nullable() })),
+});
+export const proposalList = z.looseObject({ proposals: z.array(proposalView) });
+/** A raw amount in whole units, exact, without trailing zeros. */
+export function tokenAmount(raw, decimals) {
+    const digits = raw.padStart(decimals + 1, "0");
+    const whole = digits.slice(0, digits.length - decimals);
+    const fraction = digits.slice(digits.length - decimals).replace(/0+$/, "");
+    return fraction ? `${whole}.${fraction}` : whole;
+}
+const shown = (asset, raw) => {
+    const token = PROPOSAL_TOKENS[asset];
+    return token ? `${tokenAmount(raw, token.decimals)} ${token.symbol} (${raw})` : `${raw} of ${asset}`;
+};
+/**
+ * The exact text the owner signs to approve (or reject) a proposal: the platform accepts only these bytes. The host is
+ * the NEP-413 recipient, so it isn't repeated here.
+ */
+export function proposalText(proposal, verdict) {
+    return [
+        `${verdict === "approve" ? "Approve" : "Reject"} Treasury proposal ${proposal.id}`,
+        `Agent ${proposal.agentId}`,
+        `Proposed by ${proposal.deployment} for ${proposal.organization}`,
+        ...proposal.legs.map((leg, i) => `${i + 1}. Swap ${shown(leg.from, leg.amount)} for at least ${shown(leg.to, leg.minAmountOut)}`),
+        `Under policy revision ${proposal.policyRevision ?? "none"} (${proposal.policyDigest ?? "none"}), strategy ${proposal.strategyDigest}`,
+        `Valid until ${proposal.expiresAt}. Proposal sha256 ${proposal.sha256}.`,
+    ].join("\n");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@multiagency/sdk",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "type": "module",
   "license": "MIT",
   "description": "MultiAgency SDK: payee, compensation and owner-app schemas, typed payee and owner clients, and the shared release asset server.",

package/provenance.json

@@ -1,6 +1,6 @@
 {
   "name": "@multiagency/sdk",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "wire": {
     "payeeManifestVersion": 1,
     "capabilities": [
@@ -12,50 +12,52 @@
       "supplier-agent-connections-v1"
     ]
   },
-  "sourceHead": "766b3f3a25b6ae90ac4d4f1d8bb65ef5597f6f66",
+  "sourceHead": "1a7fe9818e2a83c548e1ba8d587f10acac37716a",
   "dirtyPaths": [],
   "snapshot": {
-    "runDigest": "106ed6be37bc8f6b133006b49b74264cb9519807f20c3b70ad17cb2cbbf12136",
+    "runDigest": "c8dafe626d05552a1d101d8119f41441f67bb4c25dec60331dc98e2e62589de8",
     "overlayDiffSha256": null
   },
   "sources": {
     "src/compensation-contract.ts": "3443b0690db7921d6dec04375d9281a2e1df3f4ffbe48c2b821e89af177f14c1",
     "src/contract/agent-connection.ts": "cfe3ec3b3cdc4da2773b20de008e1a004f2862499d0df5831923637f8b39a746",
-    "src/contract/app-access.ts": "f5c792723dcaf870bf000265de9816b819035883cf79227e7de0cccc25681363",
-    "src/contract/app-client.ts": "d1ae48532320e8bfa5337f68b915f699566eea77d59d836ccd55e00676ea82b3",
-    "src/contract/app-consent.ts": "671d5904b448af50bc06aee19bdefa84359494b6cfe38cc0725042703ca6418a",
+    "src/contract/app-access.ts": "9385fc9ef5fbb26734b70ed9ddba916113815ebbaf6f2fb8e6fbc3809bb78f59",
+    "src/contract/app-client.ts": "a505db256012feb3659c02f001444b4bddc90fc7a091200c36b32c88d63832d5",
+    "src/contract/app-consent.ts": "6649a7d27f19ab84f23433deeefb877b4e386934d64f3ac2040d04b9d3309d3d",
     "src/contract/assets.ts": "b6cc3a160e488bfecf273b50e747e4640c8f4ba4d000bd6898db4f805ae9f310",
     "src/contract/client.ts": "1eabd53e3119078d3c01a18850c180fab45385eec6ad210b92aa7fa158a03996",
     "src/contract/gateway.ts": "e66bb199ab504b007e5a04617e0cf53b5b3d9641328a799c7df33f8901fa473b",
-    "src/contract/index.ts": "7c2daca088c9841b4e5e986825cd0501ef9f271fb4b9bc2804e83c93b5f938c5",
+    "src/contract/index.ts": "e1b0f7dc2618543de5e98c6a94c9ed979c43a17e625445daa395d4be42a0396c",
     "src/contract/inputs.ts": "a7b16ff1ff05a65bc2bd6b8bdaa978296d912e45098d105e0a578a8174a029d3",
     "src/contract/intents-account.ts": "8e88f6f41de28fdb48fa49243ccb4e0035dc7823586931658922927cf92f8fea",
     "src/contract/orpc-client.ts": "94cbd34bc64bd06152f2dbf17d2ff6b270d1d3b703e3bb7019483bcce93eeb04",
-    "src/contract/owner-capabilities.ts": "1cee82270d4c9bf2984e71297515da0763b2e6b3c2d8052c96efed89813fb326",
+    "src/contract/owner-capabilities.ts": "31aadb5a44b776ea34dc5f7b5a4306a765c6deec0b4a802337fe6fefd4373f69",
     "src/contract/owner-client.ts": "468a2e06784e95242087ecf45af805092de28af4e59ad0d445b29999b145b9f6",
     "src/contract/owner-contract.ts": "339f63d7b585d652f1fd2175ebc94a5d8ef5e31a1f4730e554c2b0b89b24ab11",
-    "src/contract/owner-inputs.ts": "4328b6734a955fe524cf04852a0e4d9c20cf3c618416c5e91d857c98ffa1b837",
-    "src/contract/owner-outputs.ts": "59e9d8a712c4e6dc60075edaef86fee3f50a6b6c99273cd992431efbdefee75a",
-    "src/contract/package-version.ts": "a1495bd2343727a79d50e56af598990d3efce9e3253538b0d8b09feddc9e0736",
+    "src/contract/owner-inputs.ts": "e8dab47bbbffcf1dbe268fae4e0ffa703b8c46bb79b2cc5659bb1cc6ecd9c2e2",
+    "src/contract/owner-outputs.ts": "1e88bf152ddfdf2f7ee74ae53d3a05dafc3f994b01a6e22b720856dfa616f4aa",
+    "src/contract/package-version.ts": "e97007b462544c8e245b29c002930918e2f9a357be0b3346fc02a68ecdb8a1a6",
     "src/contract/payee-entry.ts": "9557ec0f53dd4ab3411d3a81ccd82667f83766386332fb84e93a50caa8287bef",
     "src/contract/payee.ts": "ec6e0c628be8592b997a5ceccfcd1ca18f891bb969731214fd4205b7e3f07a66",
-    "src/contract/permissions.ts": "fd0280c696cc070390360f20ff941f4ef2cf8143d81d55856103de43a935c93d",
+    "src/contract/permissions.ts": "03171e6e382cf70f264760c6d9734e06d3bfd371c3bc12238335f763cd0b4242",
     "src/contract/proposals.ts": "8a9abb34f1ee09fcfb1de2cc2ced2773d3fa189f20faa0bc1a31ed9fae82beef",
     "src/contract/run-log-schema.ts": "2ef522a589f6a70cff58e4ded63ddf41a6d3998b2fde96a1bf9176b363da3847",
     "src/contract/run-progress-schema.ts": "5eead5bde373e8f058f7f42cf588c4a71e1960d5d7097e0381384c03f6a4bbfb",
+    "src/contract/treasury-proposals.ts": "8b0e9cfca940e706689a3da92fd781f0e8279753bbd8f866452a8ad249d6cae3",
     "src/payee-contract.ts": "800260c35c1edbc6e8361f9213fe5f4ccdc22d8d7b1510db08a590f83a152351",
     "src/contract/release-server.mjs": "a2177a0fc28bc19edefae2e5d5e8e11dffa3c4f099f604cee82457cb8eca51c7",
     "src/contract/release-server.d.mts": "05fb535f8d1f3ff4aac62395b717144aecf1f4b0c5b388ca83d8b4cb677d2764",
-    "docs/sdk-changes.md": "969bd9a4fcc3774660dea0717798e5e5e300f54d40dc88b104fa75122a0ce567",
+    "docs/sdk-changes.md": "5cd4a1fab6ab8ae15c27bd99a587bbcae9ee393d00214e38dea7321d4189a154",
     "src/contract/README.md": "e80e5cbbab40fef5d4a8deadb90b02133b2998df7fc17ff031910e818e6909a9",
     "LICENSE": "0f90c37abe95e72f99ddb9b9dfc5e54b663d8bfed929d4c261669059443ba822",
-    "src/contract/skills/app-server/SKILL.md": "0bef6c331bc86eeae588c0c54ce2932c25cb5d2d07107912c728213bcf943071",
-    "src/contract/skills/getting-started/SKILL.md": "c8b2bce01aa946c8a6c3540266208e93e3ae08ddb7cf5deff7a6ccae2b92f622",
-    "src/contract/skills/owner-workflows/SKILL.md": "e6b88d764aa8b6cafd1a26ad7a21cbbd842625a9b145c96dd922a6ef6ae080ed",
-    "src/contract/skills/payee-workflows/SKILL.md": "efa1bd5e07d4b06405d54c5fc424d9357ab336883bdd55e66bbd7094bb01441a"
+    "src/contract/skills/app-server/SKILL.md": "fe120aaec480521947ea4cef71ea50e810db7619aa8a8b2ca7cf04e598de63b1",
+    "src/contract/skills/getting-started/SKILL.md": "f46e923f1c5b69746f99f3fc7809248c2c7b6a036d45e53fbaa27040d18d05c1",
+    "src/contract/skills/owner-workflows/SKILL.md": "f4d8585663430808e89c9f527b010c76519ad21592e7281f443d4c7d675cd34d",
+    "src/contract/skills/payee-workflows/SKILL.md": "6839aef4532fcfd6c5a4fdf1bb34faff1477a879c06f0ede2bd514961aa24680",
+    "src/contract/skills/treasury-app/SKILL.md": "d53226515032de733f75a34c91f5287241df99be67d2ebd248d35ed69258d7ab"
   },
   "sourcesDirty": [],
   "node": "v24.22.1",
   "typescript": "Version 7.0.2",
-  "builtAt": "2026-10-31T04:39:35.856Z"
+  "builtAt": "2026-11-03T01:24:16.514Z"
 }

package/skills/app-server/SKILL.md

@@ -10,7 +10,7 @@ metadata:
   purpose: 'An app server''s access to agents: credential, consents, relayed owner actions, and payout requests by requestId with recovery by state.'
   type: core
   library: '@multiagency/sdk'
-  library_version: '0.3.1'
+  library_version: '0.4.0'
 requires:
   - getting-started
   - owner-workflows
@@ -25,8 +25,8 @@ sources:
 
 Read getting-started and owner-workflows first. `appClient` runs on your server with the deployment's service credential
 (`tap_…`), issued by the platform operator: a server secret, never sent to a browser. A call reaches an agent only
-under a live owner consent for that Organization and agent, and only within the consent's scopes: `read`, `owner`, and
-`payout`. No production MultiAgency host serves the `/apps/v1` routes yet; the operator runs them on a staging host for
+under a live owner consent for that Organization and agent, and only within the consent's scopes: `read`, `owner`,
+`payout`, and for Treasury `treasury` and `treasury-execute` (see treasury-app). No production MultiAgency host serves the `/apps/v1` routes yet; the operator runs them on a staging host for
 its own tests. Until a production host does, build against the SDK repository's local stack
 (`pnpm test:e2e:stack --app <deployment>`). Use only `/apps/v1` and the confirm page on the platform's host: it serves
 nothing else (no sign-in or owner page), and setup there is for Payables agents only.

package/skills/getting-started/SKILL.md

@@ -9,7 +9,7 @@ metadata:
   purpose: 'Orients an app or agent author: the two clients, the four identities and their server-side limits, recovery kinds, and the supported surface of this package version.'
   type: lifecycle
   library: '@multiagency/sdk'
-  library_version: '0.3.1'
+  library_version: '0.4.0'
 sources:
   - 'MultiAgency/platform:src/contract/index.ts'
   - 'MultiAgency/platform:src/contract/payee-entry.ts'
@@ -62,11 +62,12 @@ it may retry.
 
 ## What this package version supports
 
-`@multiagency/sdk` 0.3.1, entries:
+`@multiagency/sdk` 0.4.0, entries:
 - `@multiagency/sdk`: `ownerClient` with `OwnerResult`/`OwnerFailure`, `appClient` with `AppRouteResult` and the
   consent and setup texts (`consentMessage`, `setupMessage`), `ownerOutputs` and `OwnerInputs`/`OwnerOutput`
   per procedure, `ownerCapabilities` and `mayCall` (display only), gateway discovery (`gatewayDiscovery`,
-  `gatewayDenialScope`), schemas for runs (`RecordingSchema`) and proposals, `ASSETS` and account helpers. It also
+  `gatewayDenialScope`), schemas for runs (`RecordingSchema`), DAO proposals and Treasury proposals (`proposalView`,
+  `proposalText`; see treasury-app), `ASSETS` and account helpers. It also
   re-exports the payee entry. Peer: zod ^4.6.5. It bundles `@orpc/client` 2.0.0-beta.47 and loads no other oRPC
   package, so it runs beside a host that shares its own oRPC. It depends on `@ag-ui/core` 1.0.3.
 - `@multiagency/sdk/contract`: `ownerContract`, `ownerErrors` and `OwnerContract`, for an app implementing a server

package/skills/owner-workflows/SKILL.md

@@ -9,7 +9,7 @@ metadata:
   purpose: 'Owner reads, owner-signed actions and money streams with ownerClient, with recovery by result kind and retained identities.'
   type: core
   library: '@multiagency/sdk'
-  library_version: '0.3.1'
+  library_version: '0.4.0'
 requires:
   - getting-started
 sources:
@@ -120,6 +120,8 @@ export function machineClient(origin: string, agent: string, token: string) {
 Result: `await machineClient(origin, "treasury", token).call("overview")` answers like the browser client. A procedure
 outside the credential's scopes, or an expired or revoked credential, answers `forbidden` or `session`. Results, streams
 and recovery are the same as above: a lost `executePlan` or `sweep` is `unknown`, and nothing is sent again.
+`executePlan` runs only while the owner's live grant binds the saved strategy (`treasury:<suffix>`, signed once per
+saved strategy); otherwise it answers one `rejected` event naming the grant, and nothing is claimed.
 
 ## Recover an action that returned no identity
 

package/skills/payee-workflows/SKILL.md

@@ -9,7 +9,7 @@ metadata:
   purpose: 'Payee reports and their payment status with payeeClient, from a browser session or an agent connection, with recovery by kept identities.'
   type: core
   library: '@multiagency/sdk'
-  library_version: '0.3.1'
+  library_version: '0.4.0'
 requires:
   - getting-started
 sources:

package/skills/treasury-app/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: treasury-app
+description: >
+  Use when an app's server proposes Treasury swaps for an Organization's agent through @multiagency/sdk and has them
+  executed once the owner approves later: proposals by requestId, the exact text the owner signs, one execution per
+  proposal with recovery by state, and the two Treasury consent scopes. Server side only. Read app-server first.
+metadata:
+  purpose: 'Treasury proposals through an app: propose by requestId, the owner signs the exact terms, execute once, recover by state.'
+  type: core
+  library: '@multiagency/sdk'
+  library_version: '0.4.0'
+requires:
+  - getting-started
+  - app-server
+sources:
+  - 'MultiAgency/platform:src/contract/treasury-proposals.ts'
+  - 'MultiAgency/platform:src/contract/app-access.ts'
+  - 'MultiAgency/platform:src/proposals/service.ts'
+  - 'MultiAgency/platform:docs/enforcement.md'
+---
+
+# Treasury proposals from an app's server
+
+Read app-server first: the same credential, consent and result kinds apply. An agent runtime (your CLI, an assistant)
+calls your server, never the platform. A proposal is a list of swaps your app proposes now; the agent's owner approves
+its exact terms later (hours or days), by signing a text in their own wallet; then your server asks for its execution,
+which runs once, under the owner's signed policy. No production host serves this yet; build against the SDK
+repository's local stack.
+
+Two consent scopes, each named in the text the owner signs:
+- `treasury`: Treasury reads (`strategy/get`, `autopilot/get`, `autopilot/evidence`, `autopilot/log`, `treasury/get`),
+  strategy settings (`strategy/save`, which act only once the owner signs a grant binding them), `autopilot/enable` and
+  `autopilot/stop`, `sweep`, and every `proposals/*` procedure.
+- `treasury-execute`, only beside `treasury`: `rebalance`, `externalPlan` and `executePlan`, five-minute plans executed
+  within the policy without a signature per swap, and only while the owner's live grant binds the strategy they were
+  planned under. `sweep`, `rebalance` and `executePlan` are streams: read them with `app.agent(...).stream(path, input)`.
+
+## Propose, once per requestId
+
+Store the `requestId` (1–64 of `[A-Za-z0-9_-]`) and the request before calling. `legs` is your chosen swaps in raw units
+(at most 8; a `minAmountOut` you require is kept if it is above the quote's floor), or `"strategy"` for the legs a
+rebalance toward the owner's strategy picks now. `expiresAt` is at most 7 days ahead.
+
+```ts
+import { appClient, proposalText, type ProposalView } from "@multiagency/sdk";
+
+type Request = { requestId: string; legs: { from: string; to: string; amount: string; minAmountOut?: string }[] | "strategy"; expiresAt: string };
+type SignNep413 = (message: string, recipient: string, nonce: Uint8Array) => Promise<{ publicKey: string; signature: string }>;
+
+export async function propose(app: ReturnType<typeof appClient>, organization: string, agent: string, request: Request) {
+  const calls = app.agent(organization, agent);
+  const made = await calls.call("proposals/create", request);
+  if (made.ok || (made.kind !== "unknown" && made.kind !== "unavailable")) return made;
+  // The answer was lost: the same requestId and request answer the stored proposal and store nothing new.
+  return calls.call("proposals/create", request);
+}
+
+export async function approve(app: ReturnType<typeof appClient>, organization: string, agent: string, host: string,
+  proposal: ProposalView, sign: SignNep413) {
+  // The platform accepts only this exact text; show the owner this text, which their wallet shows as it signs.
+  const message = proposalText(proposal, "approve");
+  const nonce = crypto.getRandomValues(new Uint8Array(32));
+  const { publicKey, signature } = await sign(message, host, nonce);
+  return app.agent(organization, agent).call("proposals/approve", { id: proposal.id,
+    signed: { message, nonce: btoa(String.fromCharCode(...nonce)), publicKey, signature } });
+}
+```
+
+Result: `{ ok: true, value: proposal }` with `state` `proposed`, then `approved`. The text names each swap with its
+floor (the least it may return), the policy revision and strategy it was proposed under, the expiry and the
+proposal's sha256; the host is the NEP-413 recipient. Approving records the signature and sends nothing. Refusals carry
+`code`: `request_conflict` (another request under that `requestId`), `expiry_invalid`, `too_many_proposals`,
+`not_proposable` (a provider warning, an output the policy forbids, a floor above the quote, cost over the strategy's
+limit, or a balance short: the message says which), `signature_invalid`, `invalidated` (the policy, strategy or agent
+changed since: propose again), `not_open`, `expired`, `withdrawn` (made under a consent that has since ended). The owner
+rejects with `proposalText(proposal, "reject")` and `proposals/reject`; your app withdraws with `proposals/withdraw`.
+
+## Execute once, and follow it
+
+```ts
+import { appClient } from "@multiagency/sdk";
+
+export async function execute(app: ReturnType<typeof appClient>, organization: string, agent: string, id: string) {
+  const calls = app.agent(organization, agent);
+  const ran = await calls.call("proposals/execute", { id });
+  if (ran.ok || (ran.kind !== "unknown" && ran.kind !== "unavailable")) return ran;
+  // The answer was lost: read the proposal. Never propose the same swaps again because of a lost answer.
+  return calls.call("proposals/get", { id });
+}
+```
+
+Result: the proposal, `state`:
+- `executed`: every swap succeeded; `operations` lists them.
+- `stopped`: claimed, then a swap didn't succeed or was refused, or nothing was sent. It never runs again: propose the
+  rest anew.
+- `unknown`: a swap's outcome isn't proven. It blocks the agent's sends until resolved and is never resent: read later.
+- `executing`: running now; read later.
+- `invalidated`, `expired`, `rejected`, `withdrawn`: it ended without running.
+
+A refusal `not_executable` means the attempt was refused before anything was claimed (price below a signed floor, a
+provider warning, a short balance, no live treasury grant, the policy not in force): nothing was sent, the proposal
+stays `approved`, and asking again later is safe. `not_approved`: the owner hasn't approved it. Execution re-quotes
+every swap and sends each with a floor at least the signed one.
+
+## Common mistakes
+
+- **Building your own approval text** (CRITICAL): sign only `proposalText(proposal, "approve")` from the proposal the
+  platform returned; any other text is refused, and a summary of yours is not what the owner signs.
+- **A new requestId after `unknown`** (CRITICAL): the swaps may have run. Read `proposals/get`.
+- **Treating `stopped` as nothing sent** (HIGH): read `operations`; a swap may have succeeded before it stopped.
+- **Asking for `treasury-execute` when proposals suffice** (HIGH): it lets your app swap within the policy without a
+  signature per swap. Ask for it only when the owner wants unattended execution.
+
+## Completion
+
+Every proposal you created has a read state; none reads `unknown` or `executing` without a later `proposals/get`.
+Report anything you could not read; do not act again.