feat(amm-client): add lossless host adapters

This commit is contained in:
Ricardo Guilherme Schmidt
2026-08-10 11:22:44 -03:00
parent 9d356cfa31
commit ae0bb310b0
9 changed files with 494 additions and 18 deletions
+19 -1
View File
@@ -159,6 +159,8 @@ shown in this table and the sections below.
| `operation` | Additional fields |
|---|---|
| `protocol_constants` | none; returns decimal-string `minimumLiquidity`, `feeBpsDenominator`, `slippageBpsDenominator`, and `supportedFeeTiers` |
| `account_snapshot_from_sequencer_response` | canonical base58 `accountId`, original `getAccount` response text in `response` |
| `human_price_ratio_to_q64_64` | caller-ordered token IDs, `firstAmount`, `secondAmount`, and decimal-string `firstTokenDecimals`/`secondTokenDecimals` |
| `derive_config_id` | `ammProgramId` |
| `inspect_config` | `ammProgramId`, raw `config` snapshot |
| `canonical_pair` | `firstTokenDefinitionId`, `secondTokenDefinitionId` |
@@ -200,6 +202,20 @@ Quote values use these result shapes:
A `pool` result contains decimal-string `liquidityPoolSupply`, `reserveA`, `reserveB`, and
`spotPriceQ64_64` fields.
## Host adapters
`account_snapshot_from_sequencer_response` accepts the original JSON-RPC response as a JSON string,
not a host-parsed object. It decodes sequencer numeric literals directly as Rust `u128` values and
returns the standard snapshot fields: `id`, `programOwner`, `balance`, `nonce`, and `data`. This
preserves balances and nonces above `2^53`. Do not route the response through a JavaScript or QML
numeric value first.
`human_price_ratio_to_q64_64` declares that `firstAmount` human units of the first token equal
`secondAmount` human units of the second token. Amounts are unsigned decimal text and may contain
up to 38 fractional digits. Token decimals are accepted from `0` through `38`. The adapter derives
stored token A/B order from the token IDs, applies unequal token decimals, floors once, and returns
decimal-string `priceQ64_64`. Callers keep display order; reversed pairs must not invert locally.
## Discovery, inspection, and opening intents
Discovery functions derive IDs only; adapters fetch the returned accounts and submit raw
@@ -315,7 +331,9 @@ Every failure uses `{ "code": "...", "message": "..." }`. `code` is the stable
machine-readable contract; `message` is diagnostic text. JSON adapter failures return
`invalid_request` or `unsupported_schema`. The C envelope additionally returns `null_request`,
`invalid_utf8`, `invalid_json`, `response_serialization_failed`, or `response_contains_nul` for
boundary failures.
boundary failures. Sequencer adapters return `invalid_sequencer_response`,
`sequencer_account_error`, `sequencer_account_missing`, or `account_data_too_large`. Human-price
conversion uses the stable `IntentError` codes documented by the Rust API.
No request performs network I/O or checks an ImageID, release version, compatibility manifest, or
program allowlist. Deployment configuration is expected to select the corresponding AMM build.