[anitahhhh]

Summary

Two protocol-economics features across the three money-moving contracts, both
delivered as storage sidecars with appended DataKey tails and new
entrypoints, so no existing XDR shape changes:

• Add a refundable creation bond forfeited when a market is guardian-voided #23 — refundable creation bond. The creator posts bond on top of
  seed_amount in a single atomic transfer. It is refunded on normal
  resolution and on a NoFault void, and forfeited to the fee recipient when
  the guardian voids the market for cause. claim_bond(market_id) is
  permissionless once final so a keeper can drive it.
• Add integrator (frontend) fees on buy and sell with per-market caps #24 — integrator (frontend) fees. buy_via / sell_via /
  quote_buy_via / quote_sell_via charge an integrator cut bounded by a
  per-market cap snapshotted at creation, accrue it to
  DataKey::IntegratorFees(Address), and pay it out through
  claim_integrator_fees. buy / sell keep their exact prior behaviour as
  the zero-integrator path.

Branch is 11 commits on develop@f1900f4, head 1820f98. This PR was resumed from a
pushed-but-unopened branch; two defects in the inherited code were found and
fixed here (see Inherited code).

The model/fpmm_model.py mirror is the one part of this PR that ran on this
host and passed — see The one gate that executed. Nothing else did.

Closes #23
Closes #24

---

What changed, per contract

File	+/-	Contents
contracts/market-core/src/lib.rs	1502 / 6	bond config + sidecar, void_market_with_reason, claim_bond, integrator caps + accrual + claim, *_via entrypoints, 4 new errors/events, 33 tests
contracts/market-core/src/math.rs	196 / 12	calc_buy_with / calc_sell_with; calc_buy / calc_sell re-expressed as the zero-integrator calls, 6 tests
contracts/treasury/src/lib.rs	218 / 4	agent_create_market funds and caps the bond, 3 tests
contracts/resolver/src/lib.rs	281 / 1	guardian_void_market_v2, VoidReason mirror, name-dispatch void, GuardianVoided, 4 tests
docs/adr/0010-bond-and-fee-sidecars.md	185 / 0	new ADR
docs/architecture.md	35 / 0	global solvency invariant restated
docs/frontend-integration.md	87 / 0	how to pass an integrator; what to show at creation
model/fpmm_model.py	221 / 0	Python mirror of calc_buy_with / calc_sell_with + 6 checks

No *.wasm, no *.wasm.sha256, no packages/bindings file is touched
(git diff --name-only develop...HEAD | grep -c wasm → 0).

market-core

• DataKey::CreationBond (instance, default 0) and the per-market snapshot
  DataKey::Bond(u64) -> MarketBond { amount, state, void_reason, forfeit_to }.
  BondState { None, Held, Refunded, Forfeited }.
• create_market pulls seed_amount + creation_bond in one
  token.transfer (checked_add → Overflow), because treasury's nested-transfer
  pre-authorisation matches exactly one (from, to, amount) triple.
• void_market(market_id) keeps its pre-Add a refundable creation bond forfeited when a market is guardian-voided #23 semantics by delegating to
  void_inner(.., NoFault); void_market_with_reason(market_id, reason) is the
  new resolver-only entrypoint.
• claim_bond applies CEI: state flips to Refunded/Forfeited before the
  transfer, so a replay pays nothing; a second call is AlreadyClaimed (17).
  Forfeiture happens only on MarketStatus::Void && void_reason == GuardianFault.
  forfeit_to is snapshotted at void time (falling back to DataKey::Treasury)
  so a later propose_treasury/accept_treasury cannot redirect the forfeit between the void and the
  claim — the issue's edge-case recommendation.
• Legacy markets have no Bond entry: claim_bond → NoBond (28), and the
  solvency helper reads absent as 0. The upgrade is migration-free.
• set_max_integrator_fee_bps / get_max_integrator_fee_bps (global, default
  0) and the per-market snapshot DataKey::MarketMaxIntegratorFee(u64), with
  default_fee_bps + bps ≤ MAX_FEE_BPS enforced at the setter and per trade
  (validate_integrator_fee), because the market snapshot is authoritative.
