From 708fd20a6473b41ad3147e213e4dd6812d139c0a Mon Sep 17 00:00:00 2001
From: Fluid <90795031+fluiderson@users.noreply.github.com>
Date: Thu, 14 Mar 2024 22:38:11 +0200
Subject: [PATCH] Add more docs

---
 docs/assumptions.md |  14 ++++
 docs/database.md    | 156 ++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 170 insertions(+)
 create mode 100644 docs/assumptions.md
 create mode 100644 docs/database.md

diff --git a/docs/assumptions.md b/docs/assumptions.md
new file mode 100644
index 0000000..86720db
--- /dev/null
+++ b/docs/assumptions.md
@@ -0,0 +1,14 @@
+The current Substrate RPC API & pallets used by the daemon, unfortunately, don't have any strict standart, which all nodes & chains follow, and the common implementations of RPC API & pallets lack of some essential features. This creates restrictions & assumptions for which nodes & chains the daemon can be used with. Of course, our first priority is and will be a support of the Polkadot relaychain & the Polkadot Asset Hub parachain with a support of USDT & USDC assets on that parachain but in the future, we'll try to lift the following limitations and support a broader range of nodes & chains along with the evolution of the Substrate ecosystem & its standarts.
+
+### Transfers
+
+All extrinsics sent by the daemon are transfer transactions. Despite they themselves are quite unsophisticated, the whole process of the approximate fee calculation to subtract it from the transfer amount and then, in case of a fail because a real fee was higher than the daemon estimated, the resending of the same transaction after another never accurate calculation does sound like a really hard path.
+
+We tried to use the [`transfer_allow_death`] call in the Balances pallet for all transfers because we thought that a transfer fee would never be greater than the existential deposit but that isn't true for all chains (e.g. it's true for Polkadot, but not for Kusama), and unlikely will be a standart, so we stuck with the [`transfer_all`] call for transfers to both the beneficiary & overpayers accounts.
+
+The Assets pallet doesn't have a call similar to Balances's [`transfer_all`], so the daemon uses [`transfer`] assuming that a fee for that call wouldn't be higher than asset's [`min_balance`]. For now, that's true for USDT & USDC on Polkadot Asset Hub, but **if one these or another asset won't meet this criteria, the daemon won't be able to work with them**. We plan to propose and hopefully include some kind of `transfer_all` call in Assets pallet to subsequently eliminate this restriction.
+
+[`transfer_all`]: https://docs.rs/pallet-balances/30.0.0/pallet_balances/pallet/struct.Pallet.html#method.transfer_all
+[`transfer_allow_death`]: https://docs.rs/pallet-balances/30.0.0/pallet_balances/pallet/struct.Pallet.html#method.transfer_allow_death
+[`transfer`]: https://docs.rs/pallet-assets/31.0.0/pallet_assets/pallet/struct.Pallet.html#method.transfer
+[`min_balance`]: https://docs.rs/pallet-assets/31.0.0/src/pallet_assets/types.rs.html#66
diff --git a/docs/database.md b/docs/database.md
new file mode 100644
index 0000000..09c0686
--- /dev/null
+++ b/docs/database.md
@@ -0,0 +1,156 @@
+## 1
+
+**All slots are encoded with `parity-scale-codec = "3"`.**
+
+### Tables
+
+* `root`
+```rs
+type Key = String;
+type Value = Vec<u8>;
+```
+
+Public keys of all active accounts.
+* `keys`
+```rs
+/// A public key.
+type Key = [u8; 32];
+/// An accounts amount (never equals 0).
+type Value = U256;
+```
+
+* `chains`
+```rs
+/// A chain hash.
+type Key = [u8; 32];
+/// A last scanned block.
+type Value = Compact<u64>;
+```
+
+* `invoices`
+```rs
+/// An invoice name.
+type Key = Vec<u8>;
+type Value = Invoice;
+```
+
+* `accounts[chain_hash]`
+```rs
+/// An asset ID & an account ID.
+type Key = (u128, [u8; 32]);
+/// An invoice name.
+type Value = Vec<u8>;
+```
+
+* `transactions[chain_hash]`
+```rs
+/// A death block.
+type Key = Compact<u64>;
+/// Pending transactions.
+/// An account ID, a transaction nonce, a transaction.
+type Values = ([u8; 32], u32, ???);
+```
+
+* `hit_list`
+```rs
+/// A creation timestamp.
+type Key = u64;
+/// A chain hash, an asset ID, and an account ID.
+type Value = ([u8; 32], u128, [u8; 32]);
+```
+
+* `archive`
+```rs
+???
+```
+
+### `root` keyed untyped slots
+
+* `db_version`
+```rs
+Compact<u64>
+```
+
+* `daemon_info`
+```rs
+struct DaemonInfo {
+    /// A chain name, genesis hash, database hash, and type.
+    chains: Vec<(String, String, [u8; 32], ChainType)>,
+    /// The current public key.
+    current_key: [u8; 32],
+}
+```
+
+### Typed slots
+
+```rs
+struct Invoice {
+    /// A public key & a derivation hash.
+    derivation: ([u8; 32], [u8; 32]),
+    status: InvoiceStatus,
+    /// A creation timestamp.
+    timestamp: u64
+}
+
+enum InvoiceStatus {
+    Unpaid(u128),
+    Paid,
+}
+
+??? ChainType {
+    ???
+}
+```
+
+## 0
+
+**All slots are encoded with `parity-scale-codec = "3"`.**
+
+### Tables
+
+* `root`
+```rs
+type Key = String;
+type Value = Vec<u8>;
+```
+
+* `invoices`
+```rs
+type Key = [u8; 32];
+type Value = Invoice;
+```
+
+### `root` keyed untyped slots
+
+* `db_version`
+```rs
+Compact<u64>
+```
+
+* `daemon_info`
+```rs
+struct DaemonInfo {
+    rpc: String,
+    key: [u8; 32],
+}
+```
+
+* `last_block`
+```rs
+Compact<u32>
+```
+
+### Typed slots
+
+```rs
+struct Invoice {
+    recipient: [u8; 32],
+    order: [u8; 32],
+    status: InvoiceStatus,
+}
+
+enum InvoiceStatus {
+    Unpaid(u128),
+    Paid(u128),
+}
+```