add usecases and concepts

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)