Documentation for developers and users interested in the details of the protocol

Accumulate uses a custom binary encoding, loosely based off of Protocol Buffers. The fields of structured types (i.e. structs) are numbered, and when a field is encoded the (encoded) value of the field is prefixed with the field's number. However, unlike Protocol Buffers, Accumulate does not permit fields to be reordered - fields must be presented in order of their field number. For example, fields 2 and 4 of the same value must appear in that order - if they appear in the reverse order, the value will be rejected.

Value formats

• Field numbers must be between 1 and 31 (inclusive) and thus they can be (and are) encoded in a single byte. Structured types cannot have more than 31 fields.

• Integer values with a max size of 64 bytes or smaller are encoded as ().

• All other variable length values (i.e. excluding varints) are encoded to bytes, then prefixed with their byte length encoded as an unsigned varint.

• Arbitrary precision integer values are encoded as bytes (length-prefixed) in big-endian order.

• Floating point values are encoded as in IEEE 754 double-precision binary floating-point format (float64/binary64).

• Boolean values are encoded as 0x00 (false) or 0x01 (true).

• Dates and timestamps are converted to a UTC Unix timestamp (seconds) and encoded as a signed varint.

• Durations are split into seconds and nanoseconds and encoded as a pair of unsigned varints.

• Enumerations are converted to an integer and encoded as an unsigned varint.

• Hashes (32-byte values, aka 256-bit integers) are encoded raw, as 32 bytes (with no length prefix).

• Byte sequences are encoded raw, with a length prefix.

• Strings are encoded as a byte sequence.

• URLs and transaction IDs are converted to a string and encoded as a byte sequence.

Forwards compatibility and epilogues

Scenario: Two systems, A and B, wish to communicate with each other via binary encoded records. However, system A is using a newer type definitions for records, and these new definitions include additional fields that system B is not aware of. If A sends a message that includes a record with one of these additional fields, B will record the additional fields as the record's epilogue.

The epilogue is essentially extra bytes that are appended to the end of the record when converting it to binary. However, the epilogue has a condition: it must be prefixed with a field number higher than that of any of the known fields, such that it appears to be an additional field. For example, if record R defines three fields (numbered 1, 2, and 3), then the epilogue must be prefixed with 04. This allows the binary encoding format to be forwards compatible. If system A thinks record R has four fields, and system B thinks record R has three fields, and system A sends a message including a record of type R with all four fields set, the value of the fourth field will be prefixed with it's field number and thus system B will treat it as an epilogue.

This is not a license to append private data to objects. If system A adds a fourth, private field knowing that other systems will interpret that data as an epilogue, and then the other systems add a fourth field of a different type, the other systems will not be able to decode messages from system A due to the conflicting data type of the fourth field.

Repeatable fields

A repeatable field (usually typed as an array/slice/list) is encoded simply by repeating the field. For example, given struct A with a repeatable unsigned integer field X (number 1), A{X: [7, 8, 9]} would be encoded as 01 07 01 08 01 09.

Nested structured values

A field that is itself a structured value is encoded by encoding the structured value, then encoding the resulting bytes as a byte sequence (i.e. with a length prefix). For example, given struct A with a field X of type B, and struct B with an unsigned integer field Y, B{Y: 15} would be encoded as 01 0F thus A{X: B{Y: 15}} would be encoded as 01 02 01 0F.

Unions

Accumulate uses tagged unions. Each union type has a corresponding enumeration that enumerates the members of the union. Each union member has an implicit type field, numbered 1, with its value set to the enumeration value that corresponds to the member type. For example, the Account union type corresponds to the AccountType enumeration, and the KeyBook struct type (a member of the Account union) corresponds to AccountTypeKeyBook (a value of the AccountType enumeration).

Union values are encoded in the same way as any other structured type. Since the first field of a member of a union type is always the corresponding enumeration value, union values are decoded by decoding that first field, looking up the corresponding union member, then decoding the remainder of the fields using that type definition.

For example, KeyBook{Url: "foo", PageCount: 1} (with Type: AccountTypeKeyBook implicit) is encoded as 01 0a 02 03 66 6f 6f 05 01. To decode this, first the type field (numbered 1) is decoded; since AccountTypeKeyBook (0x0a) corresponds to the KeyBook struct type, the remaining values are decoded using that type's field definitions.

