add proposal for v0.2

docs/proposals/2023-10-05-proposal-v0.2.md

@@ -0,0 +1,128 @@
+# DRAFT: Proposal v0.2 - 2023-10-05
+
+## Objective
+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
+- Scheduler: is the responsible for execute and make the control flow for states, and for push and pull states input/output (it should be multitask in the future allowing concurrency and parallelism based on state tags)
+
+## Functional requirements
+- A state machine with handlers and state storage (context) that enables us to compound states and use it as input for a new state
+- A state storage should be a trait (based on a commit message process?) that should enable a non-local storage implementation in the future
+- The state-local storage as the first implementation of the state storage traits
+- 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)
+- Non-deterministic states needs to be tagged as is (e.g. impure)
+- A scheduler will run the state handlers and control flow
+- A scheduler will control flow with error handlers based on common error types
+- A scheduler error handler should be replaceable
+- Describe any operation that should be a sequence of states with a start input
+- Operation can be composed as a Machine by composing the states of each operation 
+- An Operation should be able to create their own error handler and replace the default scheduler error handler
+- Machine should be a set of operations that will be composed by a series of sub states of all those operations filtered by tags (e.g. excluding user interaction inside an Machine with five Operations)
+- The state-local storage needs to carry historically all states data until the operation finish
+- 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
+
+## 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 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;
+- generate_report;
+- report_to_operator;
+
+### How to swap between two assets on-chain?
+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;
+- 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)
+
+#### 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;
+- 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)
+
+## Future possible extension of this functional requirements
+- Scheduler can be multitasking using concurrency and parallelism of state handlers bases on tags
+- Scheduler can instrument all state executions with input and output data by tracing the executions and the state storage (e.g. implementing opentelemetry tracing)
+- State storage can have multiple implementation like databases or caches
+- We can "replay" or "continue" any operation or machine interruptions just re-executing the next state of the last confirmed state with the correct input
+
+## References
+- https://en.wikipedia.org/wiki/Finite-state_machine
+- https://en.wikipedia.org/wiki/Event-driven_finite-state_machine
+- https://en.wikipedia.org/wiki/State_pattern
+- https://en.wikipedia.org/wiki/Scheduling_(computing)
+