@perkos/agent-sdk 0.7.0 → 0.8.0-rc.1

package/CHANGELOG.md

@@ -4,6 +4,80 @@ All notable changes to `@perkos/agent-sdk` are documented here.
 
 ## Unreleased
 
+## 0.8.0-rc.1 — QA release candidate (not published)
+
+This candidate packages the QA additions below without changing the default v5/v4 contracts.
+Publication requires separate approval and must use the `next` tag, leaving `latest` at 0.7.1.
+See [candidate release notes](docs/RELEASE_0.8.0_RC1.md) for installation and validation gates.
+
+- Record the verified internal Hermes sBTC lifecycle and its public settlement evidence.
+  Separate published npm 0.7.1 from the reviewed QA artifact, conversation completion from
+  on-chain outcomes, and manifest hashes from versioned commitments. Preserve all release,
+  signing and production boundaries; no npm publication or default changes.
+
+- Return `null` for absent reputation-sync records on autonomous STX/sBTC contracts
+  (`u823`/`u923`), preserving earlier `u623`/`u723` handling. Keep unrelated contract
+  errors visible; add regression coverage and readable error descriptions. No changes
+  to signing, settlement, contract defaults or npm publication.
+
+- Allow 45 seconds for public QA evaluation admission (15 seconds for status reads)
+  to accommodate paced eligibility checks. Return sanitized, actionable quota,
+  eligibility and transport errors without automatic retries or budget changes.
+  Preserve deterministic-ID reconciliation after an ambiguous response.
+
+- Document wallet funding versus escrow, per-role QA budgets, six-burn custody confirmation,
+  job-bound provider handoff and ambiguous-operation recovery. Align README and buyer/provider
+  manuals without changing SDK runtime, production defaults or npm publication.
+
+- Start external onboarding with an already running agent and its own LLM; no PerkOS-LLM
+  account or model migration required. Add separate operator-owned wallet/signer preparation,
+  registration confirmation/read-back, role handoffs and release boundaries. Align the Hermes
+  examples and README; no wallet-generation tool, runtime behavior or npm release changes.
+
+- Add explicit provider-only QA MCP evaluation admission/status, bound to a custody-authorized
+  job and confirmed submission. Validate on-chain identity, budget and commitments; query the
+  deterministic evaluation ID before admission. Fixed public endpoint, bounded/sanitized replies,
+  no evaluator credentials, new signing, automatic retry, extra fee or x402 purchase. Off by default.
+
+- Add opt-in QA custody delegation: Linux signer service, immutable per-job/role permits, fixed gas and escrow caps, durable pre-sign reservation/pre-broadcast txid, nonce/chain guards and fail-closed replay/recovery. Signing stays off by default. No mainnet, npm publication, live Hermes validation or deployment is implied.
+- Add real Unix-socket/MCP protocol tests, offline fixture signing and actual SDK lifecycle planning against mocked testnet reads. Document the separate-UID isolation gate, fee consent and remaining evaluator/x402/video work.
+
+- Package a Node-only QA MCP stdio binary with six read/prepare tools per role, fixed testnet contracts, strict inputs and sanitized failures. No wallet, signing, broadcast or x402 capabilities are added to this adapter.
+- Add official MCP protocol/stdio tests and an honest candidate installation guide. Browser exports, published npm package and deployments remain unchanged.
+
+- Add QA commitment helpers for client criteria and provider evidence using existing contract fields.
+- Replace the old centralized lifecycle example with role-separated, journaled actions and appeal-aware finalization; offline preview remains default.
+- Document candidate-only onboarding, isolated custody, fee consent and deployment/E2E limitations; npm and deployment defaults are unchanged.
+
+- Add explicit opt-in STX v6/sBTC v5 earned-service-fee reads, initialization, waiver and treasury-funded refund methods. Published 0.7.1 and deployed defaults remain unchanged.
+- Require client/provider acceptance of gross budget, 200 bps, treasury and net rejection refund before candidate funding/submission; fail closed on inconsistent live state.
+- Preserve aggregate gross deny-mode settlement constraints and job-pinned sBTC tokens; account for treasury refunds in spending limits.
+- Add a signer-free fee inspection example, candidate integration guide, accounting/consent/role regression tests. No x402 second charge, contract deployment or npm publication is introduced.
+
+## 0.7.1 - 2026-09-02
+
+### Changed
+
+- Promote the source-verified `agentic-commerce-v5`, `sbtc-commerce-v4` and
+  `reputation-registry-v3` generation to the default mainnet and testnet deployment map.
+- Make autonomous decisions, role-specific appeals, human resolution and permissionless
+  finalization available without contract overrides.
+
+### Evidence
+
+- Record the exact-source mainnet deployments in blocks `8905872` and `8905874` and configuration
+  through block `8905886` with the fixed 12-block review and 144-block appeal policy.
+- Record controlled mainnet STX and canonical-sBTC appeal canaries passing 47/47 and 50/50 checks,
+  followed by an independent signer-free 75/75 public-state postcheck. These internal actors do
+  not count as external adoption, non-team wallets or revenue.
+
+### Security
+
+- Preserve v4/v3 and earlier generations only as explicit same-network historical overrides.
+- Keep the separately pinned appeal authority outside the SDK signer boundary; the SDK derives
+  settlement recipients from authoritative on-chain state and retains exact deny-mode outflow
+  post-conditions.
+
 ## 0.7.0 - 2026-09-01
 
 ### Added

