aztec3-speccing-book
We are going to lean heavily on copying how Ethereum manages its EIPs, but instead adopt the name of AZIPs, or AZtec Improvement Proposals.
AZIP stands for Aztec Improvement Proposal. An AZIP is a design document providing information to the Aztec community, or describing a new feature for Aztec or its processes or environment. The AZIP should provide a concise technical specification of the feature and a rationale for the feature. The AZIP author is responsible for building consensus within the community and documenting dissenting
opinions.
We intend AZIPs to be the primary mechanisms for proposing new features, for collecting community technical input on an issue, and for documenting the design decisions that have gone into Aztec. Because the AZIPs are maintained as text files in a versioned repository, their revision history is the historical record of the feature proposal.
For Aztec implementers, AZIPs are a convenient way to track the progress of their implementation. Ideally each implementation maintainer would list the AZIPs that they have implemented. This will give end users a convenient way to know the current status of a given implementation or library.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in technical specifications are to be interpreted as described in RFC 2119 and RFC 8174.
The following outlines the various stages an AZIP moves through. It does not enforce when development of a particular piece of work should begin, for example work may start as soon as drafted, but the work is heavily subject to change. Aztec engineers will likely be developing a reference implementation of the system, before an AZIP reaches Final
status. External developers working on their own implemenatations, will likely wait for finality.
Final
. An AZIP Editor will assign Last Call
status and set a review end date, typically 14 days later. If this period results in necessary normative changes it will revert the AZIP to Review
.Draft
or Review
if inactive for a period of 6 months or greater is moved to Stagnant
. An AZIP may be resurrected from this state by Authors or AZIP Editors through moving it back to Draft
.Each AZIP is given a category based on what it's specifying. The AZIP number prefix is picked based on this type.
Following Ethereum's conventions, when referring to an AZIP with a category
of ARC
, it must be written in the hyphenated form ARC-X
where X
is that AZIP’s assigned number. When referring to AZIPs with any other category
, it must be written in the hyphenated form AZIP-X
where X
is that AZIP’s assigned number.
Living
. Informational AZIPs do not necessarily represent Aztec community consensus or a recommendation, so users and implementers are free to ignore Informational AZIPs or follow their advice.Each AZIP should have the following parts:
../assets/azip-###/<filename>
.Final
without a Security Considerations discussion deemed sufficient by the reviewers.Copyright and related rights waived via [CC0](/LICENSE).
AZIPs should be written in markdown format. There is a template to follow.
Each AZIP must begin with a header preamble. The headers must appear in the following order.
azip |
AZIP number (this is determined by the AZIP Editor). |
title |
The AZIP title is a few words, not a complete sentence. |
description |
Description is one full (short) sentence. |
author |
Comma separated list of the author's. Example: FirstName LastName (@GitHubUsername) , FirstName LastName <foo@bar.com> |
discussions-to |
The URL pointing to the official discussion thread in the Aztec forum. |
status |
Draft , Review , Last Call , Final , Stagnant , Withdrawn or Living . |
last-call-deadline |
The date last call period ends on (Optional field, only needed when status is Last Call ). |
category |
Informational , Core , Networking , Interfaces, Crypto , DSL , ARC or Meta . |
created |
Date created on, in ISO 8601 (yyyy-mm-dd) format. |
requires |
AZIP number(s) of AZIPs this AZIP depends on (Optional field). |
withdrawal-reason |
A sentence explaining why the AZIP was withdrawn. (Optional field, only needed when status is Withdrawn ). |
Headers that permit lists must separate elements with commas.
Headers requiring dates will always do so in the format of ISO 8601 (yyyy-mm-dd).
author
headerThe author
header lists the names, email addresses or usernames of the authors/owners of the AZIP. Those who prefer anonymity may use a username only, or a first name and a username. The format of the author
header value must be:
Random J. User <address@dom.ain>
or
Random J. User (@username)
if the email address or GitHub username is included, and
Random J. User
if the email address is not given.
It is not possible to use both an email and a GitHub username at the same time. If important to include both, one could include their name twice, once with the GitHub username, and once with the email.
At least one author must use a GitHub username, in order to get notified on change requests and have the capability to approve or reject them.
discussions-to
headerWhile an AZIP is a draft, a discussions-to
header will indicate the URL where the AZIP is being discussed (in the Aztec forum).
Links to external resources SHOULD NOT be included. External resources may disappear, move, or change unexpectedly.
References to other AZIPs should follow the format AZIP-N
where N
is the AZIP number you are referring to. Each AZIP that is referenced in an AZIP MUST be accompanied by a relative markdown link the first time it is referenced, and MAY be accompanied by a link on subsequent references. The link MUST always be done via relative paths so that the links work in the GitHub repository, forks of this repository, the main AZIPs site, mirrors of the main AZIP site, etc.
Images, diagrams and auxiliary files should be included in a subdirectory of the assets
folder for that AZIP as follows: assets/azip-N
(where N is to be replaced with the AZIP number). When linking to an image in the AZIP, use relative links such as ../assets/azip-1/image.png
.
It occasionally becomes necessary to transfer ownership of AZIPs to a new champion. In general, we'd like to retain the original author as a co-author of the transferred AZIP, 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 AZIP 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 AZIP. We try to build consensus around an AZIP, but if that's not possible, you can always submit a competing AZIP.
If you are interested in assuming ownership of an AZIP, send a message asking to take over, addressed to both the original author and the AZIP editor. If the original author doesn't respond to the email in a timely manner, the AZIP editor will make a unilateral decision (it's not like such decisions can't be reversed.
The current AZIP editors are:
For each new AZIP that comes in, an editor does the following:
If the AZIP isn't ready, the editor will send it back to the author for revision, with specific instructions.
Once the AZIP is ready for the repository, the AZIP editor will:
Many AZIPs are written and maintained by developers with write access to the Aztec codebase. The AZIP editors monitor AZIP changes, and correct any structure, grammar, spelling, or markup mistakes we see.
The title
field in the preamble:
The description
field in the preamble:
When referring to an AZIP by number, it should be written in the hyphenated form AZIP-X
where X
is the AZIP's assigned number.
AZIPs are encouraged to follow RFC 2119 and RFC 8174 for terminology and to insert the following at the beginning of the Specification section:
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 and RFC 8174.
This document was derived heavily from Ethereums EIP-001, which in turn was derived from Bitcoin's BIP-0001 written by Amir Taaki which in turn was derived from Python's PEP-0001. In many places text was simply copied and modified. Do not bother the authors of these ancestor works with technical questions specific to Aztec or the AZIP. Please direct all comments to the AZIP editors.
Copyright and related rights waived via CC0.