High-level Architecture

Shardeum Core Frame

1. What the Core Protocol does:

  • Handling sharding and consensus: Shardus Core Protocol focuses on managing sharding and making sure that all parts of the network agree (consensus). It's designed to not worry about the specific details of what's happening in transactions on the dapps that run on Shardeum.
  • Staying neutral: The protocol doesn’t deal directly with the data or actions of transactions in dapps. It uses a set of simple commands (APIs) that help it stay out of the specifics, meaning it doesn’t know or need to know what each transaction is about.

2. DApps and their interaction with Shardus Core Protocol

  • Connecting through APIs: Dapps on Shardeum, especially those that work like Ethereum Dapps, talk to the core protocol using a specific set of commands known as an API. This lets the Dapps use important features like agreement and data accuracy, while they can still do their own thing for their specific needs. Here you can see all of them.
  • DApps keep their own rules: Each dapp on Shardeum has its own set of rules and logic that fit what the dapp is designed to do. This setup means that even if dapps change or update, they don’t mess with the core protocol. This makes it easier to add new features to dapps without complicating things.

3. Benefits of Shardeum’s design:

  • Freedom to create: Developers can build new and varied dapps without being limited by the system underneath. This freedom means they can quickly adapt to new needs and ideas.
  • Easy to grow: Because the core protocol stays out of the dapp details, Shardeum can grow and improve without being bogged down by changes in individual dapps.
  • Safe and stable: Keeping the core system separate from the dapps means the whole network is safer and more stable. It protects the core from any risky or poorly made dapp code.

4. More about how it works:

  • Handling data: The core protocol takes care of the big picture stuff like making sure all parts of the network are working together. It doesn’t store or deal with specific dapp data; dapps handle their own data and only talk to the core protocol for making sure everyone agrees.
  • Managing nodes: The rules about how nodes (the individual parts of the network) operate are detailed in the protocol's documentation. The core protocol manages whether nodes are active or on standby, but it doesn’t get involved in the specific data that nodes deal with for dapps.


Shardeum is an EVM based L1 that uses dynamic state sharding to achieve linearly scalability while attaining atomic composability across shards. This means Shardeum can increase its TPS capacity with each validator added to the network to retain low fees forever.

Shardeum provides the highest throughput capacity of any EVM based L1 without sacrificing on decentralization. Developers can deploy and interact with Solidity or Vyper contracts without special considerations for sharding, since contracts are deployed to unique shards automatically while retaining atomic composability across all shards.

Shardeum is the solution to the blockchain trilemma. As blockchain tries to achieve scalability, decentralization and security, it will only be able to attain two. There must be a trade-off between decentralization and scalability with security an essential element. Shardeum achieves scalability, decentralization and still maintains security.

Shardeum’s auto-scaling feature allows the network to automatically adjust the number and size of shards based on the current workload. This allows the system to optimize performance and maintain high levels of scalability as it grows and evolves.

1. Integration

  • Shardeum is built on the foundation of the Shardus Core Protocol, presenting itself as the first EVM-compliant Layer 1 blockchain, optimized for dynamic sharding.
  • This architecture uniquely enables the network to scale transaction throughput linearly with the addition of nodes, addressing the scalability issues commonly faced by traditional blockchains.
  • Shardeum is designed to support a diverse array of DApps, making it a versatile platform for developers and businesses.

