Welcome to the æternity user tools section, where you'll find practical guides for participating in and utilizing the æternity blockchain. Whether you're interested in running a node to support the network, mining AE tokens, creating your first NFT, or simply setting up a wallet to store and transfer tokens, you'll find step-by-step instructions here. These guides are designed to be accessible while providing the technical details needed for successful interaction with the network. Each section walks you through the necessary tools, requirements, and best practices to help you get started.

æternity is a highly scalable blockchain platform designed with developers in mind, offering unique features like state channels, oracles, naming system, and the secure Sophia smart contract language. This Quick Start Guide will walk you through everything you need to begin building decentralized applications (æpps) on æternity. Whether you're creating smart contracts, implementing state channels, or building full-scale applications, we'll cover the essential tools, development environment setup, and core concepts you need to get started. By following this guide, you'll learn how to interact with the æternity blockchain at every level - from the FATE virtual machine up to end-user applications - and be ready to leverage æternity's powerful features for your projects.

The æternity network layer forms a sophisticated decentralized infrastructure that enables seamless node communication and efficient transaction processing. At its core, the network utilizes a gossip protocol for rapid message propagation across all nodes, ensuring that transactions and blocks are quickly distributed throughout the ecosystem. The Stratum protocol facilitates efficient mining operations and pool management, allowing miners to participate in securing the network. Additionally, æternity provides utility features that enhance network functionality and user experience. The following sections delve into each of these network components, providing detailed explanations of how they work together to maintain a robust, scalable, and secure blockchain network.

Engaging with the æternity Blockchain

The æternity blockchain presents a variety of opportunities for both users and developers to engage with its features and contribute to its growth. Whether you're interested in utilizing decentralized applications, building innovative solutions, or actively participating in the network's development, æternity offers a range of avenues for involvement.

æternity blockchain users

As a user, you can experience the benefits of blockchain technology through intuitive and user-friendly interfaces. For example, the Æternity Naming System (ÆNS) allows you to register human-readable names, simplifying transactions and reducing the chance of errors. You can manage your AE coins, the native currency of æternity, through compatible wallets, and engage with various decentralized applications (aepps) built on the platform. Further, as an AE coin holder, you can actively participate in the platform's governance by voting on proposals that shape the future development of æternity.

æternity for developers

æternity offers a robust and developer-friendly environment for building and deploying innovative blockchain solutions. The Sophia smart contract language provides a secure and clear syntax, minimizing vulnerabilities and simplifying the development process. Sophia contracts are executed on the FATE virtual machine, designed for efficiency and optimized for low gas costs. The platform provides various Application Programming Interfaces (APIs) and Software Development Kits (SDKs) and libraries to support development across multiple programming languages. Developers can contribute to the network's decentralization and security by running a full node, and even participate in mining AE coins using the memory-bound Cuckoo Cycle algorithm. Additionally, as an open-source project, developers can contribute code to various components of the æternity ecosystem, including the core protocol, Sophia compiler, and FATE VM. Now, with the advent of æternity Hyperchains, organizations can deploy secure, purpose-built blockchain solutions that leverage the robustness of established networks without sacrificing independence, efficiency, or flexibility.

Building upon the foundation of æternity, developers can explore a wide range of possibilities, such as:

• Creating fungible and non-fungible tokens utilizing the AEX-9 and AEX-141 standards, respectively.

• Developing decentralized exchanges (DEXs) based on automated market makers (AMMs) to facilitate trustless token trading.

• Implementing secure multi-signature wallets that enhance security and control over transactions.

• Designing applications that leverage the power of off-chain state channels for faster and more private transactions.

The tools and resources provided by æternity empower developers to create innovative solutions across various domains, expanding the functionality and reach of the blockchain ecosystem.

Community involvement forms a crucial aspect of the æternity ecosystem. Whether you're a user seeking information or a developer looking to collaborate, there are numerous avenues for engagement. You can join the æternity community forum and Discord server to discuss the platform, seek assistance, and share your ideas. the æternity telegram group provide a platform for connecting with æternity enthusiasts from all around the globe. Stay updated on the latest news and developments through æternity's blog, as well as the æternity forum.

The æternity blockchain is built upon the principles of security, scalability, and user-friendliness. It offers a comprehensive ecosystem for users and developers to participate in and shape the future of decentralized technology. Whether it's through the use of aepps, the development of innovative solutions, or active involvement in the community, æternity provides the tools and infrastructure for a thriving and collaborative blockchain ecosystem.

Feel free to explore the topics outlined in the sidebar menu, or jump to different sections of the aeternity Hub using the links below:

Founded in 2016 by Yanislav Malahov, the æternity blockchain project was born out of a desire for a more fair Internet supported by scalable, open-source and cryptographic software, with a commitment to technical excellence. æternity blockchain itself launched as the public æternity mainnet in 2018. It is now a blossoming community of users and developers supported via the Aeternity Foundation.

æternity is an open-source blockchain platform designed to deliver scalable and secure smart contracts. It uses a Proof-of-Work (PoW) consensus mechanism similar to Bitcoin but incorporates several innovations to improve upon traditional PoW blockchains. At its core, æternity utilizes a system called "Bitcoin-NG" (Next Generation Nakamoto Consensus), which increases throughput by separating leader election from transaction inclusion. In this system, miners compete to solve complex mathematical problems (Cuckoo Cycle algorithm) to become "leaders." The leader can then create multiple blocks containing transactions (called micro-blocks) for a set period. This results in faster transaction processing and reduced latency compared to blockchains like Bitcoin.

æternity distinguishes itself from other blockchains through several key features:

• : To further boost transaction speed and privacy, æternity employs state channels, enabling participants to interact and execute smart contracts off-chain, only settling the final result on the main blockchain. This leads to near-instant transaction confirmations and significantly reduces fees.

• Sophia: æternity utilizes , a functional programming language for writing smart contracts. Sophia is designed with an emphasis on security and clarity, minimizing common vulnerabilities found in other smart contract languages. The use of Sophia aims to make smart contracts more robust and easier to audit.

• : The FATE (Fast æternity Transaction Engine) virtual machine executes Sophia smart contracts. FATE is designed for efficiency and security, featuring typed operations, a restricted memory model, and high-level instructions that optimize contract execution and reduce gas costs.

æternity is designed to be a versatile platform suitable for a wide range of applications, including:

• Decentralized Finance (DeFi): æternity's high throughput and low transaction fees make it suitable for DeFi applications that require fast and cost-effective transactions.

• Supply Chain Management: The immutability and transparency of the blockchain can be leveraged to create secure and auditable supply chain solutions.

• Gaming: State channels can enable fast and private in-game transactions, enhancing the user experience in blockchain-based games.

As æternity continues to evolve, it aims to implement further scaling solutions like a hybrid blockchain architecture that allows for even greater throughput and the ability to create private or specialized blockchains tailored to specific use cases. This, along with ongoing development of the core protocol and ecosystem, positions æternity as a platform with the potential to meet the demands of a growing and diverse blockchain ecosystem.

A Blockchain for All

Engineered to scale and last, æternity is an easily accessible blockchain platform for the global public. With numerous innovative functionalities and performance far ahead of earlier blockchains, æternity allows its users and community to seamlessly venture into the new era of society, economy, and digital interactions. This documentation site is a compendium of all documentation needed to use and build the æternity ecosystem. If there is anything missing or incorrect please contact us through the forum or drop us a line.

Jump right in

The is a configuration tool designed to simplify the process of setting up and deploying Hyperchains. Currently in beta, this tool helps users generate the necessary configuration files and smart contracts required to initiate a new Hyperchain. The application provides a step-by-step interface for configuring chain parameters, validator settings, and parent chain connections. There's a complete step-by-step guide to help you use the app to set up your very own Hyperchain.

IMPORTANT: This beta release is intended for testing and development purposes only. Users should exclusively test Hyperchains on the Aeternity testnet (ae_uat) to avoid risking real assets. The current version focuses solely on chain initialization and configuration generation - it does not yet support ongoing chain management or monitoring features. As a beta product, users may encounter occasional issues and should report them through our GitHub repository.

Superhero Wallet is a multi-blockchain wallet to manage crypto assets and navigate the web3 and DeFi space. Powered by æternity.

Superhero Wallet is the multi-blockchain wallet to manage crypto assets and navigate web3 and DeFi Space. It currently supports Aeternity, Bitcoin and Ethereum Accounts. Connect also to the Superhero community with the dedicated Superhero Wallet extension. Send and receive tips, store or withdraw AE Tokens, and participate in community voting to have your voice heard. Superhero gives you the power to tip anybody anywhere online or around the world — without third party interference, fees, or commissions. You can register your .chain name today with the .

Creating NFTs on æternity with AEX-141

Ready to create your first NFT on the æternity blockchain? In this tutorial, we'll walk through implementing the AEX-141 standard to create your own unique digital assets. The AEX-141 standard provides a robust framework for NFTs, combining the security of æternity's FATE virtual machine with the flexibility of the Sophia programming language. Whether you're building a collection of digital art, gaming assets, or any other unique tokens, this step-by-step guide will show you how to mint, transfer, and manage your NFTs using the battle-tested AEX-141 standard. You'll learn how to handle metadata, implement proper ownership tracking, and add custom functionality to your NFTs. Let's dive in and create something unique on æternity!

Development Environment Setup

Prerequisites

The æternity blockchain offers a robust suite of core components designed to power the next generation of decentralized applications. At the heart of the protocol lies the Next Generation Nakamoto mechanism, which achieves significantly higher throughput compared to traditional blockchains through its innovative use of key-blocks and micro-blocks. The ecosystem includes that provide flexible authentication options beyond standard signatures, Smart Contracts with - a functional programming language built for security, and State Channels for off-chain transaction processing. Additionally, æternity features built-in Oracles for bringing real-world data onto the blockchain, creating a comprehensive infrastructure that combines scalability, security, and developer-friendly tools in one cohesive platform. Each of these components is explored in detail in the following sections, providing comprehensive documentation for both developers and users to understand and leverage the full potential of the æternity blockchain.

Generalized Accounts in æternity offer enhanced flexibility in how transactions can be authenticated, moving beyond traditional public-private key signatures. This powerful feature allows users to define custom logic for transaction authorization through smart contracts, enabling various authentication schemes such as multi-signature setups, spending limits, specific transaction type restrictions, or even alternative cryptographic signing algorithms like ECDSA used in Bitcoin and Ethereum.

The Generalized Accounts documentation provides comprehensive technical specifications for Generalized Accounts, including detailed examples of implementation. You'll find practical examples such as an ECDSA authentication contract that allows users to sign æternity transactions with their Bitcoin private keys, along with important security considerations and best practices for implementing authentication functions in these contracts.

The native smart contract language for æternity is the Sophia Language, although there is limited support for Solidity. The following sections include in-depth information about Sophia, followed by a short section on specifications for Solidity support.

Sophia Extension for Visual Studio Code

The Sophia VSCode extension provides essential development support for writing smart contracts in the Sophia programming language on the æternity blockchain. This extension enhances your development experience with syntax highlighting and language support features.

Quick Start

Contract transactions on æternity enable the creation, execution, and management of smart contracts on the blockchain. These transactions handle everything from deploying new contracts to calling their functions, managing gas costs, and handling contract-related account operations. The contract transactions provides detailed specifications of the four main transaction types (Create, Attach, Call, and Disable), explaining how transactions are processed, how gas costs are calculated and charged, and how contract addresses are generated. It also covers important security measures like pre-execution fee deduction and includes specific details about transaction requirements, signing, and state management.​​​​​​​​​​​​​​​​

Serialization in æternity defines the standardized binary formats used to encode different blockchain objects for critical operations like hashing, Merkle Patricia Tree insertion, and transaction signing. These formats ensure consistent data representation across the network, enabling reliable cryptographic operations and state management.

The provides detailed technical specifications for serializing all æternity blockchain objects, including blocks, transactions, accounts, smart contracts, and state trees. It covers RLP (Recursive Length Prefix) encoding specifications, version handling, and format changes across protocol upgrades like Roma, Fortuna, and Lima. The documentation is particularly thorough in detailing object tags, field specifications, and special type handling, making it an essential reference for developers working with æternity's data structures at a protocol level.

The æternity blockchain offers essential utility services that enhance user experience and enable seamless integration with external systems. The æternity Naming System (AENS) allows users to replace complex 256-bit addresses with human-readable names, similar to how DNS works for the internet, making blockchain interactions more intuitive and user-friendly. Serialization Formats standardize how data is encoded, decoded, and transmitted across the network, ensuring consistent communication between different nodes and services. These utility services form the backbone of æternity's user-centric approach to blockchain technology, making it easier for both developers and end-users to interact with the ecosystem. The sections that follow provide comprehensive guides on how to implement and utilize these essential network utilities.

The Development Infrastructure section provides comprehensive documentation of the essential tools and interfaces needed to build on the æternity blockchain. From command-line interfaces and software development kits to middleware components and testing environments, these tools enable developers to effectively create, test, and deploy decentralized applications. Whether you're developing smart contracts, building client applications, or integrating with the blockchain, you'll find the necessary resources and documentation to support your development workflow.

Node API reference has it's own webite here: https://api-docs.aeternity.io/

The æternity development ecosystem provides robust testing infrastructure and resources to ensure smooth development and deployment of blockchain applications. The aeproject framework offers a comprehensive toolkit for developers, streamlining contract deployment, testing, and project management with built-in templates and utilities. Multiple testnet environments are available for testing applications under various network conditions, allowing developers to experiment without risking real funds. The faucet service enables easy access to test tokens for development purposes, removing common barriers to experimentation. These development support services create a seamless environment for building, testing, and iterating on decentralized applications before mainnet deployment. The following sections provide detailed guidance on leveraging these development tools and testing environments effectively.

Transactions form the foundation of all operations within the æternity blockchain. Every change to the blockchain's state, whether it's transferring tokens, deploying smart contracts, registering names, or updating oracle data, occurs through transactions.

Unlike simpler blockchain implementations that use a single transaction type and implement additional functionality through smart contracts, æternity provides specialized transaction types as native features of the protocol. This architectural choice offers significant advantages in efficiency, security, and usability. By implementing common operations as distinct transaction types rather than smart contract calls, æternity reduces computational overhead, provides clearer semantics for different operations, and enables optimized processing for each type of interaction within the network.

æternity's unique Bitcoin-NG consensus mechanism influences how transactions are processed. Rather than batching transactions into traditional blocks, the system separates leader election (through key blocks) from transaction processing (in micro blocks). This separation allows for faster transaction processing while maintaining security, achieving approximately 117 transactions per second with three-second micro block times.

The transaction system in æternity is designed to support both on-chain and off-chain operations through state channels, enabling scalable applications while maintaining security. Whether processing simple token transfers or complex smart contract interactions, the transaction system provides the foundation for all network operations while ensuring efficiency, security, and usability.

In This Section

The following pages provide detailed information about different aspects of transactions in æternity:

Getting Started with Nodes

Running a Node

Running an æternity node involves several key steps. First, you'll need to install the required dependencies and download the node software. After configuring your node settings according to your intended role in the network, you can start the node and connect to the network. Detailed installation and configuration guides are available in the technical documentation.

Best Practices

Successful node operation requires attention to several key areas. Ensuring sufficient hardware resources and maintaining good network connectivity are essential for optimal performance. Keeping your node software updated and following security best practices will help maintain the network's integrity. Regular monitoring and maintenance will ensure your node continues to operate effectively.

Node Monitoring and Maintenance

Performance Monitoring

Effective node operation requires continuous monitoring of several key metrics. Your node's synchronization status indicates how well it's keeping up with the network. Memory usage and network connectivity affect your node's ability to process transactions and communicate with peers. Processing performance and block validation speed are crucial indicators of your node's health and contribution to the network.

Maintenance Tasks

Regular maintenance is essential for keeping your node running smoothly. This includes updating node software as new versions become available and backing up node data to prevent loss. Regular monitoring of disk space and network connections, along with reviewing log files, helps prevent potential issues before they impact performance.

Mining on æternity

Ever since the Ethereum merge and the Proof of Stake switch, there has been a hash power vacuum in the crypto mining ecosystem. The æternity blockchain, as one of the longest-running and most resilient Proof of Work blockchains, comes to the fore as the best option for all crypto mining efforts

Profitable mining

Mining is the cornerstone for any and all Proof of Work blockchains out there, seeing as how it is what guarantees the security and stability of the entire framework. Through mining, blockchain power is unleashed- all who take part can contribute hash power and make sure that the æternity blockchain persists, along with all that it stands for persists. That, and obtaining a reward for their work, of course.

The æternity blockchain has an inherent, long-standing link with the very concept of Proof of Work and will, as such, remain on the barricades as the best place for all miners to mine — be it solo or in a pool. (For pools, we recommend 2miners or Woolypooly).

Hardware recommendations

Software recommendations

Mining pools

Mining community

Understanding æScan: Your Window into the æternity Blockchain

æScan serves as your comprehensive window into the æternity blockchain, providing real-time insights into all network activity. As the official block explorer, it offers an intuitive interface for viewing transactions, blocks, and network statistics.

