This is the suggested template for new AEXs.

Note that an AEX number will be assigned by an editor. When opening a pull request to submit your AEX, please use an abbreviated title in the filename,aex-draft_title_abbrev.md.

The title should be 44 characters or less.

Simple Summary

"If you can't explain it simply, you don't understand it well enough." Provide a simplified and layman-accessible explanation of the AEX.

Abstract

A short (~200 word) description of the technical issue being addressed.

Motivation

The motivation should clearly explain why existing specifications are inadequate to address the problem that the AEX solves. AEX submissions without sufficient motivation may be rejected outright.

Specification

The technical specification should describe the syntax and semantics of any new or changed feature. The specification should be detailed enough to allow competing, interoperable implementations.

Rationale

The rationale fleshes out the specification by describing what motivated the design and why particular design decisions were made. It should describe alternate designs that were considered and related work, e.g. how the feature is supported in other languages. The rationale may also provide evidence of consensus within the community, and should discuss important objections or concerns raised during discussion.

Backwards Compatibility

All AEXs that introduce backwards incompatibilities must include a section describing these incompatibilities and their severity. The AEX must explain how the author proposes to deal with these incompatibilities. AEX submissions without a sufficient backwards compatibility treatise may be rejected outright.

Implementation

The implementations, if applicable, must be completed before any AEX is given status "Last Call", and it needs be completed before the AEX is accepted. There is merit to the approach of reaching consensus on the specification and rationale before writing code, but the principle of "rough consensus and running code" is still useful when it comes to resolving many discussions of API details.

Copyright

Copyright and related rights go here if the License and License-Code fields don't cover the copyright requirements.

Here you'll find a curated set of development resources spanning blockchain infrastructure, programming language support, cross-chain bridges, SDKs, and developer tooling. Whether you're a seasoned blockchain developer or just starting your journey with æternity, these tools are designed to streamline your development process and unlock the full potential of decentralized technology.

From our Sophia smart contract language support to JavaScript SDKs, middleware tools, and integration bridges, we provide a robust ecosystem that empowers developers to create cutting-edge blockchain applications with efficiency and ease.

Explore the sidebar to dive into specific tools and technologies, and start building with æternity today.

If you want to go back to other sections of the Documentation Hub, click one of the links below or click on "Documentation Hub" in the upper left corner at the top of the sidebar.

When opening a pull request to submit a new AEX, please use the suggested template:

The Aeternity Expansions (AEX), or aexpansions, are standards proposed by the community at large, i.e. everyone. Some of them can be mandatory in a specific context, e.g. AEX-1 describes the set of rules governing this repository, but are restricted to the application layer.

Quick Aexpansions filter

• Recently updated

For open Aexpansions

Goals

The purpose of this repository is to provide a high quality and accessible set of specifications; ideally together with implementations ready to be used if applicable.

Contributing

If you want to contribute please follow these steps:

1. Read

2. Fork this repository

3. Add your proposal to your fork, using the template provided

4. Submit a pull request to the AEX repository

Each proposal should go into the AEXS directory. If you need to embed images or other assets add a subdirectory in the assets directory with the number of your proposal once assigned, e.g. assets/aex-1/image.png.

Everything beyond step 4 is governed by .

Status terms

Read for more details.

• Draft - an AEX that is open for consideration and is undergoing rapid iteration and changes.

• Review - an AEX that is done with its initial iteration and in review by a wide audience.

• Last Call - In review by a wide audience - last call for accepting changes.

• Final - an AEX that has been in Last Call for at least 2 weeks and all technical changes that were requested have been addressed by the author.

AEXs

Copyright

This README is released under the license.

Is your feature request related to a problem? Please describe. A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]

Describe the solution you'd like A clear and concise description of what you want to happen.

Describe alternatives you've considered A clear and concise description of any alternative solutions or features you've considered.

Additional context Add any other context or screenshots about the feature request here.

Is your feature request related to a problem? Please describe. A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]

Describe the solution you'd like A clear and concise description of what you want to happen.

Describe alternatives you've considered A clear and concise description of any alternative solutions or features you've considered.

Additional context Add any other context or screenshots about the feature request here.

Discussions-To:

Paste here the link to the topic on forum.aeternity.com

Content URL

Paste here the url where the content of the AEX can be found

ATTENTION!

If you would like to submit an AEX and it has already been written as a draft (see the for an example), please submit it as a .

If you are considering a proposal but would like to get some feedback on the idea before submitting a draft, then continue opening an issue as a thread for discussion. Note that the more clearly and completely you state your idea the higher the quality of the feedback you are likely to receive.

Keep in mind the following guidelines from :

Each AEX must have a champion - someone who writes the AEX using the style and format described below, shepherds the discussions in the appropriate forums, and attempts to build community consensus around the idea. The AEX champion (a.k.a. Author) should first attempt to ascertain whether the idea is AEX- able. Posting to the the Protocol Discussion forum or opening an issue is the best way to go about this.

