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.

Next, we will cover core concepts of the æternity blockchain, starting with the protocol itself. Feel free to explore the topics outlined in the sidebar menu, or jump to different sections 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:

• State Channels: 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 Smart Contracts: æternity utilizes Sophia, 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.

• FATE Virtual Machine: 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.

• ÆNS (æternity Naming System): This system enables users to replace complex blockchain addresses with human-readable names, making blockchain interactions more user-friendly and less prone to errors.

• Native Oracles: Oracles, which bridge the blockchain with real-world data, are a native part of the æternity protocol. This enables developers to easily incorporate external information into their smart contracts, enhancing the functionality and possibilities of decentralized applications.

• Weighted Delegated Coin-Voting: æternity features a governance system that allows AE coin holders to participate in the decision-making process concerning the future development of the platform. This system utilizes a weighted voting approach where voting power is proportional to the number of coins held.

• Hyperchains: Hyperchains are æternity's innovative solution for creating secure, customizable blockchains that leverage the security of established proof-of-work networks. By periodically anchoring their state to a pinning chain, Hyperchains enable organizations to deploy specialized blockchain solutions with minimal infrastructure investment while maintaining robust security. This technology uniquely positions æternity as a platform that makes enterprise-grade blockchain implementations accessible and practical, expanding the ecosystem's utility for businesses and developers.

æ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.

• Identity Management: The security and decentralization of æternity can be utilized to build secure and user-controlled identity systems that are more user-friendly than other Web3 solutions.

As æternity continues to evolve, it aims to implement further scaling solutions like Hyperchains, a sidechain technology that will allow 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.

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.

At the heart of the æternity protocol lies the AE coin, the native currency of the æternity blockchain. AE coins are the lifeblood of the system, powering all operations on the blockchain, from simple value transfers to the execution of sophisticated smart contracts. Every transaction on the æternity blockchain incurs a fee, paid in AE coins, which is known as a "transaction fee" or "gas fee.".

Next Generation Nakamoto Consensus (Bitcoin-NG)

To achieve a high transaction throughput, æternity leverages a modified version of the consensus mechanism used by Bitcoin, known as Bitcoin-NG. Bitcoin-NG introduces a distinction between two types of blocks: key-blocks and micro-blocks. Key-blocks are responsible for electing a new "leader" miner, granting them the exclusive right to add transactions to the blockchain for a designated period. Once a leader is elected, they can generate a series of smaller micro-blocks in quick succession, each containing a limited number of transactions. This separation of leader selection and transaction processing enhances the efficiency of the blockchain, allowing for faster transaction confirmation times. In æternity, micro-blocks are created every three seconds.

The process of electing a leader involves solving a computational challenge known as "proof-of-work." æternity utilizes the Cuckoo Cycle algorithm for this purpose. Cuckoo Cycle is a memory-bound algorithm, meaning its performance is heavily reliant on memory access speeds. This characteristic makes it more challenging for specialized mining hardware (ASICs) to dominate the mining process, promoting a more decentralized and equitable distribution of mining power.

Weighted Delegated Coin-Voting

Beyond the mining process, AE coin holders have a say in the governance of the æternity blockchain through a mechanism called weighted delegated coin-voting. This system enables coin holders to delegate their voting rights to other accounts on the blockchain. The weight of each vote is proportional to the number of coins held, embodying a "skin in the game" principle where those with a greater stake have a stronger influence on decision-making.

State Channels

For further scalability and privacy enhancements, æternity incorporates state channels. State channels function as off-chain agreements between two parties, facilitating numerous transactions away from the main blockchain. Only the concluding outcome of these transactions is ultimately recorded on the blockchain, minimizing the on-chain footprint and expediting transaction speeds.

ÆNS, Oracles, Sophia, and the FATE VM

The æternity protocol also encompasses a native naming system known as ÆNS, a method for incorporating real-world data through oracles, and a dedicated smart contract language and virtual machine. These components contribute to the platform's versatility and user-friendliness. Smart contracts, self-executing agreements encoded on the blockchain, are written in Sophia, a functional programming language designed with security and efficiency as top priorities. Sophia contracts are then executed within the FATE (Fast Æternity Transaction Engine) VM, a virtual machine custom-built for the æternity blockchain.

The æternity protocol represents a comprehensive and meticulously engineered framework for a secure, efficient, and user-centric blockchain platform. Its implementation in Erlang and its open-source philosophy underscore a dedication to reliability, transparency, and community engagement.

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

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.

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.

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.

Mining Æ Coins: The Cuckoo Cycle Algorithm

The creation of new Æ coins is governed by a process called mining, which is closely tied to the consensus mechanism of the æternity blockchain. æternity utilizes a modified version of the Nakamoto consensus algorithm, known as Bitcoin-NG, which introduces the concept of key-blocks and micro-blocks. Miners compete to solve complex computational puzzles using the Cuckoo Cycle algorithm, a memory-bound proof-of-work system designed to be resistant to specialized mining hardware.

When a miner successfully solves a Cuckoo Cycle puzzle, they earn the right to produce a key-block, which initiates a new "generation" on the blockchain. This key-block grants the miner the authority to generate a sequence of micro-blocks, each containing a limited number of transactions. Miners receive rewards in the form of newly minted Æ coins for both creating key-blocks and including transactions in micro-blocks.

Economic Model and Coin Supply

The æternity blockchain follows a predefined economic model with a finite coin supply. During the initial token sale in 2017, a significant portion of the initial AE Tokens/Æ coins were distributed, with the remainder allocated to the founding team, company, and foundation for future use. Following the launch of the mainnet, mining began, gradually increasing the total number of Æ coins in circulation. Similar to Bitcoin, the rate of new coin creation decreases over time, eventually reaching a maximum limit. This controlled issuance schedule ensures scarcity and helps to maintain the value of Æ coins.

Essential Information and Future Considerations

Understanding the role and function of Æcoins is fundamental to navigating the æternity ecosystem. These coins are not merely a speculative asset but the driving force behind all activity on the blockchain. The mining process, consensus mechanism, and economic model work together to ensure the security, stability, and sustainability of the æternity network. As the æternity blockchain continues to evolve, Æ coins will undoubtedly remain a central element of its operation and growth.

æ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 Erlang, 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 user tools or developer tools section.

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.

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.

Full Nodes

Full nodes serve as the backbone of the æternity network, maintaining a complete copy of the blockchain and participating in all core network functions. These nodes store the entire blockchain history, including all key blocks since genesis, micro blocks and their transactions, the current state tree, smart contract states, and oracle data. This comprehensive data storage enables full nodes to independently verify all transactions and states, contributing to the network's decentralization and security.

The responsibilities of full nodes extend beyond simple data storage. They actively participate in transaction validation, ensuring that all new transactions comply with network rules. They propagate blocks and transactions throughout the network, maintaining the network's connectivity and information flow. Additionally, full nodes verify smart contract execution and maintain the current state of the blockchain, making them crucial for network integrity.

Operating a full node demands significant resources. Operators must provide substantial disk space to store the complete blockchain, adequate RAM for efficient state management, and a reliable network connection for peer-to-peer communication. Despite these requirements, running a full node represents the most complete form of network participation and provides the highest level of security and independence in network interaction.

Mining Nodes

Mining nodes build upon the functionality of full nodes by adding active participation in the block creation process. These nodes implement the Cuckoo Cycle proof-of-work system, æternity's chosen mining algorithm. Mining nodes not only maintain the network like full nodes but also compete to create new key blocks and, when selected as leaders, generate micro blocks containing transactions.

The mining process in æternity is particularly distinctive due to its memory-bound nature. The Cuckoo Cycle algorithm requires significant memory resources rather than pure computational power, making mining more accessible to general-purpose hardware. This design choice helps maintain network decentralization by reducing the advantage of specialized mining hardware.

Mining nodes earn rewards through multiple mechanisms. They receive rewards for creating key blocks, collect transaction fees from micro blocks they generate, and can earn additional income from oracle query fees and name registration fees. This economic model incentivizes continued participation in network security and transaction processing.

Light Nodes

Light nodes offer a resource-efficient alternative for network participation, making them ideal for mobile applications, IoT devices, and environments with limited resources. These nodes operate by storing only essential blockchain data, primarily block headers, while relying on full nodes for complete data verification. This approach significantly reduces the resource requirements while maintaining security through cryptographic verification of received data.