package/README.md

@@ -9,21 +9,68 @@ This repository is the continuation of `PerkOS-xyz/PerkOS-Agent-SDK`, renamed to
 public SDK with the Nayori product identity. The npm package remains `@perkos/agent-sdk` and the
 complete Git history, releases, issues, and pull requests are preserved.
 
-> Status: 0.7.0 release candidate; 0.6.0 remains the current public npm release. Read clients,
+> Status: npm 0.7.1 uses Nayori's verified v5/v4 contracts as the
+> default integration. Read clients,
 > transaction builders, browser and headless signer
 > adapters, confirmation receipts, safety policies, and a transactional testnet quickstart are
 > implemented. The x402 v2 client and Stacks facilitator foundations are implemented, with
-> wallet-linked OAuth and MCP support for the invite-only testnet pilot. The hosted testnet rollout
-> is live; external review and independently attributable adoption evidence remain open. The direct x402
+> wallet-linked OAuth and MCP support for invite-only partners. QA uses Stacks testnet;
+> production uses mainnet. External review and independently attributable adoption evidence remain open. The direct x402
 > profile includes request-bound pure verification
 > and payer-side intent, policy, Leather, and remote-signer foundations for STX, sBTC, and USDCx.
 > The SDK also implements the MPP PaymentAuth `usdc`/`charge` Stacks profile for direct USDCx,
 > including canonical challenges, credentials, pure verification and settlement receipts.
 > Every payment signature remains delegated to the configured wallet or custody boundary. Mainnet
-> facilitator settlement remains disabled.
+> facilitator settlement is confirmation-gated and payer-approved; sponsorship remains disabled.
+
+## Connect an existing agent
+
+This source prepares **0.8.0-rc.1**, an unpublished QA candidate. Stable npm remains 0.7.1.
+See [candidate release notes and exact installation](docs/RELEASE_0.8.0_RC1.md).
+The candidate preserves default v5/v4 contracts; its Hermes signer pilot is testnet-only.
+
+Your agent is already installed and working with your own LLM. Keep that setup: Nayori does not
+require PerkOS-LLM, Hermes or sharing model credentials. Start with the
+[existing-agent onboarding guide](docs/EXISTING_AGENT.md): choose SDK/MCP → prepare your own
+wallet/signer separately → pin testnet and limits → register and verify the agent ID → create
+or fulfill work → verify settlement and reputation. Wallet creation is not registration, and
+OAuth access is not payment authority. The Hermes walkthrough is an unreleased QA example,
+not a prerequisite. One operator-supervised internal sBTC lifecycle has passed; this is not
+certification of external onboarding. See [validation and release boundaries](docs/VALIDATION_AND_RELEASE.md).
+
+Use the [QA checkpoints and confirmation guide](docs/HERMES_CHECKPOINTS.md) to distinguish
+wallet funding, registration, funded escrow, submitted work and final settlement. The custody
+pilot requires six subsequent Bitcoin burn blocks before advancing an operation; a txid or
+explorer success alone does not clear that gate. Preserve the journal rather than re-signing.
 
 ## Requirements
 
+### Unreleased Hermes MCP foundation
+
+The QA candidate includes the Node-only `nayori-mcp` stdio binary for public testnet
+reads and offline buyer/provider commitments. It has **no signer, broadcast, x402 purchase
+or wallet-generation tools by default**. Optional operator-configured delegation to the separate
+`nayori-custody` candidate enables bounded QA actions without putting a key in MCP. Neither
+candidate is published. The reviewed QA source passed one funded, operator-supervised Hermes
+buyer/provider lifecycle; npm-only installation, broader autonomy and x402 remain separate gates.
+Provider operators may additionally enable public QA evaluation admission for the permitted,
+confirmed submission; this does not enable x402 purchases or expose evaluator credentials. See
+[MCP setup](docs/HERMES_MCP.md) and [custody permissions, limits and release gates](docs/HERMES_CUSTODY.md).
+Role-specific recording/QA guides: [buyer](docs/HERMES_BUYER.md) and [provider](docs/HERMES_PROVIDER.md).
+Evaluation admission has a bounded 45-second timeout; status reads retain 15 seconds.
+Check evaluator capacity before submission and reconcile the existing evaluation ID after
+an error. Do not retry an expired review or increase spending limits automatically.
+
+### Unreleased earned-service-fee integration
+
+This branch adds opt-in STX v6/sBTC v5 support for a 2% **included**, evaluation-earned fee:
+net provider payout on approval or net client refund on evaluated rejection. The full budget
+stays in escrow until final settlement. The new methods are not in npm 0.7.1 and the candidate
+contracts are not deployed defaults. Existing jobs remain unchanged. See the
+[integration and accounting guide](docs/SERVICE_FEES.md) before enabling any signer.
+
+### Runtime
+
 - Node.js 20 or newer
 - npm 10 or newer
 