When you visit æScan, you'll immediately see current network statistics including price information, market capitalization, and token distribution. The explorer makes it simple to track recent transactions, view block details, and monitor network activity.

One of æScan's key features is its ability to track the æternity naming system (AENS). You can easily view active .chain names, monitor ongoing auctions, and see recent name registrations. The explorer also shows you active state channels, which are æternity's solution for fast, private transactions.

For token holders and network participants, æScan provides detailed information about network economics, including circulating supply, burned tokens, and current block rewards. You can also monitor oracle activity, smart contract deployments, and overall network health.

The explorer is constantly updating with new blocks and transactions, giving you a real-time view of network activity. Whether you're checking a transaction status, looking up an account balance, or monitoring network metrics, æScan provides all the information you need in an accessible format.

The æternity protocol documentation provides comprehensive technical specifications for all core components of the æternity blockchain. Click on a card below to go the three major sections of the protocol documentation. The sections outlined below are also reflected in the sidebar menu, which also includes direct navigation to documentation on specific features.

References

Sophia is æternity's native smart contract language, designed with security and functional programming principles at its core. As a strongly typed functional language, Sophia helps prevent common smart contract vulnerabilities while providing powerful features for blockchain development. It combines the safety of functional programming with blockchain-specific features like state handling, contract interactions, and oracle integration, making it particularly well-suited for developing secure and efficient decentralized applications.

The Sophia documentation spans multiple areas to support developers at every stage of their journey. It begins with an Introduction and In-Depth Overview of the language fundamentals, then covers practical aspects through comprehensive libraries documentation. Documentation includes information on the Sophia Compiler. Development tools like the æStudio, Sophia Visual Studio extension and æREPL (an interactive development environment) are thoroughly documented to aid in code writing and testing. For deployment and testing, developers will find detailed guides on using æproject (the project management tool) and interacting with the testnet. The documentation also includes specialized sections on HTTP compiler interactions and various integration capabilities, providing a complete resource for Sophia development from concept to deployment.

Sophia HTTP Interface Documentation

The documentation describes the HTTP API for the Sophia smart contract compiler on the æternity blockchain. It covers essential endpoints including contract compilation, ACI generation, calldata encoding/decoding, bytecode validation, and version information.

The documentation provides practical Docker deployment instructions and demonstrates real-world usage through examples with a SimpleStorage contract. Each example shows the complete request/response cycle using curl commands, illustrating how to compile contracts, validate bytecode, encode function calls, decode contract responses, and extract compiler information.

The interface primarily accepts and returns JSON-formatted data, with endpoints operating on port 3080 by default. The documentation serves as a comprehensive reference for developers building applications that interact with Sophia smart contracts on the æternity platform.

The Solidity Language

æternity has limited support for the Solidity language bytecode and ABI. There are a number of test cases and some scaffolding code. However, it is not mature enough to be part of consensus and thus the Solidity ABI is not allowed on chain.

For a full description of Solidity see The Solidity Specification.

The Solidity_01 ABI

Note that the Solidity_01 ABI specifies that the create contract initial call returns the actual bytecode to be stored in the contract state tree to be used for future calls.

See

Storing the contract state

Contracts store the VM storage map containing 256 bit binaries for both keys and values in the MPT. Undefined keys are treated as having the value 0 and keys bound to the value zero are stored as the empty binary, thus purging them from the tree.

