module arch.node.engines.commitment_behaviour;

import prelude open;
import arch.system.identity.identity open;
import arch.node.engines.commitment_messages open;
import arch.node.engines.commitment_config open;
import arch.node.engines.commitment_environment open;
import arch.node.types.basics open;
import arch.node.types.identities open;
import arch.node.types.messages open;
import arch.node.types.engine open;
import arch.node.types.anoma as Anoma open;

Commitment Behaviour¶

Overview¶

The behavior of the Commitment Engine defines how it processes incoming commitment requests and produces the corresponding commitments/signatures.

Commitment Action Flowchart¶

commitAction flowchart¶

flowchart TD
    Start([Client Request]) --> MsgReq[MsgCommitmentRequest<br>data: Signable]

    subgraph Guard["commitGuard (Message Validation)"]
        MsgReq --> ValidType{Is message type<br>CommitmentRequest?}
        ValidType -->|No| Reject([Reject Request])
        ValidType -->|Yes| ActionEntry[Enter Action Phase]
    end

    ActionEntry --> Action

    subgraph Action["commitAction (Processing)"]
        direction TB
        Sign[Generate signature<br>using backend signer]
        Sign --> Success{Signature<br>Generated?}
        Success -->|Yes| GoodResp[Create Response<br>with signature]
        Success -->|No| ErrResp[Create Response<br>with error]
    end

    GoodResp --> Response[MsgCommitmentResponse<br>commitment: Commitment<br>err: none]
    ErrResp --> ErrResponse[MsgCommitmentResponse<br>commitment: empty<br>err: Some error]

    Response --> Client([Return to Client])
    ErrResponse --> Client

Explanation¶

1. Initial Request

   • A client sends a MsgCommitmentRequest containing data (Signable) that needs to be signed.
   • The data must be in a format that can be signed by the backend (e.g., a byte string, transaction data, etc.).

2. Guard Phase (commitGuard)

   • Validates that the incoming message is a proper commitment request.
   • Checks occur in the following order:
     • Verifies message type is MsgCommitmentRequest.
     • If validation fails, request is rejected without entering the action phase.
     • On success, passes control to commitActionLabel.

3. Action Phase (commitAction)

   • Processes valid commitment requests through these steps:
     • Extracts the data to be signed from the request.
     • Retrieves the signer from the engine's configuration.
     • Attempts to generate a signature using the backend signer.
     • Constructs an appropriate response message.

4. Response Generation

   • Successful Case
     • Creates MsgCommitmentResponse with:
       • commitment: The generated signature.
       • err: None.
   • Error Case
     • In all error cases, returns MsgCommitmentResponse with:
       • commitment: Empty.
       • err: Some(error message).

5. Response Delivery

   • Response is sent back to the original requester.
   • Uses mailbox 0 (default mailbox for responses).

Important Notes:¶

• The commitment engine is stateless - each request is handled independently.

Action arguments¶

CommitmentActionArgumentReplyTo ReplyTo¶

type ReplyTo :=
  mkReplyTo@{
    whoAsked : Option EngineID;
    mailbox : Option MailboxID;
  };

This action argument contains the address and mailbox ID of where the response message should be sent.

whoAsked:

is the address of the engine that sent the message.

mailbox:

is the mailbox ID where the response message should be sent.

CommitmentActionArgument¶

type CommitmentActionArgument := | CommitmentActionArgumentReplyTo ReplyTo;

CommitmentActionArguments¶

CommitmentActionArguments : Type := List CommitmentActionArgument;

Actions¶

CommitmentAction : Type :=
  Action
    CommitmentCfg
    CommitmentLocalState
    CommitmentMailboxState
    CommitmentTimerHandle
    CommitmentActionArguments
    Anoma.Msg
    Anoma.Cfg
    Anoma.Env;

CommitmentActionInput : Type :=
  ActionInput
    CommitmentCfg
    CommitmentLocalState
    CommitmentMailboxState
    CommitmentTimerHandle
    CommitmentActionArguments
    Anoma.Msg;

