Skip to content
Juvix imports

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
commitAction flowchart

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

Auxiliary Juvix code

CommitmentAction

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

CommitmentActionInput

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

CommitmentActionEffect

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

CommitmentActionExec

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

Auxiliary Juvix code

CommitmentGuard

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

CommitmentGuardOutput

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

CommitmentGuardEval

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];
};