Main, scratch, and signature chains

Lite Accounts

Lite identity

Lite token account

Lite data account

ADI accounts

Identity (ADI)

Key books

Key page

Token account

Data account

Token issuer

System accounts

System ledger

Block ledger

Synthetic ledger

Anchor ledger

Wait for a transaction to complete

Transactions are operations that modify the state of accounts. See for a complete list.

Principals and transaction flows

A transaction has a principal account that is the context within which the transaction is executed. In most cases, the principal can be considered to be the account that is executing the action. For example, when sending tokens the principal is the account that the tokens are withdrawn from; in some sense the principal is the entity that is sending the tokens. In a few cases the relationship between the transaction and its principal is less clear, but the principal still has a key role in determining how signatures are validated and how the transaction is executed.

Talk about partitions, anchoring, and how everything actually works.

Talk about how the system is put together and how everything really works under the hood.

The accumulate repository includes a simulator. The simulator runs a fully functional Accumulate engine and API, though it does not simulate Tendermint. It does simulate multiple nodes with a basic consensus mechanism, so it will catch most potential consensus failures.

Run the simulator

The easiest way to run the simulator is via Docker:

Alternatively, --net=host can be used instead of -p 26660:26660. Without -v, all history will be lost if the simulator is stopped or restarted. The data directory (/data) can be bound to an arbitrary host directory, or to a docker volume, but it must be bound to something outside of the container if the simulator's state is to be persisted.

Using the simulator in Go programs

simulator.New requires four parameters: a logger, database provider, network definition, and snapshot provider. These parameters are structs, functions, or simple interfaces, so the caller may provide custom inputs if they wish, though the simulator package includes implementations.

For the database provider, the simulator package includes MemoryDatabase, which opens transient in-memory databases, and BadgerDatabaseFromDirectory, which opens persistent Badger databases in the given directory.

For the network definition, the simulator package includes SimpleNetwork, which defines an N x M network with N BVNs, each with M nodes; and LocalNetwork, which defines an N x M network with IP addresses, which allows the simulator to be made network accessible.

For the snapshot provider, the simulator package includes Genesis and friends, which construct genesis snapshots; SnapshotMap, which returns snapshots from a map provided by the caller; and SnapshotFromDirectory, which returns snapshots read from a directory.

simulator.Simulator has a number of methods to submit messages, and hook into and modify the inner workings of the systems (for testing purposes), as well as a full implementation of API v3.

The simulator must be manually stepped. simulator.Simulator has a Step method that must be called to execute blocks.

Using the simulator in Go tests

The test/harness package defines a test harness that simplifies writing tests using the simulator. See for an example of how this can be used.

Using the simulator via the API

simulator.Simulator has a ListenAndServe method that serves API v2 and/or v3 on its various interfaces.

Alternatively, the tools/cmd/simulator command can be used to run the simulator and serve API v2 and v3.

User transactions

Unless otherwise noted, the principal of a transaction must be an existing account, meaning the transaction will fail if the principal does not exist.

API v3 supports multiple transports:

• JSON-RPC (over HTTP)

• Custom JSON over WebSocket

• Custom binary over libp2p

Accumulate's authentication and authorization model has three major components: accounts, authorities, and signers.

Accounts

An account is governed by a set of authorities. An authority of an account may be enabled for all transactions executed against that account, or for specific types of transactions. The active authority set for a transaction is the set of the principal's authorities that are enabled for that type of transaction. A transaction is executed if and only if every authority of its active authority set accepts the transaction. Thus a transaction is rejected if any active authority rejects the transaction or explicitly abstains from responding, since that precludes unanimous acceptance.

The authority set of an ADI or ADI account is defined explicitly and is mutable. The authority set of a lite token account is defined structurally - it is governed by the lite identity it belongs to. A lite identity is governed by itself. Lite data accounts are not governed by any authority and can be written to by any account (except for another lite data account). Thus the authority set of a lite account is fixed and immutable.

Authorities