Despite their minimal resource footprint, light nodes provide crucial functionality for network interaction. They enable basic transaction verification, support smart contract interaction, and offer wallet functionality. This makes them perfect for end-user applications that need to interact with the blockchain without the overhead of running a full node.

Specialized Node Roles

The æternity network supports specialized node roles that enhance network functionality. Any full node can serve as an oracle operator, providing external data to the blockchain through the oracle system. These nodes register as oracle providers, respond to oracle queries, and maintain oracle state. The oracle system enables smart contracts to access real-world data, expanding the potential applications of the blockchain.

State channel facilitation represents another specialized role that nodes can adopt. Nodes participating in state channels manage channel state, process off-chain transactions, and handle dispute resolution. This capability is crucial for æternity's scaling solution, allowing many transactions to occur off-chain while maintaining security through the main chain.

Future Evolution

As the æternity network continues to evolve, the roles and requirements of different node types may shift to accommodate new features and scaling solutions. Hyperchains, for example, represent a major advancement in scalability by enabling specialized blockchain networks that inherit security from established proof-of-work chains while operating with greater efficiency and throughput. This development opens new possibilities for cross-chain interoperability and enterprise adoption. Future developments might introduce new specialized node types or modify existing roles to support advanced features like sharding or enhanced cross-chain communication.

Node operators should stay informed about network developments and requirements, as hardware and software needs may change over time. The network's evolution will likely bring new opportunities for participation and specialization, while maintaining the core principles of decentralization and security that underpin the æternity blockchain.

Understanding these node types helps participants choose the most appropriate level of network involvement for their needs and resources. Whether operating a full node for maximum security, running a mining node to earn rewards, or using a light node for efficient network interaction, each type of participation contributes to the network's overall strength and functionality.

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.

Consensus Participation

Every active node in the network participates in consensus by validating and propagating blocks and transactions. When receiving new blocks, nodes verify their validity according to network rules, including proper formatting, valid proof-of-work for key blocks, and correct transaction execution in micro blocks. This distributed validation ensures network security and maintains consensus across all participants.

During the Bitcoin-NG consensus process, nodes evaluate both key blocks and micro blocks. They verify that key blocks contain valid proof-of-work solutions and that micro blocks are properly signed by the current leader. This dual validation process maintains the integrity of æternity's unique consensus mechanism.

Transaction Processing

Nodes play a vital role in transaction processing by maintaining a transaction pool of pending transactions. They receive transactions from users and other nodes, validate them against current network rules and state, and propagate valid transactions to peers. This distributed transaction handling ensures that valid transactions reach miners for inclusion in blocks.

When handling transactions, nodes perform preliminary validations including signature verification, nonce checking, and balance validation. This pre-validation helps maintain network efficiency by filtering invalid transactions before they consume network resources.

State Management and Verification

Nodes maintain and verify the current state of the blockchain, including account balances, contract states, and oracle data. They process state transitions as new blocks arrive, ensuring that all changes follow network rules. This state management role is crucial for maintaining network consistency and enabling smart contract execution.

For smart contracts, nodes execute contract code through the FATE virtual machine, maintaining contract state and processing contract interactions. They verify that all contract executions produce consistent results across the network, ensuring reliable decentralized application operation.

Network Services

Many nodes provide essential services to network users and applications. They offer API endpoints for submitting transactions, querying blockchain state, and accessing historical data. These services enable user interactions with the blockchain and support decentralized application functionality.

Oracle Operations

Nodes can serve as oracle operators, providing external data to the blockchain. In this role, they register as oracle providers, respond to oracle queries with real-world data, and maintain the integrity of the oracle system. This service is crucial for smart contracts that need access to external information.

State Channel Facilitation

Nodes support state channel operations, enabling off-chain scaling solutions. They process channel creation, help maintain channel state, and handle dispute resolution when channels close. This role is essential for enabling high-throughput applications while maintaining security through the main chain.

Network Stability

All nodes contribute to network stability through their participation in the peer-to-peer network. They maintain connections with multiple peers, share network information, and help new nodes synchronize with the current state. This interconnected operation ensures network resilience and reliable operation.

Chain Quality Assurance

Nodes collectively ensure chain quality by following the network's fork choice rules and maintaining the canonical chain. They help prevent and resolve chain splits, maintain proper block ordering, and ensure that the network converges on a single, valid chain state.

Future Network Evolution

As the æternity network evolves, node roles may expand to support new features and capabilities. Nodes may take on additional responsibilities for scaling solutions, cross-chain communication, or enhanced privacy features. This adaptability ensures that the network can grow and improve while maintaining its decentralized nature.

Through these various roles, nodes work together to maintain a secure, efficient, and reliable blockchain network. Each node's participation, regardless of its specific roles, contributes to the overall health and functionality of the æternity ecosystem.

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.

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:

• Types of Transactions

• Transaction Lifecycle

• Transaction Fees

• Meta-transactions and Generalized Accounts

• State Channel Transactions

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.

Network Propagation

Once signed, transactions enter the network propagation phase. Nodes receiving new transactions perform initial validation checks, verifying the transaction format, signature, and basic requirements like adequate fees and correct nonce values. Valid transactions are added to the node's transaction pool and propagated to peer nodes across the network.

Transaction Pool Management

While transactions wait for inclusion in blocks, they reside in nodes' transaction pools. Nodes maintain these pools, regularly updating transaction status and removing transactions that become invalid or expire. The pool management system prioritizes transactions based on fees and other criteria, helping miners select transactions for inclusion in blocks.

Block Inclusion Process

The Bitcoin-NG consensus model used by æternity creates a unique block inclusion process. Unlike traditional blockchains where transactions are included in proof-of-work blocks, æternity separates leader election (key blocks) from transaction processing (micro blocks). The current leader, elected through key block mining, creates micro blocks containing transactions approximately every three seconds.

Confirmation and State Updates

When a transaction is included in a micro block, it undergoes execution, updating the blockchain state according to its type and parameters. The transaction's effects become visible in the network state, though full confirmation requires additional key blocks to ensure finality. This dual-block structure enables faster transaction processing while maintaining security.

Finality and Reorgs

Transaction finality in æternity considers both micro block acceptance and key block confirmations. While transactions in micro blocks update the state quickly, the possibility of chain reorganizations means that participants should wait for several key block confirmations before considering high-value transactions fully final.

Fork Resolution

During network operation, temporary forks may occur when multiple valid chain versions exist. The network's fork resolution rules determine which chain version prevails, potentially affecting transaction inclusion and ordering. Transactions in orphaned blocks return to transaction pools for inclusion in the winning chain.

State Channel Processing

Transactions within state channels follow a modified lifecycle. They are processed off-chain between channel participants, with only channel opening, dispute resolution, and closing transactions appearing on the main chain. This approach enables high-throughput applications while maintaining security through main chain anchoring.

Transaction Monitoring

Throughout their lifecycle, transactions can be monitored through node APIs and blockchain explorers. These tools provide information about transaction status, including pool inclusion, block inclusion, and confirmation depth, helping users and applications track their transactions' progress through the system.

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.

Fee Distribution

The Bitcoin-NG consensus model influences how transaction fees are distributed. When transactions are included in micro blocks, the fees are split between the current leader who created the micro block and the miner who creates the next key block. This split incentivizes both efficient transaction processing and network security, with 40% going to the micro block creator and 60% to the next key block miner.

Fee Calculation

Transaction fees are calculated based on several factors including transaction size, computational complexity, and current network conditions. Smart contract executions include gas costs that reflect the computational and storage resources required. The FATE virtual machine's efficient design helps keep these costs predictable and reasonable for users.

Dynamic Fee Adjustment

While base fees remain constant, effective transaction fees can vary based on network conditions. During periods of high network usage, users may need to offer higher fees to ensure their transactions are processed promptly. The node software helps users estimate appropriate fees based on current network conditions.

Fee Burning

A portion of certain transaction fees, particularly those related to name registration and oracle operations, may be burned (permanently removed from circulation). This mechanism helps manage token supply while adding cost to certain network operations that consume long-term resources.

State Channel Fee Considerations

Transactions within state channels typically don't incur on-chain fees, as they're processed off-chain. However, channel opening, closing, and dispute resolution transactions do require standard network fees. This fee structure makes state channels particularly efficient for high-frequency interactions between parties.

