Glossary
Terms and definitions for the merobox ecosystem
30+
terms defined
A–Z
alphabetical
A
AuthManager
Component that manages JWT authentication tokens for merod node endpoints. Handles /auth/token and /auth/refresh calls with disk-based token caching for persistence across runs.
assert (step)
Workflow step type that validates conditions against workflow results. Supports equality, contains, regex, and not_null comparators. Fails the workflow if the assertion is not met.
apply_bootstrap_nodes
Config helper function that injects bootstrap node multiaddresses into a merod config.toml, enabling peer discovery on startup.
apply_e2e_defaults
Config helper that sets sensible defaults for E2E testing: faster timeouts, verbose logging, smaller caches, and disabled rate limiting.
B
BaseStep
Abstract base class for all workflow step types. Defines the validate() and execute() interface. All step types (call, create_context, etc.) inherit from BaseStep.
BinaryManager
Node management backend that spawns native merod processes instead of Docker containers. Uses PID files for tracking and signal-based cleanup (SIGTERM/SIGKILL).
Bootstrap
The process of initializing a new merobox project with default configuration files, workflow templates, and directory structure. Also refers to node bootstrap: the initial peer discovery phase.
C
calimero-client-py
Python JSON-RPC client library for communicating with merod nodes. Used by workflow steps to execute methods, query state, and manage contexts. External dependency.
call (step)
Workflow step type that invokes a method on an application within a context via JSON-RPC. Supports arguments, expected return values, and retry configuration.
Click
Python CLI framework used by merobox for command parsing, argument handling, and help generation. All 7 merobox commands are Click commands or command groups.
ClusterEnv
TypedDict used by the testing module to describe a running cluster environment: node endpoints, sandbox URL, deployed contracts, and auth tokens.
Context
A Calimero context binds a WASM application to a group of nodes. In merobox, the create_context step creates one, and subsequent steps reference it by context_id.
config.toml
TOML configuration file for merod nodes. Generated by DockerManager or BinaryManager with per-node settings: ports, bootstrap nodes, NEAR config, and storage paths.
D
DockerManager
Primary node management backend. Uses the Docker SDK to manage container lifecycle: image pull, network creation, container creation/start/stop/remove, and volume management.
Docker SDK (docker-py)
Python library for interacting with the Docker Engine API. Used by DockerManager for all container operations.
Dynamic Values
Placeholder references like ${results.step_name.field} that are resolved at step execution time from the workflow_results dictionary.
E–F
Environment Variables
Placeholders in YAML like ${CONTRACT_DIR} that are expanded at parse time from the shell environment. Different from dynamic values which resolve at runtime.
fuzzy_test (step)
Advanced step type that generates random inputs, executes calls across multiple nodes, and verifies eventual consistency of state. Used for chaos/fuzz testing of CRDT convergence.
fail()
Helper function that creates a failed StepResult with an error message. Triggers workflow cleanup unless the step has special error handling.
G–J
Genesis
The initial state of the NEAR sandbox, created by near-sandbox init. Includes the root account (test.near) with initial balance.
JSON-RPC
The protocol used to communicate with merod nodes. calimero-client-py sends JSON-RPC 2.0 requests to node endpoints for method execution and state queries.
JWT
JSON Web Token. Used by AuthManager to authenticate with merod nodes. Tokens are cached to disk and refreshed on expiry.
M–N
merod
The Calimero node daemon binary. merobox manages merod instances via Docker containers or native subprocesses.
MeroboxError
Root exception class for all merobox errors. Subclasses include NodeResolutionError, AuthenticationError, WorkflowError, ConfigurationError, and MeroboxTimeoutError.
NEAR Sandbox
A local, single-validator NEAR blockchain instance used for E2E testing. SandboxManager downloads and manages the near-sandbox binary, exposing RPC on port 3030.
NearDevnetClient
High-level wrapper around py-near that provides account creation, key management, contract deployment, and token transfer operations against the NEAR sandbox.
NodeResolver
Component that determines how each declared workflow node maps to a running merod instance. Resolution order: registered remote → URL → Docker → binary.
Nuke
The operation of destroying all merobox-managed resources: stopping containers, killing binary processes, removing volumes, clearing sandbox data, and deleting PID files.
O–P
ok()
Helper function that creates a successful StepResult with optional data. The data dict is stored in workflow_results for use by subsequent steps.
parallel (step)
Control-flow step type that executes multiple sub-steps concurrently using asyncio.gather. Supports fail-fast mode where remaining steps are cancelled on first failure.
PID File
File containing a process ID, written by BinaryManager when spawning merod processes. Used for process tracking and cleanup.
Placeholder
A template variable in YAML config: ${ENV_VAR} for environment variables (parse-time) or ${results.step.field} for dynamic values (runtime).
R
Relayer Mode
NEAR integration mode where merobox connects to an existing NEAR network (testnet/mainnet) via a relayer account for meta-transactions, instead of running a local sandbox.
RemoteNodeManager
Component that registers and manages remote node connections via the portal API. Used when workflows reference pre-existing merod instances.
repeat (step)
Control-flow step type that loops a sequence of sub-steps a specified number of times. Exposes an iteration variable accessible by child steps.
RetryConfig
Configuration object for the retry system: max retries, base delay, max delay, backoff factor, jitter, and which error types are retryable.
S
SandboxManager
Component that manages the local NEAR sandbox lifecycle: binary download, genesis initialization, process management, health checking, and shutdown.
script (step)
Utility step type that runs arbitrary shell commands. Captures stdout, stderr, and exit code. Useful for custom validation or setup tasks.
Step
The atomic unit of work in a workflow. Each step has a type (call, assert, etc.), optional name (for result storage), and type-specific configuration.
StepFactory
Registry that maps step type strings to their corresponding BaseStep subclass. Used by WorkflowExecutor to instantiate the correct handler for each step in the YAML.
StepResult
Return type of BaseStep.execute(). Contains success flag, data dict, optional error message, exception reference, and execution duration.
T–W
Traefik
Reverse proxy deployed alongside Docker containers to provide unified HTTP routing. Routes requests to merod containers based on Host headers and path prefixes.
wait_for_sync (step)
Step type that polls nodes until they all report synchronized state for a given context. Uses configurable timeout and poll interval.
Workflow
A YAML file that declares nodes and an ordered sequence of steps. Executed by the WorkflowExecutor, which manages the full lifecycle from environment setup to teardown.
WorkflowEnv
TypedDict used by the testing module’s workflow() context manager. Provides access to the running environment: nodes, sandbox, results, and cleanup.
WorkflowExecutor
The core orchestration engine. Manages the full lifecycle: parse YAML → nuke → pull → sandbox → deploy → nodes → register → steps → cleanup. Maintains the workflow_results dictionary.
workflow_results
Dictionary maintained by WorkflowExecutor that accumulates step outputs. Keys are step names, values are the data dicts returned by ok(). Used for placeholder resolution.
@with_retry
Decorator that wraps async functions with automatic retry logic using exponential backoff. Configured via RetryConfig. Only retries on specified exception types.