An authority is an entity that can act as an authority of an account and defines signers that may sign on its behalf. An authority accepts or rejects a transaction when any of its signers accept or reject the transaction. An authority that defines multiple signers must also define the precedence of those signers in the case that one signer accepts and another signer rejects a transaction. If a signer explicitly abstains from responding to a transaction, it is ignored unless every signer abstains.

Accumulate defines two types of authorities: lite identities and key books. A lite identity is also a signer. A key book contains one or more key pages, numbered in order of precedence.

Signers

A signer is an entity that can sign a transaction, accepting or rejecting it or explicitly abstaining from responding. The signing mechanisms differ depending on the nature of the signer, but in general a signer can sign a transaction directly with a key, or it can delegate to another authority.

Accumulate defines two types of signers: lite identities and key pages. A lite identity signs transactions with a specific key, determined by the URL of the lite identity.

Key pages

Key pages are highly configurable: at its simplest a key page is a one-of-one signer that signs with a key, at its most complex a key page can model complex authorization structures. A key page defines keys and other authorities (delegates) that may sign on its behalf.

A key page must define an acceptance threshold and may define rejection, response, and block thresholds. If a key page's response threshold is set, it will not accept, reject, or abstain from (collectively, respond to) a transaction until that number of its keys and/or delegates have responded to the transaction. If a key page's block threshold is set, it will not respond to a transaction until that number of blocks after the first response by a key or delegate. If those thresholds are met and/or unset, the key book will accept the transaction once the number of keys and/or delegates that accepted it meets the acceptance threshold, or it will reject the transaction once the number of keys and/or delegates that rejected it exceeds the rejection threshold (if the rejection threshold is unset the acceptance threshold is used instead). If the key page cannot possibly meet the acceptance or rejection threshold due to a split vote and/or abstentions, the key page abstains from the transaction.

Caveats

The protocol also defines a special signer used to sign synthetic and system transactions. This signer is one of a kind and cannot be used directly.

Use the query method to read the state of the network. query has the following parameters:

• scope is the scope of the query. This must be an account URL or a message ID. The message ID may be suffixed with an account or with unknown. For example:

Prove a transaction

Prove .

Get a BVN receipt for the transaction's main chain entry

The three fundamental elements of the Accumulate model are accounts, identities, and transactions. Accounts have state and can be modified. Identities are containers of accounts, and are themselves a type of account. Transactions are operations that modify the state of an account.

A domain is an atomic collection of accounts organized in a hierarchy by URL. In terms of URLs, the domain of an account is the same as the domain of a normal URL. The domain is itself an account, in most cases a lite identity or an ADI. The domain of a lite token account is a lite identity. An ADI is a domain if it is the root ADI - that is, if it is not contained with/a child of another ADI. The domain of an ADI account is the root ADI atr the top of the container tree.

There are some special accounts that are domains but cannot contain any other accounts or are otherwise atypical. ACME is a token issuer, not an identity; however is not within anything so it is a domain. Similarly, lite data accounts exist outside of any container. However, neither of these are identities: they cannot contain other accounts.

Two accounts are said to be local if they belong to the same domain and remote if they do not. Locality relates specifically to the root of an account. Two accounts that belong to different sub-ADIs are still local to each other if they have the same root identity.

Domains are siloed from each other. A domain cannot interact directly with any other domain. More generally, two accounts cannot interact directly if they are not local to each other; that is if they do not belong to the same domain. A transaction is executed within the context of some account; a transaction is expressly forbidden from interacting with (modifying) any account that is not local to its principal. In other words, a transaction may only interact with accounts that belong to the same domain as the transaction's principal.

An account in Accumulate is an entity that records transactions and has state, both mutable and immutable. See Accounts for a complete list.

Identities

An identity in Accumulate is a container, the primary purpose of which is to contain other accounts. Accumulate defines two types of identities: Accumulate digital identifiers (ADIs) and Lite identities.

Accounts are split into two broad categories: ADI accounts and lite accounts. ADIs may contain ADI accounts and sub-ADIs; lite identities may contain lite token accounts. Lite identites cannot be manipulated directly as their purpose is to hold lite token accounts. Lite identities cannot contain sub-identities.

