amm_client is the stateless host boundary for the AMM program. It reuses amm_program::quote for economic calculations, builds the actual amm_core::Instruction variants, derives protocol accounts through core PDA helpers, and encodes instructions with the RISC Zero Serde codec consumed by the guest.

The crate does not fetch accounts, manage keys, sign, or submit transactions. Those remain host adapter responsibilities.

Rust API

quote validates fetched config, pool, vault, token-definition, LP-definition, and user-holding snapshots before delegating calculations to amm_program::quote.
discovery derives config and complete pair read manifests, then classifies raw pair snapshots as missing or active without performing network I/O.
intent prepares canonical opening amounts and caller/stored order mappings with integer-only protocol math.
slippage converts validated quotes into integer-only instruction guards. Minimum guards round down, maximum guards round up, and checked overflow returns a typed error.
plan covers all ten guest instructions and returns the canonical instruction plus ordered account roles and writable, signer, and init flags.
transaction binds complete snapshots, canonical quotes, exact plans, caller amounts, wallet prerequisites, and a refreshable quote commitment for create/add/remove/swap tasks.
TransactionPlan::instruction_data serializes its amm_core::Instruction with risc0_zkvm::serde::to_vec.
wire exposes lossless JSON adapters for non-Rust hosts.

Planner coverage:

Guest instruction	Planner
`Initialize`	`plan_initialize`
`UpdateConfig`	`plan_update_config`
`CreatePriceObservations`	`plan_create_price_observations`
`CreateOraclePriceAccount`	`plan_create_oracle_price_account`
`NewDefinition`	`plan_create_pool`
`AddLiquidity`	`plan_add_liquidity`
`RemoveLiquidity`	`plan_remove_liquidity`
`SwapExactInput`	`plan_swap_exact_input`
`SwapExactOutput`	`plan_swap_exact_output`
`SyncReserves`	`plan_sync_reserves`

Quote coverage includes protocol constants, pair ordering, pool creation, preview and exact add/remove liquidity, preview and exact-input/output swaps, reserve synchronization, and oracle-price initialization. prepare_create_pool, prepare_add_liquidity, prepare_remove_liquidity, prepare_swap_exact_input, and prepare_swap_exact_output return a quote plus the exact amount fields to pass to the corresponding planner. Consumers choose a slippage tolerance in basis points but do not calculate chain guards. Prepared add-liquidity maxima preserve caller caps because substituting rounded actual deposits can change execution's proportional integer quote. The task-level transaction API validates funding against those caps.

Compatibility assumption

The client and deployed AMM are expected to be built from the corresponding source version. The client performs no runtime ImageID, release-version, or program allowlist check. The supplied AMM program ID is used for transaction targeting and canonical PDA derivation. Snapshot owner, account relationship, and PDA checks remain normal protocol validation.

C and JSON boundary

The built library exports:

char *amm_client_plan(const char *request_json);
char *amm_client_quote(const char *request_json);
void amm_client_free(char *value);

Every call returns an owned JSON envelope. Release it exactly once with amm_client_free; passing NULL to the free function is allowed. See include/amm_client.h and docs/wire-api.md for the complete transport contract.

Raw u128 and u64 values cross JSON as decimal strings. Account IDs use their canonical base58 display form, program IDs use eight JSON u32 words, account data uses hexadecimal, and encoded instruction words remain JSON u32 numbers. No JavaScript Number conversion is required for chain amounts or deadlines. Plan JSON also includes typed instructionArgs, derived directly from the same amm_core::Instruction encoded in instructionWords. Both C entrypoints accept the five snapshot-bound prepare_*_transaction operations.