mvx_project_architecture_skill

This skill provides production-grade MultiversX project structure patterns, enabling clean trait-based contract design, modular modules, and safer upgrades.

10

GitHub Stars

1

Bundled Files

2 months ago

Catalog Refreshed

4 months ago

First Indexed

Readme & install

Copy the install command, review bundled files from the catalogue, and read any extended description pulled from the listing source.

Installation

Preview and clipboard use veilstrat where the catalogue uses aiagentskills.

npx veilstrat add skill multiversx/mx-ai-skills --skill mvx_project_architecture

SKILL.md2.3 KB

Overview

This skill documents production-grade project structure patterns for building MultiversX smart contracts. It prescribes a clear file layout, lib.rs responsibilities, naming conventions, and when to extract shared crates. The goal is consistency, testability, and safe upgrade paths for contracts.

How this skill works

The guide splits contract code into focused modules: a minimal lib.rs that composes trait modules, dedicated files for storage, views, config, events, validation, errors, and helpers, plus separate meta, wasm, and test folders. It enforces lib.rs as trait composition only (init/upgrade/entrypoints call into modules) and centralizes static error strings and naming rules to avoid ambiguity. When multiple contracts share identical logic, it recommends extracting that code into a common workspace crate.

When to use it

Starting a new MultiversX smart contract project to enforce maintainable structure
Refactoring a monolithic contract into testable, composable modules
Preparing contracts for safe upgrades and clear initialization logic
Sharing math, struct, error, or event definitions across two or more contracts
Standardizing naming and ABI visibility for a team or organization

Best practices

Keep lib.rs minimal: only trait composition plus init and upgrade handlers
Place persistence mappings in storage.rs and keep keys consistent (camelCase)
Define all static error messages in errors.rs using SCREAMING_SNAKE constants
Implement pure logic in helpers.rs so functions are easier to unit-test
Extract common structs, math, errors, and events to a common workspace crate when reused

Example use cases

A single-token liquidity pool contract with storage, views, and admin config separated
An upgradeable governance contract where init/upgrade remain thin and modules handle logic
A suite of DeFi contracts sharing token math and error types moved into a common crate
A wallet or bridge contract with clear validation and event modules for auditability

FAQ

Minimizing lib.rs reduces coupling, makes upgrades safer, and forces implementation details into testable modules.

When should I create a common crate?

If the same structs, math, errors, or events appear in two or more contracts, extract them to a shared crate to avoid duplication and ensure consistency.