Before you begin, vet your idea, this will save you time. Ask the Aeternity community first if an idea is original to avoid wasting time on something that will be be rejected based on prior research (searching the Internet does not always do the trick). It also helps to make sure the idea is applicable to the entire community and not just the author. Just because an idea sounds good to the author does not mean it will work for most people in most areas where Aeternity is used. Examples of appropriate public forums to gauge interest around your AEX include the and the issues section of this repository. In particular, the issues section of this repository is an excellent place to discuss your proposal with the community and start creating more formalised language around your AEX.

Once the champion has asked the Aeternity community as to whether an idea has any chance of acceptance, a draft AEX should be presented as a pull request. This gives the author a chance to flesh out the draft AEX to make properly formatted, of high quality, and to address initial concerns about the proposal.

This guide explains basic interactions on getting access to accounts on Aeternity snap for MetaMask using JS SDK.

Prerequisite

Run the code from below you need:

• a MetaMask extension 12.2.4 or above installed in Chrome or Firefox browser;

• to setup an account in MetaMask (create a new one or restore by mnemonic phrase).

Usage

Firstly, you need to create a factory of MetaMask accounts

Using the factory, you can create instances of specific accounts by providing an index

The private key for the account would be derived in the MetaMask browser extension using the provided index and the mnemonic phrase it was initialized with. The private key won't leave the extension.

The complete examples of how to use it in browser can be found .

Account persistence

Account can be persisted and restored by saving values of index, address properties

It can be used to remember accounts between app restarts.

Account discovery

In addition to the above, it is possible to get access to a sequence of accounts that already have been used on chain. It is needed, for example, to restore the previously used accounts in case the user connects MetaMask to an app that doesn't aware of them.

Error handling

If the user rejects an action (snap installation or connection, address retrieving or transaction/message signing) you will get an exception as a plain object with property code equals 4001, and message equals "User rejected the request.".

If the snap downgrade is requested, the code will be -32602.

This application is created for interacting with the æternity <> EVM Bridge contracts provided by Acurast. Executing proper bridge actions using this application will result in moving the sent funds to the other chain.

Getting started

Before running the application, first project dependencies needs to be installed with the following command:

Afterwards, to run the application locally in development mode, following command needs to be run at the project directory:

This guide describes all breaking changes introduced with v9.0.0.

drop waitMined static method

If you used it like

then you have to rewrite it using Stamp composition

or pass it to specific methods, like

or even

Common structure

The whole idea is heavily inspired by . To get a signature needed to calculate hash(hash(domain), hash(aci), hash(data)).

hash function is blake2b.

domain is a record containing not required properties:

Note: for support questions, please use the . This repository's issues are reserved for feature requests and bug reports.

• Do you want to request a feature or report a bug?

• What is the current behavior?

• If the current behavior is a bug, please provide the steps to reproduce and if possible a minimal demo of the problem

Overview

This is a sample æpp that compiles contracts using the æternity JavaScript SDK.

How it works

Aeproject can already be used for testing and setup with the upcoming node versions.

Automatic update

Use aeproject init --next to initialize a new project that has the necessary adjustments to use the latest versions.

Use aeproject init --update --next to update an existing project with the adjustments to use the latest versions.

Describe the bug A clear and concise description of what the bug is.

To Reproduce Steps to reproduce the behavior:

1. Go to '...'

2. Click on '....'

3. Scroll down to '....'

aeproject init [folder]

Optionally a folder can be specified for the project to be initialized in, otherwise the current directory is used.

Creates a new project structure with a few folders in which the developer can create contracts and tests, as well as installing needed dependencies.

Update existing project

For upgrade from old AEproject versions check out Migration from 3.x.x to 4.x.x and Migration from 4.x.x to 5.x.x.

aeproject init --update

Updates the project structure and needed artifacts to the latest version, as well as installing needed dependencies.

Upcoming Hard-fork initialization

The additional parameter --next can be used to either initialize or update a project with changes for an upcoming hard-fork if available.

Simple Summary

The document describes and defines the deep linking specification that every æternity supported wallet can implement and follow to redirect users to a specific activity or page inside the application.

Motivation

URI based deep linking enables websites or applications to interact with native applications registered to listen for aeternity URI scheme and trigger wallet actions like open wallet accounts directly from third-party applications.

This also enables users to sign transaction using desktop or mobile based wallets without the need to copy or remember long addresses. This is especially beneficial for mobile wallet users as they can simply click on the wallet deep link to open the wallet app from the vendor app, confirm the transaction and return back to the vendor app through the callback url.

Specification

URI Scheme

• ae:

• aeternity:

Methods

1. View/Open Account in the wallet

   URI: aeternity:<wallet_address>

   Associated wallet app will:

   1. Open the wallet app

   2. Check if the address exists or not

Reference

• https://github.com/bitcoin/bips/blob/master/bip-0021.mediawiki