The æREPL (æternity Read-Eval-Print Loop) is an interactive shell for the Sophia programming language that enables developers to experiment with and test Sophia code in real-time. This powerful development tool allows users to evaluate Sophia expressions, define functions and types, work with contract code, and maintain state - all without needing to connect to a remote network or use Docker containers. The interface is inspired by GHCi (Haskell's interactive environment) and provides convenient features like type checking, file loading, and state management.

The REPL maintains its own internal state and supports multiple output formats, including Sophia-compatible syntax, FATE runtime representation, and JSON encoding. It can be used either through its command-line interface or as a library through its generic server interface, making it versatile for different development workflows. The tool serves as an essential resource for developers working with Sophia, allowing them to rapidly prototype code, test contract behavior, and better understand the language's features in an isolated environment.

Gossip is a crucial networking protocol in æternity that governs how nodes discover, select, and maintain connections with peers across the network. It defines the mechanisms for peer information exchange, connection management, and network resilience against attacks. The provides comprehensive coverage of the gossip protocol's components, including initial peer configuration, peer identification and maintenance, connection management, and security measures. Special attention is given to preventing peer poisoning and Sybil attacks through sophisticated peer pool management and persistence mechanisms, making it essential reading for anyone working with æternity's networking layer.

Sophia is æternity's native smart contract language, designed with security and functional programming principles at its core. As a strongly typed functional language, Sophia helps prevent common smart contract vulnerabilities while providing powerful features for blockchain development. It combines the safety of functional programming with blockchain-specific features like state handling, contract interactions, and oracle integration, making it particularly well-suited for developing secure and efficient decentralized applications.

The Sophia documentation spans multiple areas to support developers at every stage of their journey. It begins with an Introduction and In-Depth Overview of the language fundamentals, then covers practical aspects through comprehensive libraries documentation. Documentation includes information on the Sophia Compiler. Development tools like the æStudio, Sophia Visual Studio extension and æREPL (an interactive development environment) are thoroughly documented to aid in code writing and testing. For deployment and testing, developers will find detailed guides on using æproject (the project management tool) and interacting with the testnet. The documentation also includes specialized sections on HTTP compiler interactions and various integration capabilities, providing a complete resource for Sophia development from concept to deployment.

Stratum is æternity's mining pool protocol, enabling coordinated mining operations by allowing miners to connect to pool servers that distribute work packages and manage reward distribution. The protocol is adapted from Bitcoin's Stratum protocol but modified to accommodate æternity's Bitcoin-NG consensus mechanism, which introduces distinct roles for keyblock mining and microblock creation.

The provides detailed protocol specifications, including JSON-RPC message formats, mining methods (subscribe, authorize, notify, submit), error handling, and connection management. It covers important pool operator considerations regarding Bitcoin-NG integration and includes technical details for implementing both client and server sides of the protocol, making it essential reading for mining pool operators and mining software developers.

Here is the documentation for outdated SDKs for the æternity blockchain. They are no longer updated, but might prove useful to developers using Python, Elixer or Go. If you have an urgent need for one of the following SDKs or any other programming language let us know!

Official, but support (currently) discontinued

• aepp-sdk-elixir - Outdated.

  • Documentation: https://aeternity.com/aepp-sdk-elixir

• - Iris compatible, some features (e.g. PayingForTx) missing.

• - Outdated, can still be used for regular SpendTx.

  • Documentation:

Community

• - Outdated.

The æternity blockchain is built on several fundamental concepts and technologies that work together to create a scalable, efficient, and developer-friendly platform. These core concepts form the foundation of æternity's architecture and feature set. Here you'll find detailed explanations of the protocol that governs the network, the innovative consensus mechanisms that secure it, and the unique features that set æternity apart from other blockchain platforms. Whether you're a developer looking to build on æternity, or simply want to understand how the technology works, understanding these core concepts is essential to grasping the full potential of the platform.

The æternity Protocol: Implementation and Maintenance

The æternity protocol forms the foundation of the æternity blockchain, outlining the rules and procedures that govern its operation. The current iteration of the æternity protocol replaces initial versions and incorporates the latest advancements in blockchain technology. The protocol is developed in Erlang, a programming language renowned for its ability to create highly reliable and concurrent systems, attributes crucial for a robust blockchain. The choice of Erlang reflects a commitment to building a stable and scalable platform capable of handling a large volume of transactions.

Understanding Æ Coins: The Currency of the æternity Blockchain

Æ coins (formerly AE tokens or aeons) are the native currency of the æternity blockchain. These coins are essential for all operations within the æternity ecosystem, functioning as the fuel that powers transactions and smart contract interactions. Just as gasoline is required to run a car, AE coins are needed to execute any action on the æternity blockchain.

One primary function of Æ coins is to facilitate value transfer between users. The most basic transaction on the æternity blockchain is the "spend transaction," which allows users to send Æ coins to other accounts, oracles, or smart contracts. This straightforward mechanism forms the basis of economic activity within the æternity network.

Beyond simple transfers, Æ coins play a critical role in powering the execution of smart contracts. Smart contracts, essentially self-executing agreements encoded on the blockchain, require computational resources to operate. Each operation performed by a smart contract incurs a cost, measured in "gas," and this gas must be paid for using Æ coins. This "gas fee" mechanism ensures that users pay for the computational resources they consume, preventing abuse and incentivizing efficient contract design.

Node Roles in the æternity Network

Overview

In the æternity blockchain network, nodes work together to maintain network security, process transactions, and provide essential services. Each node can fulfill various roles in the network, contributing to different aspects of network operation. Understanding these roles is crucial for comprehending how the network functions as a whole.

Node Types

Overview

The æternity blockchain network operates through a diverse ecosystem of nodes, each serving specific purposes within the network. Understanding these different node types is crucial for anyone looking to participate in the network, as each type contributes uniquely to the network's functionality, security, and performance.

Transactions in the æternity blockchain follow a distinct lifecycle from creation to confirmation, influenced by the network's Bitcoin-NG consensus mechanism and micro block structure. Understanding this lifecycle is crucial for developers and users interacting with the network.

Transaction Creation and Signing

The transaction lifecycle begins when a transaction is created and signed by its originator. During creation, the transaction is structured according to its type-specific format and includes essential elements such as the sender's account, nonce, fee, and any type-specific data. The originator signs the transaction using their private key, creating a cryptographic proof of authorization.

Transaction fees in the æternity blockchain serve multiple purposes: preventing spam, compensating miners, and prioritizing transactions. The fee structure is designed to work efficiently with the Bitcoin-NG consensus mechanism and support various transaction types while maintaining network sustainability.

Fee Structure

Every transaction in æternity requires a fee paid in AE coins. The fee consists of two main components: a base fee that varies by transaction type, and a computation fee based on the complexity of the operation. For smart contract executions, the computation fee is calculated using gas, similar to other blockchain platforms, but with optimizations specific to the FATE virtual machine.

In the æternity blockchain, Generalized Accounts provide increased flexibility in transaction authentication. This powerful feature enables custom authorization schemes through the combination of attach transactions and meta-transactions, allowing accounts to implement sophisticated control mechanisms beyond traditional cryptographic signatures.

Creating Generalized Accounts Through Attach Transactions

The journey to creating a generalized account begins with an attach transaction. This special transaction type transforms a standard account into a generalized account by associating it with a smart contract that controls all future authorizations. The attach transaction must include the smart contract code and be signed using the account's standard EdDSA signature. This is a one-way transformation - once an account becomes a generalized account, it cannot revert to a standard account.

æternity Networks

Overview

The æternity blockchain ecosystem consists of different networks that serve various purposes, from main network operations to development and testing. Each network type maintains the core features of æternity, including Bitcoin-NG consensus, state channels, oracles, and the FATE virtual machine, while serving specific needs within the ecosystem.

Next Generation Nakamoto Consensus (Bitcoin-NG)

In traditional blockchain systems like Bitcoin, each block serves two purposes: it establishes who gets to add the next block (leader election) and contains the actual transactions. This dual role creates a fundamental limitation on transaction throughput because the network must wait for a new block to be mined before processing new transactions. æternity solves this problem by implementing Bitcoin-NG, a next-generation consensus protocol that separates these two functions.

Oracles in æternity serve as trusted bridges between the blockchain and the outside world, enabling smart contracts to access external data. Unlike many blockchain platforms where oracles are implemented through complex smart contracts, æternity provides native protocol-level support for oracles, making them more efficient, cost-effective, and easier to use.

Understanding Oracles

Blockchains operate in closed systems, unable to directly access external information. An oracle solves this limitation by providing a mechanism to bring outside data onto the blockchain in a verifiable way. This could be anything from weather data and sports results to stock prices and supply chain information. What makes æternity's approach unique is that oracle functionality is built directly into the protocol rather than being implemented through smart contracts, leading to more efficient operation and reduced costs.

The æternity Naming System (AENS) transforms complex blockchain addresses into human-readable names, making the blockchain more accessible and user-friendly. While other blockchains implement naming systems through smart contracts, AENS is built directly into æternity's protocol, offering enhanced efficiency, security, and usability.

Understanding AENS

In the blockchain world, addresses are typically long strings of numbers and letters that are difficult to remember and prone to error when typing. AENS solves this problem by allowing users to register memorable names that point to their accounts, contracts, or oracles. Every name in the system ends with '.chain' (for example, 'superhero.chain'), creating a consistent and recognizable namespace.

What sets AENS apart from other blockchain naming systems is its protocol-level implementation. Instead of relying on smart contracts, AENS uses native blockchain operations, making name registration and management more efficient and cost-effective. When you use a name in a transaction, the translation from name to address happens directly in the protocol, providing better security guarantees than smart contract-based solutions.

The æternity Crypto Foundation is a non-profit organization established in Liechtenstein that supports and advances the æternity blockchain ecosystem. While independent from the blockchain itself, the Foundation plays a crucial role in fostering development, innovation, and community growth.

Foundation's Role

It's important to understand that the Foundation is not æternity blockchain, nor does it own or manage it. Rather, the Foundation acts as one of many contributors to the ecosystem, focusing on ensuring the smooth operation of the blockchain, supporting continuous development, and empowering the community. The Foundation maintains a particular focus on technical excellence and user-friendly applications, providing resources and infrastructure to create a stable environment for the æternity ecosystem.

The æternity blockchain uses a modified version of the Bitcoin-NG (Next Generation) consensus protocol, designed to significantly improve scalability and transaction throughput while maintaining security. Unlike traditional blockchain protocols that combine leader election and transaction processing in a single block, Bitcoin-NG separates these functions: key blocks handle leader election through proof-of-work mining, while micro blocks, created by the elected leader, contain transactions. This innovative approach allows æternity to achieve higher transaction speeds (approximately 120 transactions per second) and shorter confirmation times (around 3 seconds) compared to traditional blockchain architectures, all while preserving decentralization and security.

Our consensus protocol documentation provides detailed technical specifications of this implementation, covering Bitcoin-NG's adaptation for æternity, the handling of coinbase rewards at different block heights, fundamental consensus mechanisms, and the protocol's coin locking features for participation in governance and delegation.

Smart contracts on æternity are powered by Sophia, a functional programming language designed specifically for blockchain applications with security and efficiency in mind. These contracts are executed on FATE (Fast Aeternity Transaction Engine), a custom-built virtual machine that provides enhanced security features and improved performance compared to traditional blockchain VMs. For backward compatibility, æternity also supports the AEVM (æternity Ethereum Virtual Machine), allowing developers familiar with Solidity to deploy their contracts.

• The covers all aspects of smart contract development on æternity, including detailed specifications of both virtual machines (FATE and AEVM), contract state management, transaction types, and event handling. You'll find comprehensive guides for both Sophia and Solidity development, along with standard library documentation and contract examples. A particular focus is placed on the FATE VM and Sophia language, as these represent æternity's native and most efficient smart contract implementation path.

This is the sophia compiler for the æternity system which compiles contracts written in sophia to instructions.

The compiler is currently being used three places

• In tests

Oracles in æternity serve as a bridge between the blockchain and external data sources, enabling smart contracts to access real-world information in a decentralized manner. As native protocol-level entities, rather than smart contract implementations, oracles in æternity offer an efficient and reliable way to bring outside data onto the blockchain.

The covers the complete oracle lifecycle, from registration and operation to querying and response handling, including technical specifications for oracle APIs, type systems, and time-to-live (TTL) mechanisms.

State Channels in æternity provide a secure way to conduct transactions and execute smart contracts off-chain while maintaining blockchain-level security guarantees. This scaling solution enables participants to interact directly with each other, only using the blockchain as an arbiter in case of disputes, resulting in faster transactions and reduced costs.

provides comprehensive coverage of state channel implementation, including protocol specifications, communication methods, and contract execution. It details both off-chain and on-chain components, explains the node configuration required for state channels, and covers important concepts like channel topology, incentive structures, and fee handling. Special attention is given to security measures, privacy considerations, and dispute resolution mechanisms, making this documentation essential for developers implementing state channel solutions on æternity.

The Sync protocol is a fundamental component of æternity's network infrastructure, enabling nodes to exchange and synchronize state transitions across the distributed ledger in a secure and efficient manner. It defines how peers discover each other, communicate, and share blockchain data, even in environments where participants may not trust each other or could be acting maliciously. The documentation provides detailed specifications of the sync protocol, covering transport layer security, peer-to-peer networking, bootstrapping mechanisms, and synchronization procedures for blocks and transactions. Special attention is given to security considerations, including threat models and protection against various attack vectors.

The æternity Naming System (AENS) provides human-readable names for blockchain entities like accounts, oracles, and contracts, making the system more user-friendly than working with raw cryptographic addresses. AENS implements an auction-based registration system for shorter, more desirable names, while allowing instant registration for longer names, with all names having the .chain extension in the current implementation.

The provides comprehensive coverage of the naming system's technical specifications, including name registration mechanisms, auction procedures, protocol fees, and namespace governance. It details the commitment scheme that prevents front-running, explains name management operations (claiming, updating, transferring, revoking), and outlines important protocol upgrades like Lima and Ceres that introduced key features such as auctions and optional pre-claims. The documentation also discusses potential future extensions like decentralized name exchange and interoperability with other naming systems.

Sophia Extension for Visual Studio Code

The Sophia VSCode extension provides essential development support for writing smart contracts in the Sophia programming language on the æternity blockchain. This extension enhances your development experience with syntax highlighting and language support features.

Quick Start

Sophia HTTP Interface Documentation

The documentation describes the HTTP API for the Sophia smart contract compiler on the æternity blockchain. It covers essential endpoints including contract compilation, ACI generation, calldata encoding/decoding, bytecode validation, and version information.

The documentation provides practical Docker deployment instructions and demonstrates real-world usage through examples with a SimpleStorage contract. Each example shows the complete request/response cycle using curl commands, illustrating how to compile contracts, validate bytecode, encode function calls, decode contract responses, and extract compiler information.

The interface primarily accepts and returns JSON-formatted data, with endpoints operating on port 3080 by default. The documentation serves as a comprehensive reference for developers building applications that interact with Sophia smart contracts on the æternity platform.

Node Architecture

Overview

The æternity blockchain implements a sophisticated node architecture that sets it apart from traditional blockchain designs. At its core, the architecture leverages the Bitcoin-NG consensus mechanism and specialized components to achieve high transaction throughput while maintaining security and decentralization. This unique approach allows the network to process transactions more efficiently than traditional blockchain architectures, while ensuring robust security and decentralization.

Bitcoin-NG Implementation

The implementation of Bitcoin-NG (Next Generation) in æternity represents a fundamental advancement in blockchain consensus mechanisms. Traditional blockchains combine leader election and transaction processing into a single block type, creating bottlenecks in transaction processing. æternity takes a different approach by separating these functions into two distinct block types: key blocks and micro blocks.

Key blocks serve as the foundation of leader election in the network. When a miner successfully solves a Cuckoo Cycle proof-of-work puzzle, they create a key block that establishes them as the leader for the next generation. These blocks contain no transactions but instead focus solely on the consensus mechanism, referencing both the previous key block and micro block while starting a new mining epoch.

Once established as a leader through a key block, a miner gains the ability to generate micro blocks. These blocks contain the actual transactions and are created approximately every three seconds. Micro blocks don't require proof-of-work, instead gaining their legitimacy through the leader's digital signature. This separation of concerns allows æternity to achieve approximately 117 transactions per second, far exceeding the capabilities of traditional blockchain architectures.

Mining and Consensus

The consensus mechanism in æternity centers around the Cuckoo Cycle proof-of-work algorithm, chosen specifically for its memory-bound properties. Unlike traditional proof-of-work systems that rely heavily on processing power, Cuckoo Cycle's performance is primarily limited by memory latency. This characteristic helps democratize the mining process by reducing the advantage of specialized mining hardware, promoting greater decentralization of the network.

The network automatically adjusts mining difficulty to maintain consistent block times using a sophisticated algorithm that considers the timestamps of the last 17 blocks. This adaptive system ensures stable key block generation while accounting for the inherent reliability issues in timestamp data. The difficulty adjustment mechanism plays a crucial role in maintaining network stability and predictable block generation.

Fork resolution in the network follows clear consensus rules designed to maintain network consistency. Nodes automatically prefer the longest chain when confronted with competing versions of the blockchain, using difficulty as a tiebreaker when chains have equal length. The Bitcoin-NG structure allows for efficient resolution of micro-forks, minimizing network disruption during consensus conflicts.

System Components Integration

The node architecture integrates several key components that work in concert to provide the network's functionality. The network layer handles peer-to-peer communication, managing both block propagation and transaction distribution throughout the network. This component ensures efficient information flow between nodes, maintaining network connectivity and consistency.

The consensus engine manages the implementation of Bitcoin-NG, handling block validation and chain selection processes. It works closely with the state management system, which maintains the current blockchain state, including accounts, contracts, and oracle data. This tight integration ensures consistent state transitions and reliable transaction processing.

The FATE virtual machine represents another crucial component, providing highly efficient and secure smart contract execution. Its integration with the node architecture allows for deterministic contract execution while maintaining strict security guarantees and efficient resource utilization.

Security Considerations

Security remains paramount in the æternity node architecture, with several mechanisms working together to maintain network integrity. The proof-of-fraud system allows the network to detect and punish malicious leaders who attempt to abuse their position. This system enables other nodes to report fraudulent behavior, with punishment enacted through the withholding of mining rewards.

The reward system itself incorporates security considerations through its distribution mechanism. Mining rewards are split between key block miners and micro block creators, with 60% allocated to key block miners and 40% to micro block creators. These rewards are locked for 180 blocks, providing a window for fraud detection and reporting.

Performance Characteristics

The architectural design of æternity nodes enables significant performance improvements over traditional blockchain systems. The three-second micro block time allows for rapid transaction processing, while the separation of leader election and transaction processing reduces network congestion. This design enables efficient block propagation and helps maintain network performance even under heavy load.

Future Scalability

Looking ahead, the æternity node architecture incorporates design elements that support future scaling solutions. The architecture already supports state channel integration for off-chain scaling, with potential for further enhancements through sharding implementation. The system's design also accounts for cross-chain communication capabilities and oracle system expansion, ensuring the network can evolve to meet future demands while maintaining its core principles of security and decentralization.

Through this careful integration of components and forward-thinking design, æternity's node architecture provides a robust foundation for blockchain operations while maintaining the flexibility to adapt to future needs and challenges.

Basic Transaction Types

The most fundamental transaction type in æternity is the spend transaction, used to transfer AE coins between accounts. These transactions specify a sender, receiver, amount, and optional payload data. The payload feature allows users to attach arbitrary binary data to transactions, enabling proof of existence or custom messaging capabilities.

Contract-related transactions form another essential category. These include contract creation transactions, which deploy new smart contracts to the blockchain, and contract call transactions, which interact with existing contracts. Contract creation transactions contain the compiled bytecode of the contract along with its initialization parameters, while call transactions specify the contract address, function to call, and any required arguments.

Oracle Transactions

Oracle functionality in æternity is implemented through specific transaction types. Oracle registration transactions announce new oracles to the network, specifying the expected query format and response format. Oracle query transactions allow users to request information from registered oracles, while oracle response transactions enable oracle operators to provide answers to these queries. The oracle system also supports transactions for extending oracle TTL (Time To Live) and updating oracle configurations.

Name Service Transactions

The æternity Naming System (AENS) uses several specialized transaction types. Name preclaim transactions initiate the two-step name claiming process by submitting a hash of the desired name and a random number. Name claim transactions follow preclaims, revealing the actual name and completing the registration process. Name update transactions modify the information associated with a name, while name transfer transactions change name ownership. Name revoke transactions allow owners to release names back to the system.

Governance and System Transactions

Governance in æternity is supported by specific transaction types that enable network participants to signal their preferences and participate in decision-making. These transactions include delegation of voting power and actual voting transactions for network proposals.

Channel transactions facilitate state channel operations. Channel create transactions establish new state channels between parties, while channel deposit and withdraw transactions manage fund allocation within channels. Channel close transactions handle both mutual and forced channel closures, implementing the dispute resolution mechanisms crucial for state channel security.

Meta-Transactions

Meta-transactions provide a layer of abstraction over standard transactions through generalized accounts. These transactions wrap ordinary transactions with additional authentication data, enabling custom verification logic and advanced account management features. This mechanism allows for innovative transaction authorization schemes beyond standard cryptographic signatures.

Channel State Transactions

Within state channels, specialized transaction types handle off-chain state updates. These transactions never appear on the main chain unless needed for dispute resolution. They include state updates, intermediate settlements, and force progress transactions that enable contract execution within channels.

System Management Transactions

The protocol includes system-level transactions for network maintenance and updates. These specialized transactions handle protocol upgrades, network parameter adjustments, and other system-level operations that maintain and evolve the network's functionality.

Each transaction type implements specific validation rules and includes appropriate authorization mechanisms. Understanding these different transaction types is crucial for developers building on æternity and for users interacting with the network's various features.

æternity uses Cuckoo Cycle as its proof-of-work algorithm, representing a significant departure from traditional proof-of-work systems. While many blockchain networks use computational puzzles that favor specialized hardware, Cuckoo Cycle is designed to be memory-bound rather than computation-bound, promoting more democratic participation in the mining process.

What Makes Cuckoo Cycle Different

Traditional proof-of-work algorithms like Bitcoin's SHA-256 are primarily limited by computational power, leading to an arms race in specialized mining hardware (ASICs). Cuckoo Cycle takes a different approach by making memory access speed the primary constraint. This choice has important implications for the network:

Memory latency doesn't improve as rapidly as computational power, reducing the advantage of specialized hardware over general-purpose computers. This characteristic helps maintain a more decentralized network by allowing broader participation in the mining process.

The algorithm requires miners to find cycles of a specific length in a large graph, making the mining process fundamentally different from traditional hash-based approaches. This graph-theoretic problem has proven to be both challenging to solve and easy to verify, making it an ideal candidate for proof of work.

Technical Implementation

In æternity's implementation, Cuckoo Cycle operates with specific parameters that balance security with efficiency:

The algorithm searches for cycles of length 42 in a graph defined by 30-bit edges. The ratio between the number of edges and nodes (set to 1/2 by default) helps control the difficulty of the problem. This configuration has been carefully chosen to provide the right balance between security and mining accessibility.

The final step of the mining process involves hashing the solution and comparing it to a difficulty target. This additional step allows for fine-grained control over block creation timing, ensuring consistent block production even as network conditions change.

Difficulty Adjustment

æternity implements an adaptive difficulty mechanism that helps maintain consistent block times:

The difficulty target is adjusted based on the timestamps of the last 17 blocks. While timestamps in a decentralized system can't be perfectly reliable, the protocol ensures that block timestamps cannot precede those of previous blocks.

Miners must meet the target difficulty specified in the previous block. Any block submitted with an incorrect difficulty target or failing to meet the required difficulty is rejected by honest nodes. This system ensures that the network can adapt to changes in total mining power while maintaining predictable block generation times.

Mining Process

The mining process in æternity follows these steps:

1. A miner attempts to find a valid cycle in the graph defined by the Cuckoo Cycle parameters

2. Upon finding a cycle, the solution is hashed

3. The hash is compared against the current difficulty target

4. If the hash meets the target requirement, the solution is valid and can be included in a key block

This process occurs only for key blocks in the Bitcoin-NG protocol, while micro blocks are generated without mining, allowing for rapid transaction processing between key blocks.

Benefits for Network Security

Cuckoo Cycle's memory-bound nature provides several security benefits:

Memory bottlenecks help prevent the centralization of mining power that has occurred in many other blockchain networks. The algorithm's requirements make it more practical for a diverse set of participants to contribute to network security.

The verification process is extremely efficient, reducing the overhead for nodes validating new blocks. This efficiency is particularly important in æternity's Bitcoin-NG implementation, where rapid block verification is essential for maintaining high transaction throughput.

Future Development

The Cuckoo Cycle implementation continues to evolve with the æternity platform. Ongoing research and development focus on optimizing the algorithm parameters and exploring potential improvements to further enhance decentralization and efficiency.

For developers and miners interested in participating in the network, understanding Cuckoo Cycle is essential as it fundamentally influences how new blocks are created and validated. The algorithm's unique properties contribute to æternity's goals of maintaining a secure, decentralized, and accessible blockchain platform.

The æternity blockchain implements a sophisticated governance mechanism that combines delegative democracy with coin-weighted voting. This system ensures that all stakeholders can participate in network governance while providing a structured approach to decision-making that scales with network growth.

Understanding Weighted Coin Voting

In the æternity ecosystem, governance power is proportional to the stake held in the network, following the principle of "one coin, one vote" rather than "one person, one vote." This approach aligns voting power with economic investment in the network's success. Stakeholders who hold AE coins can participate directly in governance decisions or delegate their voting power to other participants who they believe will make informed decisions on their behalf.

The weighted voting system creates a natural balance between large and small stakeholders. While larger stakeholders have more influence over decisions, the ability to delegate votes ensures that expertise and active participation are rewarded regardless of stake size. This delegative aspect of the system, sometimes called liquid democracy, allows the network to benefit from the wisdom of its most engaged participants while maintaining broad representation.

Delegation and Liquid Democracy

The delegation mechanism in æternity's governance system provides flexibility in how stakeholders participate in decision-making. Any coin holder can delegate their voting power to another account, and these delegations can be changed at any time. This dynamic delegation system encourages active participation in governance while allowing stakeholders to adjust their delegation choices based on delegates' performance and decision-making history.

Delegates earn their influence through demonstrated expertise and commitment to the network's success, rather than solely through token ownership. This creates a meritocratic element within the governance system, where knowledge and active participation are rewarded with increased influence. The liquid nature of delegations means that delegates must maintain the trust of their delegators or risk losing their voting power.

Network Parameter Governance

æternity's governance system plays a crucial role in managing network parameters and protocol upgrades. Stakeholders can propose and vote on changes to various aspects of the network, including technical parameters, economic policies, and protocol improvements. This participatory approach ensures that the network can evolve to meet changing needs while maintaining consensus among stakeholders.

One practical example of parameter governance is the adjustment of epoch lengths in Hyperchains. Stakeholders can propose and vote on changes to these parameters, allowing child chains to optimize their performance based on real-world usage patterns and requirements. The voting process ensures that such changes have broad support from the network's stakeholders before being implemented.

Fork Choice and Protocol Updates

The weighted coin voting system also plays a crucial role in managing potential network forks and protocol updates. When contentious changes to the protocol are proposed, stakeholders can signal their preferences through their votes, helping the network reach consensus on which chain to follow. This mechanism provides a structured way to handle protocol upgrades while minimizing the risk of contentious hard forks.

Miners in the network can observe these voting signals when choosing which fork to mine, creating an economic incentive to follow the chain preferred by the majority of stakeholders. This alignment of interests between miners and stakeholders helps maintain network stability during upgrades and protocol changes.

Coordination and Security

The governance system serves as a coordination mechanism for the network's various consensus components. It helps align the interests of different participant groups - including miners, stakers, and regular users - ensuring that protocol changes benefit the network as a whole. The system's design makes it resistant to manipulation, as acquiring enough voting power to force unfavorable changes would require significant economic investment in the network.

Security is enhanced by the requirement that governance proposals must go through a deliberation period before implementation. This allows stakeholders time to evaluate proposals and their potential impacts, reducing the risk of hasty or poorly considered changes. The delegation system also helps protect against governance attacks by allowing stakeholders to quickly realign their voting power if they detect malicious behavior.

Future Developments and Hyperchains

As æternity continues to evolve, its governance system will expand to accommodate new features and technologies, particularly with the introduction of Hyperchains. These specialized chains will be able to implement customized governance mechanisms tailored to specific use cases, while still benefiting from the security and stability of æternity's core weighted coin voting system. For example, a Hyperchain designed for decentralized finance might implement governance optimized for rapid response to market conditions, while one designed for community organizations could focus on broader participation patterns.

The extensibility of æternity's governance model ensures that as new technologies and use cases emerge, the platform can adapt while maintaining its foundational principles of security and stakeholder representation. Whether operating independently or integrated with mainnet activities, Hyperchains represent an exciting evolution in how blockchain governance can be customized to serve diverse community needs while maintaining the decentralized nature that is fundamental to blockchain technology.

Understanding the FATE VM: A Secure and Efficient Engine for æternity Smart Contracts

The Fast Æternity Transaction Engine, or FATE VM, uses a higher level of abstraction and automatically minimizes error with type checking, delivering a simpler, easier, safer programming environment.

The FATE VM is the heart of smart contract execution on the æternity blockchain. Designed specifically for the æternity ecosystem, FATE is a virtual machine, an execution engine that provides a secure and controlled environment for running smart contracts. Unlike traditional byte-code virtual machines found on other blockchains, FATE operates directly on the state tree of the æternity blockchain, providing a highly integrated and efficient approach.

Built for Security and Efficiency

FATE prioritizes both security and efficiency in its design and implementation. The VM utilizes a high-level instruction set, enabling concise and understandable contract code. Each operation in FATE is typed, meaning that any type mismatch results in an exception, reverting any changes and preventing potential vulnerabilities. This strict type checking enhances the security of smart contracts by minimizing the risk of unexpected behavior.

Furthermore, FATE incorporates several features to prevent common smart contract vulnerabilities:

• Separation of data and control flow: This prevents malicious modification of contract code during execution.

• Unbounded integer arithmetic: Eliminates the risk of integer overflows, a common vulnerability in other smart contract platforms.

• Restricted jump destinations: Limits jumps to defined basic blocks, preventing arbitrary code execution and enhancing control flow security.

This focus on security makes FATE a reliable and trustworthy platform for deploying valuable smart contracts.

Efficiency through High-Level Instructions

FATE's use of high-level instructions contributes significantly to its efficiency. These instructions provide direct access to core blockchain functionalities, such as interacting with oracles, managing names in the ÆNS (æternity Naming System), and handling state channels. By directly integrating with these features, FATE eliminates the need for complex workarounds, resulting in smaller contract sizes, faster execution, and lower gas costs.

Developer Interaction and Benefits

Developers interact with FATE primarily through the Sophia programming language. Sophia is a functional smart contract language designed for security and ease of use, seamlessly integrating with FATE. Sophia contracts compile into FATE bytecode, which is then executed on the FATE VM.

FATE's security features benefit developers by minimizing the potential for errors and vulnerabilities during contract development. The efficient execution environment reduces gas costs, making æternity smart contracts more affordable to deploy and use. Furthermore, FATE's tight integration with æternity-specific features, such as oracles and the ÆNS, simplifies the development of complex blockchain applications.

Comparison to Other VMs

FATE distinguishes itself from virtual machines on other blockchains through its specialized design and focus on æternity's unique features. Compared to the Ethereum Virtual Machine (EVM), for instance, FATE contracts tend to be significantly smaller and execute more efficiently, consuming less gas. FATE's security features, such as strict type checking and control flow restrictions, address known vulnerabilities in other VMs, making it a more secure platform for smart contract deployment.

FATE's Role in the æternity Ecosystem

The FATE VM is an essential component of the æternity blockchain. It provides a secure and efficient platform for executing smart contracts, powering a wide range of decentralized applications and enabling the integration of real-world data through oracles. Its specialized design and focus on security make it a robust and reliable engine for building and deploying the next generation of blockchain applications.

æternity nodes are the backbone of the æternity blockchain network. They work together to maintain the network's integrity, process transactions, and ensure the blockchain operates smoothly and securely. Think of nodes as the individual computers that collectively make up the æternity network - each playing a crucial role in keeping the blockchain running.

Why are Nodes Important?

The importance of nodes stems from their fundamental role in maintaining the decentralized nature of the æternity blockchain. Through distributed consensus, nodes work collectively to process and validate every transaction that occurs on the network. They store and distribute blockchain data across the network, enabling robust peer-to-peer communication. Additionally, nodes support the execution of smart contracts and facilitate mining operations, making them essential to every aspect of the blockchain's functionality.

Technical Architecture

Built with Erlang

æternity nodes are implemented in , a programming language specifically designed for building robust, concurrent, and distributed systems. This choice provides excellent handling of concurrent operations and built-in distribution capabilities. The language's focus on high reliability and fault tolerance, combined with efficient process management, makes it ideal for blockchain node implementation.

Core Components

Network Layer

The network layer forms the communication backbone of æternity nodes. It manages peer-to-peer communication and handles node discovery and connection establishment. Through this layer, nodes synchronize blockchain data and propagate transactions and blocks across the network, ensuring all participants maintain a consistent view of the blockchain state.

Consensus Engine

The consensus engine implements the Bitcoin-NG consensus protocol, managing both key-block and micro-block creation. This component handles chain selection during forks and validates blockchain state transitions, ensuring all nodes agree on the current state of the network.

Virtual Machine (FATE)

The FATE virtual machine executes smart contracts within the node environment. It manages contract state and handles gas calculations while ensuring deterministic execution across all nodes. This component is crucial for maintaining consistent smart contract behavior throughout the network.

State Management

State management is responsible for maintaining the blockchain's current state. This includes tracking account balances, managing smart contract states, and handling name resolution through the ÆNS system. The state management system ensures all nodes maintain identical copies of the current blockchain state.

Advanced Topics

Node Communication

Nodes communicate using a sophisticated peer-to-peer protocol that automatically discovers other nodes and exchanges blockchain data efficiently. The protocol maintains network topology and handles network partitions gracefully, ensuring reliable communication even under adverse conditions.

State Channels

State channels are a key scaling solution supported by æternity nodes. They enable off-chain transaction processing, significantly improving transaction speed and reducing blockchain load. State channels also enhance privacy by keeping transaction details off the main chain until settlement.

Oracle Integration

Nodes play a crucial role in oracle functionality, facilitating access to external data sources. They process oracle queries and validate responses, maintaining oracle state information that can be used by smart contracts and other blockchain applications.

Exploring Node Architecture Further

Understanding æternity nodes is crucial for anyone looking to participate in the network or build on the platform. The following sections provide detailed information about specific aspects of node implementation and operation:

• Node Architecture - Technical implementation details and internal node components

• Node Types - Different kinds of nodes and their specific requirements

• Node Roles in the Network - How nodes contribute to network functionality and consensus

Each section explores these crucial aspects of æternity nodes in detail, providing the knowledge needed to understand, operate, and develop with æternity nodes effectively.

If you want information on how to start running an æternity node, please go to the or section.

State channel transactions in æternity represent a sophisticated approach to scaling blockchain operations by moving many transactions off-chain while maintaining security through periodic main chain anchoring. This system enables high-throughput applications while minimizing on-chain transaction costs.

Channel Establishment

State channels begin with on-chain transactions that establish the channel between participants. These initialization transactions lock funds into the channel and set up the initial state. The channel creation process requires mutual agreement from all participants, expressed through properly signed transactions that are processed on the main chain.

Off-chain Transactions

Once established, state channels enable participants to conduct numerous transactions off-chain. These transactions modify the channel state through mutual agreement, without requiring main chain processing. Off-chain transactions can include value transfers, contract interactions, and state updates, all validated and signed by channel participants.

State Management

Each off-chain transaction updates the channel's state, creating a new valid state that all participants agree upon. These state updates include appropriate signatures from all parties and maintain a sequence number or nonce to ensure proper ordering. The latest agreed-upon state represents the current distribution of funds and contract states within the channel.

Contract Execution

State channels support smart contract execution, allowing complex applications to operate off-chain. Contract calls within channels follow similar patterns to on-chain execution but process faster and without network fees. The FATE virtual machine ensures consistent contract execution both on and off-chain, maintaining deterministic results.

Dispute Resolution

The state channel system includes robust dispute resolution mechanisms implemented through on-chain transactions. If participants disagree about channel state, they can submit evidence to the main chain through force-progress transactions. The blockchain's consensus mechanism then helps resolve disputes based on signed state updates and contract logic.

Channel Closure

Channels can be closed either cooperatively or through a unilateral process. Cooperative closure occurs when all participants agree on the final state, requiring a single on-chain transaction. Unilateral closure initiates a challenge period during which other participants can dispute the closing state, ensuring that the final settlement reflects the latest valid channel state.

State Channel Economics

The economic model of state channels enables efficient resource use by amortizing on-chain costs across many off-chain transactions. While channel opening and closing require standard transaction fees, off-chain transactions incur no network costs. This model makes state channels particularly suitable for applications requiring frequent interactions between known participants.

Introduction to Consensus Mechanisms

In blockchain networks, consensus mechanisms are the protocols that allow all participants to agree on the current state of the network. Think of it as a sophisticated voting system that helps maintain order and security without requiring trust between participants. These mechanisms are crucial because they solve the fundamental problem of how to achieve agreement in a decentralized system where some participants might be malicious or unreliable.

æternity implements an innovative hybrid consensus approach that addresses three critical challenges in blockchain technology: security, scalability, and energy efficiency. At its core, æternity uses a next-generation version of Nakamoto consensus called Bitcoin-NG (Next Generation), enhanced with a unique Cuckoo Cycle proof-of-work algorithm and a weighted coin voting system for governance.

The Bitcoin-NG consensus mechanism separates leader election from transaction processing, allowing for significantly higher transaction throughput compared to traditional blockchain systems. While Bitcoin processes around seven transactions per second with ten-minute block confirmation times, æternity can handle approximately 117 transactions per second with just three-second block confirmation times. This remarkable improvement in performance doesn't come at the cost of security; instead, it's achieved through a clever redesign of how blocks are created and processed.

What makes æternity's consensus particularly interesting is its modular approach. The system uses two types of blocks: key blocks for leader election through proof of work, and micro blocks for transaction processing. This separation allows for rapid transaction confirmation while maintaining the security guarantees of proof of work. Additionally, the Cuckoo Cycle proof-of-work algorithm used for mining key blocks is designed to be more memory-bound than computation-bound, promoting more democratic participation in the mining process.

æternity is also forward-looking in its consensus design. With the introduction of Hyperchains, the platform will support delegated proof-of-stake mechanisms for specialized chains while maintaining the security benefits of the main chain's proof of work. This hybrid approach allows for the creation of highly scalable and efficient blockchain applications while leveraging the security of the main network.

The combination of these consensus mechanisms reflects æternity's commitment to building a blockchain platform that is not only secure and decentralized but also practical and efficient for real-world applications. In the following sections, we'll explore each component of æternity's consensus mechanism in detail, understanding how they work together to create a robust and scalable blockchain platform.

Transparent Governance

The æternity protocol is governed by miners, AE coin users and developers. Æ coin holders can vote on a regular basis about changes of the software system. Everyone's voice in the ecosystem should be and is considered.

æternity implements a sophisticated governance system that combines on-chain voting mechanisms with community-driven decision making. This hybrid approach ensures that the blockchain can evolve to meet changing needs while maintaining stability and protecting the interests of all stakeholders.

Understanding æternity Governance

Governance in æternity operates at multiple levels, from technical protocol updates to economic policy decisions. The system is designed to be transparent and inclusive, allowing all stakeholders to participate in the network's evolution. Unlike traditional governance systems that rely solely on developer decisions or pure on-chain voting, æternity's approach balances technical expertise with community input.

On-Chain Governance Mechanisms

At the protocol level, æternity implements a weighted delegated coin-voting system where voting power is proportional to the stake held in the network. This system allows AE token holders to signal their preferences on important protocol decisions, such as accepting or rejecting proposed protocol changes. Token holders can either vote directly or delegate their voting power to other participants who they believe will make informed decisions.

The voting mechanism includes sophisticated features to prevent manipulation and ensure fair representation. For example, votes are weighted based on both the number of tokens held and the duration they've been held, encouraging long-term thinking and commitment to the network's success.

Protocol Updates and Forks

Protocol updates in æternity follow a structured process designed to maintain network stability while enabling innovation. When significant changes are proposed, they are first discussed within the community and thoroughly tested. The implementation of major protocol updates occurs through a predefined process that includes several key steps:

First, proposed changes are developed and tested in a staging environment. Once testing is complete, the changes are implemented in a protocol upgrade that specifies an activation height. This allows node operators and other network participants adequate time to prepare for the transition. The weighted coin-voting system allows stakeholders to signal their support or opposition to proposed changes, helping to build consensus before implementation.

Hard Forks and Network Evolution

When protocol changes require hard forks, æternity's governance system helps coordinate the transition smoothly. Miners can observe voting signals from stakeholders to align their actions with community preferences, reducing the risk of contentious forks. This coordination mechanism has helped æternity successfully implement several protocol upgrades, each adding new features and improvements to the network.

Economic Governance

Beyond technical protocol decisions, æternity's governance system also handles economic parameters that affect the network's operation. This includes decisions about fee structures, reward distributions, and other economic policies that impact network participants. The weighted coin-voting system ensures that those with the most stake in the network's success have proportional input in these decisions.

Community Participation

æternity's governance system extends beyond on-chain voting to include active community participation through various channels. Technical discussions, improvement proposals, and community feedback are integral parts of the governance process. This multi-faceted approach ensures that all voices can be heard and that decisions benefit from diverse perspectives within the community.

Getting Involved

The æternity ecosystem welcomes participation from developers, users, and stakeholders in its governance processes. Community members can engage through multiple channels, from participating in technical discussions and contributing to code development, to joining governance discussions and participating in voting processes.

For those interested in taking a more active role in æternity's governance, several pathways are available. Developers can contribute to protocol development, users can participate in governance discussions and voting, and community members can help shape the network's future through active engagement in the ecosystem. The development team regularly hosts community calls, maintains active discussion forums, and welcomes new contributors to the project.

Related Documentation

Detailed technical information about governance mechanisms, including voting processes and protocol upgrade procedures, can be found in the Developer Tools section. For those interested in participating in governance decisions, practical guides and current governance proposals are available in the User Guides section.

Superhero DEX is at its core a tool for developers and AEX-9 builders as part of our DeFiReady toolkit.

Superhero DEX takes full advantage of Sophia — a unique smart contract language, light-speed on-chain transactions, and virtually non-existent transaction fees. It facilitates the creation and provision of liquidity for AEX-9 token pairs — thus enabling liquidity providers to earn passive income. Unlike with centralized exchanges, with the Superhero DEX, traders can access projects earlier, exit earlier, and try and access funding more frequently. Furthermore, Superhero DEX has no need for a KYC procedure and no personal information is gathered on users. Superhero DEX is powered by the advanced æternity blockchain — a more scalable smart contract platform with advanced built-in features, such as state channels for smart contracts, a human-readable naming system, oracles, and hugely efficient virtual machine — FATE.

No hidden
 fees

Don't forget - unlike other DEXs out there, Superhero DEX has no platform fees other than those that reward our liquidity providers (and these are capped off at 0.3% of transaction value). No hidden nor subsequent fees - just complete freedom for you to do as you wish!

Using æpps on æternity

Decentralized applications (æpps) on æternity provide secure, user-focused solutions with minimal fees thanks to state channel technology. Getting started is simple:

Base æpp - Your Gateway to æternity

Base æpp is your starting point for exploring æternity's ecosystem. This mobile-only application serves as both a wallet and a hub for accessing other æpps. Through Base, you can:

• Send and receive AE tokens

• Create and manage accounts

• Access the wider æpp ecosystem

Popular æpps

• : A decentralized tipping platform that leverages state channels for near-zero fee transactions, empowering content creators and their supporters

• : Platform for participating in blockchain governance through weighted delegated coin-voting

• : Creative platform for images to be transformed to a unique artistic style on the æternity blockchain, with the artist bidding AE Coin to include their artwork in the communal wall.

Getting Started

1. Download on your computer or mobile device

2. Create or import your wallet

3. Get some AE tokens (use the Faucet æpp for testnet tokens)

4. Explore the available æpps through Base

Remember that transactions on æternity are fast and cost-effective thanks to state channel technology, making the platform ideal for frequent interactions and microtransactions.

For secure key management, consider exploring options like AirGap Vault or other supported wallets in the ecosystem.

Visit for a comprehensive list of community-developed æpps.

The æternity Command Line Interfaces (CLIs) provide powerful tools for interacting with the æternity blockchain directly from your terminal. The Sophia CLI focuses on smart contract development, allowing you to compile, test, and deploy Sophia contracts with ease. The æternity CLI enables direct blockchain interactions such as managing accounts, sending transactions, and working with oracles or names through simple terminal commands. These tools are essential for developers who prefer command-line workflows or need to automate blockchain interactions in their development process.

Note: Throughout this documentation, we'll refer to the æternity CLI (aepp-cli-js) as either "æternity CLI" or "aepp CLI" for consistency.

The æREPL (æternity Read-Eval-Print Loop) is an interactive shell for the Sophia programming language that enables developers to experiment with and test Sophia code in real-time. This powerful development tool allows users to evaluate Sophia expressions, define functions and types, work with contract code, and maintain state - all without needing to connect to a remote network or use Docker containers. The interface is inspired by GHCi (Haskell's interactive environment) and provides convenient features like type checking, file loading, and state management.

The REPL maintains its own internal state and supports multiple output formats, including Sophia-compatible syntax, FATE runtime representation, and JSON encoding. It can be used either through its command-line interface or as a library through its generic server interface, making it versatile for different development workflows. The tool serves as an essential resource for developers working with Sophia, allowing them to rapidly prototype code, test contract behavior, and better understand the language's features in an isolated environment.

The SDKs and APIs section provides information about available tools and interfaces for interacting with the æternity blockchain. The JavaScript SDK is our primary and actively maintained development kit, offering comprehensive functionality for building applications on æternity. While there are other SDKs available (Python, Go, etc.), these are currently not actively maintained but may still offer useful reference implementations. In terms of APIs, the Node API serves as the core interface for blockchain interactions, with additional APIs to be documented as they are developed or discovered. This section aims to provide developers with the necessary resources to effectively build and integrate with the æternity ecosystem.

æternity nodes are the backbone of the blockchain network, responsible for maintaining the distributed ledger, processing transactions, and participating in consensus. Each node can serve different purposes - from full nodes that maintain the complete blockchain state and validate transactions, to mining nodes that participate in block creation, to API nodes that provide interfaces for applications. Nodes communicate with each other using various protocols for synchronization, gossip-based message propagation, and mining coordination, enabling the decentralized operation of the æternity network. The Nodes Documentation describes how to install, configure and operate an aeternity node. One can install it from a package, run a docker image or build it themselves. There is also additional documentation on mining with CUDA and build and/or join a Stratum pool. The provides comprehensive coverage of the node's API functionalities, including the core API that enables interaction with the blockchain, the specialized Channels WebSocket API for state channel operations, and detailed guidance on utilizing the user API for common blockchain interactions. This documentation serves as an essential reference for developers working with æternity nodes, whether they're building applications, implementing state channels, or integrating with the blockchain. The Node API can be found on its own webpage.

The aepp-sdk-java is a community developed Java SDK to interact with the æternity blockchain.

Latest Release

Documentation

The documentation placed in the /docs folder is generated via MkDocs and served via gh-pages:

License

Licensed under the

Support us

If you like this project we would appreciate your support. You can find multiple ways to support us here:

Hyperchains Bridge

The Hyperchains Bridge is a decentralized application that establishes a trustless connection between the æternity blockchain and its network of Hyperchains. This tool enables secure, seamless movement of assets across chains without requiring centralized intermediaries.

Key Features

• Secure Asset Transfers: Move tokens between æternity and Hyperchains using cryptographic proofs

• Enhanced Liquidity: Bridge assets back to æternity mainnet as wrapped tokens for trading on DEXs

• Improved PoS Distribution: Support healthier stake distribution across validators and delegators

• Decentralized Security: Contribute to the resilience and decentralization of the Hyperchain ecosystem

How It Works

1. You submit a transfer request through the bridge application

2. Smart contracts lock your assets on the source chain

3. The system monitors and confirms your transaction

4. Depending on direction, either wrapped tokens are minted on the destination chain or original tokens are released

The Hyperchains Bridge plays a crucial role in strengthening utility, security, and scalability within the æternity ecosystem by enabling seamless interoperability between chains.

Hyperchains represent æternity's innovative approach to blockchain scalability, combining the security benefits of proof-of-work with the efficiency of proof-of-stake systems. This hybrid solution allows for the creation of specialized chains that can process transactions more rapidly while maintaining security through periodic synchronization with the main æternity blockchain.

Understanding Hyperchains

A Hyperchain operates as a child chain that leverages the security of the main æternity blockchain (parent chain) while maintaining its own consensus mechanism. Think of it as a specialized blockchain that inherits security from its parent while having the freedom to optimize for specific use cases.

The relationship between parent and child chains is carefully orchestrated through a system of epochs and synchronization points. Each Hyperchain maintains its own network of validators who stake tokens to participate in block production, while periodically anchoring its state to the main æternity blockchain for enhanced security.

State channels are one of æternity's core scaling solutions, enabling millions of transactions per second between parties while maintaining the security guarantees of the blockchain. Unlike other blockchain platforms where state channels are an add-on feature, æternity was built with state channels as a fundamental component, integrating them deeply into the protocol level.

Understanding State Channels

Think of a state channel as a private conversation between two parties who agree to keep track of their interactions off the main blockchain. Much like how you might keep a running tab at your local coffee shop and settle up at the end of the month, state channels allow participants to conduct numerous transactions quickly and privately, only recording the final result on the blockchain.

ærc Bridge User Guide

The ærc bridge is a cross-chain bridge enabling seamless transfer of tokens and native cryptocurrencies between Ethereum and æternity blockchains. This guide will walk you through using the bridge, understanding its mechanics, and troubleshooting common issues.

Core Development Tools

1. CLI

• Project scaffolding

This is the sophia compiler for the æternity system which compiles contracts written in sophia to instructions.

The compiler is currently being used three places

• In tests

The (MDW) is a powerful caching and reporting layer that sits between applications and æternity nodes, designed to enhance query performance and extend the blockchain's querying capabilities. It provides fast access to blockchain data and supports complex queries that would be inefficient or impractical to implement directly on the node level.

The Middleware documentation covers everything you need to know about setting up, configuring, and using the middleware, including:

• Complete setup instructions for both mainnet and testnet environments

• Comprehensive API reference for all available endpoints

AEproject is æternity's comprehensive development framework designed to streamline the development lifecycle from initial setup to deployment. This powerful command-line tool automates the creation of new projects with pre-configured directory structures, complete with example contracts and test suites written in the Sophia language. Developers can quickly spin up local blockchain environments using built-in Docker configurations, enabling rapid prototyping and testing without the need for complex setup procedures. AEproject includes intelligent compilation tools, sophisticated testing harnesses, and deployment utilities that handle the intricacies of contract management across different networks. Whether you're a seasoned blockchain developer or just starting with æternity, AEproject provides the essential scaffolding and workflows needed to build robust decentralized applications efficiently. For comprehensive tutorials and detailed usage instructions, please refer to the documentation.

The æternity JavaScript SDK is a comprehensive toolkit that enables developers to interact with the æternity blockchain using JavaScript. Whether you're building decentralized applications (æpps), integrating blockchain functionality into existing applications, or developing tools for the æternity ecosystem, this SDK provides all the necessary methods and utilities to work with æternity's features, including smart contracts, oracles, naming system (AENS), and state channels.

This documentation covers everything from basic setup to advanced blockchain interactions. You'll find detailed guides for core functionalities, examples for common use cases, and comprehensive API references. The documentation is structured to support both newcomers getting started with blockchain development and experienced developers looking to leverage æternity's full feature set. Navigate through the sections on the left to find detailed information about specific features and functionalities.

Developing æpps on æternity

æternity provides a robust platform for building decentralized applications (æpps) with its functional smart contract language Sophia and efficient FATE virtual machine. The blockchain's native features like state channels, oracles, and naming system (AENS) provide powerful building blocks for developers.

æScan Technical Documentation

Explorer Architecture and Integration

æScan is built on æternity's core infrastructure, utilizing both node and middleware services to provide comprehensive blockchain data access. The explorer interfaces with the latest protocol versions:

Access Points

Production Environment

Testing Environment

API Integration

æScan leverages the æternity middleware API for data retrieval and processing. Key endpoints include:

Development Resources

API Documentation

• Node API: Comprehensive documentation for direct node interaction

• Middleware API: Extended functionality for building applications

WebSocket Support

æScan maintains WebSocket connections for real-time data updates. Example connection:

Hyperchain Integration

The explorer is being enhanced to support Hyperchains, æternity's scaling solution. Developers will be able to:

• Track cross-chain transactions

• Monitor Hyperchain validator activity

• Access Hyperchain-specific metrics

• Query state across multiple chains

For developers looking to build applications on æternity, æScan's infrastructure provides a reliable reference implementation for blockchain data access and processing. The codebase demonstrates best practices for handling æternity protocol interactions and real-time blockchain data management.

FATE (Fast Aeternity Transaction Engine) is æternity's custom-built virtual machine, designed specifically to execute Sophia smart contracts with enhanced security and efficiency. It uses high-level instructions that operate directly on the blockchain's state tree, enabling native integration with protocol features like oracles and state channels. FATE's functional approach, strong typing, and arithmetic safeguards prevent common smart contract vulnerabilities, while its efficient design results in smaller contract sizes and lower gas costs compared to traditional blockchain virtual machines.

The FATE documentation provides detailed specifications of FATE's architecture, including its instruction set, type system, and security features. You'll find technical explanations of how FATE integrates with the blockchain's state tree, handles contract execution, and implements its efficient computational model. The documentation also covers FATE's approach to gas calculation and resource management, essential for developers optimizing their smart contracts.

The æternity Blockchain Stack

The æternity blockchain stack is a comprehensive ecosystem designed to support scalable and secure decentralized applications. Let's explore the architecture of the æternity stack from its foundation to the application layer.

Level One:

First Steps with æternity Blockchain Development

Setting Up Your First Project

Getting started with æternity blockchain development is straightforward with the æternity project tool (aeproject). This command-line utility helps you initialize projects, compile smart contracts, run tests, and deploy to the blockchain.

Introduction to Hyperchains

Hyperchains represent a revolutionary advancement in blockchain technology, offering a unique solution that combines the speed and efficiency of proof-of-stake systems with the robust security of established proof-of-work networks. At its core, a Hyperchain is a specialized blockchain that operates independently while securing itself through periodic connections to a pinning (parent) chain like æternity or Bitcoin, enabling organizations and developers to deploy custom blockchain solutions without the massive infrastructure investments typically required for blockchain security.

Built on æternity's innovative technology, Hyperchains allow anyone to create specialized networks that inherit security from established proof-of-work chains. This groundbreaking approach to blockchain scalability and customization makes sophisticated blockchain implementations accessible to organizations of all sizes, while maintaining the highest standards of security through their connection to established networks.​​​​​​​​​​​​​​​​ .

Understanding Hyperchains

Think of a Hyperchain as a mountain climber ascending a steep cliff. The climber (the Hyperchain) moves swiftly and independently, but regularly secures themselves by placing pins into the mountain face (the pinning chain). These security pins ensure that even if something goes wrong, the climber can only fall back to their last secure point. In blockchain terms, this means that while a Hyperchain processes transactions quickly and efficiently using proof-of-stake, it regularly "pins" its state to a more secure parent chain, inheriting the parent chain's security guarantees.

Unlike traditional side chains or layer-2 solutions, Hyperchains offer unprecedented flexibility while maintaining this secure foundation. Each Hyperchain functions as a specialized blockchain that leverages the security of an existing blockchain (called the parent chain) while maintaining its own independent operations. This unique architecture allows organizations to customize their Hyperchains with specific consensus mechanisms, block times, and governance structures, while processing transactions more rapidly and cost-effectively than traditional blockchains.

How Hyperchains work

Hyperchains operate through a sophisticated yet elegant mechanism that combines the best aspects of different blockchain technologies. At its core, a Hyperchain uses proof of stake for fast, low-cost transactions while maintaining security through periodic synchronization with a proof of work parent chain. This hybrid approach enables rapid transaction processing while inheriting the robust security guarantees of established networks.

The Hyperchain processes transactions using epochs - defined periods where a set of validators, selected through stake-weighted randomization, produce blocks. The system uses the parent chain's block hash as a source of randomness for selecting these validators, ensuring an unbiased and tamper-resistant selection process. Each epoch consists of a staking phase, leader election phase, block production phase, and payout phase, creating a continuous cycle of secure operation.

The block production structure within each epoch can be customized based on the specific implementation and requirements. For example, when using æternity as a parent chain, the Hyperchain can utilize a Bitcoin-NG-style consensus with key blocks and microblocks, allowing for higher transaction throughput. Key blocks establish the leader for a generation, while microblocks contain the actual transactions, enabling rapid transaction processing between leader elections.

The critical link between the Hyperchain and its parent chain is maintained through the pinning process. During each epoch, selected validators take snapshots of the Hyperchain's state - including block hashes, heights, and epoch information - and anchor this data to the parent chain. To ensure regular pinning occurs, the system implements an innovative reward mechanism where unclaimed pinning rewards accumulate over time, creating a stronger economic incentive for validators to maintain these security anchors.

Key Benefits of Hyperchains

Security through proven networks: Hyperchains inherit security from established proof-of-work chains through periodic state anchoring.

Customizable performance: Organizations can define their own parameters for block time, epoch length, and validation requirements to meet specific performance needs.

Cost-effective scaling: Transaction throughput is limited only by the Hyperchain's parameters, not the parent chain's constraints.

Flexible governance: Each Hyperchain can implement specialized governance mechanisms, from rapid enterprise decision-making to broad community participation.

Adaptable architecture: The system can evolve through stakeholder voting on network parameters and operational decisions.

Creating and Using Hyperchains

Organizations can customize their Hyperchains to meet specific requirements and use cases. While æternity serves as an ideal parent chain with built-in Hyperchain support, the technology can potentially work with any proof-of-work blockchain that meets certain criteria. Creators define key parameters such as block time, epoch length, and validation requirements to match their specific needs.

Practical Applications

Hyperchains excel in scenarios requiring high transaction throughput, quick finality, or specialized functionality. Financial institutions can deploy Hyperchains optimized for high-speed trading, while gaming platforms might create ones designed for handling numerous micro-transactions. Supply chain solutions benefit from Hyperchains customized for tracking and verifying product movements, while decentralized autonomous organizations (DAOs) can implement governance mechanisms tailored to their community needs.

For enterprise applications, Hyperchains offer particular value through their ability to implement private or permissioned chains while still benefiting from public blockchain security. Organizations can create solutions that balance their need for control and transparency with robust security guarantees.

Partners and Development Support

The Hyperchain ecosystem is supported by key technical partnerships that demonstrate its real-world applications. Nupont, a digital transformation specialist, integrates Hyperchain technology into business solutions, enhancing efficiency and transparency for enterprise clients. Meanwhile, BOS (Bitcoin Operating System) expands Bitcoin's framework to create more scalable, decentralized applications, showcasing how Hyperchains can interact with and enhance existing blockchain infrastructure.

These partnerships represent the first steps in building a robust Hyperchain ecosystem, with more collaborations and implementations in development. Through these strategic relationships, we're demonstrating how Hyperchains can solve real business challenges while maintaining the highest standards of security and performance.

Related Documentation

Developers interested in creating and deploying Hyperchains can find comprehensive technical documentation in the Developer Tools section. There is also the Hyperchains Web App (with its own documenation) for easier configuration and the Hyperchains White paper.

æternity provides robust testing environments that mirror mainnet functionality while using test tokens with no real value. The testing infrastructure includes a node testnet for blockchain testing, middleware testnet for æpp backend services, hyperchains testnet and a comprehensive testnet explorer for viewing the testnet's transaction history and status. Developers can obtain test AE tokens through the faucet to begin building and testing their applications before deploying to mainnet.

Testing Networks & Status Endpoints

æternity provides comprehensive network status monitoring through various endpoints across both mainnet and testnet environments. Before deploying on mainnet, developers can use these endpoints to validate their applications, monitor network health, and ensure proper connectivity. Status endpoints provide real-time information about node synchronization, network performance, and API availability.

Available Services

Node Access

Mainnet and testnet status endpoints let you check node health and network status. The Swagger-UI provides an interactive interface for testing Node API endpoints during development.

Middleware Status

Monitor backend services through middleware status endpoints for both networks. This is particularly useful when developing æpps that require middleware integration.

Block Explorer

View transaction history and network activity through dedicated explorers for both mainnet and testnet environments. The testnet explorer is especially valuable for tracking test transactions and smart contract interactions during development.

Using Status Endpoints

Check network status using cURL:

Node

• - Access to the status endpoint

• - Access to the status endpoint

• - Explore and interact with the Node API

Middleware

• - Access to the status endpoint

• - Access to the status endpoint

Explorer

• - Explore the history of æternity mainnet

• - Explore the history of æternity testnet

Other Services

Faucet

• - Fund your wallet with some Æ coins and get started

Best Practices

1. Always test against testnet first

2. Monitor both mainnet and testnet status during development

3. Use the Swagger UI to explore and test API endpoints

4. Verify middleware sync status when building æpps

Token Standards on æternity

The æternity blockchain provides robust support for both fungible and non-fungible tokens through well-defined token standards. These standards ensure interoperability and consistency across different implementations while leveraging the security and efficiency of æternity's native FATE virtual machine. Similar to how ERC-20 and ERC-721 revolutionized token creation on Ethereum, AEX-9 and AEX-141 serve as the foundational standards for building fungible and non-fungible tokens on æternity.

These standards have enabled the development of various DeFi applications and NFT projects within the æternity ecosystem. From decentralized exchanges and tipping systems to complex NFT collections, developers can utilize these battle-tested standards and reference implementations to build secure and scalable token-based applications. The standards are specifically designed to take advantage of æternity's unique features, including state channels for scalability and the Sophia smart contract language for enhanced security.

Hyperchains: Bridging Security and Scalability Through Periodic Synchronization

Version 2.0 - Revision 03_25

by: Erik Steinman, Thomas Arts, Hans Svensson, Måns Klerker, Justin Mitchell, Susan Ploetz

For for detailed technical specifications, refer to the Technical Details section of the 2023 Hyperchains Whitepaper.

Introduction

Blockchain technology has revolutionized digital trust systems but faces critical limitations as adoption grows. Bitcoin's Proof-of-Work (PoW) established trustless distributed ledgers but struggles with energy consumption and scalability. Proof-of-Stake (PoS) alternatives improve efficiency but introduce new vulnerabilities, particularly the "Nothing at Stake" dilemma where validators can support multiple forks without cost.

Hyperchains address these challenges by combining the security of established PoW networks with the efficiency of PoS systems. This paper examines how the periodically syncing Hyperchains architecture resolves fundamental blockchain challenges through innovative cross-chain synchronization mechanisms.

Background and Motivation

The Blockchain Trilemma

Traditional blockchains face an inherent trilemma between security, scalability, and decentralization. Proof-of-Work chains like Bitcoin excel in security through their robust consensus mechanism, but they process transactions slowly and consume enormous energy resources. Proof-of-Stake chains offer better efficiency and scalability but introduce new security challenges related to stake distribution and validator incentives.

This trilemma has historically forced blockchain architects to prioritize one or two properties at the expense of others. Hyperchains aim to transcend this limitation by creating a system that inherits security from established PoW networks while enabling efficient transaction processing through an optimized PoS mechanism implemented on æternity blockchain architecture.

Fundamental Challenges in Hybrid Blockchain Systems

Previous attempts to combine PoW and PoS through cross-chain mechanisms revealed significant technical challenges:

Security and Randomness: A secure, unbiasable source of randomness is critical for leader selection in PoS systems. Parent chain block hashes provide this randomness but require careful implementation to prevent manipulation. Using finalized parent chain blocks addresses this vulnerability.

Chain Synchronization: Early hybrid implementations attempting continuous "lockstep" synchronization proved brittle—parent chain delays would halt child chain progression, demanding a more flexible synchronization model.

Validator Coordination: The "Nothing at Stake" problem required mitigation without the prohibitive costs of continuous cross-chain commitments. Token-locking and formal registration processes created excessive operational overhead.

Cross-Chain Complexity: Managing different chain speeds, handling reorganizations, and balancing coordination costs with security benefits all required innovative solutions beyond simple chain linking. The realization that global time assumptions don't exist in decentralized systems drove the move toward periodic rather than continuous synchronization.

The Evolution of Hyperchains

The Hyperchains concept has undergone significant transformation since its inception in 2016. When Yanislav Malahov first proposed the idea, he envisioned leveraging established blockchain security to create efficient, scalable systems without duplicating mining efforts—effectively "recycling the power of blockchains."

The original concept employed "cross-timestamping," where smaller chains would anchor their state to established networks like Bitcoin. Early implementation attempts revealed fundamental challenges: proving an event happened "before" a specific time proved significantly harder than proving it happened "after" another event—an insight that would later shape the periodic synchronization model.

Between 2017 and 2020, as æternity matured with innovations like Bitcoin-NG consensus and the FATE virtual machine, these technologies created a foundation for addressing cross-chain synchronization challenges. The 2020 whitepaper "Æternity Hyperchains: Recycling Power of Blockchains" proposed a comprehensive framework with validators posting commitments to the parent chain and sophisticated leader election mechanisms.

However, implementation revealed critical flaws. The "lockstep" synchronization approach proved brittle—when the parent chain slowed, the entire child chain halted. Additionally, frequent validator commitments generated unsustainable transaction costs. By 2023, the team fundamentally reconceptualized their approach, eliminating the assumption of global time between chains and implementing an epoch-based system with three crucial innovations:

1. Decoupling real-time dependencies through predefined epochs

2. Implementing future leader election using well-finalized historical blocks

3. Replacing continuous commitments with strategic pinning operations

Real-world testing in 2024 led to further refinements, including the addition of a fifth epoch—the Entropy Epoch—creating a buffer ensuring continuous operation during parent chain delays. The pinning mechanism evolved with cumulative rewards and third-party participation to address practical operational scenarios.

This development journey revealed critical insights: theoretical security must balance with operational reality; periodic verification provides sufficient security without continuous interaction; and economic incentives drive security behaviors more effectively than rigid protocols. The architecture that emerged combines æternity's advanced technical features with innovative cross-chain security mechanisms, creating a practical framework for enterprise blockchain applications.

Key Innovations

The Periodically Syncing Hyperchains architecture introduces four groundbreaking innovations:

Future Leader Election enables pre-emptive block producer selection using secure randomness from finalized parent chain blocks, establishing a predictable yet unpredictable leadership schedule that maintains security while enabling rapid transaction finalization.

Five-Epoch Staking Cycle separates stake collection, entropy gathering, leader selection, block production, and reward distribution into distinct phases, providing clear boundaries for state transitions.

Strategic Pinning enables efficient state verification through periodic proof posting rather than continuous on-chain commitments, significantly reducing operational costs while maintaining security guarantees.

Flexible Chain Speed allows independent operation rates between parent and child chains, eliminating the brittleness of earlier approaches while maintaining security guarantees.

These innovations represent the culmination of years of research tackling blockchain's fundamental trilemma and the specific challenges of hybrid architectures.

Hyperchains Architecture

Fundamental Concept

A Hyperchain consists of two distinct but interconnected blockchain systems: the Parent Chain and the Child Chain. The Parent Chain (also called the Pinning Chain) is an established, secure blockchain—typically running Proof-of-Work consensus—that provides security anchoring and randomness. This chain continues to operate according to its own protocol, unaware of the child chain's existence. The implementation allows for various parent chains including Bitcoin, Litecoin, Dogecoin, or aeternity itself, providing flexibility in security model selection.

The Child Chain (Hyper Chain) is built on Aeternity's blockchain architecture, inheriting its advanced technical capabilities while implementing a specialized Proof-of-Stake consensus mechanism. The child chain leverages the parent chain's security while offering faster transaction processing and finality. By building on aeternity's foundation, Hyperchains benefit from established features including state channels for off-chain scaling, the efficient FATE virtual machine for smart contract execution, the aeternity naming system (AENS), and oracle capabilities—all while adding the security benefits of parent chain anchoring.

This architecture creates a system where the child chain can operate independently most of the time while periodically "checking in" with the parent chain for security anchoring and randomness collection. This periodic rather than continuous synchronization is a key innovation that emerged from practical implementation experience, resolving the brittleness of earlier approaches that required constant parent-child chain interaction.

The Five-Epoch Staking Cycle

The Hyperchain operates through a structured five-epoch cycle that coordinates all system activities. This structure, refined through multiple implementation iterations, provides clear boundaries for critical operations while maintaining operational flexibility.

The first phase is the Staking Epoch, during which participants register and adjust their stakes, providing the economic security for the network. This establishes the validator set that will be eligible for future leader selection. During this epoch, the system collects the staking power distribution that will influence future leader elections, creating a clear snapshot of network participation.

Next comes the Entropy Epoch, added in the 2024 implementation based on real-world testing that revealed the need for dedicated randomness collection. The system collects random values from the parent chain, specifically block hashes from finalized parent chain blocks. This dedicated epoch ensures reliable access to unbiasable randomness even when parent chain block production experiences temporary delays.

In the Leader Election Epoch, the system uses the collected entropy and staking data to deterministically select validators who will serve as block producers in subsequent epochs. This pre-emptive selection is a key innovation enabling operational continuity. The election process creates a complete schedule of leaders for the upcoming block production epoch, providing predictability while maintaining security through unbiasable selection.

During the Block Production & Pinning Epoch, selected leaders create blocks, process transactions, and anchor the child chain state to the parent chain through strategic pinning operations. Leaders follow the predetermined schedule, creating blocks and processing transactions according to aeternity's efficient transaction model. At designated intervals, typically at epoch boundaries, the system anchors its state to the parent chain through pinning transactions.

Finally, the Payout Epoch completes the cycle as rewards are distributed to validators based on their contributions, and stake positions are updated accordingly. This creates a clear accounting of participation and rewards, setting the stage for the next cycle to begin.

Each epoch serves a specific purpose in maintaining the chain's security and operational efficiency. The addition of a dedicated entropy epoch enhances the system's randomness generation, crucial for fair and unpredictable leader selection. The full five-epoch structure creates a comprehensive system that balances security, performance, and operational continuity.

System Participants

The Hyperchain ecosystem involves several interconnected participant roles that maintain network security and efficiency. Chain Initiators configure and launch Hyperchains, establishing fundamental parameters and deploying required smart contracts. Validators operate nodes that process transactions and potentially produce blocks when selected as leaders, while Delegators contribute stake without running nodes themselves. Selected validators become Block Producers (Leaders) during specific periods based on the election process, and typically the producer of an epoch's final block serves as a Pinner, anchoring the child chain state to the parent chain. This interconnected system creates balanced responsibilities and incentives that maintain operational integrity.

Transcending the Blockchain Trilemma

Hyperchains address the blockchain trilemma through a sophisticated architecture that combines the strengths of different consensus models while mitigating their weaknesses.

By anchoring critical state information to a secure parent chain, the child chain inherits robust security guarantees without duplicating energy-intensive mining operations. This security inheritance is achieved through strategic pinning operations that create cryptographic links between the child and parent chains, leveraging established PoW security for the PoS child chain.

The child chain operates at its own pace, processing transactions rapidly through an efficient Proof-of-Stake mechanism with predetermined leader schedules. Built on aeternity's high-performance blockchain technology, the child chain achieves throughput and finality times that far exceed traditional PoW systems, enabling practical applications that require rapid transaction processing.

The leader election process uses unbiasable randomness from the parent chain combined with stake-weighted selection, ensuring fair participation while preventing centralization. This mechanism creates unpredictable yet verifiable leader selection that cannot be manipulated by individual participants, maintaining decentralization despite the efficiencies of the PoS model.

This balanced approach creates a system that achieves previously impossible combinations of security, efficiency, and decentralization. By carefully integrating the strengths of aeternity's blockchain technology with strategic parent chain anchoring, Hyperchains solve fundamental challenges that have limited blockchain adoption for performance-critical applications.

Technical Components

Future Leader Election

The future leader election process represents a fundamental innovation in the Hyperchain architecture. Rather than selecting leaders in real-time—which creates dependencies on immediate parent chain progression—the system selects leaders in advance using verifiable randomness derived from finalized parent chain history. This approach emerged directly from implementation experience with earlier Hyperchain versions that suffered from operational disruptions when parent chains experienced delays.

The core principle behind future leader election is predictable unpredictability—creating a leader selection process that is deterministic enough to plan operations around but unpredictable enough to prevent manipulation. This balance is achieved by combining entropy from the parent chain with stake distribution from the child chain.

The system derives randomness from historical parent chain blocks that have achieved finality. By looking sufficiently far back in the parent chain's history—beyond the practical reorganization depth—the system ensures that powerful miners cannot manipulate the entropy source even. This approach addresses a fundamental vulnerability in cross-chain systems: the potential for parent chain miners to influence child chain leadership if recent blocks are used for randomness.

Complementing this external randomness, the system incorporates stake distribution data from previous child chain epochs. This creates an economically aligned selection mechanism where leadership opportunities are proportional to network investment. Importantly, the stake distribution used for selection is recorded at a fixed point in the past, preventing participants from strategically adjusting their stakes after seeing the entropy that will determine selection.

The combination of these two elements—external randomness and historical stake distribution—creates a selection process that is both fair and secure. At designated points in the child chain's operation, the system executes the leader selection algorithm, creating a complete schedule of leaders for upcoming blocks. This preemptive selection allows the child chain to continue operation even during temporary parent chain disruptions, as leadership is determined well in advance.

The timing of these elements is carefully coordinated through the epoch structure. Leader election for a particular epoch uses data from multiple epochs in the past, ensuring that all inputs to the selection process are firmly established and immutable by the time selected leaders begin block production. This forward-looking approach enables validators to prepare for their leadership responsibilities while maintaining the security guarantees necessary for trustless operation.

This election mechanism represents a significant advancement over earlier approaches that required continuous parent chain monitoring. By decoupling real-time operation from leader selection, the system achieves both security and operational resilience—qualities that had previously seemed mutually exclusive in cross-chain architectures.

Periodic Synchronization Framework

The child chain maintains loose synchronization with the parent chain through the pinning mechanism, allowing for independent operation when needed while creating security anchors at regular intervals. This approach enables flexible chain speed adjustments through a structured governance process.

The system implements epoch alignment where child chain epochs are calibrated to align with parent chain timing characteristics, establishing a semi-lock-step movement through coordinated epochs. Dynamic adjustment mechanisms recalibrate when timing deviations occur, primarily through adjustments to the Child Epoch Length (CEL) parameter.

While individual block times on PoW chains are variable, the system leverages the statistical stability of block production over longer periods to establish reliable synchronization. Chain speed management occurs through a structured governance process where stakeholders can submit proposals for CEL adjustment as special transactions, which undergo validation before proceeding to an automated voting process.

This periodic synchronization approach represents a significant advancement over earlier attempts at continuous cross-chain coupling. By eliminating real-time dependencies while maintaining strategic synchronization points, the system achieves both security and operational flexibility.

Pinning Mechanism

The pinning mechanism anchors the child chain's state to the parent chain at strategic intervals, creating an immutable cross-chain record that leverages parent chain security. This approach has evolved significantly from initial concepts that required continuous commitments from all validators in the 2020 whitepaper implementation.

At its core, pinning addresses a fundamental security concern in Proof-of-Stake systems: the possibility of long-term history rewrite attacks. In these attacks, adversaries might acquire old addresses with substantial staking power to create an alternative chain from an early state. By periodically anchoring critical child chain state information to the more secure parent chain, the system creates verifiable checkpoints that prevent such manipulation even if stake ownership changes over time.

The evolution of the pinning mechanism reflects a key insight gained through implementation experience: security anchoring does not require continuous interaction to be effective against long-term attacks. Since history rewrite attacks necessarily unfold over extended periods, periodic anchoring provides sufficient protection while dramatically reducing operational costs compared to continuous approaches.

The pinning process operates as an incentivized action within the Hyperchain ecosystem. At designated intervals, typically at epoch boundaries, a participant (referred to as the Pinner) creates a transaction on the parent chain that contains cryptographic proof of the child chain's current state. This proof includes references to block identifiers, heights, and epoch information from the child chain—creating a verifiable link between the two chains.

Once this anchoring transaction achieves finality on the parent chain, the Pinner submits proof of the anchoring back to the child chain. This creates a circular verification path where the child chain can confirm its state has been properly anchored while parent chain observers can verify the authenticity of anchored information. This two-way verification is crucial for maintaining trust in the cross-chain relationship without requiring continuous monitoring of both chains.

To ensure consistent pinning operations, the system implements economic incentives that align participant behavior with security requirements. Each successful pinning action earns a specific reward, but if pinning actions are missed, the allocated reward carries over to subsequent opportunities. This creates an increasing incentive for pinning as missed actions accumulate, ensuring that temporary disruptions do not compromise long-term security.

The system also supports third-party pinning, allowing any interested party to execute the pinning transaction on the parent chain. This flexibility addresses practical operational scenarios where designated participants might be temporarily unavailable or face resource constraints. By opening pinning participation beyond primary validators, the system creates redundancy that enhances overall security while maintaining proper reward attribution.

This flexible, economically incentivized approach to cross-chain anchoring represents a significant advancement over earlier designs. It achieves robust security guarantees while minimizing operational overhead, creating a sustainable model for long-term cross-chain operation that balances theoretical security with practical implementation considerations.

Economic Incentives

The Hyperchain architecture incorporates a carefully designed economic incentive structure to ensure reliable operation and active participation. The system offers two primary reward categories: Block Production Rewards for validators who successfully produce blocks during their designated slots, and Pinning Rewards for participants who anchor the child chain state to the parent chain.

The pinning reward system includes an innovative approach to cumulative rewards. By rolling over missed pinning rewards to subsequent opportunities, the system creates an increasing economic incentive that ensures eventual pinning without requiring constant transactions. A rational validator will perform pinning when it becomes cost-efficient, while security-minded participants might pin more frequently than strictly economical.

This incentive model extends to support third-party pinning, allowing stakeholders to contribute to chain security even if they aren't validators themselves. This broadens participation while maintaining security through appropriate reward distribution, creating additional economic opportunities within the ecosystem.

By aligning economic incentives with security-enhancing behaviors, the Hyperchain creates a self-sustaining system that maintains robust security guarantees while minimizing operational costs.

Implementation and Validation

Smart Contract Architecture

The consensus and operational mechanisms of the child chain are implemented through a system of smart contracts deployed during genesis. The foundational contract is the staking contract, which tracks validator stakes and manages the five-phase staking cycle.

This contract maintains critical protocol functions including tracking validator stakes and positions at each height, managing state transitions between epochs, processing pinning rewards and distributions, and handling epoch length adjustments through validator voting.

Additional contracts can be deployed based on specific requirements, such as delegation contracts enabling stake delegation to validators. All contract interactions occur through visible on-chain calls, ensuring transparency and verifiability of system operations.

Epoch length adjustments follow a structured governance process through this contract system. The last leader of a production epoch can propose changes through specialized contract calls, with proposals voted on in the subsequent epoch and changes taking effect in following production epochs if approved.

Child Chain Implementation

The Hyperchain implementation requires a specialized blockchain architecture that diverges from traditional Proof of Stake systems. While the child chain builds upon established Aeternity node architecture, it introduces crucial modifications to support Hyperchain-specific operations.

These modifications include sophisticated pinning proof verification mechanisms, comprehensive epoch awareness throughout state transitions, precise tracking of stake distributions and leader schedules, continuous monitoring of parent chain block finality, and enhanced fork choice rules that consider both traditional consensus factors and pinning status.

This implementation demonstrates the architecture's practical application while establishing a production-ready reference for future deployments. The system's modular design ensures that the fundamental benefits of the Hyperchains approach—security, efficiency, and scalability—remain consistent across different implementations.

Reference Implementation

While the Hyperchains architecture is designed to be blockchain-agnostic, the initial implementation utilizes the æternity blockchain as both parent chain and technological foundation. This choice leverages æternity's established proof-of-work security while implementing specialized proof-of-stake mechanisms for the child chain.

This reference implementation showcases how the core architectural elements work together in practice while maintaining flexibility for future implementations to use different parent chains based on specific security and operational requirements.

Applications and Use Cases

The Periodically Syncing Hyperchains architecture enables new applications across multiple industries by providing a unique combination of security, scalability, and economic efficiency. By leveraging aeternity's robust technical foundation while adding enhanced security through parent chain anchoring, Hyperchains create opportunities for blockchain deployment in environments with demanding performance and security requirements.

Financial Services

Financial institutions can deploy private Hyperchains for internal settlement systems, leveraging public blockchains for security while maintaining control over transaction validation. This combination addresses the traditional struggle between transaction throughput and security guarantees.

Hyperchains enable high-frequency trading settlement through rapid block production while anchoring finality to established public blockchains. This supports cross-border payment networks with regional compliance and global settlement through parent chain anchoring. Tokenized asset exchanges benefit from aeternity's efficient state handling plus enhanced security for high-value transactions. Compliance systems leverage the dual nature of Hyperchains—maintaining detailed transaction records on the child chain with immutable audit points through parent chain anchoring.

Financial institutions value operating private validation networks with public blockchain security benefits, controlling access and transaction validation while preventing history rewrites through external verification.

Supply Chain Management

Supply chain ecosystems benefit from Hyperchains' efficient transaction processing and immutable record anchoring. This balance makes it ideal for complex supply chains spanning multiple organizations with varying trust requirements.

Real-time inventory tracking is facilitated through efficient child chain structures and predetermined leader schedules. Provenance verification becomes more robust with periodic anchoring to public blockchains, creating irrefutable product history records. Multi-party coordination leverages smart contract capabilities with enhanced security, executing complex processes efficiently while maintaining tamper-proof records. Regulatory compliance is simplified through cryptographically verifiable timestamps, easing verification for auditors and regulators.

Supply chains with participants of different technical expertise benefit from simple verification mechanisms through parent chain references, enabling even non-blockchain specialists to verify critical transaction history.

Healthcare and Data Management

Industries with strict data retention requirements, such as healthcare, can utilize Hyperchains for secure data management while maintaining regulatory compliance. The periodic pinning mechanism creates immutable proof points while the child chain maintains the flexibility needed for sensitive data management scenarios.

Patient record management systems built on Hyperchains can maintain patient privacy on the child chain while creating verifiable timestamps of record state through parent chain anchoring. Clinical trial data validation becomes more robust when trial results are recorded on Hyperchains, providing both the efficiency needed for large datasets and the security required for regulatory approval through parent chain verification. Cross-institutional data sharing benefits from aeternity's advanced smart contract capabilities combined with Hyperchains' security model, enabling controlled access to sensitive information while maintaining cryptographic proof of data integrity. Regulatory compliance verification is simplified through periodic parent chain anchoring, which provides immutable evidence of data integrity that can be verified independently by regulators.

Healthcare organizations particularly value the combination of data privacy controls possible with private child chains and the immutable verification points created through parent chain anchoring, addressing both confidentiality and integrity requirements.

Identity and Governance

Self-sovereign identity systems, digital voting platforms, decentralized autonomous organizations, and public sector administrative systems can all leverage Hyperchains architecture to create secure operational frameworks with rapid finality and verifiable outcomes.

Identity systems benefit from aeternity's naming system combined with Hyperchains' security model, enabling efficient identity verification while preventing unauthorized modifications through periodic parent chain verification. Digital voting platforms can achieve both the high throughput needed for large-scale elections and the security required for vote integrity through parent chain anchoring of election results. Decentralized autonomous organizations can operate efficiently on the child chain while securing critical governance decisions through parent chain verification. Public sector administrative systems can maintain both the performance needed for day-to-day operations and the long-term record integrity required for government functions through strategic parent chain anchoring of administrative state.

Future Directions and Conclusion

Development Opportunities

The Hyperchains architecture is designed to be highly adaptable and customizable, with several potential development paths. As an open-source project, its evolution will be driven by community contributions and specialized implementations for specific use cases.

To support adoption, a web application has been developed that helps users initiate a Hyperchain, set up validators, and delegate stake. This tool simplifies the deployment process and reduces the technical barriers to entry. Additionally, bridge functionality to aeternity and potentially other Hyperchains enables cross-chain value and information exchange.

The modular design of Hyperchains creates opportunities for enhancement in several areas. Privacy mechanisms could be implemented through zero-knowledge proofs while maintaining security anchoring. Governance capabilities could be expanded to create more responsive parameter adjustment and protocol upgrade processes. These potential enhancements highlight the composable nature of the Hyperchains architecture, which can be adapted to diverse requirements without sacrificing its core security model.

Broader Implications

Hyperchains represent a significant advancement in blockchain architecture, addressing fundamental limitations in existing systems through lessons learned from implementation experience. By combining established proof-of-work security with efficient proof-of-stake transaction processing, they enable applications requiring both throughput and security—previously impossible in single-chain systems.

The periodic synchronization approach significantly reduces environmental impact by leveraging existing proof-of-work security rather than duplicating mining operations. Economically, minimal

*This is taken from the , which may be more frequently updated :

The Sophia Language

An Æternity BlockChain Language

The Sophia is a language in the ML family. It is strongly typed and has restricted mutable state.

Sophia is customized for smart contracts, which can be published to a blockchain (the Æternity BlockChain). Thus some features of conventional languages, such as floating point arithmetic, are not present in Sophia, and some blockchain specific primitives, constructions and types have been added.

Table of Contents

• • • Calling other contracts

    • Protected contract calls

Language Features

Contracts

The main unit of code in Sophia is the contract.

• A contract implementation, or simply a contract, is the code for a smart contract and consists of a list of types, entrypoints and local functions. Only the entrypoints can be called from outside the contract.

• A contract instance is an entity living on the block chain (or in a state channel). Each instance has an address that can be used to call its entrypoints, either from another contract or in a call transaction.

• A contract may define a type state encapsulating its local state. When creating a new contract the init entrypoint is executed and the state is initialized to its return value.

The language offers some primitive functions to interact with the blockchain and contracts. Please refer to the Chain, Contract and the Call namespaces in the documentation.

Calling other contracts

To call a function in another contract you need the address to an instance of the contract. The type of the address must be a contract type, which consists of a number of type definitions and entrypoint declarations. For instance,

Now given contract address of type VotingType you can call the vote entrypoint of that contract:

Contract calls take two optional named arguments gas : int and value : int that lets you set a gas limit and provide tokens to a contract call. If omitted the defaults are no gas limit and no tokens. Suppose there is a fee for voting:

Named arguments can be given in any order.

Note that reentrant calls are not permitted. In other words, when calling another contract it cannot call you back (directly or indirectly).

To construct a value of a contract type you can give a contract address literal (for instance ct_2gPXZnZdKU716QBUFKaT4VdBZituK93KLvHJB3n4EnbrHHw4Ay), or convert an account address to a contract address using Address.to_contract. Note that if the contract does not exist, or it doesn't have the entrypoint, or the type of the entrypoint does not match the stated contract type, the call fails.

To recover the underlying address of a contract instance there is a field address : address. For instance, to send tokens to the voting contract (given that it is payable) without calling it you can write

Protected contract calls

If a contract call fails for any reason (for instance, the remote contract crashes or runs out of gas, or the entrypoint doesn't exist or has the wrong type) the parent call also fails. To make it possible to recover from failures, contract calls takes a named argument protected : bool (default false).

The protected argument must be a literal boolean, and when set to true changes the type of the contract call, wrapping the result in an option type. If the call fails the result is None, otherwise it's Some(r) where r is the return value of the call.

Any gas that was consumed by the contract call before the failure stays consumed, which means that in order to protect against the remote contract running out of gas it is necessary to set a gas limit using the gas argument. However, note that errors that would normally consume all the gas in the transaction still only uses up the gas spent running the contract.

Contract factories and child contracts

Since the version 6.0.0 Sophia supports deploying contracts by other contracts. This can be done in two ways:

• Contract cloning via Chain.clone

• Direct deploy via Chain.create

These functions take variable number of arguments that must match the created contract's init function. Beside that they take some additional named arguments – please refer to their documentation for the details.

While Chain.clone requires only a contract interface and a living instance of a given contract on the chain, Chain.create needs a full definition of a to-create contract defined by the standard contract syntax, for example

In case of a presence of child contracts (IntHolder in this case), the main contract must be pointed out with the main keyword as shown in the example.

Mutable state

Sophia does not have arbitrary mutable state, but only a limited form of state associated with each contract instance.

• Each contract defines a type state encapsulating its mutable state. The type state defaults to the unit.

• The initial state of a contract is computed by the contract's init function. The init function is pure and returns the initial state as its return value. If the type state is unit, the init

To make it convenient to update parts of a deeply nested state Sophia provides special syntax for map/record updates.

Stateful functions

Top-level functions and entrypoints must be annotated with the stateful keyword to be allowed to affect the state of the running contract. For instance,

Without the stateful annotation the compiler does not allow the call to put. A stateful annotation is required to

• Use a stateful primitive function. These are

  • put

  • Chain.spend

A stateful annotation is not required to

• Read the contract state.

• Issue an event using the event function.

• Call another contract with value = 0, even if the called function is stateful.

Payable

Payable contracts

A concrete contract is by default not payable. Any attempt at spending to such a contract (either a Chain.spend or a normal spend transaction) will fail. If a contract shall be able to receive funds in this way it has to be declared payable:

If in doubt, it is possible to check if an address is payable using Address.is_payable(addr).

Payable entrypoints

A contract entrypoint is by default not payable. Any call to such a function (either a Remote call or a contract call transaction) that has a non-zero value will fail. Contract entrypoints that should be called with a non-zero value should be declared payable.

Note: In the Aeternity VM (AEVM) contracts and entrypoints were by default payable until the Lima release.

Namespaces

Code can be split into libraries using the namespace construct. Namespaces can appear at the top-level and can contain type and function definitions, but not entrypoints. Outside the namespace you can refer to the (non-private) names by qualifying them with the namespace (Namespace.name). For example,

Functions in namespaces have access to the same environment (including the Chain, Call, and Contract, builtin namespaces) as function in a contract, with the exception of state, put and Chain.event since these are dependent on the specific state and event types of the contract.

Splitting code over multiple files

Code from another file can be included in a contract using an include statement. These must appear at the top-level (outside the main contract). The included file can contain one or more namespaces and abstract contracts. For example, if the file library.aes contains

you can use it from another file using an include:

This behaves as if the contents of library.aes was textually inserted into the file, except that error messages will refer to the original source locations. The language will try to include each file at most one time automatically, so even cyclic includes should be working without any special tinkering.

Standard library

Sophia offers standard library which exposes some primitive operations and some higher level utilities. The builtin namespaces like Chain, Contract, Map are included by default and are supported internally by the compiler. Others like List, Frac, Option need to be manually included using the include directive. For example

Types

Sophia has the following types:

Literals

Arithmetic

Sophia integers (int) are represented by 256-bit (AEVM) or arbitrary-sized (FATE) signed words and supports the following arithmetic operations:

• addition (x + y)

• subtraction (x - y)

• multiplication (x * y)

All operations are safe with respect to overflow and underflow. On AEVM they behave as the corresponding operations on arbitrary-size integers and fail with arithmetic_error if the result cannot be represented by a 256-bit signed word. For example, 2 ^ 255 fails rather than wrapping around to -2²⁵⁵.

The division and modulo operations also throw an arithmetic error if the second argument is zero.

Bit fields

Sophia integers do not support bit arithmetic. Instead there is a separate type bits. See the standard library documentation.

On the AEVM a bit field is represented by a 256-bit word and reading or writing a bit outside the 0..255 range fails with an arithmetic_error. On FATE a bit field can be of arbitrary size (but it is still represented by the corresponding integer, so setting very high bits can be expensive).

Type aliases

Type aliases can be introduced with the type keyword and can be parameterized. For instance

A type alias and its definition can be used interchangeably. Sophia does not support higher-kinded types, meaning that following type alias is invalid: type wrap('f, 'a) = 'f('a)

Algebraic data types

Sophia supports algebraic data types (variant types) and pattern matching. Data types are declared by giving a list of constructors with their respective arguments. For instance,

Elements of data types can be pattern matched against, using the switch construct:

or directly in the left-hand side:

NOTE: Data types cannot currently be recursive.

Lists

A Sophia list is a dynamically sized, homogenous, immutable, singly linked list. A list is constructed with the syntax [1, 2, 3]. The elements of a list can be any of datatype but they must have the same type. The type of lists with elements of type 'e is written list('e). For example we can have the following lists:

New elements can be prepended to the front of a list with the :: operator. So 42 :: [1, 2, 3] returns the list [42, 1, 2, 3]. The concatenation operator ++ appends its second argument to its first and returns the resulting list. So concatenating two lists [1, 22, 33] ++ [10, 18, 55] returns the list [1, 22, 33, 10, 18, 55].

Sophia supports list comprehensions known from languages like Python, Haskell or Erlang. Example syntax:

Lists can be constructed using the range syntax using special .. operator:

The ranges are always ascending and have step equal to 1.

Please refer to the standard library for the predefined functionalities.

Maps and records

A Sophia record type is given by a fixed set of fields with associated, possibly different, types. For instance

Maps, on the other hand, can contain an arbitrary number of key-value bindings, but of a fixed type. The type of maps with keys of type 'k and values of type 'v is written map('k, 'v). The key type can be any type that does not contain a map or a function type.

Please refer to the standard library for the predefined functionalities.

Constructing maps and records

A value of record type is constructed by giving a value for each of the fields. For the example above,

Maps are constructed similarly, with keys enclosed in square brackets

The empty map is written {}.

Accessing values

Record fields access is written r.f and map lookup m[k]. For instance,

Looking up a non-existing key in a map results in contract execution failing. A default value to return for non-existing keys can be provided using the syntax m[k = default]. See also Map.member and Map.lookup below.

Updating a value

Record field updates are written r{f = v}. This creates a new record value which is the same as r, but with the value of the field f replaced by v. Similarly, m{[k] = v} constructs a map with the same values as m except that k maps to v. It makes no difference if m has a mapping for k or not.

It is possible to give a name to the old value of a field or mapping in an update: instead of acc{ balance = acc.balance + 100 } it is possible to write acc{ balance @ b = b + 100 }, binding b to acc.balance. When giving a name to a map value (m{ [k] @ x = v }), the corresponding key must be present in the map or execution fails, but a default value can be provided: m{ [k = default] @ x = v }. In this case x is bound to default if k is not in the map.

Updates can be nested:

This is equivalent to accounts{ [a] @ acc = acc{ history = [] } } and thus requires a to be present in the accounts map. To have clear_history create an account if a is not in the map you can write (given a function empty_account):

Map implementation

Internally in the VM maps are implemented as hash maps and support fast lookup and update. Large maps can be stored in the contract state and the size of the map does not contribute to the gas costs of a contract call reading or updating it.

Strings

There is a builtin type string, which can be seen as an array of bytes. Strings can be compared for equality (==, !=), used as keys in maps and records, and used in builtin functions String.length, String.concat and the hash functions described below.

Please refer to the String library documentation.

Chars

There is a builtin type char (the underlying representation being an integer), mainly used to manipulate strings via String.to_list/String.from_list.

Characters can also be introduced as character literals (`'x', '+', ...).

Please refer to the Char library documentation.

Byte arrays

Byte arrays are fixed size arrays of 8-bit integers. They are described in hexadecimal system, for example the literal #cafe creates a two-element array of bytes ca (202) and fe (254) and thus is a value of type bytes(2).

Please refer to the Bytes library documentation.

Cryptographic builins

Libraries Crypto and String provide functions to hash objects, verify signatures etc. The hash is a type alias for bytes(32).

AEVM note

The hash functions in String hash strings interpreted as byte arrays, and the Crypto hash functions accept an element of any (first-order) type. The result is the hash of the binary encoding of the argument as described below. Note that this means that for s : string, String.sha3(s) and Crypto.sha3(s) will give different results on AEVM.

Authorization interface

When a Generalized account is authorized, the authorization function needs access to the transaction and the transaction hash for the wrapped transaction. (A GAMetaTx wrapping a transaction.) The transaction and the transaction hash is available in the primitive Auth.tx and Auth.tx_hash respectively, they are only available during authentication if invoked by a normal contract call they return None.

Oracle interface

You can attach an oracle to the current contract and you can interact with oracles through the Oracle interface.

For a full description of how Oracle works see . For a functionality documentation refer to the standard library.

Example

Example for an oracle answering questions of type string with answers of type int:

Sanity checks

When an Oracle literal is passed to a contract, no deep checks are performed. For extra safety Oracle.check and Oracle.check_query functions are provided.

AENS interface

Contracts can interact with the . For this purpose the AENS library was exposed.

Example

In this example we assume that the name name already exists, and is owned by an account with address addr. In order to allow a contract ct to handle name the account holder needs to create a signature sig of addr | name.hash | ct.address.

Armed with this information we can for example write a function that extends the name if it expires within 1000 blocks:

And we can write functions that adds and removes keys from the pointers of the name:

Note: From the Iris hardfork more strict rules apply for AENS pointers, when a Sophia contract lookup or update (bad) legacy pointers, the bad keys are automatically removed so they will not appear in the pointers map.

Events

Sophia contracts log structured messages to an event log in the resulting blockchain transaction. The event log is quite similar to . Events are further discussed in the .

To use events a contract must declare a datatype event, and events are then logged using the Chain.event function:

The event can have 0-3 indexed fields, and an optional payload field. A field is indexed if it fits in a 32-byte word, i.e.

• bool

• int

• bits

• address

The payload field must be either a string or a byte array of more than 32 bytes. The fields can appear in any order.

NOTE: Indexing is not part of the core aeternity node.

Events are emitted by using the Chain.event function. The following function will emit one Event of each kind in the example.

Argument order

It is only possible to have one (1) string parameter in the event, but it can be placed in any position (and its value will end up in the data field), i.e.

would yield exactly the same result in the example above!

Compiler pragmas

To enforce that a contract is only compiled with specific versions of the Sophia compiler, you can give one or more @compiler pragmas at the top-level (typically at the beginning) of a file. For instance, to enforce that a contract is compiled with version 4.3 of the compiler you write

Valid operators in compiler pragmas are <, =<, ==, >=, and >. Version numbers are given as a sequence of non-negative integers separated by dots. Trailing zeros are ignored, so 4.0.0 == 4. If a constraint is violated an error is reported and compilation fails.

Exceptions

Contracts can fail with an (uncatchable) exception using the built-in function

Calling abort causes the top-level call transaction to return an error result containing the reason string. Only the gas used up to and including the abort call is charged. This is different from termination due to a crash which consumes all available gas.

For convenience the following function is also built-in:

Syntax

Lexical syntax

Comments

Single line comments start with // and block comments are enclosed in /* and */ and can be nested.

Keywords

Tokens

• Id = [a-z_][A-Za-z0-9_']* identifiers start with a lower case letter.

• Con = [A-Z][A-Za-z0-9_']* constructors start with an upper case letter.

• QId = (Con\.)+Id qualified identifiers (e.g. Map.member)

Valid string escape codes are

See the for the details on the base58 literals.

Layout blocks

Sophia uses Python-style layout rules to group declarations and statements. A layout block with more than one element must start on a separate line and be indented more than the currently enclosing layout block. Blocks with a single element can be written on the same line as the previous token.

Each element of the block must share the same indentation and no part of an element may be indented less than the indentation of the block. For instance

Notation

In describing the syntax below, we use the following conventions:

• Upper-case identifiers denote non-terminals (like Expr) or terminals with some associated value (like Id).

• Keywords and symbols are enclosed in single quotes: 'let' or '='.

• Choices are separated by vertical bars: |

Declarations

A Sophia file consists of a sequence of declarations in a layout block.

Contract declarations must appear at the top-level.

For example,

There are three forms of type declarations: type aliases (declared with the type keyword), record type definitions (record) and data type definitions (datatype):

For example,

Types

The function type arrow associates to the right.

Example,

Statements

Function bodies are blocks of statements, where a statement is one of the following

if statements can be followed by zero or more elif statements and an optional final else statement. For example,

Expressions

Operators types

Operator precendences

In order of highest to lowest precedence.

Examples

Delegation signature

Some chain operations (Oracle.<operation> and AENS.<operation>) have an optional delegation signature. This is typically used when a user/accounts would like to allow a contract to act on it's behalf. The exact data to be signed varies for the different operations, but in all cases you should prepend the signature data with the network_id (ae_mainnet for the Aeternity mainnet, etc.).

*This is taken from the , which may be more frequently updated :

The Sophia Language

An Æternity BlockChain Language

The Sophia is a language in the ML family. It is strongly typed and has restricted mutable state.

Sophia is customized for smart contracts, which can be published to a blockchain (the Æternity BlockChain). Thus some features of conventional languages, such as floating point arithmetic, are not present in Sophia, and some blockchain specific primitives, constructions and types have been added.

Table of Contents

• • • Calling other contracts

    • Protected contract calls

Language Features

Contracts

The main unit of code in Sophia is the contract.

• A contract implementation, or simply a contract, is the code for a smart contract and consists of a list of types, entrypoints and local functions. Only the entrypoints can be called from outside the contract.

• A contract instance is an entity living on the block chain (or in a state channel). Each instance has an address that can be used to call its entrypoints, either from another contract or in a call transaction.

• A contract may define a type state encapsulating its local state. When creating a new contract the init entrypoint is executed and the state is initialized to its return value.

The language offers some primitive functions to interact with the blockchain and contracts. Please refer to the Chain, Contract and the Call namespaces in the documentation.

Calling other contracts

To call a function in another contract you need the address to an instance of the contract. The type of the address must be a contract type, which consists of a number of type definitions and entrypoint declarations. For instance,

Now given contract address of type VotingType you can call the vote entrypoint of that contract:

Contract calls take two optional named arguments gas : int and value : int that lets you set a gas limit and provide tokens to a contract call. If omitted the defaults are no gas limit and no tokens. Suppose there is a fee for voting:

Named arguments can be given in any order.

Note that reentrant calls are not permitted. In other words, when calling another contract it cannot call you back (directly or indirectly).

To construct a value of a contract type you can give a contract address literal (for instance ct_2gPXZnZdKU716QBUFKaT4VdBZituK93KLvHJB3n4EnbrHHw4Ay), or convert an account address to a contract address using Address.to_contract. Note that if the contract does not exist, or it doesn't have the entrypoint, or the type of the entrypoint does not match the stated contract type, the call fails.

To recover the underlying address of a contract instance there is a field address : address. For instance, to send tokens to the voting contract (given that it is payable) without calling it you can write

Protected contract calls

If a contract call fails for any reason (for instance, the remote contract crashes or runs out of gas, or the entrypoint doesn't exist or has the wrong type) the parent call also fails. To make it possible to recover from failures, contract calls takes a named argument protected : bool (default false).

The protected argument must be a literal boolean, and when set to true changes the type of the contract call, wrapping the result in an option type. If the call fails the result is None, otherwise it's Some(r) where r is the return value of the call.

Any gas that was consumed by the contract call before the failure stays consumed, which means that in order to protect against the remote contract running out of gas it is necessary to set a gas limit using the gas argument. However, note that errors that would normally consume all the gas in the transaction still only uses up the gas spent running the contract.

Contract factories and child contracts

Since the version 6.0.0 Sophia supports deploying contracts by other contracts. This can be done in two ways:

• Contract cloning via Chain.clone

• Direct deploy via Chain.create

These functions take variable number of arguments that must match the created contract's init function. Beside that they take some additional named arguments – please refer to their documentation for the details.

While Chain.clone requires only a contract interface and a living instance of a given contract on the chain, Chain.create needs a full definition of a to-create contract defined by the standard contract syntax, for example

In case of a presence of child contracts (IntHolder in this case), the main contract must be pointed out with the main keyword as shown in the example.

Mutable state

Sophia does not have arbitrary mutable state, but only a limited form of state associated with each contract instance.

• Each contract defines a type state encapsulating its mutable state. The type state defaults to the unit.

• The initial state of a contract is computed by the contract's init function. The init function is pure and returns the initial state as its return value. If the type state is unit, the init

To make it convenient to update parts of a deeply nested state Sophia provides special syntax for map/record updates.

Stateful functions

Top-level functions and entrypoints must be annotated with the stateful keyword to be allowed to affect the state of the running contract. For instance,

Without the stateful annotation the compiler does not allow the call to put. A stateful annotation is required to

• Use a stateful primitive function. These are

  • put

  • Chain.spend

A stateful annotation is not required to

• Read the contract state.

• Issue an event using the event function.

• Call another contract with value = 0, even if the called function is stateful.

Payable

Payable contracts

A concrete contract is by default not payable. Any attempt at spending to such a contract (either a Chain.spend or a normal spend transaction) will fail. If a contract shall be able to receive funds in this way it has to be declared payable:

If in doubt, it is possible to check if an address is payable using Address.is_payable(addr).

Payable entrypoints

A contract entrypoint is by default not payable. Any call to such a function (either a Remote call or a contract call transaction) that has a non-zero value will fail. Contract entrypoints that should be called with a non-zero value should be declared payable.

Note: In the Aeternity VM (AEVM) contracts and entrypoints were by default payable until the Lima release.

Namespaces

Code can be split into libraries using the namespace construct. Namespaces can appear at the top-level and can contain type and function definitions, but not entrypoints. Outside the namespace you can refer to the (non-private) names by qualifying them with the namespace (Namespace.name). For example,

Functions in namespaces have access to the same environment (including the Chain, Call, and Contract, builtin namespaces) as function in a contract, with the exception of state, put and Chain.event since these are dependent on the specific state and event types of the contract.

Splitting code over multiple files

Code from another file can be included in a contract using an include statement. These must appear at the top-level (outside the main contract). The included file can contain one or more namespaces and abstract contracts. For example, if the file library.aes contains

you can use it from another file using an include:

This behaves as if the contents of library.aes was textually inserted into the file, except that error messages will refer to the original source locations. The language will try to include each file at most one time automatically, so even cyclic includes should be working without any special tinkering.

Standard library

Sophia offers standard library which exposes some primitive operations and some higher level utilities. The builtin namespaces like Chain, Contract, Map are included by default and are supported internally by the compiler. Others like List, Frac, Option need to be manually included using the include directive. For example

Types

Sophia has the following types:

Literals

Arithmetic

Sophia integers (int) are represented by 256-bit (AEVM) or arbitrary-sized (FATE) signed words and supports the following arithmetic operations:

• addition (x + y)

• subtraction (x - y)

• multiplication (x * y)

All operations are safe with respect to overflow and underflow. On AEVM they behave as the corresponding operations on arbitrary-size integers and fail with arithmetic_error if the result cannot be represented by a 256-bit signed word. For example, 2 ^ 255 fails rather than wrapping around to -2²⁵⁵.

The division and modulo operations also throw an arithmetic error if the second argument is zero.

Bit fields

Sophia integers do not support bit arithmetic. Instead there is a separate type bits. See the standard library documentation.

On the AEVM a bit field is represented by a 256-bit word and reading or writing a bit outside the 0..255 range fails with an arithmetic_error. On FATE a bit field can be of arbitrary size (but it is still represented by the corresponding integer, so setting very high bits can be expensive).

Type aliases

Type aliases can be introduced with the type keyword and can be parameterized. For instance

A type alias and its definition can be used interchangeably. Sophia does not support higher-kinded types, meaning that following type alias is invalid: type wrap('f, 'a) = 'f('a)

Algebraic data types

Sophia supports algebraic data types (variant types) and pattern matching. Data types are declared by giving a list of constructors with their respective arguments. For instance,

Elements of data types can be pattern matched against, using the switch construct:

or directly in the left-hand side:

NOTE: Data types cannot currently be recursive.

Lists

A Sophia list is a dynamically sized, homogenous, immutable, singly linked list. A list is constructed with the syntax [1, 2, 3]. The elements of a list can be any of datatype but they must have the same type. The type of lists with elements of type 'e is written list('e). For example we can have the following lists:

New elements can be prepended to the front of a list with the :: operator. So 42 :: [1, 2, 3] returns the list [42, 1, 2, 3]. The concatenation operator ++ appends its second argument to its first and returns the resulting list. So concatenating two lists [1, 22, 33] ++ [10, 18, 55] returns the list [1, 22, 33, 10, 18, 55].

Sophia supports list comprehensions known from languages like Python, Haskell or Erlang. Example syntax:

Lists can be constructed using the range syntax using special .. operator:

The ranges are always ascending and have step equal to 1.

Please refer to the standard library for the predefined functionalities.

Maps and records

A Sophia record type is given by a fixed set of fields with associated, possibly different, types. For instance

Maps, on the other hand, can contain an arbitrary number of key-value bindings, but of a fixed type. The type of maps with keys of type 'k and values of type 'v is written map('k, 'v). The key type can be any type that does not contain a map or a function type.

Please refer to the standard library for the predefined functionalities.

Constructing maps and records

A value of record type is constructed by giving a value for each of the fields. For the example above,

Maps are constructed similarly, with keys enclosed in square brackets

The empty map is written {}.

Accessing values

Record fields access is written r.f and map lookup m[k]. For instance,

Looking up a non-existing key in a map results in contract execution failing. A default value to return for non-existing keys can be provided using the syntax m[k = default]. See also Map.member and Map.lookup below.

Updating a value

Record field updates are written r{f = v}. This creates a new record value which is the same as r, but with the value of the field f replaced by v. Similarly, m{[k] = v} constructs a map with the same values as m except that k maps to v. It makes no difference if m has a mapping for k or not.

It is possible to give a name to the old value of a field or mapping in an update: instead of acc{ balance = acc.balance + 100 } it is possible to write acc{ balance @ b = b + 100 }, binding b to acc.balance. When giving a name to a map value (m{ [k] @ x = v }), the corresponding key must be present in the map or execution fails, but a default value can be provided: m{ [k = default] @ x = v }. In this case x is bound to default if k is not in the map.

Updates can be nested:

This is equivalent to accounts{ [a] @ acc = acc{ history = [] } } and thus requires a to be present in the accounts map. To have clear_history create an account if a is not in the map you can write (given a function empty_account):

Map implementation

Internally in the VM maps are implemented as hash maps and support fast lookup and update. Large maps can be stored in the contract state and the size of the map does not contribute to the gas costs of a contract call reading or updating it.

Strings

There is a builtin type string, which can be seen as an array of bytes. Strings can be compared for equality (==, !=), used as keys in maps and records, and used in builtin functions String.length, String.concat and the hash functions described below.

Please refer to the String library documentation.

Chars

There is a builtin type char (the underlying representation being an integer), mainly used to manipulate strings via String.to_list/String.from_list.

Characters can also be introduced as character literals (`'x', '+', ...).

Please refer to the Char library documentation.

Byte arrays

Byte arrays are fixed size arrays of 8-bit integers. They are described in hexadecimal system, for example the literal #cafe creates a two-element array of bytes ca (202) and fe (254) and thus is a value of type bytes(2).

Please refer to the Bytes library documentation.

Cryptographic builins

Libraries Crypto and String provide functions to hash objects, verify signatures etc. The hash is a type alias for bytes(32).

AEVM note

The hash functions in String hash strings interpreted as byte arrays, and the Crypto hash functions accept an element of any (first-order) type. The result is the hash of the binary encoding of the argument as described below. Note that this means that for s : string, String.sha3(s) and Crypto.sha3(s) will give different results on AEVM.

Authorization interface

When a Generalized account is authorized, the authorization function needs access to the transaction and the transaction hash for the wrapped transaction. (A GAMetaTx wrapping a transaction.) The transaction and the transaction hash is available in the primitive Auth.tx and Auth.tx_hash respectively, they are only available during authentication if invoked by a normal contract call they return None.

Oracle interface

You can attach an oracle to the current contract and you can interact with oracles through the Oracle interface.

For a full description of how Oracle works see . For a functionality documentation refer to the standard library.

Example

Example for an oracle answering questions of type string with answers of type int:

Sanity checks

When an Oracle literal is passed to a contract, no deep checks are performed. For extra safety Oracle.check and Oracle.check_query functions are provided.

AENS interface

Contracts can interact with the . For this purpose the AENS library was exposed.

Example

In this example we assume that the name name already exists, and is owned by an account with address addr. In order to allow a contract ct to handle name the account holder needs to create a signature sig of addr | name.hash | ct.address.

Armed with this information we can for example write a function that extends the name if it expires within 1000 blocks:

And we can write functions that adds and removes keys from the pointers of the name:

Note: From the Iris hardfork more strict rules apply for AENS pointers, when a Sophia contract lookup or update (bad) legacy pointers, the bad keys are automatically removed so they will not appear in the pointers map.

Events

Sophia contracts log structured messages to an event log in the resulting blockchain transaction. The event log is quite similar to . Events are further discussed in the .

To use events a contract must declare a datatype event, and events are then logged using the Chain.event function:

The event can have 0-3 indexed fields, and an optional payload field. A field is indexed if it fits in a 32-byte word, i.e.

• bool

• int

• bits

• address

The payload field must be either a string or a byte array of more than 32 bytes. The fields can appear in any order.

NOTE: Indexing is not part of the core aeternity node.

Events are emitted by using the Chain.event function. The following function will emit one Event of each kind in the example.

Argument order

It is only possible to have one (1) string parameter in the event, but it can be placed in any position (and its value will end up in the data field), i.e.

would yield exactly the same result in the example above!

Compiler pragmas

To enforce that a contract is only compiled with specific versions of the Sophia compiler, you can give one or more @compiler pragmas at the top-level (typically at the beginning) of a file. For instance, to enforce that a contract is compiled with version 4.3 of the compiler you write

Valid operators in compiler pragmas are <, =<, ==, >=, and >. Version numbers are given as a sequence of non-negative integers separated by dots. Trailing zeros are ignored, so 4.0.0 == 4. If a constraint is violated an error is reported and compilation fails.

Exceptions

Contracts can fail with an (uncatchable) exception using the built-in function

Calling abort causes the top-level call transaction to return an error result containing the reason string. Only the gas used up to and including the abort call is charged. This is different from termination due to a crash which consumes all available gas.

For convenience the following function is also built-in:

Syntax

Lexical syntax

Comments

Single line comments start with // and block comments are enclosed in /* and */ and can be nested.

Keywords

Tokens

• Id = [a-z_][A-Za-z0-9_']* identifiers start with a lower case letter.

• Con = [A-Z][A-Za-z0-9_']* constructors start with an upper case letter.

• QId = (Con\.)+Id qualified identifiers (e.g. Map.member)