Ecosystem/serai
Ecosystem/serai
1
0
Fork 0
mirror of https://github.com/serai-dex/serai.git synced 2024-12-31 16:09:47 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 1

Document Serai's Application Calls and update Instructions accordingly

Browse source
This commit is contained in:
Luke Parker 2022-07-21 23:27:21 -04:00
parent 9cc35a06ab
commit c3ab201517
2 changed files with 69 additions and 74 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

33
docs/Serai.md Normal file
View file

@ -0,0 +1,33 @@
# Serai
Serai is a decentralization execution layer whose validators form multisig
wallets for various connected networks, offering secure decentralized custody of
foreign assets to applications built on it.
Serai is exemplified by Serai DEX, an automated-market-maker (AMM) decentralized
exchange, allowing swapping BTC, ETH, USDC, DAI, and XMR. It is the premier
application of Serai.
### Substrate
Serai is based on [Substrate](https://docs.substrate.io), a blockchain framework
offering a robust infrastructure.
### Smart Contracts
Serai offers WASM-based smart contracts. All applications are built over these
contracts, enabling composable interactions within a mutual layer. These
contracts are primarily written in [ink!](https://ink.substrate.io/), a
framework for building contracts in Rust.
Initially, smart contract deployment will not be enabled. Solely Serai DEX will
be available, due to the variety of economic considerations around securing the
multisig. Serai may expand in the future with more explicitly added
applications, each with tailored economic models, or may enable arbitrary
contract deployment. At this time, we solely plan for Serai DEX's availabiliy.
### Application Calls
Applications, such as Serai DEX, may be called via calling their relevant smart
contracts. At a low level, this is done via specifying the address of the
contract being interacted with, along with SCALE-encoded calldata.

110
docs/integrations/Instructions.md
View file

@ -1,10 +1,22 @@
# Instructions
Instructions have two forms, In and Out. For a transaction originating on a
connected network, an In Instruction must be provided, which may embed an Out
Instruction. For a transaction originating on Serai, only an Out Instruction is
allowed. Additionally, short hand forms are provided to minimize representations
on connected networks.
Instructions are used to communicate with networks connected to Serai, and they
come in two forms:
- In Instructions are [Application Calls](../Serai.md#application-call),
paired with incoming funds. Encoded in transactions on connected networks,
Serai will parse out instructions when it receives funds, executing the included
calls.
- Out Instructions detail how to transfer assets, either to a Serai address or
an address native to the asset in question.
A transaction containing an In Instruction and an Out Instruction (to a native
address) will receive funds to Serai and send funds 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, beyond being a valid enum entry (when applicable)
@ -25,16 +37,16 @@ Certain fields may be omitted depending on the network in question.
### In Instructions
- `origin` (Address): Address from the network of origin which sent funds in.
- `target` (Address): The ink! contract to transfer the incoming funds to.
- `data` (Vec<u8>): The data to call the target with.
- `origin` (Address): Address from the network of origin which sent funds in.
- `target` (Address): The ink! contract to transfer the incoming funds to.
- `data` (Vec\<u8>): The data to call `target` with.
Networks may automatically provide `origin`. If they do, the instruction may
still provide `origin`, overriding the automatically provided value. If no
`origin` is provided, the instruction is dropped.
Upon receiving funds, the respective Serai Asset contract is called, minting the
appropriate amount of coins, and transferring them to the specified target with
appropriate amount of coins, and transferring them to `target`, calling it with
the attached data.
If the transaction fails, funds are scheduled to be returned to `origin`.
@ -46,25 +58,25 @@ funds to.
- `data` (Vec<u8>): The data to call
the target with.
If the network is Serai, this is a transfer. Else, it's a withdrawal to the
specified address with the specified data. Asset contracts perform no validation
on these fields.
Transfer the funds included with this instruction to the specified address with
the specified data. Asset contracts perform no validation on native
addresses/data.
### Shorthand
All In Instructions are encoded as Shorthand. Shorthand is an enum which expands
to an In Instruction.
Shorthand is an enum which expands to an In Instruction.
##### Raw
Raw Shorthand encodes a raw In Instruction with no further processing.
Raw Shorthand encodes a raw In Instruction with no further processing. This is
a verbose fallback option for infrequent use cases not covered by Shorthand.
##### Swap
- `origin` (Option<Address>): In Instruction's `origin`.
- `coin` (Coin): Coin to swap funds for.
- `minimum` (Amount): Minimum amount of `coin` to receive.
- `out` (Out Instruction): Final destination for funds.
- `origin` (Option\<Address>): In Instruction's `origin`.
- `coin` (Coin): Coin to swap funds for.
- `minimum` (Amount): Minimum amount of `coin` to receive.
- `out` (Out Instruction): Final destination for funds.
which expands to:
@ -83,25 +95,13 @@ where `swap` is a function which:
3) Checks the amount of `coin` received is greater than `minimum`.
4) Executes `out` with the amount of `coin` received.
For a Bitcoin to Monero swap, Swap Shorthand is expected to generally take:
- 1 byte to identify as Swap.
- 1 byte to not override `origin`.
- 1 byte for `coin`.
- 4 bytes for `minimum`.
- 1 byte for `out`'s `destination` field label.
- 1 byte for `out`'s `destination`'s ordinal byte.
- 65 bytes for `out`'s `destination`'s address.
Or 74 bytes.
##### Add Liquidity
- `origin` (Option<Address>): In Instruction's `origin`.
- `minimum` (Amount): Minimum amount of SRI to receive.
- `gas` (Amount): Amount of SRI to send to `address` to cover gas in the
future.
- `address` (Address): Account to give the created liquidity tokens.
- `origin` (Option\<Address>): In Instruction's `origin`.
- `minimum` (Amount): Minimum amount of SRI to receive.
- `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:
@ -120,41 +120,3 @@ where `swap_and_add_liquidity` is a function which:
3) Calls `swap_and_add_liquidity` with the amount of SRI received - `gas`, and
a matching amount of the incoming asset.
4) Transfers any leftover funds to `address`.
For adding liquidity from Bitcoin, Add Liquidity Shorthand is expected to
generally take:
- 1 byte to identify as Add Liquidity.
- 1 byte to not override `origin`.
- 5 bytes for `minimum`.
- 1/4 bytes for `gas`.
- 32 bytes for `address`.
Or 40/43 bytes, depending on whether or not the Serai address already has gas.
### Examples
All examples are assumed to be from Bitcoin.
##### Pong Example
```
In Instruction {
target: Bitcoin Asset Contract,
data: Withdraw(Out Instruction { destination: Native(Bitcoin Sender) })
}
```
would cause the created seraiBTC to be transferred to the Bitcoin Asset Contract
and withdrawn to the Bitcoin Sender.
##### Wrap Example
```
In Instruction {
target: Serai Address
}
```
would cause the created seraiBTC to be transferred to the specified Serai
address for usage on Serai.