Move docs to spec

spec/integrations/Bitcoin.md

@@ -0,0 +1,23 @@
+# Bitcoin
+
+### Addresses
+
+Bitcoin addresses are an enum, defined as follows:
+
+  - `p2pkh`:  20-byte hash.
+  - `p2sh`:   20-byte hash.
+  - `p2wpkh`: 20-byte hash.
+  - `p2wsh`:  32-byte hash.
+  - `p2tr`:   32-byte key.
+
+### In Instructions
+
+Bitcoin In Instructions are present via the transaction's last output in the
+form of `OP_RETURN`, and accordingly limited to 80 bytes. `origin` is
+automatically set to the transaction's first input's address, if recognized.
+If it's not recognized, an address of the multisig's current Bitcoin address is
+used, causing any failure to become a donation.
+
+### Out Instructions
+
+Out Instructions ignore `data`.

spec/integrations/Ethereum.md

@@ -0,0 +1,38 @@
+# Ethereum
+
+### Addresses
+
+Ethereum addresses are 20-byte hashes.
+
+### In Instructions
+
+Ethereum In Instructions are present via being appended to the calldata
+transferring funds to Serai. `origin` is automatically set to the party from
+which funds are being transferred. For an ERC20, this is `from`. For ETH, this
+is the caller.
+
+### Out Instructions
+
+`data` is limited to 512 bytes.
+
+If `data` is provided, the Ethereum Router will call a contract-calling child
+contract in order to sandbox it. The first byte of `data` designates which child
+child contract to call. After this byte is read, `data` is solely considered as
+`data`, post its first byte. The child contract is sent the funds before this
+call is performed.
+
+##### Child Contract 0
+
+This contract is intended to enable connecting with other protocols, and should
+be used to convert withdrawn assets to other assets on Ethereum.
+
+  1) Transfers the asset to `destination`.
+  2) Calls `destination` with `data`.
+
+##### Child Contract 1
+
+This contract is intended to enable authenticated calls from Serai.
+
+  1) Transfers the asset to `destination`.
+  2) Calls `destination` with `data[.. 4], serai_address, data[4 ..]`, where
+`serai_address` is the address which triggered this Out Instruction.

spec/integrations/Instructions.md

@@ -0,0 +1,123 @@
+# 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 network of the coins 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.
+
+### In Instruction
+
+InInstruction is an enum of:
+
+  - `Transfer`
+  - `Dex(Data)`
+
+The specified target will be minted an appropriate amount of the respective
+Serai token. If `Dex`, 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 contains a Refundable In Instruction directly. 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: InInstruction::Dex(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: InInstruction::Dex(
+    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`.

spec/integrations/Monero.md

@@ -0,0 +1,37 @@
+# Monero
+
+### Addresses
+
+Monero addresses are structs, defined as follows:
+
+  - `kind`:  Enum {
+               Standard,
+               Subaddress,
+               Featured { flags: u8 }
+             }
+  - `spend`: [u8; 32]
+  - `view`:  [u8; 32]
+
+Integrated addresses are not supported due to only being able to send to one
+per Monero transaction. Supporting them would add a level of complexity
+to Serai which isn't worth it.
+
+This definition of Featured Addresses is non-standard since the flags are
+represented by a u8, not a VarInt. Currently, only half of the bits are used,
+with no further planned features. Accordingly, it should be fine to fix its
+size. If needed, another enum entry for a 2-byte flags Featured Address could be
+added.
+
+This definition is also non-standard by not having a Payment ID field. This is
+per not supporting integrated addresses.
+
+### In Instructions
+
+Monero In Instructions are present via `tx.extra`, specifically via inclusion
+in a `TX_EXTRA_NONCE` tag. The tag is followed by the VarInt length of its
+contents, and then additionally marked by a byte `127`. The following data is
+limited to 254 bytes.
+
+### Out Instructions
+
+Out Instructions ignore `data`.