Document Serai's Application Calls and update Instructions accordingly

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.

docs/integrations/Instructions.md

@@ -1,10 +1,22 @@
 # Instructions
 
-Instructions have two forms, In and Out. For a transaction originating on a
+Instructions are used to communicate with networks connected to Serai, and they
-connected network, an In Instruction must be provided, which may embed an Out
+come in two forms:
-Instruction. For a transaction originating on Serai, only an Out Instruction is
+
-allowed. Additionally, short hand forms are provided to minimize representations
+  - In Instructions are [Application Calls](../Serai.md#application-call),
-on connected networks.
+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.
+  - `origin` (Address):  Address from the network of origin which sent funds in.
-  - `target` (Address): The ink! contract to transfer the incoming funds to.
+  - `target` (Address):  The ink! contract to transfer the incoming funds to.
-  - `data`   (Vec<u8>): The data to call the target with.
+  - `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
+Transfer the funds included with this instruction to the specified address with
-specified address with the specified data. Asset contracts perform no validation
+the specified data. Asset contracts perform no validation on native
-on these fields.
+addresses/data.
 
 ### Shorthand
 
-All In Instructions are encoded as Shorthand. Shorthand is an enum which expands
+Shorthand is an enum which expands to an In Instruction.
-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`.
+  - `origin`  (Option\<Address>): In Instruction's `origin`.
-  - `coin`    (Coin):            Coin to swap funds for.
+  - `coin`    (Coin):             Coin to swap funds for.
-  - `minimum` (Amount):          Minimum amount of `coin` to receive.
+  - `minimum` (Amount):           Minimum amount of `coin` to receive.
-  - `out`     (Out Instruction): Final destination for funds.
+  - `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`.
+  - `origin`  (Option\<Address>): In Instruction's `origin`.
-  - `minimum` (Amount):  Minimum amount of SRI to receive.
+  - `minimum` (Amount):           Minimum amount of SRI to receive.
-  - `gas`     (Amount):  Amount of SRI to send to `address` to cover gas in the
+  - `gas`     (Amount):           Amount of SRI to send to `address` to cover
-future.
+gas in the future.
-  - `address` (Address): Account to give the created liquidity tokens.
+  - `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.