æ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.

Mainnet

The æternity mainnet is the primary production network where real AE tokens hold economic value. Launched in November 2018, the mainnet implements all protocol features with full security measures in place. This network processes actual transactions, executes smart contracts, and maintains the authoritative state of the blockchain. The mainnet uses Cuckoo Cycle proof-of-work for consensus, with carefully calibrated difficulty adjustments to maintain consistent block times.

Development Networks

For developers building on æternity, several development network options exist. The most commonly used is the local development network, which developers can run on their own machines. These networks allow developers to test applications, smart contracts, and protocol features without spending real tokens or waiting for network confirmations.

Development networks can be configured with different parameters than the mainnet, such as faster block times or lower mining difficulty, to facilitate rapid development and testing. They support all mainnet features, including state channels and oracles, making them ideal for application development and testing.

Testnet

The æternity testnet serves as a staging environment for testing applications and protocol updates before mainnet deployment. This network mirrors the mainnet's functionality but uses test tokens without real economic value. Developers and users can experiment with new features, test applications, and validate protocol upgrades on the testnet without risk.

The testnet maintains the same core architecture as the mainnet, including the Bitcoin-NG consensus mechanism and all protocol features. This ensures that testing conditions closely match production environments while providing a safe space for experimentation.

Network Differences

While all æternity networks implement the same basic protocol, they can differ in several aspects:

Genesis configuration determines the initial state of each network, including token distribution and protocol parameters. Mining difficulty varies between networks, with development networks typically using lower difficulties to facilitate faster block creation. Network parameters such as minimum fees, name registration costs, and oracle query fees may be adjusted for different network purposes.

Cross-Network Considerations

When developing on æternity, it's important to consider the differences between networks. Code that works on a development network should be thoroughly tested on the testnet before mainnet deployment. State channel applications, in particular, should be tested across networks to ensure proper behavior under different network conditions.

Future Network Evolution

The æternity protocol continues to evolve, with new features and improvements being developed. These changes typically follow a path from development networks through testnet validation before reaching mainnet deployment. This progression ensures that protocol updates are thoroughly tested and validated before affecting the main network.

Through this network structure, æternity provides a complete environment for both development and production use, enabling secure and efficient blockchain operations while supporting continued innovation and development.

For more information on how to set up a local development network or run the testnet, please refer to the Development Infrastructure section of our developer Tools section.

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.

Key Blocks and Micro Blocks

Bitcoin-NG introduces two distinct types of blocks: key blocks and micro blocks. This separation is at the heart of æternity's improved performance:

Key blocks are used for leader election through proof of work, similar to traditional Bitcoin blocks. When a miner successfully creates a key block, they become the leader for that generation (or epoch). Each new key block starts a new generation and contains the public key of the new leader.

Micro blocks contain the actual transactions and are created by the current leader in rapid succession. Unlike key blocks, micro blocks don't require proof of work, allowing them to be generated quickly - every three seconds in æternity's implementation. This rapid micro block creation is what enables æternity to achieve its high transaction throughput.

Leader Responsibilities and Incentives

Once elected through a key block, a leader can create micro blocks until the next key block is mined. To incentivize proper behavior, transaction fees are split between block creators: 40% goes to the leader who creates a micro block, while 60% goes to the miner of the next key block. This split incentivizes both efficient transaction processing and continued participation in the mining process.

Security and Fork Resolution

The Bitcoin-NG protocol includes several mechanisms to maintain security and prevent abuse:

Fraudulent behavior by leaders (such as creating multiple conflicting micro blocks) can be detected and proven through a Proof-of-Fraud mechanism. When detected, the malicious leader loses their block reward, which is held for 180 blocks before being released.

If a new key block is mined while micro blocks are still being processed, some transactions might temporarily appear in a "micro-fork." These transactions are automatically returned to the transaction pool and will be included in future micro blocks by the new leader.

Performance Benefits

This innovative approach to consensus provides several key advantages:

• Transaction throughput increases to approximately 117 transactions per second, compared to Bitcoin's 7 transactions per second

• Block confirmation time reduces to just 3 seconds, versus Bitcoin's 10 minutes

• Network bandwidth is used more efficiently by spreading transaction data across multiple smaller micro blocks

• The system maintains high security while achieving better scalability

Future Innovations

The Bitcoin-NG consensus mechanism in æternity is designed to be forward-compatible with future improvements. As the platform evolves, this foundation enables the implementation of additional scaling solutions like state channels and Hyperchains, while maintaining the core benefits of decentralization and security.

Understanding Bitcoin-NG is crucial for developers building on æternity, as it influences how transactions are processed and confirmed. The rapid block time and high throughput enable new types of applications that wouldn't be practical on traditional blockchain platforms.

æ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.

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.

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.

The smart contract attached to the account must implement an authentication function that accepts data as input and returns a boolean value indicating whether authentication is successful. This function defines the rules for authorizing transactions from the account, enabling flexible authentication schemes like multi-signature requirements, spending limits, or alternative cryptographic methods.

Understanding Meta-Transactions and Transaction Processing

After an account becomes generalized, all its transactions must be wrapped in meta-transactions. A meta-transaction packages a standard transaction (with its nonce set to zero) along with the necessary authentication data required by the account's smart contract. The meta-transaction includes additional information such as fees and gas needed to execute the smart contract's authorization function.

When the network processes a meta-transaction, it first executes the authentication function in the associated smart contract using the provided authentication data. Only if authentication succeeds does the network process the inner transaction. This two-step process ensures that all transactions follow the custom authorization rules defined in the account's contract while maintaining the security of the network.

Implementation Example: Bitcoin Key Integration

A practical example of generalized accounts is enabling æternity transactions to be signed using Bitcoin private keys. The attached smart contract is initialized with the desired public key and implements ECDSA signature verification using the Secp256k1 curve. The authentication function verifies signatures created by the corresponding Bitcoin private key, allowing users to manage their æternity accounts using familiar Bitcoin key management tools.

In this implementation, the contract tracks its own nonce to prevent transaction replay attacks. Users must maintain awareness of the contract's nonce state to ensure proper transaction sequencing. The contract verifies signatures against a Blake2b hash of the transaction data and nonce, providing secure transaction authorization using Bitcoin keypairs.

Security Considerations and Protection Mechanisms

The implementation of generalized accounts includes careful consideration of potential security risks. To prevent abuse, the system only charges gas for successful authentication attempts, protecting account holders from potential drain attacks through failed authentications. However, this creates a potential risk of resource exhaustion attacks against miners who must execute authentication functions.

To mitigate these risks, authentication functions are restricted from performing expensive chain operations. Miners can also implement rules to reject transactions that appear to be attempting resource exhaustion. These protections ensure the security of both individual accounts and the network as a whole.

Advanced Applications and Future Potential

Generalized accounts enable numerous sophisticated account management schemes. Beyond alternative signature algorithms, they can implement multi-signature wallets, spending limits based on time periods, and restrictions on transaction types. The flexibility of smart contract-based authorization allows for innovative account control mechanisms while maintaining strong security guarantees.

When implementing generalized accounts, developers must carefully design their authorization functions to include proper integrity checking and replay protection. The power and flexibility of this system require thoughtful implementation to prevent potential security vulnerabilities while enabling advanced account management features.

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.

æternity's Oracle Implementation

In æternity, oracles are first-class citizens of the blockchain, implemented through specific transaction types rather than smart contracts. This native integration means that common oracle operations like registration, querying, and response handling are streamlined and cost-effective. When an oracle is registered on the chain, it specifies the format it expects for both queries and responses, along with the fee required for each query.

The process begins with an oracle operator registering their service through a register oracle transaction. Once registered, any user can query the oracle using a query oracle transaction that includes the appropriate fee. Oracle operators monitor the blockchain for relevant queries and post oracle response transactions with answers in the predefined format. This makes the data available on-chain and accessible to any smart contract.

Security and Reliability

æternity's oracle system includes several mechanisms to ensure reliability and prevent abuse. Oracle responses are permanently recorded on the blockchain, making them publicly verifiable and immutable. The system implements query TTL (Time To Live) parameters, which can be set as either absolute or relative key-block heights. This ensures that oracle queries receive timely responses and that users aren't charged for queries that go unanswered.