• https://github.com/bitcoin/bips/blob/master/bip-0070.mediawiki

• https://github.com/bitcoin/bips/blob/master/bip-0072.mediawiki

• https://hackmd.io/s/BJObJntjQ

This package is expected to work in these environments:

Interactions

AeSdk is a general, high-level interface that wraps multiple low-level interfaces. A general interface is preferred for its simplicity and resilience to breaking changes.

But there is also low-level interfaces. It's excellent for additional control, and as a teaching tool to understand the underlying operations. Most real-world requirements involves a series of low-level operations, so the SDK provides abstractions for these.

Node API

The aeternity node exposes . This API is described in the . SDK uses this document to generate a TypeScript client. The result client (implemented in ) a basically a mapping of all node endpoints as functions.

So to get a transaction based on its hash you would invoke node.getTransactionByHash('th_fWEsg152BNYcrqA9jDh9VVpacYojCUb1yu45zUnqhmQ3dAAC6'). In this way the SDK is simply a mapping of the raw API calls into JavaScript.

Transaction builder

Any blockchain state change requires signing a transaction. Transaction should be built according to the . SDK implements it in , , and . requires fewer arguments than , but it expects the node instance provided in arguments.

High-level SDK usage (preferable)

Example spend call, using æternity's SDK abstraction:

Low-level SDK usage

The same spend execution, but using low-level SDK functions:

In this example we will send 1 AE coin from one account to another. For more specific information on setups with Frameworks and TypeScript, please refer to the installation instructions.

1. Specify imports

For the following snippets in the guide you need to specify multiple imports.

2. Create a sender account

3. Get some AE using the Faucet

To receive some AE you can use the . Just paste sender's address, hit Top UP and you'll immediately get some test coins.

4. Interact with the æternity blockchain

This example shows:

• how to create an instance of the SDK using the AeSdk class

• how to spend (send) 1 AE from the account the SDK instance was initialized with to some other AE address

Note:

• You may remove code from Step 2 as this serves only for one-time creation

• The spend function expects the amount to be spent in aettos (the smallest possible unit, 1 AE equal to 1 000 000 000 000 000 000 aettos)

• See and track your transactions

Simple Summary

This aexpansion specify the derivation path used in the Aeternity blockchain for deterministic wallets

Motivation

The aexpansion is meant to avoid incompatibility with deterministic wallet implementations across the Aeternity landscape and to make it easy for the derivation path to be found.

Specification

Accounts derivation path is taken from , except that in all path segments hardened derivation is used since does not support public derivation.

