playbooks

home / skills / multiversx / mx-ai-skills / mvx_protocol_experts

mvx_protocol_experts skill

/antigravity/skills/mvx_protocol_experts

This skill provides expert guidance on the MultiversX Protocol, SPoS, sharding, and MIPs to review architecture and ensure safe, scalable dApp designs.

npx playbooks add skill multiversx/mx-ai-skills --skill mvx_protocol_experts

Review the files below or copy the command above to add this skill to your agents.

Files (1)
SKILL.md
3.0 KB
---
name: mvx_protocol_experts
description: Expert knowledge of the MultiversX Protocol, Consensus (SPoS), Sharding, and Standard Implementations (MIPs).
---

# MultiversX Protocol Expertise

This skill encompasses deep knowledge of the core MultiversX protocol architecture, utilized for reviewing protocol-level changes, complex dApp architectures involving cross-shard logic, and sovereign chain integrations.

## 1. Core Architecture: Adaptive State Sharding
- **Sharding Types**:
    - **Network Sharding**: Nodes are distributed into shards.
    - **Transaction Sharding**: Transactions are processed by the shard containing the sender's account.
    - **State Sharding**: Each shard maintains a portion of the global state (account space).
- **Metachain**:
    - The coordinator shard.
    - Handles: Validator churning, Epoch/Round verification, Slashing, Header notarization.
    - **Does NOT** execute general smart contracts (except for system contracts like Staking, ESDT management).
- **Cross-Shard Transactions**:
    - **Async (Process -> Relay -> Execute)**: Sender Shard processes TX -> Generates internal transaction (Scratchpad) -> Relayer -> Receiver Shard executes.
    - **Atomicity**: Cross-shard is atomic but asynchronous.

## 2. Consensus: Secure Proof of Stake (SPoS)
- **Selection**: Deterministic selection of validators based on stake + rating.
- **BLS Signing**: Validators sign proposed blocks using BLS multi-signatures.
- **Finality**: Instant finality (within seconds) due to PBFT-like consensus within the shard.

## 3. Token Standards (ESDT)
- **Native Implementation**: Tokens are NOT smart contracts (unlike ERC-20). They are part of the protocol account state.
- **ESDT Properties**:
    - **CanFreeze**: Protocol can freeze assets if configured.
    - **CanWipe**: Protocol can wipe assets if configured.
    - **CanPause**: Protocol can pause transfers.
- **Roles**:
    - `ESDTRoleLocalMint`: Allows minting.
    - `ESDTRoleLocalBurn`: Allows burning.

## 4. Sovereign Chains & Interoperability
- **Sovereign Chains**: Dedicated blockchains extending MultiversX.
    - **Gateway Contract**: Handles bridging between Mainchain and Sovereign Chain.
    - **Settlement**: Sovereign Chains settle proofs to the MultiversX Mainchain (acting as Layer 1).
- **Interoperability Standards**:
    - **MIP-X**: Monitor [MIPs] for latest standard adoption.

## 5. Transaction Processing
- **Gas Schedule**: Operations have deterministic costs.
- **Built-in Functions**:
    - `ESDTTransfer`: Direct transfer.
    - `ESDTNFTTransfer`: Transfer of SFT/NFT.
    - `MultiESDTNFTTransfer`: Batch transfer (often used for Contract calls).

## 6. Critical Checks for Protocol Developers
- **Intra-shard vs Cross-shard**:
    - Always assume a call *might* be cross-shard unless verified co-location.
    - **Async**: If logic depends on the result of a call to another address, it MUST be an Async Call (Callbacks).
- **Reorg Handling**:
    - Microservices must handle block rollbacks (Standard: wait for 'Finalized' status, or handle re-org events).

Overview

This skill provides expert knowledge of the MultiversX protocol, including adaptive state sharding, SPoS consensus, ESDT token semantics, and sovereign chain patterns. It is designed to help protocol reviewers, dApp architects, and integrators reason about cross-shard logic, token behavior, and secure integration patterns. The content emphasizes practical checks and common pitfalls for production-grade systems.

How this skill works

The skill inspects and explains MultiversX core components: network/transaction/state sharding, the metachain coordinator, and cross-shard transaction flow (Process -> Relay -> Execute). It details the SPoS consensus mechanics, BLS multi-signing, and instant finality within shards. It also covers ESDT native token behaviors, built-in transfer primitives, and sovereign chain gateway/settlement patterns for interoperability.

When to use it

  • Designing dApps that may invoke accounts across shards or require cross-shard callbacks
  • Reviewing protocol-level proposals, MIPs, or consensus/validator changes
  • Auditing token logic that depends on native ESDT capabilities (mint/burn/freeze)
  • Integrating a sovereign chain or building bridge/gateway contracts
  • Implementing backend services that must handle reorgs and finality semantics

Best practices

  • Assume a call may be cross-shard unless you verify co-location; use async calls with callbacks when results are required
  • Wait for finalized status or explicitly handle re-org events in off-chain services
  • Use protocol-native ESDT operations for token transfers instead of emulating tokens in smart contracts
  • Design cross-shard flows as atomic-but-asynchronous and account for relay/latency delays
  • Leverage BLS signature properties and deterministic validator selection when modelling validator or slashing logic

Example use cases

  • Architecting a cross-shard marketplace that safely updates buyer and seller balances via async callbacks
  • Reviewing a MIP that changes validator selection, slashing, or epoch handling
  • Designing a sovereign chain gateway and settlement process to post proofs back to Mainchain
  • Implementing an indexer or microservice that tracks only finalized state to avoid inconsistent reads
  • Creating batch transfer tooling using MultiESDTNFTTransfer for efficient contract interactions

FAQ

Are ESDT tokens implemented as smart contracts?

No. ESDT tokens are native protocol state entries, not smart contracts, so they use protocol-level operations for transfer, minting, and burning.

How should I handle cross-shard dependencies in contract logic?

Treat cross-shard calls as asynchronous: emit an internal transaction/scratchpad, use a relayer, and implement callbacks to handle execution results and maintain atomic semantics.