• accrue_integrator_fee adds to IntegratorFees(integrator) and emits the new
  IntegratorFeeAccrued event rather than changing Trade's field list
  (indexers decode Trade).
• claim_integrator_fees requires the integrator's auth, removes the key
  before the transfer, and returns Ok(0) on an empty balance.

math.rs — rounding

Buy: both fees are mul_div_ceil, so net = collateral_in − fee − ifee never
exceeds the pool-credit and the trader (who opted into the integrator) eats the
rounding. Sell: gross is ceiled on the combined bps, then
ifee = mul_div_floor(total_fee, int_fee_bps, fee_bps + int_fee_bps) and
fee = total_fee − ifee, so the protocol's leg is never reduced below a
protocol-only computation. The zero-denominator case (fee_bps + int_fee_bps == 0)
returns ifee = 0 instead of dividing.

treasury

agent_create_market reads the bond through a new core_creation_bond name
dispatch, then uses total_outlay = seed_amount + bond for check_trade_size,
ensure_liquid, ensure_unreserved, authorize_token_pull and
reserve_capacity — a single combined authorisation, exactly the amount the
nested transfer pulls. The bond-aware check_trade_size is gated on bond > 0
so the existing agent_create_market_rejects_seed_above_trade_cap (which expects
SeedCapExceeded for seed 151 > max_trade 150) keeps its contract.
reserve_net / record_cost deliberately stay on seed_amount: the bond is not
position cost, and treating a refund as position profit would corrupt NAV.

resolver

guardian_void_market(market_id, reason, at_fault) is added as
guardian_void_market_v2, leaving v1's signature intact, and emits
GuardianVoided { market_id, at_fault }. It reaches market-core through
env.try_invoke_contract::<(), soroban_sdk::Error>(core, &Symbol::new(env, "void_market_with_reason"), args).

Why name dispatch instead of generated clients

Two hard walls, both recorded in docs/adr/0010-bond-and-fee-sidecars.md:

1. The vendored market_core.wasm blobs are pinned by .sha256 and verified at
   build time by resolver/build.rs and treasury/build.rs; a stale blob is a
   compile error, and rebuilding them requires stellar-cli 27.1.0 while this
   host has 22.0.0, plus a rustc newer than the 1.90.0 pinned by issue Replace vendored market_core.wasm with a deterministic build and hash-pinned import #58.
2. So a regenerated client is not available, and adding a positional parameter to
   an existing entrypoint would break the three decoders that still hold the old
   spec.

Name dispatch sidesteps both: it needs no client and no blob refresh. The
encoding it relies on is not assumed — #[contracttype] enums whose variants are
all unit with no explicit discriminants encode as ScVal::Symbol("Variant")
(soroban-sdk-macros-27.0.6/derive_enum.rs:370), and
void_reason_encodes_as_plain_symbol_name asserts it directly:

assert_eq!(
    VoidReason::GuardianFault.into_val(&env),
    Symbol::new(&env, "GuardianFault").into_val(&env)
);

The fail-closed direction is deliberate: core_void_with_reason returns
MarketCoreCallFailed (44) rather than silently degrading to a no-fault void, and
core_creation_bond treats a dispatch failure as 0 (the pre-#23 core genuinely
has no bond). Both behaviours are tested.

---

Acceptance criteria — #23

• set_creation_bond / get_creation_bond exist; setter is admin-gated with
  a wrong-caller test — wrong_caller_cannot_set_creation_bond.
• create_market pulls seed + bond atomically and records Bond(id)
  without changing the Market XDR — create_market_pulls_seed_plus_bond;
  Market is byte-for-byte unmodified (verified by reading the struct).
• void_market_with_reason exists and void_market keeps NoFault —
  bond_refunded_on_plain_void_keeps_no_fault_semantics,
  wrong_caller_cannot_void_with_reason.
• claim_bond handles every terminal path and cannot run twice —
  bond_refunded_on_resolution, bond_refunded_on_explicit_no_fault_void,
  bond_forfeited_on_guardian_fault_void, claim_bond_twice_fails,
  legacy_market_has_no_bond, claim_pool_remainder_does_not_touch_bond.
