From 288c7b46f3f2842a573bec6ab11b014d9759f0bb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Willy=20Rom=C3=A3o?= Date: Thu, 5 Oct 2023 21:59:16 +0100 Subject: [PATCH] add usecases and concepts --- docs/proposals/2023-10-05-proposal-v0.2.md | 112 ++++++++++++++------- 1 file changed, 77 insertions(+), 35 deletions(-) diff --git a/docs/proposals/2023-10-05-proposal-v0.2.md b/docs/proposals/2023-10-05-proposal-v0.2.md index 6eaa44b..f2d21a9 100644 --- a/docs/proposals/2023-10-05-proposal-v0.2.md +++ b/docs/proposals/2023-10-05-proposal-v0.2.md @@ -1,66 +1,108 @@ # Proposal v0.2 - 2023-10-05 ## Objective -Currently, in the v0.1 of the MFM, we have built a lot of components as a PoC and learning process to build a finance machine that can query and execute operations on chain, and on top of that, managing portfolios of cryptoassets. -It was written without much carefully around the design and implementation details, and now it's getting harder and harder to maintain and evolve the platform. -This Proposal for the v0.2 is focused in a full redesign and refactor that should address the problems mentioned above with a highly flexible and deterministic way to operate states on chain. +Currently, in v0.1 of the MFM, we have built a lot of components as a PoC and learning process to build a finance machine that can query and execute operations on-chain and, on top of that, manage portfolios of crypto assets. +It was written without carefully around the design and implementation details, and now it's getting harder and harder to maintain and evolve the platform. +This Proposal for v0.2 is focused on a full redesign and refactor that should address the problems mentioned above with a highly flexible and deterministic way to operate states on-chain. + +## Glossary +- Operation: a task available to be performed (usually on-chain); it's described by a set of states that needs to be processed to achieve the final task objective +- Machine: a fun name matching the project name, which is a set of operations to be performed (usually on-chain); it's composed of a group of Operations, which in turn is composed of a collection of the states filtered by tags +- State: a minimal unit of pointer to the previous state, state data (input) and handler; those handlers perform minimal tasks (usually deterministically) that will be composed to make an Operation ## Goals -- Build a state machine library with a state-local storage, that enable us compond states and use it as input of a new state +- Build a state machine library with state-local storage that enables us to compound states and use it as input for a new state - The state-local storage needs to be an implementation of the state storage traits -- The state storage traits needs to be based into an commit message process that should enable an non-local storage implementation in the future -- Each state needs to have their handlers for read the input data of the state, and output an componded state for the next state -- Each state handlers needs to operate in a isolate form an behave as determinisc as possible -- States that applies side-effects needs to be tagged as is -- Describe any operation should be a sequence of states with an start input +- The state storage traits need to be based on a commit message process that should enable a non-local storage implementation in the future +- Each state needs to have handlers to read the input data of the state and output a compounded state for the next state +- Each state handler needs to operate in an isolated form and behave as determined as possible +- Each state must have tags indicating its kind of state (e.g., config, fetch_data, compute, execute, report, report_operator, report_operation, etc.) +- States that apply side-effects need to be tagged as is (e.g. apply_side_effect) +- Describe any operation that should be a sequence of states with a start input +- Operation can be composed by composing the states of each operation - The state-local storage needs to carry historically all states data until the operation finish -- Design and implement an report that can read states and report to the user (or to the program like an JSON) - -## Components -### State machine -### State storage -### State-local storage -### State report -### Operation +- Design and implement a report that can read states and report to the user (or to the program like a JSON) +- Any UI can invoke an operation; the first one should be CLI -## Example -Those are example that can help us to visualize how that should work. -Everything here is just hipotetically information/data. +## Usecases and an overview of the concepts of Machine, Operations and States +Those are just examples with hypothetical information and naming. +The objective is to understand the basic concepts of Machines, Operations and States by use cases. -### How to get an quoted price between two assets on-chain? -#### By state in order -- read_configuration; -- read_user_flags; +### How to get a quoted price between two assets on-chain? +It's an Operation composed of this list of states: +- setup_operation; - setup_a_provider; (?) - get_assets_info; - get_exchange; - build_asset_path; (?) - get_amount_out_for_pair; - discount_possible_slippage; -- report_to_user; +- generate_report; +- report_to_operator; ### How to swap between two assets on-chain? -#### By state in order -- read_configuration; -- read_user_flags; -- setup_a_provider; (?) +It's an Operation composed of this list of states: +- setup_operation; - get_assets_info; - get_exchange; - build_asset_path; (?) - get_amount_out_for_pair; - discount_possible_slippage; - swap_tokens; -- report_to_user; +- generate_report; +- report_to_operator; + +### How to report the state of a defined portfolio on-chain? +It's an Operation composed of this list of states: +- setup_operation; +- get_assets_info_for_all_networks; +- get_assets_balances_for_all_networks; +- compute_assets_balance_to_quoted_in_token; +- compute_total_balance; +- get_diffs_from_total_balance_and_portfolio_assets_percent; +- get_swap_cost_estimations_for_rebalance_portfolio; +- generate_report; +- report_to_operator; + +### How do I bridge a MATIC token from Ethereum to Polygon zkEVM and rebalance my portfolio on Polygon zkEVM? +It's a Machine which is composed of a subset of the states of three Operations: + +#### Bridge an Asset from Chain A to Chain B +- setup_operation; +- choose_a_bridge_from_chainA_to_chain_B; +- simulate; (if choose to) +- generate_report; (if choose to) +- confirm_execution_with_operator; (if choose to) +- bridge_from_chainA_to_chain_B; +- wait_until_bridge_is_done; +- generate_report; +- report_to_operator; (should be off by a previous filter excluding report_operator tag from operations in a machine) + +#### Rebalance portfolio on Chain B +- setup_operation; +- get_assets_info_for_all_networks; +- get_assets_balances_for_all_networks; +- compute_assets_balance_to_quoted_in_token; +- compute_total_balance; +- get_diffs_from_total_balance_and_portfolio_assets_percent; +- get_swap_cost_estimations_for_rebalance_portfolio; +- validate_decision_making_rebalancer_rules; +- simulate; (if choose to) +- generate_report; (if choose to) +- confirm_execution_with_operator; (if choose to) +- generate_all_transaction_to_achieve_portfolio; +- execute_all_transactions_sequencially; +- generate_report; +- report_to_operator; (should be off by a previous filter excluding report_operator tag from operations in a machine) -### How to report the state of an defined portfolio on-chain? -- read_configuration; -- read_user_flags; -- setup_providers; (?) +### Report the state of a defined portfolio on-chain +- setup_operation; - get_assets_info_for_all_networks; - get_assets_balances_for_all_networks; - compute_assets_balance_to_quoted_in_token; - compute_total_balance; - get_diffs_from_total_balance_and_portfolio_assets_percent; - get_swap_cost_estimations_for_rebalance_portfolio; -- report_to_user; +- generate_report; +- report_to_operator; (should be always on by defined in a "always list of tags" with a report_operation tag, which will make all states of a report operation always execute)