0001 XAS-1d — Interface for AMM Hooks

[RichardAH]

XAS-1d — Interface for AMM Hooks

Introduction

Automated market makers on Xahau are implemented as liquidity pool Hooks, in a similar fashion to many other chains. While the actual mathematical operation of each Hook may differ there should be a standard interface for users to interact with such Hooks. That interface is defined in this standard.

Remit Interface

All movement of funds in an out of the liquidity pool, including use of the liquidity pool for exchanges, occurs via ttREMIT, according to the table below, and is inferred by the sending of 0, 1 or 2 currencies to the Hook.

Action	Currencies Sent	Explanation
Setup	A and B	After the Hook is installed it must be setup. To do this anyone can send two currencies. The ratio sets the exchange rate.
Deposit	A and B	If the Hook is already setup then adding liquidity occurs by sending A and B in the correct ratio. Liquidity Pool tokens may either be returned by the Hook remitting them to you, or recorded internally in the Hook state under the owner's account ID as a state key.
Exchange	A or B	The Hook performs an exchange operation according to its internal mathematical logic and remits back the other currency. The Hook may reject if the user does not have a trustline for the currency.
Withdrawal	no currencies or LP tokens	If the Hook records LP tokens in Hook state only then withdrawal is by sending a blank Remit In this scenario the withdrawal is always 100% of the owned LP tokens. If the Hook has issued LP tokens as an issued currency on the ledger, then withdrawal is by sending some number of LP tokens to the Hook. The Hook will then Remit the portion of A and B owned by that user back to that user and destroy the relevant LP tokens. The last withdrawal in the pool deletes all Hook state, and places the Hook in setup-mode again.

Query Interface

All querying happens via ttINVOKE. If a user wishes to know what exchange rate they would probably get for a currency they can query that as follows: Send a ttINVOKE to the Hook that specifies the following HookParameters:

Parameter	Value
CUR	20 byte currency code to send
ISU	20 byte issuer code to send (0's for XAH)
AMT	8 byte LE XFL amount to send (XAH should be normalized to whole XAH, not drops)

The Hook should return binary encoded data in the return string as follows:

byte offset	value
0	AMM PBD\0
8	20 byte currency code to receive
28	20 byte issuer of currency to receive
48	8 byte LE XFL of amount to receive
56	8 byte LE XFL of effective exchange rate

Hook State

AMM Hooks are free to store their state any way they please. But they should have at least the following state keys:

Key	Format	Explanation
CUR	80 packed bytes comprising: 20 byte currency code A, 20 byte issuer A, 20 byte currency code B, 20 byte issuer B	Packed data describing the currency pair. XAH is described with all 0's.
A	8 byte LE XFL	How much of currency A the AMM currently owns and considers "in the pool"
B	8 byte LE XFL	How much of currency B the AMM currently owns and considers "in the pool"

[zgrguric]

What I would do is change this sentence "To do this anyone can send two currencies" because it might imply bad practice. Hook creator might choose to protect Setup to set this by owner account only or possibly set CUR, A and B state by other installer hook.