Oracles have specific lifetimes, defined in block height when they're registered. After this height, queries to the oracle no longer result in responses. However, oracle operators can extend their oracle's lifetime using an extend oracle transaction, providing flexibility while maintaining system integrity.

Data Privacy and Cost Considerations

When using oracles, it's important to understand that any data posted to the blockchain becomes public. While this transparency is often beneficial, it requires careful consideration when dealing with sensitive information. For instance, using an oracle to verify personal data might not be appropriate as the data would become permanently public once posted to the chain.

æternity's oracle system is designed with cost-effectiveness in mind. The fee structure is transparent and predictable, with oracle operators setting their query fees upfront. This allows users to make informed decisions about oracle usage based on their specific needs and budget constraints.

Practical Applications

Oracles in æternity enable a wide range of practical applications. Supply chain systems can use oracles to bring verified transaction data on-chain, decentralized insurance platforms can access real-world event data, and prediction markets can obtain reliable outcome information. The native implementation makes it particularly efficient for applications requiring frequent access to external data.

Smart contracts can use oracle responses as triggers for specific actions, creating automated systems that react to real-world events. For example, a smart contract might automatically execute payments based on weather conditions reported by an oracle, or adjust terms based on market prices provided through oracle data.

Related Topics and Resources

For developers interested in implementing oracles in their applications, comprehensive technical documentation and code examples are available in the Developer Tools section. This includes detailed information about oracle transactions, query formats, and best practices for oracle implementation. Users looking to interact with existing oracles can find practical guides in the User Guides section of this documentation.

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.

Delegated Proof of Stake Implementation

Hyperchains use a delegated proof-of-stake (DPoS) system that differs from traditional PoS implementations in several important ways:

The system operates in distinct epochs, with each epoch consisting of four phases:

1. A staking phase where participants can register and adjust their stakes

2. A leader election phase that uses randomness from the parent chain to select block producers

3. A block production phase where elected leaders create blocks

4. A payout phase where rewards are distributed based on participation

This structured approach helps maintain fairness and security while providing predictable block production schedules. Validators must meet minimum staking requirements to participate, and their chances of being selected as leaders are proportional to their stake in the network.

Security Through Parent Chain Anchoring

One of the most innovative aspects of Hyperchains is how they maintain security through a process called "pinning." During each generation, a randomly selected staker is responsible for anchoring the Hyperchain's state to the parent chain:

The pinning process creates a cryptographic link between the child and parent chains by posting specific transaction data to the main æternity blockchain. This creates an immutable record of the Hyperchain's state that inherits the security properties of the parent chain's proof-of-work consensus.

To encourage regular pinning actions, the system includes a reward mechanism that accumulates if pinning is delayed. This ensures that the economic incentives align with the security needs of the network.

Epoch Synchronization and Chain Speed

Hyperchains introduce a flexible approach to blockchain synchronization that allows for different processing speeds between parent and child chains. While earlier blockchain scaling solutions required strict synchronization, Hyperchains can operate more independently:

The child chain can process transactions at its own pace, with epoch lengths that can be adjusted through a democratic voting process. This flexibility allows Hyperchains to optimize their performance for specific use cases while maintaining security through periodic synchronization with the parent chain.

Stakeholders can propose and vote on changes to epoch length, allowing the chain to adapt to changing network conditions and requirements. This adaptive capability ensures that Hyperchains can maintain optimal performance as their usage evolves.

Governance and Participation

Hyperchains implement a weighted delegated coin-voting system that allows stakeholders to participate in network governance:

Token holders can delegate their voting power to other participants, allowing for efficient decision-making while maintaining decentralization. This delegation system helps ensure that those with the most stake in the network's success have a proportional say in its operation.

The governance system extends to important operational decisions such as adjusting epoch lengths, managing rewards, and updating network parameters. This ensures that the network can evolve to meet changing requirements while maintaining consensus among stakeholders.

Applications and Use Cases

Hyperchains open up new possibilities for blockchain applications that require enhanced performance characteristics. By providing high transaction throughput, quick finality, and specialized functionality, they enable a new generation of blockchain applications while maintaining robust security through the parent chain connection. Decentralized exchanges can leverage Hyperchains to provide near-instant trading experiences, while gaming platforms can utilize them to handle complex in-game transactions without delays. Enterprise applications particularly benefit from this architecture, as it allows them to maintain the security and transparency of a public blockchain while achieving the performance levels necessary for business operations. The cost-effective nature of Hyperchains makes them particularly attractive for applications that need to process large volumes of transactions, as they can optimize their operations for specific use cases while minimizing transaction costs.

Future Development

The Hyperchain architecture continues to evolve through ongoing research and development efforts. Current work focuses on enhancing the synchronization mechanisms between parent and child chains, implementing more sophisticated security guarantees, and finding new ways to optimize performance without compromising decentralization. The governance capabilities are being expanded to provide stakeholders with greater control over their networks while maintaining system stability. These development efforts are guided by real-world usage and community feedback, ensuring that Hyperchains remain responsive to the needs of developers and users alike. For developers building on æternity, these continuous improvements provide an increasingly powerful toolkit for creating scalable blockchain applications that can grow alongside their user base while maintaining the robust security guarantees of the main network.

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.

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.

What makes æternity's implementation special is its native support for state channels at the protocol level. This means that common operations like opening channels, executing state updates, and dispute resolution are built directly into the blockchain's architecture, making them more efficient and secure than add-on implementations found in other platforms.

Benefits and Use Cases

State channels in æternity provide several key advantages. First, they offer near-instant transaction finality between participants, as there's no need to wait for block confirmations for each interaction. Second, they significantly reduce transaction costs since only the channel opening and closing operations need to be recorded on-chain. Third, they provide enhanced privacy as the intermediate states are only known to the channel participants.

These characteristics make state channels particularly valuable for applications requiring frequent interactions between parties. Online gaming platforms can use them to handle rapid in-game transactions, streaming services can process micropayments in real-time, and IoT devices can efficiently record state changes without overwhelming the main chain. Payment channels, a simpler form of state channels, are perfect for recurring transactions between parties, such as subscription services or regular business relationships.

How State Channels Work

State channels operate in three main phases: opening, operation, and closing. To open a channel, participants must first agree to collaborate and post a mutually authenticated channel creation transaction on-chain. This transaction specifies the involved parties and the amount of coins they want to lock in the channel.

During operation, participants exchange mutually authenticated transactions off-chain through encrypted peer-to-peer communication. Each state update must be signed by both parties, creating a verifiable sequence of changes. These updates can include simple balance transfers or complex smart contract interactions, all happening privately between the participants.

Closing a channel can happen in two ways. In the optimistic case, both parties agree on the final state and post a closing transaction on-chain. However, if there's a dispute, æternity's protocol includes built-in mechanisms for resolution. Participants can post their latest valid state on-chain, and the protocol enforces a challenge period during which any fraud can be proven and punished.

Security and Dispute Resolution

æternity's state channel implementation includes robust security measures to protect participants. The protocol maintains a "lock period" after a solo closing attempt, during which the other party can contest the closure by presenting more recent valid states. This prevents malicious actors from trying to close a channel with an outdated state that benefits them.

If a dispute arises over smart contract execution within a channel, participants can use the "force progress" feature to move the contract state forward on-chain. This ensures that no party can prevent the natural progression of a contract by refusing to cooperate, while still maintaining the efficiency benefits of off-chain execution for cooperative scenarios.

Integration with Smart Contracts

One of æternity's unique features is the seamless integration between state channels and smart contracts written in Sophia. The same contract code can run both on-chain and within state channels, with the protocol automatically handling the transition between these contexts when necessary. This makes it easier for developers to build applications that can scale through state channels without requiring separate implementations for on-chain and off-chain operations.

State channels in æternity can also interact with other blockchain features like oracles, allowing for complex applications that combine off-chain scaling with access to external data. This integration enables sophisticated use cases while maintaining the performance benefits of off-chain execution.

Getting Started

For users interested in interacting with state channels, detailed guides are available in the User Guides section of this documentation. Developers looking to implement state channels in their applications can find comprehensive technical documentation, including code examples and best practices, in the Developer Tools section. The æternity team continues to develop tools and frameworks to make state channels more accessible and easier to implement in real-world applications.

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.

Fair Distribution and Anti-Squatting Measures

