serai/docs/integrations/Instructions.md
Luke Parker 2ace339975
Tokens pallet (#243)
* Use Monero-compatible additional TX keys

This still sends a fingerprinting flare up if you send to a subaddress which
needs to be fixed. Despite that, Monero no should no longer fail to scan TXs
from monero-serai regarding additional keys.

Previously it failed becuase we supplied one key as THE key, and n-1 as
additional. Monero expects n for additional.

This does correctly select when to use THE key versus when to use the additional
key when sending. That removes the ability for recipients to fingerprint
monero-serai by receiving to a standard address yet needing to use an additional
key.

* Add tokens_primitives

Moves OutInstruction from in-instructions.

Turns Destination into OutInstruction.

* Correct in-instructions DispatchClass

* Add initial tokens pallet

* Don't allow pallet addresses to equal identity

* Add support for InInstruction::transfer

Requires a cargo update due to modifications made to serai-dex/substrate.

Successfully mints a token to a SeraiAddress.

* Bind InInstructions to an amount

* Add a call filter to the runtime

Prevents worrying about calls to the assets pallet/generally tightens things
up.

* Restore Destination

It was meged into OutInstruction, yet it didn't make sense for OutInstruction
to contain a SeraiAddress.

Also deletes the excessively dated Scenarios doc.

* Split PublicKey/SeraiAddress

Lets us define a custom Display/ToString for SeraiAddress.

Also resolves an oddity where PublicKey would be encoded as String, not
[u8; 32].

* Test burning tokens/retrieving OutInstructions

Modularizes processor_coinUpdates into a shared testing utility.

* Misc lint

* Don't use PolkadotExtrinsicParams
2023-01-28 01:47:13 -05:00

131 lines
4.2 KiB
Markdown

# Instructions
Instructions are used to communicate with networks connected to Serai, and they
come in two forms:
- In Instructions are programmable specifications paired with incoming coins,
encoded into transactions on connected networks. Serai will parse included
instructions when it receives coins, executing the included specs.
- Out Instructions detail how to transfer coins, either to a Serai address or
an address native to the coin in question.
A transaction containing an In Instruction and an Out Instruction (to a native
address) will receive coins to Serai and send coins from Serai, without
requiring directly performing any transactions on Serai itself.
All instructions are encoded under [Shorthand](#shorthand). Shorthand provides
frequent use cases to create minimal data representations on connected networks.
Instructions are interpreted according to their non-Serai network. Addresses
have no validation performed unless otherwise noted. If the processor is
instructed to act on invalid data, it will drop the entire instruction.
### Serialization
Instructions are SCALE encoded.
### Application Call
- `application` (u16): The application of Serai to call. Currently, only 0,
Serai DEX is valid.
- `data` (Data): The data to call the application with.
### In Instruction
InInstruction is an enum of SeraiAddress and ApplicationCall.
The specified target will be minted an appropriate amount of the respective
Serai token. If an Application Call, the encoded call will be executed.
### Refundable In Instruction
- `origin` (Option\<ExternalAddress>): Address, from the network of
origin, which sent coins in.
- `instruction` (InInstruction): The action to perform with the
incoming coins.
Networks may automatically provide `origin`. If they do, the instruction may
still provide `origin`, overriding the automatically provided value.
If the instruction fails, coins are scheduled to be returned to `origin`,
if provided.
### Out Instruction
- `address` (ExternalAddress): Address to transfer the coins included with
this instruction to.
- `data` (Option<Data>): Data to include when transferring coins.
No validation of external addresses/data is performed on-chain. If data is
specified for a chain not supporting data, it is silently dropped.
### Destination
Destination is an enum of SeraiAddress and OutInstruction.
### Shorthand
Shorthand is an enum which expands to an Refundable In Instruction.
##### Raw
Raw Shorthand encodes a raw Refundable In Instruction in a Data, with no further
processing. This is a verbose fallback option for infrequent use cases not
covered by Shorthand.
##### Swap
- `origin` (Option\<ExternalAddress>): Refundable In Instruction's `origin`.
- `coin` (Coin): Coin to swap funds for.
- `minimum` (Amount): Minimum amount of `coin` to receive.
- `out` (Destination): Final destination for funds.
which expands to:
```
RefundableInInstruction {
origin,
instruction: ApplicationCall {
application: DEX,
data: swap(Incoming Asset, coin, minimum, out)
}
}
```
where `swap` is a function which:
1) Swaps the incoming funds for SRI.
2) Swaps the SRI for `coin`.
3) Checks the amount of `coin` received is greater than `minimum`.
4) Executes `out` with the amount of `coin` received.
##### Add Liquidity
- `origin` (Option\<ExternalAddress>): Refundable In Instruction's `origin`.
- `minimum` (Amount): Minimum amount of SRI tokens to swap
half for.
- `gas` (Amount): Amount of SRI to send to `address` to
cover gas in the future.
- `address` (Address): Account to send the created liquidity
tokens.
which expands to:
```
RefundableInInstruction {
origin,
instruction: ApplicationCall {
application: DEX,
data: swap_and_add_liquidity(Incoming Asset, minimum, gas, address)
}
}
```
where `swap_and_add_liquidity` is a function which:
1) Swaps half of the incoming funds for SRI.
2) Checks the amount of SRI received is greater than `minimum`.
3) Calls `swap_and_add_liquidity` with the amount of SRI received - `gas`, and
a matching amount of the incoming coin.
4) Transfers any leftover funds to `address`.