@@ -77,19 +124,20 @@ offline, contains no private key and does not request a wallet signature or broa
 npm run quickstart:mpp
 ```
 
-The transactional quickstart is also safe by default: it only prints a seven-step sBTC testnet
-lifecycle and its funding-policy decision.
+The candidate transactional quickstart is safe by default: it prints an offline, role-separated
+STX/sBTC testnet workflow with committed criteria, provider evidence and appeal-aware settlement.
 
 ```bash
 npm run quickstart:testnet
 ```
 
-Live testnet execution requires three distinct funded roles and the exact opt-in documented in
-[`examples/testnet.env.example`](examples/testnet.env.example). It confirms every transaction
-before moving to the next lifecycle step. The complete flow was verified on testnet with exact
-100-satoshi escrow, provider payout, cleared escrow, and reputation update; the
-[completion transaction](https://explorer.hiro.so/txid/0x5cf34295641a9291a2b6785d6db95a5c56b4d3b40d4281c86da194acd4c64248?chain=testnet)
-is publicly inspectable.
+Use the [role-separated QA guide](docs/TESTNET_QUICKSTART.md) and
+[`examples/testnet.env.example`](examples/testnet.env.example). Each process uses only its own
+client or provider signer; neither receives the evaluator key. One action runs per invocation.
+An external journal preserves txids and refuses automatic retries after ambiguous signing.
+The new bridge and quickstart are **unreleased QA candidates**, not a completed public Hermes
+integration or a new on-chain E2E result. Existing historical completion receipts concern an
+earlier workflow and do not verify these changes.
 
 ## Read on-chain state
 
@@ -141,7 +189,7 @@ more than the job requires.
 
 ## Active versioned escrow
 
-Version `0.7.0` selects Nayori's source-verified v4/v3/v3 generation by default on mainnet and
+Version `0.7.1` selects Nayori's source-verified v5/v4/v3 generation by default on mainnet and
 testnet. A normal client therefore needs no contract override:
 
 ```ts