CommitmentActionEffect : Type :=
  ActionEffect
    CommitmentLocalState
    CommitmentMailboxState
    CommitmentTimerHandle
    Anoma.Msg
    Anoma.Cfg
    Anoma.Env;

CommitmentActionExec : Type :=
  ActionExec
    CommitmentCfg
    CommitmentLocalState
    CommitmentMailboxState
    CommitmentTimerHandle
    CommitmentActionArguments
    Anoma.Msg
    Anoma.Cfg
    Anoma.Env;

commitAction¶

Generate a commitment (signature) for the given request.

State update

The state remains unchanged.

Messages to be sent

A ResponseCommitment message is sent back to the requester.

Engines to be spawned

No engine is created by this action.

Timer updates

No timers are set or cancelled.

commitAction (input : CommitmentActionInput) : Option CommitmentActionEffect :=
  let
    env := ActionInput.env input;
    cfg := ActionInput.cfg input;
    tt := ActionInput.trigger input;
  in case getEngineMsgFromTimestampedTrigger tt of
       | some emsg :=
         case emsg of {
           | mkEngineMsg@{
               msg := Anoma.MsgCommitment (MsgCommitmentRequest request);
             } :=
             let
               signedData :=
                 Signer.sign
                   (CommitmentCfg.signer (EngineCfg.cfg cfg))
                   (CommitmentCfg.backend (EngineCfg.cfg cfg))
                   (RequestCommitment.data request);
               responseMsg :=
                 mkResponseCommitment@{
                   commitment := signedData;
                   err := none;
                 };
             in some
               mkActionEffect@{
                 env := env;
                 msgs :=
                   [
                     mkEngineMsg@{
                       sender := getEngineIDFromEngineCfg cfg;
                       target := EngineMsg.sender emsg;
                       mailbox := some 0;
                       msg :=
                         Anoma.MsgCommitment
                           (MsgCommitmentResponse responseMsg);
                     };
                   ];
                 timers := [];
                 engines := [];
               }
           | _ := none
         }
       | _ := none;

Action Labels¶

commitActionLabel¶

commitActionLabel : CommitmentActionExec := Seq [commitAction];

Guards¶

CommitmentGuard : Type :=
  Guard
    CommitmentCfg
    CommitmentLocalState
    CommitmentMailboxState
    CommitmentTimerHandle
    CommitmentActionArguments
    Anoma.Msg
    Anoma.Cfg
    Anoma.Env;

CommitmentGuardOutput : Type :=
  GuardOutput
    CommitmentCfg
    CommitmentLocalState
    CommitmentMailboxState
    CommitmentTimerHandle
    CommitmentActionArguments
    Anoma.Msg
    Anoma.Cfg
    Anoma.Env;

CommitmentGuardEval : Type :=
  GuardEval
    CommitmentCfg
    CommitmentLocalState
    CommitmentMailboxState
    CommitmentTimerHandle
    CommitmentActionArguments
    Anoma.Msg
    Anoma.Cfg
    Anoma.Env;

commitGuard¶

Condition

Message type is MsgCommitmentRequest.

commitGuard
  (tt : TimestampedTrigger CommitmentTimerHandle Anoma.Msg)
  (cfg : EngineCfg CommitmentCfg)
  (env : CommitmentEnv)
  : Option CommitmentGuardOutput :=
  case getEngineMsgFromTimestampedTrigger tt of
    | some mkEngineMsg@{msg := Anoma.MsgCommitment (MsgCommitmentRequest _)} :=
      some
        mkGuardOutput@{
          action := commitActionLabel;
          args := [];
        }
    | _ := none;

The Commitment behaviour¶

CommitmentBehaviour¶

CommitmentBehaviour : Type :=
  EngineBehaviour
    CommitmentCfg
    CommitmentLocalState
    CommitmentMailboxState
    CommitmentTimerHandle
    CommitmentActionArguments
    Anoma.Msg
    Anoma.Cfg
    Anoma.Env;

Instantiation¶

commitmentBehaviour : CommitmentBehaviour :=
  mkEngineBehaviour@{
    guards := First [commitGuard];
  };