Document various Scenarios

- Pong
- Wrap
- SRI -> BTC
- BTC -> Monero
- Add Liquidity (fresh)
- Add Liquidity (SRI holder)

docs/integrations/Instructions.md

@@ -26,12 +26,14 @@ act on invalid data, or send to itself, it will drop the entire instruction.
 ### Serialization
 
   - Numbers are exclusively unsigned and encoded as compact integers under
-SCALE. If omitted, `0`.
+SCALE.
   - Enums are prefixed by an ordinal byte of their type, followed by their
 actual values.
-  - Vectors are prefixed by their length. If omitted, `vec![]`.
-  - Instruction fields are numbered and sequentially encoded, each prefixed by
-an ordinal byte. All other fields are sequentially encoded with no markers.
+  - Vectors are prefixed by their length.
+  - In Instruction fields are numbered and sequentially encoded, allowing
+omission, each prefixed by an ordinal byte. This is due to its fields being more
+frequently omitted than not, making their presence what's notable.
+  - All other types have their fields sequentially encoded with no markers.
 
 Certain fields may be omitted depending on the network in question.
 
@@ -55,7 +57,7 @@ If the instruction fails, funds are scheduled to be returned to `origin`.
 
   - `destination` (Enum { Native(Address), Serai(Address) }): Address to receive
 funds to.
-  - `data`        (Vec<u8>):                                  The data to call
+  - `data`        (Option<Vec<u8>>):                          The data to call
 the target with.
 
 Transfer the funds included with this instruction to the specified address with

docs/integrations/Scenarios.md

@@ -0,0 +1,98 @@
+# Scenarios
+
+### Pong
+
+Pong has Serai receive funds, just to return them. It's a demonstration of the
+in/out flow.
+
+```
+Shorthand::Raw(
+  In Instruction {
+    target: Incoming Asset Contract,
+    data:   native_transfer(Incoming Asset Sender)
+  }
+)
+```
+
+### Wrap
+
+Wrap wraps an asset from a connected chain into a Serai Asset, making it usable
+with applications on Serai, such as Serai DEX.
+
+```
+Shorthand::Raw(
+  In Instruction {
+    target: Serai Address
+  }
+)
+```
+
+### Swap SRI to Bitcoin
+
+For a SRI to Bitcoin swap, a SRI holder would perform an
+[Application Call](../Serai.md#application-calls) to Serai DEX, purchasing
+seraiBTC. Once they have seraiBTC, they are able to call `native_transfer`,
+transferring the BTC underlying the seraiBTC to a specified Bitcoin address.
+
+### Swap Bitcoin to Monero
+
+For a Bitcoin to Monero swap, the following Shorthand would be used.
+
+```
+Shorthand::Swap {
+  coin:    Monero,
+  minimum: Minimum Monero from Swap,
+  out:     Monero Address
+}
+```
+
+ This 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`'s ordinal byte.
+  - 65 bytes for `out`'s `destination`'s address.
+  - 1 byte to not include `data` in `out`.
+
+Or 74 bytes.
+
+### Add Liquidity (Fresh)
+
+For a user who has never used Serai before, they have three requirements to add
+liquidity:
+
+  - Minting the Serai asset they wish to add liquidity for
+  - Acquiring Serai, as liquidity is symmetric
+  - Acquiring Serai for gas fees
+
+The Add Liquidity Shorthand enables all three of these actions, and actually
+adding the liquidity, in just one transaction from a connected network.
+
+```
+Shorthand::AddLiquidity {
+  minimum: Minimum SRI from Swap,
+  gas:     Amount of SRI to keep for gas
+  address: Serai address for the liquidity tokens and gas
+}
+```
+
+For adding liquidity from Bitcoin, this Shorthand is expected to generally take:
+
+  - 1 byte to identify as Add Liquidity.
+  - 1 byte to not override `origin`.
+  - 5 bytes for `minimum`.
+  - 4 bytes for `gas`.
+  - 32 bytes for `address`.
+
+Or 43 bytes.
+
+### Add Liquidity (SRI Holder)
+
+For a user who already has SRI, they solely need to have the asset they wish to
+add liquidity for via their SRI. They can either purchase it from Serai DEX, or
+wrap it as detailed above.
+
+Once they have both their SRI and the asset they wish to provide liquidity for,
+they would use a Serai transaction to call the DEX, adding the liquidity.