@@ -155,33 +203,35 @@ const perkos = new PerkOSClient({
 const job = await perkos.getJob("sbtc", 7n);
 console.log(job?.submittedAtBurn, job?.reviewDeadline, job?.status);
 
-// After the on-chain Bitcoin review deadline, any signer may trigger the
-// exact provider payout. The plan remains deny-mode with exact escrow outflow.
-await perkos.settleReviewTimeout("sbtc", 7n);
+// The evaluator records an explainable decision without moving escrow.
+await perkos.recordDecision({
+  asset: "sbtc",
+  jobId: 7n,
+  decision: "approve",
+  evidenceHash: evidenceSha256,
+  explanationHash: explanationSha256,
+});
 
 const sync = await perkos.getReputationSync("sbtc", 7n);
 if (sync?.pending) await perkos.retryReputationSync("sbtc", 7n);
 ```
 
-The fixed 12-burn-block review window is readable through `getReviewWindow(asset)`.
-Evaluator completion/rejection is available through the exact deadline; timeout settlement is
-available only after it. Timeout payout is returned as the distinct `timeout-paid` (`u6`) status
-and must not be counted as a completed job or reputation success. A failed reputation write never
-rolls back economic settlement and can be retried permissionlessly.
+The fixed 12-burn-block review window is readable through `getReviewWindow(asset)`. A decision
+opens the appeal period: three burn blocks in isolated QA and 144 on mainnet. The affected client
+or provider may appeal, a separately pinned human authority may resolve, and permissionless
+finalizers preserve liveness after either deadline. A review timeout is returned as the distinct
+`timeout-paid` (`u6`) status and must not be counted as a completed job or reputation success. A
+failed reputation write never rolls back economic settlement and can be retried permissionlessly.
 
-## Autonomous evaluator candidate
+## Autonomous evaluation and appeals
 
-The SDK supports the source-reviewed `agentic-commerce-v5` and `sbtc-commerce-v4` candidate
-through explicit contract overrides. This does not change the active deployment defaults:
+The SDK uses the active source-reviewed `agentic-commerce-v5` and `sbtc-commerce-v4` deployment by
+default:
 
 ```ts
 const autonomous = new PerkOSClient({
-  network: "testnet",
+  network: "mainnet",
   signer,
-  contracts: {
-    stxCommerce: "ST...agentic-commerce-v5",
-    sbtcCommerce: "ST...sbtc-commerce-v4",
-  },
 });
 
 await autonomous.recordDecision({
@@ -213,8 +263,8 @@ pinned when the job was funded. Both the trait argument and exact fungible-token
 that historical token, so rotating the contract's future funding default cannot strand an existing
 escrow.
 
-The previous v3/v2 testnet generation remains supported through explicit overrides and immutable
-at 144 blocks. The active v4/v3/v3 generation first passed on Stacks testnet. Controlled STX and
+The previous v4/v3 and v3/v2 generations remain supported through explicit same-network overrides.
+The historical v4/v3/v3 generation first passed on Stacks testnet. Controlled STX and
 official PoX-5 sBTC complete paths pass 27/27 and 30/30. The real timeout path passes preparation
 20/20, settlement 12/12 and
 separate public-state verification 10/10. Job `u2` settled at burn `11290` in
@@ -223,11 +273,12 @@ ending in `timeout-paid` (`u6`) with zero escrow, one exact 1,000-atomic-unit sB
 completion, reputation or rating credit. The frozen evidence is documented in the
 [contracts/Web repository](https://github.com/PerkOS-xyz/PerkOS-Nayori/blob/main/docs/TESTNET_SECURITY_EVIDENCE.md).
 
-The same exact sources are live on mainnet under
-`SP2K7PV5NXBNRV510S6DCA6RFMTFHAF3ZPK6ZSXPH`. Deploy/configuration confirmed in blocks
-8885885–8885898. A guarded internal mainnet sBTC job then passed 26/26 checks for exactly 100
-atomic units, ending in `completed` (`u3`) with escrow zero, exact payout, synchronized reputation
-and persisted rating. Those actors are team-operated release evidence, not external adoption,
+The active v5/v4 sources are live on mainnet under
+`SP2K7PV5NXBNRV510S6DCA6RFMTFHAF3ZPK6ZSXPH`. Deployment confirmed in blocks `8905872` and
+`8905874`, with configuration through `8905886`. Guarded STX and canonical-sBTC appeal canaries
+passed 47/47 and 50/50 checks, followed by an independent 75/75 public-state postcheck. Both jobs
+settled exactly once with zero escrow and synchronized reputation. Those actors are team-operated
+release evidence, not external adoption,
 non-team wallet activity or revenue. The independent external security review remains open.
 
 ## Browser signer (Leather and other Stacks wallets)
@@ -583,8 +634,8 @@ or facilitator-submitted signed transaction.
 - OAuth client secrets and access tokens are application secrets. The SDK returns them to the
   caller but does not persist, log or refresh them automatically.
 
-The independent external security review remains open. Do not treat this release candidate as
-audited software.
+The independent external security review remains open. Do not treat this release as audited
+software.
 
 See [Architecture](docs/ARCHITECTURE.md), [x402 payments](docs/X402_PAYMENTS.md),
 [MPP payments](docs/MPP_PAYMENTS.md), [Partner pilot](docs/PARTNER_PILOT.md) and
@@ -593,12 +644,15 @@ responsible disclosure process.
 
 ## QA promotion
 
-`main` is the canonical integration branch. The `Promote exact main commit to QA` workflow accepts
-only a full commit SHA already contained in `main`, requires a fast-forward from the current `qa`
-branch, reruns verification, package inspection and dependency audit, and then pushes that exact
-SHA without force. The protected branch must grant bypass only to the official GitHub Actions app
-before the first promotion; administrator enforcement must remain enabled. QA consumes an exact
-commit or tarball and never publishes npm as a side effect.
+New integration work is reviewed in pull requests targeting `qa`; promotion to `main` is a
+separate reviewed release after QA verification. QA consumes an exact commit or tarball and
+never publishes npm as a side effect. Operator deployments are initiated from the approved Mac,
+with image builds on the VPS; do not assume GitHub-hosted runners can reach that server.
+
+The repository also retains the historical `Promote exact main commit to QA` workflow. It accepts
+only a full SHA already in `main` and a fast-forward from `qa`. It is not the forward path for
+new QA-only changes: do not force or rewind branches to make it run. Branch protection and
+restricted GitHub Actions bypass remain required where that legacy workflow is used.
 
 ## Development
 

package/dist/builders.d.ts

@@ -1,4 +1,4 @@
-import type { AppealDecisionInput, AssignProviderInput, ContractCallPlan, CreateJobInput, DecisionSettlementInput, FundJobInput, JobAmountInput, PaymentAsset, RateProviderInput, RecordDecisionInput, RegisterAgentInput, ResolvedPerkOSConfig, ResolveAppealPlanInput, SettleJobInput, SubmitWorkInput, UpdateAgentInput } from "./types.js";
+import type { AppealDecisionInput, AssignProviderInput, ContractCallPlan, CreateJobInput, DecisionSettlementInput, FundJobInput, InitializeServiceFeeProtocolInput, RefundServiceFeePlanInput, WaiveServiceFeePlanInput, JobAmountInput, PaymentAsset, RateProviderInput, RecordDecisionInput, RegisterAgentInput, ResolvedPerkOSConfig, ResolveAppealPlanInput, SettleJobInput, SubmitWorkInput, UpdateAgentInput } from "./types.js";
 export declare class PerkOSTransactionBuilder {
     readonly config: ResolvedPerkOSConfig;
     constructor(config: ResolvedPerkOSConfig);
@@ -21,6 +21,10 @@ export declare class PerkOSTransactionBuilder {
     settleAppealTimeout(input: DecisionSettlementInput): ContractCallPlan;
     retryReputationSync(asset: PaymentAsset, jobIdInput: bigint | number | string): ContractCallPlan;
     rateProvider(input: RateProviderInput): ContractCallPlan;
+    initializeServiceFeeProtocol(input: InitializeServiceFeeProtocolInput): ContractCallPlan;
+    waiveServiceFee(input: WaiveServiceFeePlanInput): ContractCallPlan;
+    refundServiceFee(input: RefundServiceFeePlanInput): ContractCallPlan;
+    private requireServiceFees;
     private decisionSettlement;
     private settlement;
 }

package/dist/builders.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"builders.d.ts","sourceRoot":"","sources":["../src/builders.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,mBAAmB,EACnB,mBAAmB,EACnB,gBAAgB,EAEhB,cAAc,EACd,uBAAuB,EACvB,YAAY,EACZ,cAAc,EAEd,YAAY,EACZ,iBAAiB,EACjB,mBAAmB,EACnB,kBAAkB,EAClB,oBAAoB,EACpB,sBAAsB,EACtB,cAAc,EACd,eAAe,EACf,gBAAgB,EACjB,MAAM,YAAY,CAAC;AAuFpB,qBAAa,wBAAwB;IACnC,QAAQ,CAAC,MAAM,EAAE,oBAAoB,CAAC;gBAE1B,MAAM,EAAE,oBAAoB;IAIxC,aAAa,CAAC,KAAK,EAAE,kBAAkB,GAAG,gBAAgB;IA8B1D,WAAW,CAAC,KAAK,EAAE,gBAAgB,GAAG,gBAAgB;IAuBtD,eAAe,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,gBAAgB;IAWzE,SAAS,CAAC,KAAK,EAAE,cAAc,GAAG,gBAAgB;IAsBlD,SAAS,CAAC,KAAK,EAAE,cAAc,GAAG,gBAAgB;IAYlD,OAAO,CAAC,KAAK,EAAE,YAAY,GAAG,gBAAgB;IA2B9C,cAAc,CAAC,KAAK,EAAE,mBAAmB,GAAG,gBAAgB;IAiB5D,UAAU,CAAC,KAAK,EAAE,eAAe,GAAG,gBAAgB;IAWpD,WAAW,CAAC,KAAK,EAAE,cAAc,GAAG,gBAAgB;IAIpD,SAAS,CAAC,KAAK,EAAE,cAAc,GAAG,gBAAgB;IAIlD,SAAS,CAAC,KAAK,EAAE,cAAc,GAAG,gBAAgB;IAIlD,mBAAmB,CAAC,KAAK,EAAE,cAAc,GAAG,gBAAgB;IAI5D,cAAc,CAAC,KAAK,EAAE,mBAAmB,GAAG,gBAAgB;IAgB5D,cAAc,CAAC,KAAK,EAAE,mBAAmB,GAAG,gBAAgB;IAc5D,gBAAgB,CAAC,KAAK,EAAE,uBAAuB,GAAG,gBAAgB;IAMlE,aAAa,CAAC,KAAK,EAAE,sBAAsB,GAAG,gBAAgB;IAQ9D,mBAAmB,CAAC,KAAK,EAAE,uBAAuB,GAAG,gBAAgB;IAMrE,mBAAmB,CACjB,KAAK,EAAE,YAAY,EACnB,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,GACnC,gBAAgB;IAWnB,YAAY,CAAC,KAAK,EAAE,iBAAiB,GAAG,gBAAgB;IAgBxD,OAAO,CAAC,kBAAkB;IAkC1B,OAAO,CAAC,UAAU;CAoCnB"}
+{"version":3,"file":"builders.d.ts","sourceRoot":"","sources":["../src/builders.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EACV,mBAAmB,EACnB,mBAAmB,EACnB,gBAAgB,EAEhB,cAAc,EACd,uBAAuB,EACvB,YAAY,EACZ,iCAAiC,EACjC,yBAAyB,EACzB,wBAAwB,EACxB,cAAc,EAEd,YAAY,EACZ,iBAAiB,EACjB,mBAAmB,EACnB,kBAAkB,EAClB,oBAAoB,EACpB,sBAAsB,EACtB,cAAc,EACd,eAAe,EACf,gBAAgB,EACjB,MAAM,YAAY,CAAC;AAiGpB,qBAAa,wBAAwB;IACnC,QAAQ,CAAC,MAAM,EAAE,oBAAoB,CAAC;gBAE1B,MAAM,EAAE,oBAAoB;IAIxC,aAAa,CAAC,KAAK,EAAE,kBAAkB,GAAG,gBAAgB;IAiC1D,WAAW,CAAC,KAAK,EAAE,gBAAgB,GAAG,gBAAgB;IA4BtD,eAAe,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,gBAAgB;IAWzE,SAAS,CAAC,KAAK,EAAE,cAAc,GAAG,gBAAgB;IA0BlD,SAAS,CAAC,KAAK,EAAE,cAAc,GAAG,gBAAgB;IAYlD,OAAO,CAAC,KAAK,EAAE,YAAY,GAAG,gBAAgB;IAkE9C,cAAc,CAAC,KAAK,EAAE,mBAAmB,GAAG,gBAAgB;IAiB5D,UAAU,CAAC,KAAK,EAAE,eAAe,GAAG,gBAAgB;IAsDpD,WAAW,CAAC,KAAK,EAAE,cAAc,GAAG,gBAAgB;IAIpD,SAAS,CAAC,KAAK,EAAE,cAAc,GAAG,gBAAgB;IAIlD,SAAS,CAAC,KAAK,EAAE,cAAc,GAAG,gBAAgB;IAIlD,mBAAmB,CAAC,KAAK,EAAE,cAAc,GAAG,gBAAgB;IAI5D,cAAc,CAAC,KAAK,EAAE,mBAAmB,GAAG,gBAAgB;IAgB5D,cAAc,CAAC,KAAK,EAAE,mBAAmB,GAAG,gBAAgB;IAW5D,gBAAgB,CAAC,KAAK,EAAE,uBAAuB,GAAG,gBAAgB;IAMlE,aAAa,CAAC,KAAK,EAAE,sBAAsB,GAAG,gBAAgB;IAQ9D,mBAAmB,CAAC,KAAK,EAAE,uBAAuB,GAAG,gBAAgB;IAMrE,mBAAmB,CACjB,KAAK,EAAE,YAAY,EACnB,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,GACnC,gBAAgB;IAWnB,YAAY,CAAC,KAAK,EAAE,iBAAiB,GAAG,gBAAgB;IAgBxD,4BAA4B,CAC1B,KAAK,EAAE,iCAAiC,GACvC,gBAAgB;IAsCnB,eAAe,CAAC,KAAK,EAAE,wBAAwB,GAAG,gBAAgB;IAkBlE,gBAAgB,CAAC,KAAK,EAAE,yBAAyB,GAAG,gBAAgB;IAyCpE,OAAO,CAAC,kBAAkB;IAU1B,OAAO,CAAC,kBAAkB;IA0D1B,OAAO,CAAC,UAAU;CA6CnB"}

package/dist/builders.js

@@ -1,8 +1,11 @@
 import { Cl, Pc } from "@stacks/transactions";
 import { PerkOSError } from "./errors.js";
+import { quoteServiceFee, supportsServiceFees, validateServiceFeeSplit, } from "./service-fees.js";
 import { assertAscii, assertPrincipal, parseContractId, toHash32, toUint, } from "./validation.js";
 function commerceContract(config, asset) {
-    return asset === "sbtc" ? config.contracts.sbtcCommerce : config.contracts.stxCommerce;
+    return asset === "sbtc"
+        ? config.contracts.sbtcCommerce
+        : config.contracts.stxCommerce;
 }
 function plan(config, contract, functionName, functionArgs, intent, postConditions = []) {
     return {
@@ -21,7 +24,9 @@ function tokenArg(config, tokenContract = config.contracts.sbtcToken) {
     return Cl.contractPrincipal(token.address, token.name);
 }
 function escrowArgs(config, asset, baseArgs, sbtcToken) {
-    return asset === "sbtc" ? [...baseArgs, tokenArg(config, sbtcToken)] : baseArgs;
+    return asset === "sbtc"
+        ? [...baseArgs, tokenArg(config, sbtcToken)]
+        : baseArgs;
 }
 function exactTransfer(config, asset, sender, amount, sbtcToken) {
     if (asset === "stx") {
@@ -85,11 +90,15 @@ export class PerkOSTransactionBuilder {
         }
         return plan(this.config, this.config.contracts.agentRegistry, "update-agent", [
             Cl.uint(agentId),
-            input.name === undefined ? Cl.none() : Cl.some(Cl.stringAscii(input.name)),
+            input.name === undefined
+                ? Cl.none()
+                : Cl.some(Cl.stringAscii(input.name)),
             input.description === undefined
                 ? Cl.none()
                 : Cl.some(Cl.stringAscii(input.description)),
-            input.wallet === undefined ? Cl.none() : Cl.some(Cl.principal(input.wallet)),
+            input.wallet === undefined
+                ? Cl.none()
+                : Cl.some(Cl.principal(input.wallet)),
         ], { operation: "update-agent" });
     }
     deactivateAgent(agentIdInput) {
@@ -125,12 +134,40 @@ export class PerkOSTransactionBuilder {
         }
         assertPrincipal(input.sender, "sender", this.config.network);
         const contract = commerceContract(this.config, input.asset);
+        if (supportsServiceFees(contract, input.asset)) {
+            const acceptance = input.serviceFeeAcceptance;
+            if (!acceptance ||
+                acceptance.gross !== amount ||
+                acceptance.basisPoints !== 200 ||
+                acceptance.rejectionRefund !== "net-after-evaluation") {
+                throw new PerkOSError("INPUT_INVALID", "Explicit 2% earned-fee acceptance, including net rejection refund, is required.");
+            }
+            validateServiceFeeSplit({
+                ...quoteServiceFee(amount),
+                treasury: acceptance.treasury,
+                waived: false,
+            }, amount, this.config.network);
+            if (acceptance.treasury === input.sender)
+                throw new PerkOSError("INPUT_INVALID", "Treasury cannot fund a job.");
+        }
+        else if (input.serviceFeeAcceptance) {
+            throw new PerkOSError("INPUT_INVALID", "This contract generation has no earned service fee.");
+        }
         return plan(this.config, contract, "fund-job", escrowArgs(this.config, input.asset, [Cl.uint(jobId)]), {
             operation: "fund-job",
             asset: input.asset,
             amount,
             jobId,
             sender: input.sender,
+            ...(input.serviceFeeAcceptance
+                ? {
+                    serviceFee: {
+                        ...quoteServiceFee(amount),
+                        treasury: input.serviceFeeAcceptance.treasury,
+                        waived: false,
+                    },
+                }
+                : {}),
         }, [exactTransfer(this.config, input.asset, input.sender, amount)]);
     }
     assignProvider(input) {
@@ -145,7 +182,36 @@ export class PerkOSTransactionBuilder {
     }
     submitWork(input) {
         const jobId = toUint(input.jobId, "jobId");
-        return plan(this.config, commerceContract(this.config, input.asset), "submit-work", [Cl.uint(jobId), Cl.buffer(deliverableBuffer(input.deliverable))], { operation: "submit-work", asset: input.asset, jobId });
+        const acceptance = input.serviceFeeAcceptance;
+        const feeContract = supportsServiceFees(commerceContract(this.config, input.asset), input.asset);
+        if (feeContract) {
+            if (!acceptance ||
+                acceptance.gross <= 0n ||
+                acceptance.basisPoints !== 200 ||
+                acceptance.rejectionRefund !== "net-after-evaluation")
+                throw new PerkOSError("INPUT_INVALID", "Provider must accept the gross budget and earned fee before submission.");
+            validateServiceFeeSplit({
+                ...quoteServiceFee(acceptance.gross),
+                treasury: acceptance.treasury,
+                waived: false,
+            }, acceptance.gross, this.config.network);
+        }
+        else if (acceptance)
+            throw new PerkOSError("INPUT_INVALID", "Unexpected service fee acceptance for this generation.");
+        return plan(this.config, commerceContract(this.config, input.asset), "submit-work", [Cl.uint(jobId), Cl.buffer(deliverableBuffer(input.deliverable))], {
+            operation: "submit-work",
+            asset: input.asset,
+            jobId,
+            ...(acceptance
+                ? {
+                    serviceFee: {
+                        ...quoteServiceFee(acceptance.gross),
+                        treasury: acceptance.treasury,
+                        waived: false,
+                    },
+                }
+                : {}),
+        });
     }
     completeJob(input) {
         return this.settlement("complete-job", input);
@@ -170,10 +236,7 @@ export class PerkOSTransactionBuilder {
     }
     appealDecision(input) {
         const jobId = toUint(input.jobId, "jobId");
-        return plan(this.config, commerceContract(this.config, input.asset), "appeal-decision", [
-            Cl.uint(jobId),
-            Cl.buffer(toHash32(input.evidenceHash, "evidenceHash")),
-        ], { operation: "appeal-decision", asset: input.asset, jobId });
+        return plan(this.config, commerceContract(this.config, input.asset), "appeal-decision", [Cl.uint(jobId), Cl.buffer(toHash32(input.evidenceHash, "evidenceHash"))], { operation: "appeal-decision", asset: input.asset, jobId });
     }
     finalizeDecision(input) {
         return this.decisionSettlement("finalize-decision", input, [
@@ -205,13 +268,89 @@ export class PerkOSTransactionBuilder {
         assertAscii(input.comment, "comment", 256, true);
         return plan(this.config, commerceContract(this.config, input.asset), "rate-provider", [Cl.uint(jobId), Cl.uint(score), Cl.stringAscii(input.comment)], { operation: "rate-provider", asset: input.asset, jobId });
     }
+    initializeServiceFeeProtocol(input) {
+        const contract = this.requireServiceFees(input.asset);
+        const appealWindow = toUint(input.appealWindow, "appealWindow");
+        const expectedWindow = this.config.network === "mainnet" ? 144n : 3n;
+        for (const [field, value] of Object.entries({
+            owner: input.owner,
+            treasury: input.treasury,
+            appealAuthority: input.appealAuthority,
+        })) {
+            assertPrincipal(value, field, this.config.network);
+        }
+        if (appealWindow !== expectedWindow ||
+            input.treasury === input.owner ||
+            input.treasury === input.appealAuthority) {
+            throw new PerkOSError("INPUT_INVALID", "Initialization requires a separate treasury and the network-specific appeal window (testnet 3, mainnet 144).");
+        }
+        return plan(this.config, contract, "initialize-protocol", [
+            Cl.uint(appealWindow),
+            Cl.principal(input.appealAuthority),
+            Cl.principal(input.treasury),
+        ], {
+            operation: "initialize-protocol",
+            asset: input.asset,
+            sender: input.owner,
+        });
+    }
+    waiveServiceFee(input) {
+        const contract = this.requireServiceFees(input.asset);
+        const jobId = toUint(input.jobId, "jobId");
+        assertPrincipal(input.authority, "authority", this.config.network);
+        return plan(this.config, contract, "waive-service-fee", [Cl.uint(jobId), Cl.buffer(toHash32(input.evidenceHash, "evidenceHash"))], {
+            operation: "waive-service-fee",
+            asset: input.asset,
+            jobId,
+            sender: input.authority,
+        });
+    }
+    refundServiceFee(input) {
+        const contract = this.requireServiceFees(input.asset);
+        const jobId = toUint(input.jobId, "jobId");
+        const amount = toUint(input.amount, "amount");
+        assertPrincipal(input.treasury, "treasury", this.config.network);
+        assertPrincipal(input.recipient, "recipient", this.config.network);
+        if (input.treasury === input.recipient)
+            throw new PerkOSError("INPUT_INVALID", "Refund recipient cannot be treasury.");
+        if (input.asset === "sbtc" && !input.sbtcToken)
+            throw new PerkOSError("INPUT_INVALID", "Refund requires the job-pinned sBTC token.");
+        return plan(this.config, contract, "refund-service-fee", escrowArgs(this.config, input.asset, [Cl.uint(jobId)], input.sbtcToken), {
+            operation: "refund-service-fee",
+            asset: input.asset,
+            jobId,
+            amount,
+            sender: input.treasury,
+            recipient: input.recipient,
+        }, [
+            exactTransfer(this.config, input.asset, input.treasury, amount, input.sbtcToken),
+        ]);
+    }
+    requireServiceFees(asset) {
+        const contract = commerceContract(this.config, asset);
+        if (!supportsServiceFees(contract, asset))
+            throw new PerkOSError("INPUT_INVALID", "Operation requires STX v6 or sBTC v5 explicitly configured.");
+        return contract;
+    }
     decisionSettlement(operation, input, functionArgs) {
         const jobId = toUint(input.jobId, "jobId");
         const amount = toUint(input.amount, "amount", true);
         assertPrincipal(input.recipient, "recipient", this.config.network);
         const contract = commerceContract(this.config, input.asset);
+        if (supportsServiceFees(contract, input.asset)) {
+            if (!input.serviceFee || amount === 0n)
+                throw new PerkOSError("INPUT_INVALID", "Fee settlement requires a verified split and positive gross escrow.");
+            validateServiceFeeSplit(input.serviceFee, amount, this.config.network);
+            if (input.serviceFee.treasury === input.recipient)
+                throw new PerkOSError("INPUT_INVALID", "Economic recipient cannot be treasury.");
+            if (input.asset === "sbtc" && !input.sbtcToken)
+                throw new PerkOSError("INPUT_INVALID", "Settlement requires the job-pinned sBTC token.");
+        }
+        else if (input.serviceFee) {
+            throw new PerkOSError("INPUT_INVALID", "Unexpected fee metadata for a no-fee contract.");
+        }
         const sbtcToken = input.asset === "sbtc"
-            ? input.sbtcToken ?? this.config.contracts.sbtcToken
+            ? (input.sbtcToken ?? this.config.contracts.sbtcToken)
             : undefined;
         if (sbtcToken)
             parseContractId(sbtcToken, "sbtcToken", this.config.network);
@@ -224,6 +363,7 @@ export class PerkOSTransactionBuilder {
             amount,
             jobId,
             recipient: input.recipient,
+            ...(input.serviceFee ? { serviceFee: input.serviceFee } : {}),
         }, postConditions);
     }
     settlement(operation, input) {
@@ -231,8 +371,12 @@ export class PerkOSTransactionBuilder {
         const amount = toUint(input.amount, "amount", true);
         assertPrincipal(input.recipient, "recipient", this.config.network);
         const contract = commerceContract(this.config, input.asset);
+        if (supportsServiceFees(contract, input.asset) &&
+            (operation === "complete-job" || operation === "reject-job")) {
+            throw new PerkOSError("INPUT_INVALID", "Use recordDecision and the autonomous decision settlement flow for this generation.");
+        }
         const sbtcToken = input.asset === "sbtc"
-            ? input.sbtcToken ?? this.config.contracts.sbtcToken
+            ? (input.sbtcToken ?? this.config.contracts.sbtcToken)
             : undefined;
         if (sbtcToken)
             parseContractId(sbtcToken, "sbtcToken", this.config.network);