diff --git a/docs/Serai.md b/docs/Serai.md new file mode 100644 index 00000000..23b2269b --- /dev/null +++ b/docs/Serai.md @@ -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. diff --git a/docs/integrations/Instructions.md b/docs/integrations/Instructions.md index 4a78e399..929acfa0 100644 --- a/docs/integrations/Instructions.md +++ b/docs/integrations/Instructions.md @@ -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): 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\): 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): 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
): 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\
): 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
): 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\
): 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.