AENS implements an innovative auction system to ensure fair name distribution and prevent name squatting. Names shorter than thirteen characters are distributed through a first-price auction system, where the auction duration and starting bid are automatically adjusted based on the name length. Shorter names, which are typically more desirable, start with higher minimum bids and longer auction periods. For example, a four-character name might start at 134.6269 coins with an auction period of approximately 62 days after the last bid.

Names longer than twelve characters can be registered instantly, making the system accessible to all users while preserving the value of shorter, more premium names. Each new bid must be at least 5% higher than the previous one, ensuring meaningful price discovery during auctions.

Security and Front-Running Protection

AENS includes sophisticated measures to prevent front-running attacks, where observers might try to steal a name by watching the network's transaction pool. The registration process occurs in two steps: first, a preclaim transaction containing a hash of the desired name and a random number (salt) is submitted. Since observers cannot determine the name from this hash, they cannot front-run the registration.

After the preclaim is accepted, the claimant reveals the name and salt in a claim transaction. To further enhance security, the protocol requires the preclaim and claim transactions to be in different blocks, effectively eliminating the possibility of front-running through block manipulation.

Name Management and Lifecycle

Once a name is registered, owners have full control over their names through a suite of protocol-level operations. They can update their names to point to different addresses or resources, transfer ownership to other users, or revoke names they no longer need. Names expire after a set period unless renewed, ensuring that unused names eventually return to the available pool.

The system's integration with the protocol means that names can be used directly in transactions. Instead of copying long addresses, users can simply reference names, and the protocol handles the resolution automatically. This tight integration reduces the risk of errors and improves the overall user experience.

Applications and Use Cases

AENS enables numerous practical applications that make blockchain interactions more user-friendly. Decentralized applications can use memorable names for their smart contracts, making them easier to discover and interact with. Payment systems can simplify their interfaces by allowing users to send transactions to human-readable names rather than cryptographic addresses.

The system also supports the creation of decentralized identities, where users can build reputations around their .chain names. This feature is particularly valuable for decentralized marketplaces, social platforms, and other applications where persistent identities enhance trust and usability.

Related Documentation

Developers looking to integrate AENS into their applications will find detailed technical specifications and implementation guides in the Developer Tools section. This includes comprehensive information about name auctions, registration processes, and integration patterns. Users interested in registering and managing their own .chain names can find step-by-step guides in the User Guides section of this documentation.

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 blockchain 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.​​​​​​​​​​​​​​​​ Read the related whitepaper.

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.

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.

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.

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.

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.

Development Focus

The Foundation prioritizes seven core development domains to support the open-source ecosystem. These include protocol maintenance and development, SDK development, wallet and interface improvements, æpp development and integrations, middleware backend API support, and development tools. This structured approach ensures consistent advancement of the technology while maintaining focus on essential components.

Supporting Innovation

Through its Ecosystem Grant Program, the Foundation supports community-driven innovation across multiple categories. The program primarily focuses on technical advancement of the open-source blockchain protocol, but also extends to other areas including:

• Open source development

• Research and education

• Community growth initiatives

• Culture and art projects

• Governance and DAO development

• NFT innovation

Vision for Web 3.0

The Foundation is dedicated to advancing Web 3.0 - envisioning a decentralized and fair internet where users maintain control over their data, identity, and destiny. This commitment drives the Foundation's support for projects that enhance blockchain technology and its applications.

Related Documentation

The Foundation maintains its own website with detailed information about grant applications, ongoing projects, and opportunities for involvement. Developers and community members interested in Foundation support can find complete guidelines and application processes on the Foundation's official channels. The Foundation welcomes contact from potential partners and grantees who want to contribute to advancing the æternity ecosystem.

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.

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!

æ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.

Overview

The ærc bridge facilitates:

• Bridging of native cryptocurrencies (ETH and AE)

• Transfer of supported tokens between chains

• Wrapped token functionality (wETH on æternity and wAE on Ethereum)

Prerequisites

Before using the bridge, ensure you have:

• A wallet compatible with Ethereum (like MetaMask)

• A wallet compatible with æternity (like Superhero Wallet)

• Sufficient funds for network fees on the source chain

Step-by-Step Bridging Process

1. Network Selection and Wallet Connection

1. Visit the ærc bridge interface

2. Select your source network (Ethereum or æternity)

3. Connect your wallet when prompted

   • Accept the connection request from your wallet

   • If no prompt appears, use the "Connect Wallet" button or reload the page

2. Asset Selection and Transfer Details

1. Choose the asset to bridge from the dropdown menu

2. Enter the recipient address on the target network

   • Must be a valid address you control

   • Can be a smart contract capable of receiving and transferring assets

3. Verify the amount you wish to bridge

3. Initiating the Transfer

1. Click the bridge/transfer button

2. Confirm the transaction in your wallet

3. Wait for transaction confirmation

   • Source chain will process the lock transaction

   • Target chain will process the release transaction

4. Completing the Transfer

Once the bridging transaction is confirmed:

• For æternity: Assets will appear automatically in Superhero Wallet

• For Ethereum: You may need to add the token to your wallet manually using the contract address from our supported tokens list

Advanced:

Troubleshooting

If you encounter issues:

1. Transaction Pending

   • Check gas prices on source network

   • Verify transaction status in block explorer

2. Assets Not Received

   • Confirm target address is correct

   • Wait for additional block confirmations

   • Add token to wallet manually (Ethereum)

3. Connection Issues

   • Clear browser cache

   • Reconnect wallet

   • Try alternative supported browser

Support

For additional assistance:

• Visit the æternity Forum

• Check GitHub Issues

• Review the ærc Bridge FAQ Section

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!

æternity Compatible Wallets

æternity blockchain offers several secure wallet options to manage your AE tokens and interact with æpps (decentralized applications). Whether you prefer enhanced security through air-gapped solutions, full-featured mobile wallets, or simple web interfaces, there's a wallet that meets your needs. Each wallet provides different features and security models, allowing you to choose the best solution for your use case - from casual users to developers to institutional holders.

Supported Wallets:

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

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

Hardware ranking

Software recommendations

HIVEON LOLMINER NB Miner Cryptoredge

Mining pools

2miners Woolypooly

Mining community

Discord

æ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.

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.

Development Environment Setup

Prerequisites

• Node.js (v12 or higher)

• Git

• Docker (recommended for running local nodes)

• Text editor with Sophia language support (VS Code recommended)

Installation Steps

1. Install the æternity CLI

bashCopynpm install -g @aeternity/aeproject

1. Install the SDK

bashCopynpm install @aeternity/aepp-sdk

• Install the Sophia extension for syntax highlighting

• Configure your workspace settings for .aes files

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

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

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

• Graffiti: 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.

• Faucet: Service for obtaining test tokens for development

Getting Started

1. Download Base æpp 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 aeknow.org for a comprehensive list of community-developed æpps.

Core Development Tools

• Project scaffolding

• Smart contract compilation

• Test framework

• Local node management

• JavaScript library for interacting with æternity blockchain

• Contract deployment and interaction

• Account management

• Transaction handling

• Virtual machine for smart contract execution

• Provides type safety and efficiency

• Native support for blockchain primitives

Node

Middleware

Explorers

Other Services

Faucet

Smart Contract Development

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: æternity Nodes

At the foundation of the æternity ecosystem are the nodes that form the network's infrastructure. These nodes are the backbone of the blockchain, responsible for maintaining consensus, processing transactions, and supporting all higher-level functionalities.

æternity nodes are implemented in Erlang, a programming language known for building highly concurrent and fault-tolerant systems. This implementation choice allows the network to handle significant loads while maintaining stability. The nodes employ the Bitcoin-NG consensus mechanism, which significantly improves throughput compared to traditional proof-of-work blockchains by separating leader election from transaction processing.

The node infrastructure supports several native features that distinguish æternity from other blockchains:

• State channels for off-chain scaling

• Built-in oracles for accessing external data

• An integrated naming system (ÆNS)

• Governance mechanisms for protocol evolution

Each node maintains the complete state of the blockchain and participates in validating new transactions and blocks, ensuring the network remains decentralized and secure.

Level Two: FATE VM

Built on top of the node infrastructure is the Fast æternity Transaction Engine (FATE) virtual machine. The FATE VM is custom-designed for executing smart contracts on the æternity blockchain with optimal efficiency and security.

Unlike more general-purpose virtual machines, FATE is specifically optimized for blockchain operations. It features:

