From 2f19dcf043d083fab3dd7586e151779ffde2d44c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Willy=20Rom=C3=A3o?= Date: Fri, 6 Oct 2023 10:07:47 +0100 Subject: [PATCH] add scheduler as functional requirement --- docs/proposals/2023-10-05-proposal-v0.2.md | 32 ++++++++++++++++++---- 1 file changed, 26 insertions(+), 6 deletions(-) diff --git a/docs/proposals/2023-10-05-proposal-v0.2.md b/docs/proposals/2023-10-05-proposal-v0.2.md index f2d21a9..d710f7f 100644 --- a/docs/proposals/2023-10-05-proposal-v0.2.md +++ b/docs/proposals/2023-10-05-proposal-v0.2.md @@ -1,25 +1,33 @@ -# Proposal v0.2 - 2023-10-05 +# 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) -## Goals -- 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 need to be based on a commit message process that should enable a non-local storage implementation in the future +## 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 by composing the states of each operation +- 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 @@ -106,3 +114,15 @@ It's a Machine which is composed of a subset of the states of three Operations: - 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) +