AEX: <to be assigned by editors>
Title: <AEX title>
Author: <a list of the author's or authors' name(s) and/or username(s), or name(s) and email(s), e.g. (use with the parentheses or triangular brackets): FirstName LastName (@GitHubUsername), FirstName LastName <[email protected]>, FirstName (@GitHubUsername) and GitHubUsername (@GitHubUsername)>
License: <license names, abbreviated>
License-Code (*optional): <license names, abbreviated>
Discussions-To: <URL>
Status: <Draft | Review | Last Call (yyyy-mm-dd to yyyy-mm-dd) | Final | Active | Updated | Superseded | Rejected | Withdrawn>
Type: <Interface | Informational | Meta>
Created: <date created on, in ISO 8601 (yyyy-mm-dd) format>
Requires (*optional): <AEX number(s)>
Replaces (*optional): <AEX number(s)>
Updates (*optional): <AEX number(s)>

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

AEX: 1
Title: AEX process
Author: Sascha Hanse <[email protected]>
License: CC0-1.0
Discussions-To: https://forum.aeternity.com/t/aeternity-best-current-practices-aexpansions/2461
Status: Active
Type: Meta
Created: 2019-02-01

Simple Summary

This document describes the process a proposal has to go through in order to be accepted into the AEX repository.

Motivation

The purpose of AEXs is to provide high quality and accessible specifications to be used when developing applications on top of Aeternity. We intend AEXs to be the primary mechanisms for proposing new standards, for collecting community technical input on an issue, and for documenting the design decisions. Because the AEXs are maintained as text files in a versioned repository, their revision history is the historical record of the feature proposal.

Specification

AEX Types

There are three types of AEXs:

• A Standards Track AEX describes any change or addition that affects the interoperability of applications using Aeternity. Standards Track AEXs consist of two parts: a design document and a reference implementation.

• An Informational AEX describes a design issue, or provides general guidelines or information to the Aeternity community, but does not propose a new feature. Informational AEXs do not necessarily represent an Aeternity community consensus or recommendation, so users and implementors are free to ignore Informational AEXs or follow their advice.

• A Meta AEX describes a process surrounding AEXs or proposes a change to (or an event in) a process. They often require community consensus; unlike Informational AEXs, they are more than recommendations, and users are typically not free to ignore them. Examples include procedures, guidelines, changes to the decision-making process, and changes to the tools or environment used in Aeternity development.

Workflow

Parties involved in the process are you, the champion or AEX author and the AEX editors.

Your role as the champion is to write the AEX using the style and format described below, shepherd the discussions in the appropriate forums, and build community consensus around the idea.

Stages

+---------------+             +---------------+             +---------------+
|     Draft     |------------>|     Review    |<----------->|   Last call   |
+---------------+             +---------------+             +---------------+
       ^      |                 |     ^                       |   |   |   |
       |      v                 |     |                       |   |   |   |
       |  +---------------+     |     |                       |   |   |   |
       |  |   Withdrawn   |<----+-----|-----------------------+   |   |   |
       |  +---------------+           |                           |   |   |
       v                              |                           |   |   |
+---------------+                     |                           |   |   |
|    Rejected   |<--------------------+---------------------------+   |   |
+---------------+                                    -----------------+   |
                                                     |                    |
                                                     v                    v
          +---------------+             +---------------+    +---------------+
          |    Updated    |<----------->|     Final     |    |     Active    |
          +---------------+             +---------------+    +---------------+
                  |                             |
                  +----------+       +----------+
                             |       |
                             v       v
                         +---------------+
                         |   Superseded  |
                         +---------------+

Each status change is requested by the AEX author and reviewed by the AEX editors. Use a pull request to update the status.

AEXs should be changed from Draft or Review status, to Rejected status, upon request by any person, if they have not made progress in three years. Such a AEX may be changed to Draft status if the champion provides revisions that meaningfully address public criticism of the proposal, or to Review status if it meets the criteria required as described in the previous paragraph.

The transition from Last Call to either Final or Active happens automatically if during the last call period, typically 14 days, no substantiated objections are voiced or left unaddressed.

A Last Call which results in material changes or substantial unaddressed technical complaints will cause the AEX to revert to Review.

Transferring AEX Ownership

It occasionally becomes necessary to transfer ownership of AEXs to a new champion. In general, we'd like to retain the original author as a co-author of the transferred AEX, but that's really up to the original author. A good reason to transfer ownership is because the original author no longer has the time or interest in updating it or following through with the AEX process, or has fallen off the face of the 'net (i.e. is unreachable or isn't responding to email). A bad reason to transfer ownership is because you don't agree with the direction of the AEX. We try to build consensus around an AEX, but if that's not possible, you can always submit a competing AEX.