The derivation path (m/purpose'/coin_type'/account_index'/change'/address_index') is therefore:

m/44_H/457_H/${account_index}_H/0_H/${address_index}_H

where account_index and address_index are integer starting from 0.

The coin type value for Aeternity, 457, has been generated on random.org and is registered in .

References

Overview

This is a sample wallet that expects an æpp to be loaded into its iframe.

How it works

1. Start this wallet, which will start on port 9000

2. Start the , which will start on port 9001

3. Visit to see the æpp included into this wallet

Installation and running

Prerequisite:

1. Install required dependencies with npm install

2. Start the application npm run serve

This folder contains examples of code samples that you can run autonomously. Create a new issue to suggest another example.

Wallet connection

Connect to a wallet

• (VueJS)

Build a wallet

• (VueJS)

NodeJS

Introduction

In æternity ecosystem, the app that has access to user's private keys and grants other apps access to them is called wallet. Respectively, the app that is granted access is called aepp.

This folder has been created to showcase the æternity SDK integration to both wallets and aepps.

Setup info

If you are trying these examples after checking out this repo, you want to first run npm install, from the repo root, to get all the SDK dependencies installed, and only then, move to individual apps installations.

Available examples

1. æpp

The Sample project (Distributed App or dapp) shows how you can create a simple æternity æpp, dependent on a Wallet, in this case: offering the possibility to work with contracts.

2. Wallet WebExtension

The example project shows how you can create a simple æternity wallet as a Chrome/Firefox browser extension. This approach is actively used in.

3. iframe-based wallet

The example project shows how you can create a simple æternity wallet that opens æpps in iframe. This approach is actively used in .

This guide describes the process of migrating to SDK version 7.0.0

Step 1

SDK will not accept url, internalUrl init arguments anymore:

Before

After

Step 2

Remove deprecated function setKeypair SDK will not accept keypair init argument anymore:

Before

After

Step 3

Change all of AENS method's first argument from nameId to name

Before

After

Other Breaking Changes

• Add new compiler methods to RPC communication (base-app update required)

• Drop compiler version to version >= 4.0.0 && version < 5.0.0

• Change node compatibility range to node >= 5.0.0 && node < 6.0.0

Overview

This is a sample wallet as an WebExtension. It works with æpp opened in a browser where it is installed.

How it works

1. Install this wallet to Chrome or Firefox

2. Start the , which will start on port 9001

3. Visit

4. This wallet should attempt to connect to the æpp

Installation and running in Google Chrome

Prerequisite:

1. Install required dependencies with npm install

2. Start the build server in watch mode npm run serve

3. Open

4. Enable "Developer mode" at the right top conner

aeproject env

The command is responsible for setting up a healthy local environment. The env command helps developers run a local node and a local compiler in dev-mode using docker. To spawn a fully functional environment it can take a couple of minutes depending on your system.

If using Windows, WSL 2 needs to be used for AEproject to work normally, see https://docs.microsoft.com/en-us/windows/wsl/tutorials/wsl-containers

You can stop both the node and the compiler by running

aeproject env --stop

There are optional parameters --nodeVersion and --compilerVersion. To specify a specific version of node or compiler, or both

This also applies to the commands aeproject node and aeproject compiler.

To see whether you have running instances of the nodes along with a compiler you could run the following command

Note: By default AEproject uses the latest-bundle tag of the official .

Compatibility:

• the sdk from @aeternity/aepp-sdk@14 >= v14.0.0 is compatible with NODE_TAG >= v7.1.0 and COMPILER_TAG >= v8.0.0

• due to a bug in the devmode plugin, NODE_TAG = v7.1.0 is not compatible with aeproject

Disclaimer

• Firewalls and any other security feature can block your docker/docker-compose requests. Please check that docker/docker-compose is NOT in its blocked list or has permission to make requests.

The Sophia language also provides you the possibility to emit in your functions. On this page you will learn how to access and decode the event log of a specific transaction.

EventEmitter contract

This example contract that emits events will be used in the following examples:

Simple Summary

The document describes and defines the secret storage approach used by æternity.

Motivation

The motivation for the AEX is to describe a standard way that is being used by æternity for secret storage.

Changes

AEproject v4.0.0 underwent some bigger changes, is now available as official package of the æternity organization on NPM and is compatible to the recently published node .

Install the new AEproject version

While base64-encoded strings have a constant length depending on the length of data to encode. In base58 it depends on the exact data to encode, e.g. it is shorter if encoded data have more leading zeroes.

Building an aepp you may need to know the range of possible address lengths to validate an user-provided addresses (though better to use ) or for designs of address-related components. Doing manual tests you may conclude that account address length is between 52 and 53 chars, but it is not correct.

Running the above code you would get something like { '51': 55, '52': 5021, '53': 4924 } depending on generated accounts. So, while the most of addresses have length between 52 and 53 chars, there is a ~0.55% chance to get an address of 51 chars.

Theoretically there can be even shorter addresses if they lucky to be prefixed with a long sequence of 0.

Running the above code you would get output like

Therefore the minimum address length is 41 chars. All these addresses valid, for exampleak_11111111111111111111111111111111273Yts

Overview

AeMdw is a middleware that acts as a caching and reporting layer for the . It responds to queries more efficiently than the node and supports additional queries.

The middleware runs an Aeternity Node alongside it in the same Docker container and BEAM VM instance. This node can be configured using the aeternity.yaml file or by passing environment variables, just like configuring the node directly.

This guide explains basic interactions on getting access to aeternity accounts on Ledger Hardware Wallet using JS SDK.

Prerequisite

Run the code from below you need:

• a Ledger Hardware Wallet like Ledger Nano X, Ledger Nano S;

This guide shows how to build either an WebExtension Wallet or a iFrame-based Wallet.

WebExtension wallet

The full implementation of this example can be found here:

Note:

Introduction

This guide explains you how to perform a PayingForTx (also known as meta-transaction) using the SDK.

It is a very powerful and efficient solution that is crucial for onboarding new users into you ecosystem. By making use of the PayingForTx you will be able to cover the fees of your users.

Run unit tests

The test command helps developers run their unit tests for æternity projects. The command executes the tests scripts that are located in the test folder of your æternity project.

This guide describes the 4 steps that are necessary to connect your application to a wallet using the RPC API.

Prerequisites

• Install for simplicity of example. You can build your own wallet in the next example

Describe the bug A clear and concise description of what the bug is.

To Reproduce Steps to reproduce the behavior:

1. Go to '...'

2. Click on '....'

3. Scroll down to '....'

This tutorial shows you how to use the SDK in your Vue.js application. You will replace the content of the default HelloWorld component and display the current block height of the æternity testnet.

1. Install Vue.js

AEproject v5.0.0 underwent some breaking changes.

Install the latest AEproject version

Various Changes

• dropped commonjs support, newly created projects will be created as esm projects, old cjs projects will not continue to work with newer aeproject versions, to keep using old cjs projects,

This guide shows you how to handle errors originating from the SDK. SDK by default exports the following error classes from file errors.ts

Error Hierarchy

Usage

// import required error classes
import {
  AeSdk,
  Node,
  AccountMemory,
  ArgumentError,
  InvalidAensNameError,
} from '@aeternity/aepp-sdk';

// setup
const payerAccount = AccountMemory.generate();
const newUserAccount = AccountMemory.generate();
const node = new Node('https://testnet.aeternity.io');
const aeSdk = new AeSdk({
  nodes: [{ name: 'testnet', instance: node }],
  accounts: [payerAccount, newUserAccount],
});

// catch exceptions
try {
  const spendTxResult = await aeSdk.spend(-1, newUserAccount.address, { onAccount: payerAccount });
} catch (err) {
  if (err instanceof ArgumentError) {
    console.log(`Amount specified is not valid, ${err.message}`);
  } else if (err instanceof InvalidAensNameError) {
    console.log(`Address specified is not valid, ${err.message}`);
  }
}

// using generic error classes
import { AensError, TransactionError, BaseError } from '@aeternity/aepp-sdk';

try {
  const spendTxResult = await aeSdk.spend(1, 'ak_2tv', { onAccount: payerAccount });
} catch (err) {
  if (err instanceof AensError) {
    // address or AENS related errors
  } else if (err instanceof TransactionError) {
    // transaction errors
  } else if (err instanceof BaseError) {
    // match any errors from the SDK
  }
}

Introduction

In some cases, aepp developer may need to send a set of transactions at once. The SDK provides optimizations for this scenario but it also requires additional effort by the developer. This guide covers specific cases with suggestions on how to proceed with them to produce a sequence of requests in an efficient way.

Multiple spend transactions

Obviously, multiple spends may be done like:

But this isn't the fastest approach, because on each iteration SDK would:

• request the sender data (its type and nonce)

• verify the transaction (including additional requests)

• wait until the transaction is mined

It can be avoided by making spends as:

This way, SDK would make a single request to get info about the sender account and a transaction post request per each item in the spends array.

Additionally, you may want to set gasPrice and fee to have predictable expenses. By default, SDK sets them based on the current network demand.

Multiple spends via contract call

If you need to transfer a fixed AE amount from the same account to more than 24 accounts, it is more efficient to do it via a smart contract.

Let's define and deploy a contract

after deployment this contract, it can be called as follows

Pros of this approach:

• less fees if more than 24 recipients;

• faster to execute because it needs to mine fewer transactions.

Cons:

• the amount of recipients in one transaction limited by the maximum gas in a block (about 800 recipients);

• harder to implement.

Fees difference

One spend tx takes approximately 0.0000167ae. The above contract deployment is 0.0000815ae. The base contract call price is 0.000182ae. Adding an address to the list costs about 0.0000058ae. So, it is more efficient to use a contract if you have more than 24 recipients. And more than 17 recipients if you use a pre-deployed contract.

Multiple contract static calls

Basically, the dry-run endpoint of the node is used to run them. Doing requests one by one, like

will make SDK create a new dry-run request for each static call. It may be not efficient because dry-run supports executing multiple transactions at a single request. It can be done by making all calls at once:

With combine flag SDK would put all of them into a single dry-run request. Also, it is necessary to generate increasing nonces on the aepp side to avoid nonce-already-used errors.

This approach has another limitation: by default, dry-run is limited by 6000000 gas. This is enough to execute only 32 plain contract calls. it can be avoided by:

• increasing the default gas limit of restricted dry-run endpoint in node configuration

• decreasing the gas limit of each static call

• using a debug dry-run endpoint instead of the restricted one

The Hyperchain Bridge enables seamless token transfers between the Aeternity blockchain and its Hyperchains. It ensures secure and efficient scalability and interoperability across these networks. By monitoring Aeternity networks, it indexes and stores bridge transactions, facilitating fast data retrieval for the user interface. Additionally, the application empowers users to integrate new Hyperchain networks, extending bridge capabilities to emerging networks.

⚠ Warning: The Hyperchain Bridge is a work in progress and is not production-ready. Use it with caution and be aware of the risk of losing funds.

Getting Started

Prerequisites

1. Install Bun.js: The bridge application uses Bun.js as its JavaScript runtime. Install Bun.js on the machine that will run the application: .

2. Setup Supabase: The bridge application relies on a PostgreSQL database hosted on the Supabase platform. The database should include the following tables: actions and networks. Use the SQL definitions below to create the tables:

   After setting up the database:

Application Checklist

Before running the application, ensure the following steps are completed:

1. Add the required environment variables to a .env file:

2. Update the network constants in src/constants/networks.ts with the deployed bridge contract addresses using the bridge operator account.

3. Ensure the Hyperchain networks are added to the constants with valid attributes. By default, only Mainnet and Testnet networks are included. Additional chains can be specified in this file or added through the network identification flow.

Running the Application

1. Install Dependencies:

2. Run the Development Build: Start the development build with hot module replacement:

3. Run the Production Build: Start the production build:

Debugging

The application can be debugged using Visual Studio Code with the Bun for Visual Studio Code extension. After installing the extension, use the debug configurations in launch.json to debug the application.

Architecture and Workflow

Tech Stack

The Hyperchain Bridge leverages the following technologies:

• TypeScript: Ensures type safety and improves developer productivity.

• Bun.js: A JavaScript runtime powering backend services for efficient handling of bridge transactions, data processing, and routing.

• React: Provides a responsive and user-friendly interface.

• Sophia: A functional smart contract language for secure and efficient contracts on the Aeternity blockchain.

Components

The project consists of the following key components:

• Smart Contracts: Includes HyperchainBridge and AEX9 FungibleToken Sophia contracts for secure transactions, along with unit tests for critical functionality.

• Deployment Scripts: Utility scripts for streamlined deployment of smart contracts.

• Backend: Listens for new bridge transactions and stores them in a PostgreSQL database.

• Frontend: Enables users to interact with the bridge contracts, perform bridge actions, view transaction history, and monitor ongoing transactions.

Bridge Workflow

The bridge workflow involves transferring tokens between Aeternity blockchains using the HyperchainBridge contract:

1. A user initiates a bridge action by calling the enter_bridge function on the HyperchainBridge contract with the destination network, token, amount, and other parameters.

2. After the entry transaction is confirmed, the user connects to the destination network specified in the call.

3. The user retrieves the necessary parameters (e.g., signature, timestamp) from the bridge API backend.

4. On the destination network, the user calls the

Network Identification Workflow

The application allows users to add new networks by providing details such as nodeURL and mdwURL. The workflow is as follows:

1. Connect to a network not specified in the networks constants.

2. Fill out the form with the required network details and submit.

3. The application verifies the network's connectivity and provides feedback.

4. Fund the bridge operator's account for contract deployment.

Simple Summary

This document defines a standard how arbitrary messages or payload can be signed using an aeternity keypair.

Motivation

Message signing can be used in a wide variety of scenarios. Common use cases include:

• Authentication / Login (Proving you are the owner of an address/pubkey)

• Authorization (Giving a user priviliges based on the coins / tokens he owns)

• Prove Data Integrity

• Voting

This technique has been around for a long time, but with the rise in crypto adoption it becomes more accessible to the average user.

Specification

Flow

1. DApp / Website / Wallet prepares a signing request containing a message (challenge) and other parameters (see below)

2. Signing request is sent to the Wallet / Signer containing the Private Key

3. User can select an identity (= keypair)

4. Message will be signed

Encoding

The signature should be encoded in hex: Buffer.from(signature).toString("hex");

Message Signing Request

Message Signing Response

The response can contain an array of signatures and publicKeys, which allows a single message to be signed by multiple identities at once.

Signing the message

Verifying the signature

Example

Serialization and Transport Layer

Serialization and Transport Layer are not part of this propaosal.

The Serialization is being discussed as part of AEX-7 Data Serialization

Security

In order to prevent malicious DApps from sending a seeminly random message to be signed that actually contains data like a valid transaction, we should add a prefix to the message so this can't be exploited.

https://github.com/ethereum/wiki/wiki/JSON-RPC#eth_sign

This document describes the requirements and the process of creating releases of aepp-sdk to npmjs.com.

Prerequisites

A user wanting to release a new version needs to be a member of the @aeternity organization on npmjs.com. An existing member with write access needs to invite them in order to achieve this. In addition, the user needs to activate any means of 2-factor authentication because the aepp-sdk package is set up to only accept new versions if a second factor for authentication is in use.

As new releases should only happen from release branch merges to the master branch of the repository on GitHub followed by a signed tag push, the user also needs direct write access to on GitHub. Normally, this can be achieved by first adding them to the and then to the, which gives automatic write access.

Branching Out

As aepp-sdk follows the for development, the release process is modelled after that strategy accordingly, with a few additions.

Branch out from develop to a dedicated release branch denoting the target version number, e.g. release/v2.3.4.

Preparing a Pre-Release

If Testnet is not yet targeting the latest Node version, but you're "ready to release", you can do a pre-release for the latest version, tagging the release as @next on npmjs.

To do this, You can follow the steps listed below, while keeping the next portion in both CHANGELOG.md and package.json files.

Preparing a Release

On the release branch, remove the next portion of the version string in package.json.

Execute npm run release to automatically

• bump version number in package.json and package-lock.json (according to)

• output changes to

• commit package-lock.json and package.json and CHANGELOG.md

Next, git diff the release, branch a release/vX.X.X (where vX.X.X is your latest release) against master and validate that all changes are covered in the changelog. You can find more instructions on how to maintain a CHANGELOG here:

PR against master

Create a pull request against master and have it peer reviewed thoroughly. As all changes should've been reviewed before when they were merged to develop, emphasize on security-related changes and small changes pushed to develop separately.

Merging

Once the integration build has successfully completed (with or without additional fixes), merge (without squash) the branch into master. This allows master to be comprised of release commits exclusively, so every commit on master corresponds to exactly one released (or at least, tagged) version of aepp-sdk, respectively.

Build, Release and Tag

Update the local working copy to a local tracking branch of master and update. Optionally, wait for the CI build to finish and execute a lastnpm run test locally.

Important: Because npm publish will use the local files on disk for releasing, perform a full clean and build in order to release to npmjs.com!

1. Cleanup - run git clean -ffdx to completely wipe out your workspace of files not in the repository. This might wipe out files you still need, so consider a separate clone of the project!

2. Execute npm run prepublishOnly to generate Documentation for the API and the SDK codebase, optionally followed by npm pack and investigate the resulting tarball's contents. This tarball resembles what users will actually download from npmjs.com once the release is completed!

3. Execute npm publish

Important: If you are releasing a Pre-Release (AKA next), make sure to tag the release as next using the command npm publish --tag next.

At this point, the release should already be in npmjs.com. The final step is to also tag the release on GitHub and push the tag, which requires direct write access.

1. git tag vX.X.X

2. git push tag vX.X.X

Recommendation: Use signed tags using the -s option to increase community's trust in the project!

Merging Back into develop

At this point, it is important to synchronize develop with any changes that have happened after branching out to the release branch. Create a new branch called realign/vX.X.X from master (where vX.X.X is your latest release) and open a Pull Request towards develop and resolve conflicts, if needed.

This concludes the release process and the development cycle.

JavaScript SDK for the revolutionary æternity blockchain, targeting theæternity node implementation. The aepp-sdk is hosted on GitHub.

Guides & Examples

Introduction

Usage guides:

• (æternity naming system)

There are also that you can directly use and play with.

CLI - Command Line Interface

To quickly test all of æternity's blockchain features from your terminal, you can install and use the by running:

1. npm i -g @aeternity/aepp-cli to globally install the CLI

2. aecli --help to get a list of possible commands

Contributing

For advanced use, to get a deeper understanding of the SDK or to contribute to its development, it is advised to read the section.

Changelog

We keep our up to date.

Requirements

In order to have AEproject working you must have installed the following:

Note: on windows WSL 2 must be used

Install

Init a project

This will create the project scaffold with an example contract including tests as well as a sample deployment script inside the specified folder. If no folder is specified the artifacts will be initialized in the current directory.

Further explained in .

Running a local environment

This will run a local æternity network in dev-mode (node, compiler and nginx-proxy).

To stop an already spawned local environment use aeproject env --stop

Further explained in .

Testing

This will run the tests located in ./test folder. Further explained in .

Help

Run this command to give you all possible commands of aeproject with help and info

Version

Running this command will give you the current installed aeproject version

Installed automatically with each project initialized with aeproject init, otherwise can be installed using npm i @aeternity/aeproject.

Available imports include helper definitions and utils using:

const { utils, wallets, networks } = require("@aeternity/aeproject");

Utils

Read the contract source from given path, just a wrapper for fs.readFileSync using utf-8 encoding.

Initialize the æternity SDK, pre-configured for optimal use in an AEproject project using æternity node devmode.

Create and wait for n number of key-blocks with the æternity node devmode, checked using the passed aeSdk.

Create a snapshot of the current chain state using the æternity node devmode, using the passed aeSdk.

Rollback to the latest snapshot using the æternity node devmode, using the passed aeSdk.

Rollback to the specified height using the æternity node devmode, using the passed aeSdk.

Get the pre-funded default accounts as MemoryAccount, so they can be used natively using the aeSdk.

Wallets

List of configured keypairs that are pre-funded using the æternity node devmode as provided in AEproject.

Networks

Exposed URLs for commonly used nodeUrl and compilerUrl, per default local devmode and optionally hosted URLs for mainnet and testnet.

Overview

AeMdw is a middleware that acts as a caching and reporting layer for the . It responds to queries more efficiently than the node and supports additional queries.

The middleware runs an Aeternity Node alongside it in the same Docker container and BEAM VM instance, so you don't need to run a standalone one. This node can be configured using the aeternity.yaml file or by passing environment variables, just like configuring the node directly.

AEproject is an æternity framework which helps with setting up a project to develop and test . It provides commands to spin up a local environment as well as utilities for compiling and testing Sophia Smart Contracts. The initial scaffold provides an example contract & corresponding tests.

Install

Generating JWT

Use signJwt to generate a JWT signed by an account provided in arguments.

Provide sub_jwk: undefined in payload to omit signer public key added by default. Do it to make JWT shorter.

Or if you using a different way to encode a signer address.

Abstract

A short (~200 word) description of the technical issue being addressed.

Motivation

The following describes standard functions a token contract and contract working with specified token can implement to prevent accidentally sends of tokens to contracts and make token transactions behave like ether transactions. Moreover, where designing the tokens we looked carfully at compliance work and wanted to make it easier for integrating compliance workflow. With this respect token transactions contains data field to be used freely to pass additional information (eg: reference) from a holder or an operator.

The goal is to make this specification useful with Native Tokens.

Specification

Interface

The token contract MUST implement the above interface. The implementation MUST follow the specifications described below.

Operators

An operator is an address which is allowed to send and burn tokens on behalf of some holder.

NOTE: A holder MAY have multiple operators at the same time.

A default operator is an implicitly authorized operator for all holders. The rules below apply to default operators:

• The token contract MUST define default operators at creation time. The default operators set MAY be empty.

• The token contract MUST NOT add or remove default operators after contract instantiation.

• AuthorizedOperator events MUST NOT be emitted when defining default operators.

• A holder MUST be allowed to revoke a default operator (unless the holder is the default operator).

The following rules apply to any operator:

• An address MUST always be an operator for itself. Hence an address MUST NOT ever be revoked as its own operator.

NOTE: A holder MAY authorize an already authorized operator. An AuthorizedOperator MUST be emitted each time.

NOTE: A holder MAY revoke an already revoked operator. A RevokedOperator MUST be emitted each time.

Functional Specification

General Notes

meta() : meta_inf

Returns information about token as a meta_inf record.

total_supply() : int

Returns: Total supply of tokens currently in circulation.

• NOTE: MUST be equal to the sum of the balances of all addresses—as returned by the balance_of function.

• NOTE: MUST be equal to the sum of all the minted tokens as defined in all the Minted events minus the sum of all the burned tokens as defined in all the Burned events.

balance_of(holder: address) : option(int)

Get the balance of the holder account. If the account is not registered (didn't use any token) then it MUST return None. Oherwise it MUST return non negative integer.

default_operators() : list(address)

List of addresses of all the default operators.

is_operator_for(operator: address, holder: address) : bool

MUST return true if the operator address is an operator for the holder. Otherwise MUST return false.

authorize_operator(operator: address)

Set a third party operator address as an operator of Call.caller to transfer and burn tokens on its behalf.

NOTE: The holder (Call.caller) is always an operator for itself. This right SHALL NOT be revoked.

revoke_operator(operator: address)

Remove the right of the operator address to be an operator for Call.caller and to send and burn tokens on its behalf.

NOTE: The holder (Call.caller) is always an operator for itself. This right SHALL NOT be revoked.

transfer(to: address, amount: int, data: string)

Send the amount of tokens from the Call.caller (holder) to the to address. data an information provided by the holder.

In the Transfer event, the operator and the holder MUST both be Call.caller.

op_transfer(from: address, to: address, amount: int, data: string, op_data: string)

Send the amount of tokens on behalf of the from address to the to address.

Reminder: If the operator address (Call.caller) is not an authorized operator of the from address, then the send process MUST abort.

burn(amount: int, data: string)

Burn the amount of tokens from the Call.caller address.

In the Burned event, the operator and the holder MUST both be Call.caller.

op_burn(from: address, amount: int, data: string, op_data: string)

Burn the amount of tokens on behalf of the from address.

Reminder: If the operator address (Call.caller) is not an authorized operator of the from address, then the burn process MUST abort.

AuthorizedOperator event

Indicates the authorization of operator as an _operator for holder. The token contract MUST emit an AuthorizedOperator event with the correct values when a holder authorizes an address as its operator (even if it's already authorized or it's defined as a default oprator).

RevokeOperator event

Indicates the revokation of operator as an _operator for holder. The token contract MUST emit an RevokeOperator event with the correct values when a holder revokes an address as its operator (even if it's already revoked or it's defined as a default oprator).

Hooks

tokensToTransfer hook

The tokensToSend hook notifies of any request to decrement the balance (transfer and burn) for a given holder. Any address (regular or contract) wishing to be notified of token debits from their address MAY register for receiving this hooks

Interface:

Notify a request to transfer or burn (if to is 0x0) an amount tokens from the from address to the to address by the operator address. The holder MAY block a send or burn process by aborting. (I.e., reject the withdrawal of tokens from its account.)

• to MUST be 0x0 for a burn.

• amount MUST be the number of tokens the holder sent or burned. MUST be non negative integer (0 is possible).

• data MUST contain the extra information (if any) provided to the send or the burn process.

NOTE: A regular address MAY register a different address—the address of a contract—implementing the interface on its behalf. A contract MAY register either its address or the address of another contract but said address MUST implement the interface on its behalf.

TODO

tokensReceived hook

The tokensToSend hook notifies of any request to increment the balance (transfer and mint) for a given holder. Any address (regular or contract) wishing to be notified of token credits from their address MAY register for receiving this hooks

Interface:

Notify a send or mint (if from is 0x0) of amount tokens from the from address to the to address by the operator address.

TOOD

Backwards Compatibility

This token provides a foundation for compliance tokens. Because of the need for refence field (data), and introduction of operators (often required in the industry and interoperability with other smart contracts), the interface is not backward compatible with proposed AEX-9 simple token standard.

Implementation

TODO