• A strong type system that prevents many common smart contract vulnerabilities

• Direct integration with blockchain primitives, making operations like oracle queries and state channel transactions more efficient

• Support for unbounded integers, eliminating overflow vulnerabilities

• Higher-level operations that reduce gas costs and contract size

The FATE VM executes bytecode compiled from the Sophia language, providing a secure runtime environment that maintains deterministic execution across all nodes in the network.

Level Three: Smart Contracts

The smart contract layer provides the programming interface for developers to create decentralized applications. At the center of this layer is Sophia, æternity's native smart contract language.

Sophia is a functional programming language designed specifically for blockchain applications. Its functional paradigm helps developers write more predictable code with fewer side effects, which is crucial for financial applications. Key features include:

• Strong static typing to catch errors at compile time

• First-class support for blockchain-specific operations

• Built-in types for oracles, state channels, and the naming system

• Immutable data structures that align with blockchain principles

Smart contracts in æternity can interact with the blockchain's native features, such as the oracle system for accessing real-world data or the state channels for high-throughput applications. This tight integration allows developers to build more sophisticated applications with less complexity.

// Example Sophia contract with oracle integration
contract WeatherBet =
  record state = { oracle      : oracle(string, int),
                   bet_amount  : int,
                   temperature : option(int) }
                   
  entrypoint init(oracle_address : oracle(string, int), amount : int) = 
    { oracle = oracle_address, 
      bet_amount = amount,
      temperature = None }
      
  payable stateful entrypoint place_bet(city : string) =
    require(Call.value == state.bet_amount, "Wrong bet amount")
    let query = Oracle.query(state.oracle, city, 
                            state.bet_amount, RelativeTTL(10), RelativeTTL(10))
    put(state)

Level Four: æternity Client APIs

To bridge the gap between the blockchain infrastructure and application developers, æternity provides a comprehensive set of APIs and SDKs. These tools abstract away much of the complexity of blockchain interaction, allowing developers to focus on application logic.

The æternity ecosystem offers:

• A REST API for direct node interaction

• A WebSocket API for real-time updates and subscriptions

• JavaScript, Python, and other language SDKs

• Libraries for common operations like contract deployment and transaction signing

These APIs provide methods for all blockchain operations, from basic account management to complex smart contract interactions and state channel operations.

// SDK example: Deploying a smart contract
const { Node, Universal: Ae, MemoryAccount } = require('@aeternity/aepp-sdk')

const deploy = async () => {
  // Connect to a node
  const client = await Ae({
    nodes: [{ name: 'testnet', instance: await Node({ url: 'https://testnet.aeternity.io' }) }],
    compilerUrl: 'https://compiler.aepps.com',
    accounts: [MemoryAccount({ keypair: { secretKey: 'YOUR_PRIVATE_KEY', publicKey: 'YOUR_PUBLIC_KEY' } })]
  })
  
  // Contract source code
  const sourceCode = `
  contract SimpleStorage =
    record state = { value : int }
    entrypoint init() = { value = 0 }
    stateful entrypoint set(x : int) = put(state{value = x})
    entrypoint get() = state.value
  `
  
  // Deploy the contract
  const contract = await client.getContractInstance(sourceCode)
  const deployInfo = await contract.deploy([])
  
  console.log(`Contract deployed at: ${deployInfo.address}`)
}

Level Five: End-User Applications

At the top of the stack are the end-user applications, often called æpps. These applications leverage all the underlying layers to provide value to end users who may not even be aware they're interacting with a blockchain.

Applications built on æternity can take many forms:

• Web-based decentralized applications (æpps)

• Mobile applications with blockchain functionality

• Integration layers for existing systems

• Specialized applications utilizing state channels for high performance

æternity applications can benefit from the platform's unique features, such as scalable micropayments through state channels, trustless data from oracles, and human-readable addressing through the naming system.

Many applications focus on use cases where æternity's specific strengths provide advantages:

• Decentralized prediction markets using the oracle system

• High-frequency financial applications via state channels

• Supply chain solutions with integrated oracle functionality

• Governance and voting systems

The end-user application layer is where the technical capabilities of the æternity stack translate into tangible value for users, whether they're individuals, businesses, or other organizations.

The Integrated Stack

The æternity blockchain stack is designed as a cohesive ecosystem where each layer builds upon and enhances the capabilities of the layers below it. This integrated approach allows developers to create sophisticated applications while maintaining performance, security, and usability.

From the foundational nodes to the user-facing applications, the æternity stack represents a complete solution for building the next generation of decentralized systems, combining technical innovation with practical utility.

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

• Whitepapers - æternity whitepaer 2020 revised version

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.

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.

To begin your journey, create a new project directory and initialize it with the aeproject tool:

The initialization process creates a well-organized project structure with dedicated directories for your smart contracts, deployment scripts, tests, and Docker configuration. The initialization process creates a well-organized project structure: my-aepp/

Now it's time to write your first smart contract in the Sophia language:

To ensure your contract works as expected, write a test file:

Run your tests with aeproject test.

Wallet Setup and Acquiring Test Tokens

Before deploying to mainnet, develop on the testnet using free test tokens. Visit https://faucet.aeternity.io or use the command:

Environment Configuration

Configure your environment to connect to the appropriate æternity network:

During development, use a local node with aeproject node for faster testing.

Next Steps

Always develop on testnet before moving to mainnet, and carefully review your code for security vulnerabilities.

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.

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.

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.

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.

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

The compiler is currently being used three places

• The command line compiler

• The HTTP compiler

• In æternity node tests

Documentation

• Introduction

• Syntax

• Features

• Standard library

• Contract examples

• Contributing

Additionally you can check out the contracts section of the æternity blockchain specification.

Versioning

Versioning should follow the semantic versioning guidelines. Id est, given a version number MAJOR.MINOR.PATCH, increment the:

• MAJOR version when you make incompatible API changes

• MINOR version when you add functionality in a backwards compatible manner

• PATCH version when you make backwards compatible bug fixes

Interface Modules

The basic modules for interfacing the compiler:

• aeso_compiler: the Sophia compiler

• aeso_aci: the ACI interface

More information about the Sophia Compiler can be found here:

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 æ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.

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

bashCopy# Install from VSCode Marketplace
1. Open VSCode
2. Go to Extensions (Ctrl+Shift+X)
3. Search for "Sophia"
4. Click Install

For developers who want to install from source or contribute to the extension, see the rest of our VS Code Documentation:

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 The Solidity Specification:ABI

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.

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.

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.

The Node API reference is it's own website maintained here: https://api-docs.aeternity.io/

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 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.

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

• Language Features

  • Contracts

    • Calling other contracts

    • Protected contract calls

    • Contract factories and child contracts

  • Mutable state

    • Stateful functions

  • Payable

    • Payable contracts

    • Payable entrypoints

  • Namespaces

  • Splitting code over multiple files

  • Standard library

  • Types

  • Literals

  • Arithmetic

  • Bit fields

  • Type aliases

  • Algebraic data types

  • Lists

  • Maps and records

    • Constructing maps and records

    • Accessing values

    • Updating a value

    • Map implementation

  • Strings

  • Chars

  • Byte arrays

  • Cryptographic builins

    • AEVM note

  • Authorization interface

  • Oracle interface

    • Example

    • Sanity checks

  • AENS interface

    • Example

  • Events

    • Argument order

  • Compiler pragmas

  • Exceptions

• Syntax

  • Lexical syntax

    • Comments

    • Keywords

    • Tokens

  • Layout blocks

  • Notation

  • Declarations

  • Types

  • Statements

  • Expressions

  • Operators types

  • Operator precendences

• Examples

  • Delegation signature

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,

// A contract type
contract interface VotingType =
  entrypoint vote : string => unit

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

contract VoteTwice =
  entrypoint voteTwice(v : VotingType, alt : string) =
    v.vote(alt)
    v.vote(alt)

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:

  entrypoint voteTwice(v : VotingType, fee : int, alt : string) =
    v.vote(value = fee, alt)
    v.vote(value = fee, alt)

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

  entrypoint pay(v : VotingType, amount : int) =
    Chain.spend(v.address, amount)

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.

contract interface VotingType =
  entrypoint : vote : string => unit

contract Voter =
  entrypoint tryVote(v : VotingType, alt : string) =
    switch(v.vote(alt, protected = true) : option(unit))
      None    => "Voting failed"
      Some(_) => "Voting successful"

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