2. Shardeum's Features

  • Dynamic State Sharding: This is the most advanced and complex way to shard the state of a network because it shards the State, Network, and Transactions dynamically, as opposed to a pre-determined way.
  • Linear Scalability: Specifically refers to the fact that a system can increase its throughput as more resources are provided, and the relationship between throughput and resources is linear.
  • Low Transaction Fees: The minimal costs associated with processing and confirming transactions on a blockchain network. These fees are paid by users to incentivize miners or validators to include their transactions in the next block of the blockchain.
  • EVM-based Smart Contract Platform: Refers to the compatibility of a blockchain network with the Ethereum Virtual Machine (EVM), allowing it to execute smart contracts and transactions that are compatible with Ethereum's existing ecosystem.
  • Solves Scalability Trilemma: Achieves a balance between decentralization, security, and scalability. Typically, enhancing scalability can compromise either decentralization or security, but innovative solutions like sharding, layer 2 protocols, and consensus algorithm improvements aim to address all three aspects simultaneously.
  • Auto Scaling: Adjusts computational resources automatically based on demand, ensuring optimal performance and cost efficiency. It handles traffic spikes efficiently, providing a seamless user experience without manual intervention.
  • Security: Ensures the protection of data integrity, transaction authenticity, and network resilience against attacks. Strong cryptographic protocols and consensus mechanisms are fundamental to maintaining high security in blockchain systems.
  • Immediate Finality: Ensures that once a transaction is confirmed, it cannot be altered, reversed, or double-spent. This is crucial for applications requiring quick and definite transaction settlements.
  • Low Latency: Refers to the minimal delay between the initiation of a transaction and its confirmation, essential for applications needing quick transaction processing and user responsiveness.
  • Low Bandwidth: Operates efficiently with minimal data transmission requirements, reducing operational costs and enabling access in regions with limited internet infrastructure.
  • High Fairness: Ensures that all participants have equal opportunities to validate transactions and propose new blocks, maintaining fairness through decentralized consensus mechanisms and transparent protocols.
  • High Capacity: The network's ability to handle a large volume of transactions per second (TPS), crucial for scalability, enabling the network to support a growing number of users and applications without performance degradation.

3. Shardus Core Protocol

  • Base protocol: The Shardus Core Protocol handles sharding and consensus without needing to know the specifics of application-level transactions. This separation ensures modularity and security, allowing the protocol to function independently of the DApps running on top of it. Here, you can take a look at how we successfully integrate the Shardus software.
const shardusSetup = (): void => {
   * interface tx {
   *   type: string
   *   from: string,
   *   to: string,
   *   amount: number,
   *   timestamp: number
   * }
    sync: sync(shardus, evmCommon),
    validateTransaction: validateTransaction(shardus),
    validateTxnFields: validateTxnFields(shardus, debugAppdata),
    async apply(timestampedTx: ShardusTypes.OpaqueTransaction, wrappedStates, originalAppData) {
  • API interaction: DApps interact with the Shardus Core Protocol through a defined API. This abstraction ensures that the core protocol does not directly access or manipulate application data, maintaining a clear boundary between the protocol and the applications.

4. EVM Compliance

  • Smart contracts: Shardeum supports the execution of Ethereum smart contracts, allowing developers to deploy their existing contracts without modification.
  • Tool compatibility: All tools and applications built for Ethereum can run on Shardeum, facilitating easy migration and adoption.
  • Execution environment: By maintaining EVM compatibility, Shardeum leverages the robustness and familiarity of the Ethereum ecosystem, making it accessible for developers.
  • EVM Initialization: Click here to examine the code in our repos.
if (ShardeumFlags.UseDBForAccounts === true) {
  AccountsStorage.init(config.server.baseDir, `${FilePaths.SHARDEUM_DB}`)
  if (isServiceMode()) AccountsStorage.lazyInit()
const appliedTxs = {} 
const shardusTxIdToEthTxId = {}
const defaultBalance = isDebugMode() ? oneSHM * BigInt(100) : BigInt(0)
const ERC20TokenBalanceMap: {
  to: string
  data: unknown
  timestamp: number
  result: unknown
}[] = []
const ERC20TokenCacheSize = 1000
interface RunStateWithLogs extends RunState {
  logs?: []
let EVM: { -readonly [P in keyof VM] }
let shardeumBlock: ShardeumBlock
let shardeumStateTXMap: Map<string, ShardeumState>
let shardusAddressToEVMAccountInfo: Map<string, EVMAccountInfo>
export let evmCommon
let debugAppdata: Map<string, unknown>
async function initEVMSingletons(): Promise<void> {
  const chainIDBN = BigInt(ShardeumFlags.ChainID)
  evmCommon = new Common({ chain: 'mainnet', hardfork: Hardfork.Istanbul, eips: [3855] })
  evmCommon.chainId = (): bigint => {
    return BigInt(chainIDBN.toString(10))
  shardeumBlock = new ShardeumBlock({ common: evmCommon })
  if (ShardeumFlags.useShardeumVM) {
    const customEVM = new EthereumVirtualMachine({
      common: evmCommon,
      stateManager: undefined,
    EVM = await VM.create({
      common: evmCommon,
      stateManager: undefined,
      evm: customEVM,
  shardeumStateTXMap = new Map<string, ShardeumState>()
  shardusAddressToEVMAccountInfo = new Map<string, EVMAccountInfo>()
  debugAppdata = new Map<string, unknown>()

On this page