Skip to content
Veive

Account interface and flows

The Account interface in the Veive protocol is a critical component that facilitates the interaction with smart accounts. It manages the flow of operations through various modules, ensuring that all actions are validated, executed, and logged according to the specified rules. Below, we detail each method of the Account interface, including their purpose, modules involved, requirements, and sequence diagrams illustrating the process flow.

Requirements

Section titled “Requirements”

In the Veive protocol’s Account interface, “requirements” are a set of predefined conditions that must be met for specific methods to be executed. These requirements serve as safeguards, ensuring that operations are carried out securely and in accordance with the defined rules and policies. Each requirement checks for specific conditions related to the caller, the operation, or the context in which the method is invoked.

Types of Requirements:

  1. _require_only_self: Ensures that the method can only be called by the contract itself. This requirement is used to protect functions that should only be invoked internally, preventing unauthorized access or modification.
  2. _require_not_self: Ensures that the method is not called by the contract itself. This requirement protects functions that should only be accessed by external entities, ensuring proper segregation of internal and external calls.
  3. _require_only_executor: Ensures that the method is only callable by a registered execution module. This requirement guarantees that certain operations are restricted to execution modules, preventing unauthorized actions.
  4. _require_not_executor: Ensures that the method is not called by a registered execution module. This requirement is used to protect functions from being invoked by modules that are meant to perform execution rather than control operations.
  5. _require_not_caller: Ensures that there is no caller. This is typically used in contexts where an operation should not be invoked by any external or internal caller, often used in initialization or special cases.
  6. _require_valid_operation: Validates the operation’s legitimacy and compliance with the predefined rules and conditions. This requirement ensures that all operations are checked for validity before execution, safeguarding against malicious or erroneous actions.

These requirements are crucial for maintaining the integrity and security of the account operations within the Veive protocol. They provide a structured way to enforce access control and operational validation, ensuring that all actions are authorized and appropriate within the context of the smart account’s governance framework.

Certainly! Let’s include the responses in the sequence diagrams to provide a complete picture of the interactions. Below is the updated explanation along with the revised sequence diagrams:

Account Class Overview

Section titled “Account Class Overview”

The Account class in the Veive protocol is a sophisticated, modular system designed to manage smart account functionalities on the Koinos blockchain. It facilitates the interaction between users, DApps, and various modules, providing a secure and flexible environment for executing and managing blockchain operations. The class contains several methods, each serving distinct purposes, from executing transactions to managing modules.

Methods and Their Descriptions

Section titled “Methods and Their Descriptions”

1. execute(args: account.execute_args): void

Purpose:
The execute method is responsible for executing specified operations after ensuring they are valid and secure. It performs pre-checks and post-checks using registered hook modules and executes the operation through the appropriate execution modules. This method ensures that all necessary validations are performed before and after an operation is executed, enhancing the security and reliability of transactions.

  • Modules Called: Validation Modules, Hook Modules (pre_check, post_check), Execution Modules
  • Requirements: _require_valid_operation, _require_not_self, _require_not_executor

HookModulePostExecutionModuleHookModulePreValidationModuleAccountDAppUserHookModulePostExecutionModuleHookModulePreValidationModuleAccountDAppUserInitiates operationexecute(args)_require_valid_operation_require_not_self_require_not_executorvalidate_operationReturns resultpre_checkReturns dataexecuteReturns resultpost_check(data)Returns resultReturns result

2. execute_executor(args: account.execute_executor_args): void

Purpose:
The execute_executor method allows execution modules to perform operations, provided they are authorized and meet the required conditions. This method is particularly useful for internal operations initiated by smart contracts, ensuring that only registered execution modules can invoke certain operations.

  • Modules Called: Hook Modules (pre_check, post_check), Execution Modules
  • Requirements: _require_valid_operation, _require_not_self, _require_only_executor

HookModulePostExecutionModuleHandlerHookModulePreAccountExecutionModuleHookModulePostExecutionModuleHandlerHookModulePreAccountExecutionModuleexecute_executor(args)_require_valid_operation_require_not_self_require_only_executorpre_checkReturns dataexecuteReturns resultpost_check(data)Returns resultReturns result

3. execute_user

Purpose:

The execute_user method is specifically designed for user-initiated operations. It serves to directly execute a user-requested operation after ensuring that it meets the necessary validation criteria. This method does not call any pre-checks or execution modules, but it does validate the operation using all registered Validation Modules. This process ensures that the operation adheres to the set rules and that the caller is authorized to perform the action. This is especially relevant for operations like token transfers or contract interactions initiated directly by the user.

  • Modules Called: Validation Modules
  • Requirements: _require_valid_operation, _require_not_caller

ValidationModuleAccountDAppUserValidationModuleAccountDAppUserInitiates operationexecute_user(operation)_require_valid_operation_require_not_callervalidate_operationReturns result (valid/invalid)System.call(operation)Returns execution result

4. install_module

Purpose:
The install_module method is used to install a new module of the specified type, such as validation, execution, signature, or hooks. This method allows the account to dynamically extend its capabilities by adding new modules, which can then interact with blockchain operations according to their defined scopes.

  • Modules Called: None (direct interaction with storage)
  • Requirements: _require_only_self

ValidationModuleAccountDAppUserValidationModuleAccountDAppUserRequest install moduleexecute_user(install_module operation)_require_valid_operationis_valid_operationReturns valid/invalid_require_only_selfInstall moduleReturns success/failure

5. uninstall_module

Purpose:
The uninstall_module method removes a module from the account’s registry. This method is essential for maintaining the security and integrity of the account by allowing outdated or unnecessary modules to be safely removed.

  • Modules Called: None (direct interaction with storage)
  • Requirements: _require_only_self

ValidationModuleAccountDAppUserValidationModuleAccountDAppUserRequest uninstall moduleexecute_user(uninstall_module operation)_require_valid_operationis_valid_operationReturns valid/invalid_require_only_selfUninstall moduleReturns success/failure

6. is_valid_signature

Purpose:
The is_valid_signature method verifies the authenticity of a transaction by validating the signature. This method is critical for ensuring that transactions are authorized by the rightful account owner.

  • Modules Called: Signature Modules
  • Requirements: None

SignatureModuleAccountCallerSignatureModuleAccountCalleris_valid_signature(signature)validate_signatureReturns resultReturns result

7. is_valid_operation

Purpose:
The is_valid_operation method checks the validity of an operation using all registered validator modules. The operation is considered valid if all validators approve it.

  • Modules Called: Validation Modules
  • Requirements: None

ValidationModuleAccountCallerValidationModuleAccountCalleris_valid_operation(operation)validate_operationReturns resultReturns result

8. authorize

Purpose:
The authorize method checks if a given operation is authorized based on the type and provided arguments. This method ensures that operations, especially those involving cross-contract calls, are properly authorized according to the account’s rules and permissions. It is automatically called by Koinos for each “external” operation (cross-contract call) that requires authorization, providing a deeper level of security by validating internal contract interactions.

  • Modules Called: Validation Modules
  • Requirements: None

ValidationModuleAccountExternalContractValidationModuleAccountExternalContractauthorize(operation)validate_operationReturns resultReturns result