lez-programs/programs/amm/client

AMM client

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. It also converts exact human price ratios and token decimals into stored-order Q64.64 prices without floating point.
• sequencer decodes original getAccount response text directly into lossless AccountSnapshot values, preserving integer fields above 2^53.
• 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 canonical base58. Program IDs use exactly eight JSON u32 words; hexadecimal and byte layouts are host-adapter-only. 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. Only amm_client_plan accepts the five snapshot-bound prepare_*_transaction operations. The quote entrypoint also exposes account_snapshot_from_sequencer_response and human_price_ratio_to_q64_64 host adapters.