Tokens

Accumulate natively supports custom tokens. Each type of token must be defined by a token issuer, an account that can issue that type of token. While token issuers define a ticker symbol to be used with the tokens it issues, there is no guarantee that the ticker symbol is unique, so Accumulate uses the address of the token issuer to uniquely identify the token.

Accumulate token accounts hold a single type of token, identified by the address of the token issuer and set when the token account is created.

Data accounts

Accumulate data accounts allow recording arbitrary data. Data is written as multipart entries, either Accumulate data entries or Factom data entries. Accumulate data entries are simply an array of byte arrays. Factom data entries exist for backwards-compatability with Factom and follow its conventions for defining and hashing data entries.

Key books and pages

Key books and pages define the key set and authorization rules for ADI accounts. A book contains one or more pages in order of priority, and a page contains one or more entries. describes books and pages in detail.

At a high level, Accumulate consists of containing that send to each other.

A domain is a boundary; that is, accounts within the same domain may interact directly with each other, but accounts in different domains cannot interact directly and instead must interact by sending messages.

Every interaction between to domains must be mediated by messages. Interactions that may cross domain boundaries are mediated by messages. All told, almost every possible interaction is mediated by a message.

From the user perspective, a single action may consist of many messages. A message may (often does) produce one or more other messages. The simplest user action - submitting a simple, single-sig transaction - involves submitting a signature and a transaction. The user's signature produces an authority signature, which triggers the execution of the transaction, which may produce another transaction, which would require various system messages. Collectively, this is called a message flow.

With few exceptions, every interaction between two accounts is mediated by a message.

Key signatures

A key signature is a message from the user to a signer saying that the user is initiating, accepting, rejecting, or abstaining from a transaction. A key signature consists of a key type, public key, signer address, transaction hash, signature, and metadata. A key signature produces an authority signature once the signer's conditions have been met, such as the acceptance threshold.

Transactions

A transaction is a message from the user or produced by some other message that updates the state of an account or accounts. A transaction is executed if and only if every relevant authority has accepted the transaction. A transaction may produce one more more additional transactions if it needs to interact with additional domains.

Authority signatures

An authority signature is a message from an authority saying that the authority accepts or rejects a transaction. It is sent as soon as the conditions of the authority and any of its signers are met.

Delegated signatures

A delegated signature is a type of key signature used when a signer has delegated its authority to another signer. A delegated signature must contain a key signature.

Synthetic messages

When a message is produced by another message, such as a transaction producing a transaction or a key signature producing an authority signature, the produced message is called 'synthetic' because it is produced by the protocol instead of by the user. Synthetic messages do not require normal signatures - instead the protocol must be able to prove that they were produced by another message.

Validator signatures

A validator signature is a special type of key signature produced by core protocol validators where the signer is the network itself instead of an account. Validator signatures are used to prevent malicious parties from submitting bogus synthetic messages, and they are used to validate anchors sent between partitions.

Accumulate supports a standards-compliant JSON-RPC implementation. For example:

curl https://mainnet.accumulatenetwork.io/v3 -X POST --data-raw '
{
  "jsonrpc": "2.0",
  "method": "query",
  "params": {
    "scope": "ACME"
  },
  "id":1
}'

# Result:
# {
#   "jsonrpc": "2.0",
#   "result": {
#     "recordType": "account",
#     "account": {
#       "type": "tokenIssuer",
#       "url": "acc://ACME",
#       "authorities": [
#         {
#           "url": "acc://dn.acme/operators",
#           "disabled": true
#         },
#         {
#           "url": "acc://staking.acme/book"
#         }
#       ],
#       "symbol": "ACME",
#       "precision": 8,
#       "issued": "24452643448428198",
#       "supplyLimit": "50000000000000000"
#     },
#     "pending": {
#       "recordType": "range",
#       "records": [
#         {
#           "recordType": "txID",
#           "value": "acc://d0049b680a8acf4636e62eb46a973fc7efb0d913af0e34b06fce614d5bda495f@acme"
#         }
#       ],
#       "start": 0,
#       "total": 1
#     }
#   },
#   "id": 1
# }