• The resolver guardian void passes the at-fault flag and emits
  GuardianVoided — guardian_void_v2_no_fault_keeps_plain_void_semantics,
  guardian_void_v2_at_fault_forwards_guardian_fault (native
  market-core), guardian_void_v2_shares_validation_and_auth,
  guardian_void_v2_at_fault_fails_closed_on_stale_wasm.
  Deviation: the issue proposed changing guardian_void_market's
  signature. That is a breaking change to a live entrypoint that three
  vendored decoders still hold, so the flag ships as a new v2 entrypoint
  instead, which is this repo's established pattern (buy → buy_v2).
• Treasury counts the bond toward caps and authorises the combined pull,
  with tests — agent_create_market_counts_bond_toward_caps,
  agent_create_market_rejects_seed_plus_bond_above_trade_cap,
  agent_create_market_funds_no_bond_against_pre_23_core.
  Not done: the optional treasury claim_bond wrapper. The market-core
  entrypoint is permissionless (the issue explicitly allows relying on it),
  so a wrapper would add an auth path with no capability.
• Multi-market solvency test including held bonds —
  global_solvency_includes_bonds_multi_market over
  test::assert_global_solvency, which sums
  sets_minted + fees_accrued + DataKey::LpFees(id) + held bonds + unclaimed integrator balances across 0..market_count().
• Vendored market_core.wasm, bindings and docs updated, make test /
  make lint pass — not met, and not achievable on this host. Docs are
  updated (architecture.md, frontend-integration.md, ADR 0010). The wasm
  blobs and generated bindings are deliberately absent; see Refusals and
  Zero execution. Consequence: against the currently vendored blob the
  resolver's at-fault path fails closed instead of voiding. The behaviour is
  correct and tested in both directions, but it is inert until a maintainer
  runs make build and re-pins the hashes.

Acceptance criteria — #24

• buy_via / sell_via / quote_buy_via / quote_sell_via exist and
  buy / sell behaviour is unchanged — buy and sell are thin
  delegations to do_buy / do_sell with None, and
  buy_via_with_zero_integrator_fee_matches_buy /
  sell_via_with_zero_integrator_fee_matches_sell pin the equivalence.
  "Bindings signatures unchanged" holds trivially because no bindings were
  regenerated.
• Integrator fees capped by a per-market snapshot; protocol + integrator
  never exceed MAX_FEE_BPS — buy_via_fee_at_exact_market_cap_is_accepted,
  combined_take_at_exact_max_fee_bps_is_accepted,
  sell_via_rejects_fee_above_market_cap,
  max_integrator_fee_snapshot_not_affected_by_admin_change.
  Deviation: the issue proposed appending max_integrator_fee_bps to
  Market. A new Market field changes the XDR that get_market returns
  and that the resolver's stale vendored decoders read, so the cap lives in
  the MarketMaxIntegratorFee(u64) sidecar with absent-means-zero, following
  the existing FeeTerms sidecar precedent. The semantics are identical;
  get_market_max_integrator_fee_bps is the accessor.
• claim_integrator_fees is integrator-authorised, zeroes before transfer,
  emits an event — claim_integrator_fees_pays_and_zeroes,
  wrong_caller_cannot_claim_integrator_fees,
  claim_integrator_fees_second_call_is_a_noop,
  integrator_fees_accumulate_across_markets.
• Property tests that the protocol fee is never reduced by rounding and that
  round trips never profit — calc_sell_with_split_never_shortchanges_protocol,
  round_trip_with_integrator_never_profits, and
  calc_buy_with_zero_integrator_matches_calc_buy over 2000 LCG iterations.