contract IntHolder =
  type state = int
  entrypoint init(x) = x
  entrypoint get() = state
  
main contract IntHolderFactory =
  stateful entrypoint new(x : int) : IntHolder =
    let ih = Chain.create(x) : IntHolder
    ih

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 function defaults to returning the value (). At contract creation time, the init function is executed and its result is stored as the contract state.

• The value of the state is accessible from inside the contract through an implicitly bound variable state.

• State updates are performed by calling a function put : state => unit.

• Aside from the put function (and similar functions for transactions and events), the language is purely functional.

• Functions modifying the state need to be annotated with the stateful keyword (see below).

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,

  stateful entrypoint set_state(s : state) =
    put(s)

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

  • Oracle.register

  • Oracle.query

  • Oracle.respond

  • Oracle.extend

  • AENS.preclaim

  • AENS.claim

  • AENS.transfer

  • AENS.revoke

  • AENS.update

• Call a stateful function in the current contract

• Call another contract with a non-zero value argument.

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:

// A payable contract
payable contract ExampleContract =
  stateful entrypoint do_stuff() = ...

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.

payable stateful entrypoint buy(to : address) =
  if(Call.value > 42)
    transfer_item(to)
  else
    abort("Value too low")

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,

namespace Library =
  type number = int
  function inc(x : number) : number = x + 1

contract MyContract =
  entrypoint plus2(x) : Library.number =
    Library.inc(Library.inc(x))

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

namespace Library =
  function inc(x) = x + 1

you can use it from another file using an include:

include "library.aes"
contract MyContract =
  entrypoint plus2(x) = Library.inc(Library.inc(x))

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

include "List.aes"
include "Pair.aes"
-- Map is already there!

namespace C =
  entrypoint keys(m : map('a, 'b)) : list('a) =
    List.map(Pair.fst, (Map.to_list(m)))

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)

• division (x / y), truncated towards zero

• remainder (x mod y), satisfying y * (x / y) + x mod y == x for non-zero y

