Transaction Lifecycle

This document outlines a transaction's process from initiation to completion within the system. It details the validation steps and the structure of the response upon completion.

Transaction Properties

Each transaction submitted to the system includes the following properties:

• Operations: This defines the specific actions to be performed within the transaction. These operations are executed sequentially.

• Address: This identifies the user account associated with the transaction.

• Nonce: This value serves as a unique identifier for transactions a user submits. It helps prevent replay attacks.

Transaction Validation

Before processing a transaction, the system performs the following validation checks:

1. Signature Validation: The system verifies the digital signature associated with the transaction. This ensures the transaction originated from the authorized user.

2. Nonce Validation: The system checks if the provided nonce is the next expected value in sequence for the user's transactions. Initially, only consecutive nonces are accepted. Future support for out-of-sequence nonces is planned, with such nonces being stored for later processing.

3. Operation Validation: Each operation within the transaction is validated to ensure its feasibility within the system. These operations are then executed sequentially.

4. Nonce Update: Upon successful validation, the user's nonce is incremented to prevent future replay of the same transaction.

5. Transaction Event Payload Generation: After successful validation and execution, a TransactionEvent payload is generated to communicate the outcome.

Transaction Completion

Once the validation and operation execution are complete, the Operation Handler transmits a response containing the transaction status and any relevant events. The structure of this response is defined by the TransactionEvent interface.

TransactionEvent Payload

The TransactionEvent interface defines the format of the response sent after transaction completion.

interface TransactionEvent {
  status: "PENDING" | "FAIL" | "SUCCESS";
  message: string;
  signature: string;
  events?: Event[];
  error?: {
    code: string;
    message: string;
  };
}

The status property indicates the outcome of the transaction:

• PENDING: This status is used when processing is ongoing, and no outcome is available yet. In this case, the transaction and error properties are not set.

• SUCCESS: This status signifies successful transaction completion. The transaction property must be set, containing details of the processed transaction, while the error property remains empty.

• FAIL: This status indicates a failed transaction. The error property must be set, containing an error code and message explaining the failure reason. The transaction property remains empty.

Note: The transaction hash is calculated separately as per the defined mechanism (refer to Transaction Hash) and is not included in the TransactionEvent payload.

Additionally, the TransactionEvent payload can include an events property. This property is an array of Event objects that describe events emitted during successful transaction execution.

interface Event {
  action: string;
  type: string;
  args: string[];
  collectionId?: string;
}

The Event interface defines the structure of individual event objects:

• action: This field specifies the specific action performed within the transaction.

• type: This field categorizes the event type.

• args: This array holds any arguments associated with the event.

• collectionId (optional): This property can optionally identify a collection involved in the event (applicable if relevant).

Example

{
  "status": "SUCCESS",
  "signature": "0x00",
  "message": "",
  "events": [
    {
      "type": "asset-link",
      "action": "delete",
      "args": [
        "equipWith_asmBrain",
        "1:evm:0x6bca6de2dbdc4e0d41f7273011785ea16ba47182:1000",
        "1:evm:0x1ea66a857de297471bc12dd12d93853ff6617284:200",
      ],
      "collectionId": "1:evm:0x6bca6de2dbdc4e0d41f7273011785ea16ba47182"
    }
  ]
}

Example webhook rule

{
  "events": {
    "type": ["asset-link"],
    "action": ["delete"],
    "collectionId": "1:evm:0x6bca6de2dbdc4e0d41f7273011785ea16ba47182:1000"
  }
}

End-to-End Transaction Sequence Diagram