# Building an SDK Documentation Template from Modularized System Models

## Concept

This template offers a framework for documenting and implementing an SDK module using the BlockScience Systems Engineering modeling specification.


## State
The state is the set of information objects at the module level necessary to maintain an active, legal project.

In an SDK, a state is named and populated with a set of variable name, datatype pairs.

State_1
| Name| Schema | VarName_1 | VarType_1 |VarName_2 | VarType_2 |VarName_n | VarType_n |
|-----|----------|----|----|----|----|----|----|
| State_1_Name| Dict_struct | Var_A | uint64 |Var_B | string|Var_C | sdk.dec|

State_2
| Name| Schema | VarName_1 | VarType_1 |VarName_2 | VarType_2 |VarName_n | VarType_n |
|-----|----------|----|----|----|----|----|----|
|-----|----------|----|----|----|----|----|----|
| State_1_Name| Dict_struct | Var_A | uint64 |Var_B | string|Var_C | sdk.dec|

The cadCAD specification delineates between state variables and the metrics, in SDK, this is referred to as a [Query](#Query). The results of a cadCAD simulation, the state is the output record with no delineation. The producer and consumer of this information must use the specification to make the distinction. There are three other potential and frequent additions to the state record in cadCAD compared to the state defined in an SDK.
1. Agent level states necessary for determining and simulating agent decisions and actions within the system.
2. Differential states necessary for developing and determining algorithmic verification.
3. External states that can impact system performance necessary for resilience testing.

## Parameters

The concept of the parameter as a variable with chosen value, which may or may not be updated, necessary for the module to function is the same for both SDK and cadCAD.

In an SDK, parameters are defined in the same manner as the module's state, where the parameter set definition contains pairs variable name and datatypes.

| Name| Schema | VarName_1 | VarType_1 |VarName_2 | VarType_2 |VarName_n | VarType_n |
|-----|----------|----|----|----|----|----|----|
| Parameter_Set| Dict_struct | Param_A | uint64 |Param_B | string|Param_C | sdk.dec|

The values and logic for initial parameter values (or range of tested values) are contained in the file `sys_params.py`, if following the cadCAD source code template.

The parameter set does not appear in the cadCAD specification diagram. Instead, module level parameters are determined through the mathematical specification of the algorithms, where any potential controllable (or unfixed) variable should be specified as a parameter. As a best practice, the user should aim to have any state transition function be a function of [State](#State), [Query](#Query),[Parameter](#Parameters) and [Message](#Message).

The delineation between controllable and necessary parameters for operation of a module and additional parameters shold be explicitly stated both in the code and the supporting documentation. Additions to the parameter set are often similar to the additons to the state, and can be:
1. Agent level parameters necessary for determining and simulating agent decisions and actions within the system.
3. External parameters that can test system performance against a range of exogeneous processes.

## Initialization

Initialization of a module contains the necessary values to create first legal state.

The first legal state corresponds with the initial state (or sometimes called genesis state) dictionary in cadCAD. The genesis state ideally contains the proper initial condition for each state variable. While the schema for a cadCAD state object is mutable, the genesis state for an SDK state variable should persist.

Conditional logic may be introduced to accept or reject genesis state values, prior to writing to the genesis state dictionary. The formulation of this logic may be strictly proven and adhered to, often written in a mathematical specification, or may be permitted within the bounds of a heuristic as is often the case with human decision logic.

The values and logic for initialization are contained in the file `state_variables.py` with frequent dependency on `sys_params.py` and other functions, if following the cadCAD source code template.

## State Transitions

State transitions are function calls to update the state.

In SDK, the state is updated through input containing Message input, Handler input, the parameter set, and state itself, specifying the required variables within the state. The algorithm performs the necessary compuation and outputs the updated state.

Update State_1

Update State_1(Message_Input_a, Handler_Input_a, VarName_1, VarName_2, params):
    Algorithm Line 1
    Call Component X
    Algorithm Line 3
    Return State_1

Update State_2

Update State_2(Message_Input_b, Handler_Input_b, VarName_1, VarName_2, params):
    Algorithm Line 1
    Call Component Y
    Algorithm Line 3
    Return State_2

The cadCAD specification diagram clearly makes the necessary distinctions to follow the SDK pattern. Furthermore, the execution of any cadCAD model calls on `Variables` functions to update a specific State variable. These functions are sometimes referred to as `State Updates` or `Mechanisms`. If the `State Update` function would only be called by the [Keepers](#Keepers), then this function would be classified as a `Control Function` in the cadCAD specification diagram. The permission is typically seen through identification of the message sender in the `Policy`.

## Messages
`Agent Action Space`

In SDK, seem to messages are the user action where each available action has a specified name. Each message contains a list of thruples of (type (name), key, value).

The cadCAD specification diagram uses `User Behavior Functions` as a subtype of `policies` to specify a message type input.

Typically a `User Behavior Functions` will contain conditional logic that has dependencies on State, agent-level parameters, and makes Querier type calls.

## Events
`Tracing agent action execution`

In SDK, Events are methods for tracking information flow.
For example, tracing the execution of a message is an Event. As an example, tracing every event would be needed by a block explorer. Additionally, an Event may be used to trigger a [Hook](#Hook) for an external module to call.

cadCAD can replicate the instantiaton of Events through tracing a particular state variable or message held as a state through `substeps` which are produced in the output record. In the case where the Event is triggering an external module call, the cadCAD specification diagram would identify this as an `Environmental Process Driver` to that other module.

## Handler
`Permissible Agent Action Determination Posterior`

In SDK, a handler is a function that can be used to process messages. Processing examples can include validations such as checksum or identity verifications.

If used, the input is the message and the output is sent to state transition function as in input.

In cadCAD, this added layer of functionality is encoded in one of two places:
1. `User Behavior Functions` where an action may not be taken because it failed a verification
2. `State Transition Function` where the `User Behavior Functions` input is conditioned, verified, or formatted.

## Keepers
`Permissible Control Action Determination Prior`

In SDK, Keepers manage access to a subset of the State of the module or the Parameter Set.

Keepers do not appear in the cadCAD specification diagram. However, permissioned logic may be applied to update a parameter set or control function through explicit definition. This definition is captured through the requirements and design phases of the systems engineering process.

## Query
`Available Prescribed State Computation`

In SDK, a Query is a pre-defined computation that may be performed on the State, executed when a [Querier](#Querier) calls the function. A `Query` is a computation intended for an end-user of the application. The scale and breadth of the Query is far-ranging. Queries may be as simple as a price check call or as ranging as a wallet scanner, in which case it would likely be called through a [Hook](#Hook) by a separate module.

The cadCAD specification diagram uses `Metrics` to call out specific KPIs computed as a function of State. However, the output record does not offer the same delineation. One must use cadCAD specification diagram to determine the partition between `State` and `Metrics` the definition of the model

The computation of any stateful metric is calculated during the dynamic simulation and thus, offers a similar method for calculation in an SDK.

## Querier
`Call on a Query`

In SDK, a Querier is a function call to execute a [Query](#Query). It is expected that an any agent may make this call.

In cadCAD, a calculation on the State is typically embedded within the conditional logic for an agent to act (send a message). Thus, preceding a message, it is expected that an agent would either make `Querier` call or perform their own determination logic. Also, this action does not need to be limited to a 'generic' agent, but may also be called within a state transition function.

## Hooks
`Module Interface`

In SDK, hooks are [Events](#Events) called by another module to provide an update to that other module. A change in `State`, `Parameter Set`, or `Message` in that other module would be triggered.

Executing a system model of a single module in cadCAD, this triggering call would be considered as external to the system. The cadCAD specification diagram would identify the Hook as an `Environmental Process Model` to that other module.