• exponentiation (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

type number = int
type string_map('a) = map(string, 'a)

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,

datatype one_or_both('a, 'b) = Left('a) | Right('b) | Both('a, 'b)

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

function get_left(x : one_or_both('a, 'b)) : option('a) =
  switch(x)
    Left(x)    => Some(x)
    Right(_)   => None
    Both(x, _) => Some(x)

or directly in the left-hand side:

function
  get_left : one_or_both('a, 'b) => option('a)
  get_left(Left(x))    = Some(x)
  get_left(Right(_))   = None
  get_left(Both(x, _)) = Some(x)

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:

[1, 33, 2, 666]                                                   : list(int)
[(1, "aaa"), (10, "jjj"), (666, "the beast")]                     : list(int * string)
[{[1] = "aaa", [10] = "jjj"}, {[5] = "eee", [666] = "the beast"}] : list(map(int, string))

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:

[x + y | x <- [1,2,3,4,5], let k = x*x, if (k > 5), y <- [k, k+1, k+2]]
// yields [12,13,14,20,21,22,30,31,32]

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

[1..4] == [1,2,3,4]

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

  record account = { name    : string,
                     balance : int,
                     history : list(transaction) }

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,

  function new_account(name) =
    {name = name, balance = 0, history = []}

Maps are constructed similarly, with keys enclosed in square brackets

  function example_map() : map(string, int) =
    {["key1"] = 1, ["key2"] = 2}

The empty map is written {}.

Accessing values

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

  function get_balance(a : address, accounts : map(address, account)) =
    accounts[a].balance

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:

function clear_history(a : address, accounts : map(address, account)) : map(address, account) =
  accounts{ [a].history = [] }

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):

  accounts{ [a = empty_account()].history = [] }

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 Oracles. For a functionality documentation refer to the standard library.

Example

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

contract Oracles =

  stateful entrypoint registerOracle(acct : address,
                                     sign : signature,   // Signed network id + oracle address + contract address
                                     qfee : int,
                                     ttl  : Chain.ttl) : oracle(string, int) =
     Oracle.register(acct, signature = sign, qfee, ttl)

  entrypoint queryFee(o : oracle(string, int)) : int =
    Oracle.query_fee(o)

  payable stateful entrypoint createQuery(o    : oracle_query(string, int),
                                          q    : string,
                                          qfee : int,
                                          qttl : Chain.ttl,
                                          rttl : int) : oracle_query(string, int) =
    require(qfee =< Call.value, "insufficient value for qfee")
    Oracle.query(o, q, qfee, qttl, RelativeTTL(rttl))

  stateful entrypoint extendOracle(o   : oracle(string, int),
                                   ttl : Chain.ttl) : unit =
    Oracle.extend(o, ttl)

  stateful entrypoint signExtendOracle(o    : oracle(string, int),
                                       sign : signature,   // Signed network id + oracle address + contract address
                                       ttl  : Chain.ttl) : unit =
    Oracle.extend(o, signature = sign, ttl)

  stateful entrypoint respond(o    : oracle(string, int),
                              q    : oracle_query(string, int),
                              sign : signature,        // Signed network id + oracle query id + contract address
                              r    : int) =
    Oracle.respond(o, q, signature = sign, r)

  entrypoint getQuestion(o : oracle(string, int),
                         q : oracle_query(string, int)) : string =
    Oracle.get_question(o, q)

  entrypoint hasAnswer(o : oracle(string, int),
                       q : oracle_query(string, int)) =
    switch(Oracle.get_answer(o, q))
      None    => false
      Some(_) => true

  entrypoint getAnswer(o : oracle(string, int),
                       q : oracle_query(string, int)) : option(int) =
    Oracle.get_answer(o, q)

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 Aeternity Naming System. 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:

  stateful entrypoint extend_if_necessary(addr : address, name : string, sig : signature) =
    switch(AENS.lookup(name))
      None => ()
      Some(AENS.Name(_, FixedTTL(expiry), _)) =>
        if(Chain.block_height + 1000 > expiry)
          AENS.update(addr, name, Some(RelativeTTL(50000)), None, None, signature = sig)

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

  stateful entrypoint add_key(addr : address, name : string, key : string,
                              pt : AENS.pointee, sig : signature) =
    switch(AENS.lookup(name))
      None => ()
      Some(AENS.Name(_, _, ptrs)) =>
        AENS.update(addr, name, None, None, Some(ptrs{[key] = pt}), signature = sig)

  stateful entrypoint delete_key(addr : address, name : string,
                                 key : string, sig : signature) =
    switch(AENS.lookup(name))
      None => ()
      Some(AENS.Name(_, _, ptrs)) =>
        let ptrs = Map.delete(key, ptrs)
        AENS.update(addr, name, None, None, Some(ptrs), signature = sig)

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 in Solidity. Events are further discussed in the protocol.

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

  datatype event
    = Event1(int, int, string)
    | Event2(string, address)

  Chain.event(e : event) : unit

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

• oracle(_, _)

• oracle_query(_, _)

• contract types

• bytes(n) for n ≤ 32, in particular hash

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.

  entrypoint emit_events() : () =
    Chain.event(Event1(42, 34, "foo"))
    Chain.event(Event2("This is not indexed", Contract.address))

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.

AnotherEvent(string, indexed address)

...

Chain.event(AnotherEvent("This is not indexed", Contract.address))

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

@compiler >= 4.3
@compiler <  4.4

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

abort(reason : string) : 'a

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:

function require(b : bool, err : string) =
    if(!b) abort(err)

Syntax

Lexical syntax

Comments

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

Keywords

contract elif else entrypoint false function if import include let mod namespace
private payable stateful switch true type record datatype main interface

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)

• QCon = (Con\.)+Con qualified constructor

• TVar = 'Id type variable (e.g 'a, 'b)

• Int = [0-9]+(_[0-9]+)*|0x[0-9A-Fa-f]+(_[0-9A-Fa-f]+)* integer literal with optional _ separators

• Bytes = #[0-9A-Fa-f]+(_[0-9A-Fa-f]+)* byte array literal with optional _ separators

• String string literal enclosed in " with escape character \

• Char character literal enclosed in ' with escape character \

• AccountAddress base58-encoded 32 byte account pubkey with ak_ prefix

• ContractAddress base58-encoded 32 byte contract address with ct_ prefix

• OracleAddress base58-encoded 32 byte oracle address with ok_ prefix

• OracleQueryId base58-encoded 32 byte oracle query id with oq_ prefix

Valid string escape codes are

See the identifier encoding scheme 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

contract Layout =
  function foo() = 0  // no layout
  function bar() =    // layout block starts on next line
    let x = foo()     // indented more than 2 spaces
    x
     + 1              // the '+' is indented more than the 'x'

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: |.

• Optional elements are enclosed in [ square brackets ].

• ( Parentheses ) are used for grouping.

• Zero or more repetitions are denoted by a postfix *, and one or more repetitions by a +.

• Block(X) denotes a layout block of Xs.

• Sep(X, S) is short for [X (S X)*], i.e. a possibly empty sequence of Xs separated by Ss.

• Sep1(X, S) is short for X (S X)*, i.e. same as Sep, but must not be empty.

Declarations

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

File ::= Block(TopDecl)

TopDecl ::= ['payable'] 'contract' Con '=' Block(Decl)
       | 'namespace' Con '=' Block(Decl)
       | '@compiler' PragmaOp Version
       | 'include' String

Decl ::= 'type'     Id ['(' TVar* ')'] '=' TypeAlias
       | 'record'   Id ['(' TVar* ')'] '=' RecordType
       | 'datatype' Id ['(' TVar* ')'] '=' DataType
       | (EModifier* 'entrypoint' | FModifier* 'function') Block(FunDecl)

FunDecl ::= Id ':' Type                             // Type signature
          | Id Args [':' Type] '=' Block(Stmt)      // Definition

PragmaOp ::= '<' | '=<' | '==' | '>=' | '>'
Version  ::= Sep1(Int, '.')

EModifier ::= 'payable' | 'stateful'
FModifier ::= 'stateful' | 'private'

Args ::= '(' Sep(Pattern, ',') ')'

Contract declarations must appear at the top-level.

For example,

contract Test =
  type t = int
  entrypoint add (x : t, y : t) = x + y

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

TypeAlias  ::= Type
RecordType ::= '{' Sep(FieldType, ',') '}'
DataType   ::= Sep1(ConDecl, '|')

FieldType  ::= Id ':' Type
ConDecl    ::= Con ['(' Sep1(Type, ',') ')']

For example,

record   point('a) = {x : 'a, y : 'a}
datatype shape('a) = Circle(point('a), 'a) | Rect(point('a), point('a))
type     int_shape = shape(int)

Types

Type ::= Domain '=>' Type             // Function type
       | Type '(' Sep(Type, ',') ')'  // Type application
       | '(' Type ')'                 // Parens
       | 'unit' | Sep(Type, '*')      // Tuples
       | Id | QId | TVar

Domain ::= Type                       // Single argument
         | '(' Sep(Type, ',') ')'     // Multiple arguments

The function type arrow associates to the right.

Example,

'a => list('a) => (int * list('a))

Statements

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

Stmt ::= 'switch' '(' Expr ')' Block(Case)
       | 'if' '(' Expr ')' Block(Stmt)
       | 'elif' '(' Expr ')' Block(Stmt)
       | 'else' Block(Stmt)
       | 'let' LetDef
       | Expr

LetDef ::= Id Args [':' Type] '=' Block(Stmt)   // Function definition
         | Pattern '=' Block(Stmt)              // Value definition

Case    ::= Pattern '=>' Block(Stmt)
Pattern ::= Expr

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

let x : int = 4
switch(f(x))
  None => 0
  Some(y) =>
    if(y > 10)
      "too big"
    elif(y < 3)
      "too small"
    else
      "just right"

Expressions

Expr ::= '(' LamArgs ')' '=>' Block(Stmt)   // Anonymous function    (x) => x + 1
       | 'if' '(' Expr ')' Expr 'else' Expr // If expression         if(x < y) y else x
       | Expr ':' Type                      // Type annotation       5 : int
       | Expr BinOp Expr                    // Binary operator       x + y
       | UnOp Expr                          // Unary operator        ! b
       | Expr '(' Sep(Expr, ',') ')'        // Application           f(x, y)
       | Expr '.' Id                        // Projection            state.x
       | Expr '[' Expr ']'                  // Map lookup            map[key]
       | Expr '{' Sep(FieldUpdate, ',') '}' // Record or map update  r{ fld[key].x = y }
       | '[' Sep(Expr, ',') ']'             // List                  [1, 2, 3]
       | '[' Expr '|' Sep(Generator, ',') ']'
                                            // List comprehension    [k | x <- [1], if (f(x)), let k = x+1]
       | '[' Expr '..' Expr ']'             // List range            [1..n]
       | '{' Sep(FieldUpdate, ',') '}'      // Record or map value   {x = 0, y = 1}, {[key] = val}
       | '(' Expr ')'                       // Parens                (1 + 2) * 3
       | Id | Con | QId | QCon              // Identifiers           x, None, Map.member, AELib.Token
       | Int | Bytes | String | Char        // Literals              123, 0xff, #00abc123, "foo", '%'
       | AccountAddress | ContractAddress   // Chain identifiers
       | OracleAddress | OracleQueryId      // Chain identifiers

Generator ::= Pattern '<-' Expr   // Generator
            | 'if' '(' Expr ')'   // Guard
            | LetDef              // Definition

LamArgs ::= '(' Sep(LamArg, ',') ')'
LamArg  ::= Id [':' Type]

FieldUpdate ::= Path '=' Expr
Path ::= Id                 // Record field
       | '[' Expr ']'       // Map key
       | Path '.' Id        // Nested record field
       | Path '[' Expr ']'  // Nested map key

BinOp ::= '||' | '&&' | '<' | '>' | '=<' | '>=' | '==' | '!='
        | '::' | '++' | '+' | '-' | '*' | '/' | 'mod' | '^'
UnOp  ::= '-' | '!'

Operators types

Operator precendences

In order of highest to lowest precedence.

Examples

/*
 * A simple crowd-funding example
 */
contract FundMe =

  record spend_args = { recipient : address,
                        amount    : int }

  record state = { contributions : map(address, int),
                   total         : int,
                   beneficiary   : address,
                   deadline      : int,
                   goal          : int }

  stateful function spend(args : spend_args) =
    Chain.spend(args.recipient, args.amount)

  entrypoint init(beneficiary, deadline, goal) : state =
    { contributions = {},
      beneficiary   = beneficiary,
      deadline      = deadline,
      total         = 0,
      goal          = goal }

  function is_contributor(addr) =
    Map.member(addr, state.contributions)

  stateful entrypoint contribute() =
    if(Chain.block_height >= state.deadline)
      spend({ recipient = Call.caller, amount = Call.value }) // Refund money
      false
    else
      let amount =
        switch(Map.lookup(Call.caller, state.contributions))
          None    => Call.value
          Some(n) => n + Call.value
      put(state{ contributions[Call.caller] = amount,
                 total @ tot = tot + Call.value })
      true

  stateful entrypoint withdraw() =
    if(Chain.block_height < state.deadline)
      abort("Cannot withdraw before deadline")
    if(Call.caller == state.beneficiary)
      withdraw_beneficiary()
    elif(is_contributor(Call.caller))
      withdraw_contributor()
    else
      abort("Not a contributor or beneficiary")

  stateful function withdraw_beneficiary() =
    require(state.total >= state.goal, "Project was not funded")
    spend({recipient = state.beneficiary,
           amount    = Contract.balance })

  stateful function withdraw_contributor() =
    if(state.total >= state.goal)
      abort("Project was funded")
    let to = Call.caller
    spend({recipient = to,
           amount    = state.contributions[to]})
    put(state{ contributions @ c = Map.delete(to, c) })

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.).

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.

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 æ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 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.

Note: As we continue to expand and update our documentation, additional APIs and related tools will be added to this section.

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.

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.

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

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

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

  • Documentation: https://aepp-sdk-python.readthedocs.io

Community

• aepp-sdk-net - Outdated.

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

æ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:

# Example testnet node status check
curl https://testnet.aeternity.io/v3/status

# Response includes:
- Node version
- Network ID
- Current height
- Peer count
- Sync status

Node

• Mainnet - Access to the status endpoint

• Testnet - Access to the status endpoint

• Swagger-UI - Explore and interact with the Node API

Middleware

• Mainnet - Access to the status endpoint

• Testnet - Access to the status endpoint