mirror of
https://github.com/logos-blockchain/lez-programs.git
synced 2026-08-25 14:11:09 +00:00
Ricardo Guilherme Schmidt
d8e2ae3d85
Remove the generic sequencer-response adapter and reuse the transaction order mapper. BREAKING CHANGE: account_snapshot_from_sequencer_response and its quote JSON operation are removed. Hosts must normalize RPC responses into canonical account snapshots before calling amm_client.
84 lines
4.4 KiB
Markdown
84 lines
4.4 KiB
Markdown
# 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.
|
|
- `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:
|
|
|
|
```c
|
|
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`](include/amm_client.h) and
|
|
[`docs/wire-api.md`](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 exposes
|
|
`human_price_ratio_to_q64_64`; hosts normalize RPC responses into canonical snapshots before
|
|
calling the client.
|