If you are interested in assuming ownership of an AEX, send a message asking to take over, addressed to both the original author and the AEX editor. If the original author doesn't respond to email in a timely manner, the AEX editor will make a unilateral decision (it's not like such decisions can't be reversed :).

Editors

For each new AEX that comes in, an editor does the following:

• Read the AEX to check if it is ready: sound and complete. The ideas must make technical sense, even if they don't seem likely to get to final status.

• The title should accurately describe the content.

• Check the AEX for language (spelling, grammar, sentence structure, etc.), markup (Github flavoured Markdown), code style

If the AEX isn't ready, the editor will send it back to the author for revision, with specific instructions.

Once the AEX is ready for the repository, the editor will:

• Assign an AEX number (generally the PR number or, if preferred by the author, the issue # if there was discussion in the issues section of this repository about this AEX)

• Merge the corresponding pull request

• Send a message back to the AEX author with the next step.

In general, the editors:

• Don't pass judgment on AEXs.

• Are intended to fulfil administrative and editorial responsibilities.

• Monitor AEX changes, and update AEX headers as appropriate.

List of editors

• Sascha Hanse (@knarz)

• Philipp Piwowarsky (@thepiwo)

Format

Successful AEXs should contain most of the following sections:

• Preamble: RFC 822 style headers containing metadata about the AEX

• Simple Summary: a simplified and layman-accessible explanation of the AEX

• Abstract: a short (~200 word) description of the (technical) issue being addressed

• Motivation: clearly explaining why the existing standards are inadequate to address the problem that the AEX solves

• Specification: should describe the syntax and semantics of any new feature and should be detailed enough to allow competing, interoperable implementations

• 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: if a proposal is supposed to supersede another proposal without providing backwards compatibility then it should contain a section describing these incompatibilities and their severity. Further, it should explain how the author proposes to deal with these incompatibilities.

• Test Cases: links to test cases if applicable

• Implementations: implementation or link to implementations, if applicable

A AEX template can be found under AEX-X.

Preamble

Each AEX must begin with an RFC 822 style header preamble. The headers must appear in the following order. Headers marked with "*" are optional and are described below. All other headers are required.

AEX: <to be assigned by editors>
Title: <AEX title>
Author: <a list of the author's or authors' name(s) and/or username(s), or name(s) and email(s), e.g. (use with the parentheses or triangular brackets): FirstName LastName (@GitHubUsername), FirstName LastName <[email protected]>, FirstName (@GitHubUsername) and GitHubUsername (@GitHubUsername)>
License: <license names, abbreviated>
License-Code (*optional): <license names, abbreviated>
Discussions-To: <URL>
Status: <Draft | Active Review | Last Call (yyyy-mm-dd to yyyy-mm-dd) | Final | Updated | Superseded | Rejected | Withdrawn>
Type: <Standards Track | Informational | Meta>
Created: <date created on, in ISO 8601 (yyyy-mm-dd) format>
Requires (*optional): <AEX number(s)>
Replaces (*optional): <AEX number(s)>
Superseded-By (*optional): <AEX number(s)>
Updates (*optional): <AEX number(s)>
Updated-By (*optional): <AEX number(s)>

Header fields permitting lists must separate elements with commas.

The Discussions-To field should point to a discussion of the proposed standard. Most of the initial work should happen in small, focused working groups and only posted once it is in a reasonably stable state. Please try to refrain from having WIP documents or very early drafts in this repository as they tend orphan.

Each proposal must start in the Draft state and will move through the phases in accordance to the criteria defined in this document.

If a proposal depends on another AEX, the Requires field should indicate so.

Superseded-By, Replaces, Updates and Updated-By fields are required since standards are in constant flux. Editors and authors should make sure that old AEXs are update where appropriate.

Copyright

The following recommended licenses should be used both for code and the specification:

Each submitted proposal needs to list at least one license. If code is included, a separate license for it can be specified. The licenses should be included in the header via the License and License-Code fields. If those fields do not cover the requirements, include a copyright section in your proposal.

License: CC0-1.0
License-Code: Apache-2.0

Or with multiple licenses:

License: CC0-1.0
         BSD-3-Clause
License-Code: Apache-2.0

Other acceptable licenses:

References

Many parts of this document are inspired by or adapted with only minor modifications from many of the already existing standardisation processes.

Simple Summary

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

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

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

where account_index and address_index are integer starting from 0.

References

Quick Aexpansions filter

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:

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.

Status terms

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

• Active - proposal can be in constant flux. No unaddressed substantiated objections are left, crucial or cosmetic updates only.

• Updated - signalling that an updating standard might have to be considered

• Superseded - an AEX that is deprecated because other AEX supersedes it.

• Rejected - editors deemed this proposal to be unworkable

• Withdrawn - signalling that the proposal is no longer relevant.

AEXs

Copyright