• [~] Python and TypeScript mirrors produce identical known values to Rust —
  Python half done and executed on this host (model/fpmm_model.py gains
  calc_buy_with / calc_sell_with, the Rust literals pinned in
  _check_integrator_known_values, and five sweeps driven by the same LCG
  stream math.rs uses, so the two languages cover identical inputs rather
  than independent random ones). python3 model/fpmm_model.py passes — the
  only real execution in this PR, see The one gate that executed.
  TypeScript not done (agents/core/fpmm.ts cannot be type-stripped by
  this host's Node). Also note what "identical" means here: the expected
  values are transcribed from the Rust source, not produced by a differential
  run, because Rust could not execute. scripts/fpmm-diff/ (oracle,
  diff.py dispatch table, vectors.jsonl) is not extended for the new
  functions either — see Refusals.
• A solvency test includes unclaimed integrator balances —
  solvency_includes_integrator_balances.
• docs/frontend-integration.md documents how to pass an integrator —
  new "Integrator (frontend) fees" and "Creation bond" sections, including
  the warning that min_shares_out must be derived from quote_buy_via, not
  quote_buy.
• make test and make lint pass — not run. See Zero execution.

---

Zero execution — read this before reviewing

No Rust in this PR was compiled, type-checked, clippy'd, or run. Not one Rust
test executed. The sole exception is the Python mirror (see The one gate that
executed). This is not an oversight; on this host it is impossible:

• cargo build / cargo test / cargo check cannot link: the vendored
  cross-contract .wasm blobs are hash-pinned by build.rs and the toolchain
  needed to rebuild them (stellar-cli 27.1.0, rustc ≥ 1.91 per soroban-sdk
  27.0.6's MSRV) is not installed — rust-toolchain.toml pins 1.90.0 per issue
  Replace vendored market_core.wasm with a deterministic build and hash-pinned import #58.
• make build, make test, make lint, make bindings all depend on that
  toolchain.
• Node here cannot strip TypeScript types, so agents/'s test runner cannot
  execute even the tests that already exist. (python3 does work, hence the
  mirror.)

So the 46 new #[test] functions in this PR are authored and statically
reviewed, never executed (the 6 new Python checks were run). They are written against helpers I read in full and
whose signatures I checked at the definition site, but their correctness is
argued, not demonstrated. Treat every test name below as an unverified claim
until a machine with the pinned toolchain runs:

cd oracledesk-stellar && make build && cargo test -p market-core && cargo test -p resolver && cargo test -p treasury

Three specific things I could not verify and would check first:

1. The two #[should_panic(expected = "Error(Contract, #27)")] expectations —
   the number is my reading of the enum, not compiler output. Every other new
   error assertion compares the named variant, so it cannot drift.
2. void_reason_encodes_as_plain_symbol_name — it asserts the
   derive_enum.rs:370 encoding I built the resolver dispatch on. If it fails,
   the resolver's at-fault path is wrong too, not just the test.
3. treasury's with_market_core(McImpl::Native, ..) usage in the two new
   bond-cap tests — the fixtures are shared with the #111/#112 lanes and I
   could not confirm the dual-registration helper's exact signature by compiling.

The one gate that executed

Python model/fpmm_model.py runs on this host, so the #24 mirror is verified,
not merely authored.

$ cd oracledesk-stellar && python3 model/fpmm_model.py
fpmm_model: all property checks passed      # exit 0

run_all() now includes the six new checks alongside the pre-existing ones, and
each was also invoked individually so a silent skip is impossible:

$ python3 -c '<import fpmm_model as m; ...>'
RAN-OK  _check_integrator_known_values
RAN-OK  _check_integrator_accounting_is_exact
RAN-OK  _check_calc_buy_with_zero_integrator_matches_calc_buy
RAN-OK  _check_calc_sell_with_zero_integrator_matches_calc_sell
RAN-OK  _check_sell_split_never_shortchanges_protocol
RAN-OK  _check_round_trip_with_integrator_never_profits
NEGATIVE-CONTROL-OK calc_buy_with(1000,1000,100,100,50).shares_out is 187 not 188
ITERATION-COUNT calc_buy zero-integrator equivalence held on 2000 distinct inputs

Two things that run proves and that review alone could not settle:

1. The rounding contract. calc_sell_with(10_000, 20_000, 1000, 100, 50) gives
   gross = 1016, total_fee = 16, ifee = floor(16*50/150) = 5, fee = 11 —
   matching the assert!(q_with.fee >= q_solo.fee) claim in
   calc_sell_with_split_never_shortchanges_protocol on 2000 shared LCG inputs.
2. _check_integrator_accounting_is_exact runs the identities the contract
   asserts on chain (collateral_in == net + fee + ifee,
   gross == collateral_out + fee + ifee) across the same domain, so the
   solvency formula in docs/architecture.md is checked rather than asserted.

This does not transfer to the Rust side. Python mirroring Rust's literals
only shows the two sources agree as written; cargo test -p market-core still
has to run the Rust copies of these five sweeps.

Gate differentials (before / after)

Two gates are available here. python3 model/fpmm_model.py genuinely executes,
and its result is in the first row below. cargo +stable fmt -p <crate> proves
rustfmt parses the file and nothing more — it is not a type check. Both are
reported as a differential against the same command at the merge base
f1900f4, never as "clean":

Gate	at base f1900f4	at HEAD	Delta
python3 model/fpmm_model.py (executes)	exit 0, pre-existing checks only	exit 0, +6 new checks, each also RAN-OK individually with a negative control	additions pass
cargo +stable fmt -p market-core -- --check	exit 0, 0 hunks	exit 0, 0 hunks	none
cargo +stable fmt -p resolver -- --check	exit 1, 13 hunks / 80 changed lines	exit 1, 13 hunks / 80 changed lines	none (see below)
cargo +stable fmt -p treasury -- --check	exit 1, 2 hunks / 27 changed lines	exit 1, 2 hunks / 27 changed lines	none (see below)
cargo build/test/check	unavailable	unavailable	no Rust gate exists on this host

The resolver and treasury non-zero exits are pre-existing on develop
and are not this PR's work; they belong to the code those branches' earlier
merges left unformatted. They are not merely equal in count: the flagged content
is byte-identical. Reproduce with (ANSI escapes stripped first — cargo colourises,
and a naive grep comparison silently returns zero lines and looks green):

strip='s/\e\[[0-9;]*[a-zA-Z]//g; s/\e\(B//g'
capture() { cargo +stable fmt -p "$1" -- --check 2>&1 | perl -pe "$strip" | grep '^[-+]' ; }
git worktree add /tmp/base f1900f4
for c in resolver treasury; do
  (cd /tmp/base/oracledesk-stellar && capture $c) > /tmp/${c}_base.txt
  (cd oracledesk-stellar                     && capture $c) > /tmp/${c}_head.txt
  diff /tmp/${c}_base.txt /tmp/${c}_head.txt   # empty
done
git worktree remove /tmp/base

My own additions did regress fmt twice, both found and fixed by hand rather
than by cargo fmt write-mode (which would have reformatted the 13 + 2
pre-existing hunks and inflated this PR's diff): five line-width hunks in
treasury, two in resolver.

Manual audit, since no compiler could do it: no duplicate Error discriminants
in market-core, no duplicate DataKey variant names, no todo! /
unimplemented!, balanced braces in all four edited .rs files, and
treasury::map_market_core_error's catch-all _ => arm means market-core's two
new variants cannot break treasury's exhaustive match.

Inherited code — two defects found and fixed

This branch was resumed from 210758c9f (pushed by an earlier lane that died
before opening a PR). Static review of inherited code caught two things that
would have failed at compile time — the exact class of bug a zero-execution
environment hides:

1. resolver: three new #23 tests had been appended inside mod golden, not
   mod test. mod golden's use super::* resolves against the crate root, so
   every fixture helper they call is out of scope: a compile error. Moved
   into mod test.
2. resolver: the at-fault success test asserted that a void happened through
   the default mc_impl(), which is McImpl::Wasm — the vendored blob that does
   not contain void_market_with_reason. It would have failed on a real
   toolchain. Wrapped in with_market_core(McImpl::Native, ..) (precedent:
   native_and_wasm_market_core_agree) and paired with
   guardian_void_v2_at_fault_fails_closed_on_stale_wasm, which asserts the
   wasm-mode behaviour is Err(MarketCoreCallFailed), status still Open, state
   still Disputed, and no GuardianVoided event published.

Tail collisions — expected, and the merge order matters

Two Error tails are extended, and both are already claimed by open sibling
PRs. Verified by reading each PR's patch, not guessed.

market-core ends at PendingAdminExpired = 26 on develop; this PR appends
IntegratorFeeTooHigh = 27 and NoBond = 28:

PR	also claims at market-core
#239	ModeRestricted = 27
#240	DirectoryEntryArchived = 27
#242	AlreadyHalted = 27, HaltTooOld = 28
#237	MigrationBatchTooLarge = 30

resolver gains MarketCoreCallFailed = 44; three PRs claim that number too:

PR	also claims at resolver
#241	QuorumNotReached = 44, FeedsDisagree = 45
#242	EventTimeMismatch = 44 … CoreUnavailable = 48

Duplicate discriminants are a hard compile error in Soroban (E0081), so
whichever merges last must re-append its variants one past whatever is then at
the tail. Blast radius of a renumber, measured rather than assumed: #27 appears
as a literal in exactly two #[should_panic(expected = "Error(Contract, #27)")]
expectations (lib.rs:4009, lib.rs:4361) and in one prose mention in
docs/frontend-integration.md. #28 and #44 need no chase at all — the tests
that depend on them compare against the named variant
(Err(Ok(Error::NoBond)), Err(Ok(Error::MarketCoreCallFailed))), so changing
the discriminant moves the number without touching an assertion. That is the
argument for keeping new tests off numeric literals, and these two variants are
the only ones here that use one. An in-code note at the collision point says so. The
same applies to the DataKey append point. Nothing in this PR can resolve the
ordering from here, and I have not "helpfully" renumbered to a gap that may be
filled by an earlier merge.

Refusals — what is deliberately not in this PR

• No .wasm and no .wasm.sha256. Regenerating them requires a toolchain
  this host does not have; committing a blob I cannot build from source is
  strictly worse than committing none, because the .sha256 pin would then
  attest to a binary nobody can reproduce. make build is the first step of
  merge, not of this PR.
• No packages/bindings. make bindings cannot run, and hand-editing
  generated files would produce a diff the generator contradicts.
• No agents/core/fpmm.ts mirror. The acceptance criterion is identical
  known values, which requires running Rust against the mirror and diffing. Rust
  cannot be run here, so a hand-transcribed mirror would be an unverifiable claim
  about arithmetic in the hottest money path in the repo — and this host's Node
  cannot even execute the TS tests that already exist. model/fpmm_model.py is
  the exception, not the rule: its port does execute (see The one gate that
  executed), which is why it was worth writing and the TS one is not.
  The remaining refusal, in order: (1) agents/core/fpmm.ts gains
  calcBuyWith / calcSellWith with collateralOutForShares taking an optional
  integratorFeeBps; (2) scripts/fpmm-diff/oracle (a cargo binary) exposes the
  two new functions, and diff.py's dispatch table gains calc_buy_with /
  calc_sell_with rows; (3) vectors.jsonl is regenerated by the differential
  run itself, so all three languages assert the same boundary inputs without
  anyone transcribing a literal.
• No neighbouring-issue fixes. Breakers, directories, quorum resolution and
  the migration schema are other lanes' tails.
• No reformatting of the pre-existing resolver / treasury fmt debt.
  It would bury the reviewable diff in noise.

Notes for whoever merges

1. Rebase first: develop moved from 5ede00a to f1900f4 during this work and
   this branch was rebased onto it (--force-with-lease, diff verified unchanged).
2. Resolve the Error / DataKey tail per Tail collisions.
3. make build, then re-pin the resolver and treasury blob hashes, then
   make bindings and check the committed bindings are not stale (CI enforces).
4. cargo build --manifest-path scripts/fpmm-diff/oracle/Cargo.toml --release
   then python3 scripts/fpmm-diff/diff.py --seed 1 --count 50000 is the real
   test of the Add integrator (frontend) fees on buy and sell with per-market caps #24 math: it runs Rust against the Python mirror already in this
   PR. Add the TS mirror after that passes, not before.
5. The resolver's GuardianVoided is a new event and guardian_void_market (v1)
   is unchanged, so backend sync scripts do not need a coordinated redeploy —
   but the bindings for buy_via/sell_via/claim_bond do need regenerating
   before any UI can call them.

[drips-wave]

@anitahhhh Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits