# Aptos SDK Specification Document

[Table of Content](#table-of-content)

![Status](https://img.shields.io/badge/version-1.0-brightgreen.svg)

## Overview

The goal of this document is to set a shared standard for implementation and development of all Aptos SDKs.

This is a living document, and should be changed and updated as changes are made when developer needs are discovered.

### Requirement Prioritization

The following document follows the [MoSCoW](https://en.wikipedia.org/wiki/MoSCoW_method) method of prioritising rules. Please follow the following guidelines when evaluating rules.

- `MUST` - Rules labeled as **must** are requirements that should not be deviated from at any cost
- `SHOULD` - Rules labeled as **should** are requirements that could be deviated from if needed, though this will have to be documented and cleared with all stakeholders before it can be disregarded.
- `COULD` - Rules labeled as **could** are requirements that are desirable but not necessary and therefore would be nice to have where time and resources permit.

We do not use the fourth **`won't`** level in this specification.

## Table of Contents

- Base Requirements
  - [1. BCS Encoding & Decoding](#1-BCS-Encoding--Decoding)
  - [2. API servers](#2-API-servers)
  - [3. Account Management](#3-Account-Management)
  - [4. Transaction](#4-Transaction)
  - [5. Coin Management](#5-Coin-Management)
- Maintenance Requirements
  - [6. Source Control](#6-source-control)
  - [7. Releases & Versioning](#7-releases--versioning)
  - [8. CI Server](#8-ci-server)
- Additional Content Requirements
  - [9. Documentation](#9-documentation)
- Dependencies & Infrastructure Requirements
  - [10. Testing](#10-testing)
  - [11. Dependencies](#11-dependencies)
  - [12. HTTP Client](#12-http-client)
  - [13. Logging](#13-reporting)
  - [14. Reporting](#14-reporting)
- Initialization & Interaction Requirements
  - [15. Initialization](#15-initalization)
  - [16. Error Handling](#16-error-handling)

## Base Requirements

### 1. BCS Encoding & Decoding

- [ ] **1.1** The SDK **must** support BCS encoding & decoding for.
  - [ ] **1.1.1** Unsigned integers u8, u32, u64, u128, u256.
  - [ ] **1.1.2** Optional arguments.
  - [ ] **1.1.3** Tuples.
  - [ ] **1.1.4** Enums.
  - [ ] **1.1.5** UTF-8 Strings as vector of u8.
  - [ ] **1.1.6** Structs.
  - [ ] **1.1.7** Vectors using uleb128.
  - [ ] **1.1.8** Addresses as a fixed 32 byte type.
  - [ ] **1.1.9** Generics.
  - [ ] **1.1.10** bool.
  - [ ] **1.1.11** Object<T> encodings as an address.
- [ ] **1.2** The encoding & decoding details **should** be hidden from the end user and done by the SDK.
  - [ ] **1.2.1** The SDK **must** encode each piece in order.
  - [ ] **1.2.2** The SDK **should** encode based on a given struct.

### 2. API servers

- [ ] **2.1** The SDK **must** interact directly with the Aptos REST API.
  - [ ] **2.1.1** The SDK **must** support pagination with optional `start` and `limit` parameters to the REST API request.
  - [ ] **2.1.2** The SDK **should** implement a client that adheres to the OpenAPI spec https://fullnode.mainnet.aptoslabs.com/v1/spec#/.
- [ ] **2.2** The SDK **should** interact directly with the Aptos Indexer API.
  - [ ] **2.2.1** The SDK **must** support pagination with optional `offset` and `limit` parameters to Indexer API request.
  - [ ] **2.2.2** The SDK **must** validate the account address when interacting with the Indexer API.
    - [ ] **2.2.2.1** The SDK **must** validate an account address is a 64 character hex string with a leading `0x`.
  - [ ] **2.2.3** The SDK **must** handle premade GraphQL queries https://cloud.hasura.io/public/graphiql?endpoint=https://api.mainnet.aptoslabs.com/v1/graphql.
  - [ ] **2.2.3** The SDK **should** allow the user to pass in a custom GraphQL query.
- [ ] **2.3** The SDK **should** support interactions with Aptos devnet, testnet and mainnet networks.
- [ ] **2.4** The SDK **should** support interactions with a custom URL.

### 3. Account Management

- [ ] **3.1** The SDK **must** support account creation.
- [ ] **3.2** The SDK **must** support account APT coin balance read.
- [ ] **3.3** The SDK **must** support key management for Ed25519 keys.
  - [ ] **3.3.1** The SDK **must** support Key generation
  - [ ] **3.3.2** The SDK **must** support Key loading from a file
  - [ ] **3.3.3** The SDK **must** support Key loading from a byte array
  - [ ] **3.3.4** The SDK **should** support Key rotation
  - [ ] **3.3.5** The SDK **could** Key management via local storage
  - [ ] **3.3.6** The SDK **could** Key management via hardware wallet (e.g. Ledger, Keystone, etc.)
- [ ] **3.4** The SDK **must** support local single-threaded sequence number management.
  - [ ] **3.4.1** The SDK **should** support multi-account sequence number management
  - [ ] **3.4.2** The SDK **should** support single threaded sequence number high throughput smart queuing
- [ ] **3.5** The SDK **must** provide multi-agent signer support.
- [ ] **3.6** The SDK **should** support account any coin balance read.
- [ ] **3.7** The SDK **should** provide multi-Ed25519 signer support.
- [ ] **3.8** The SDK **should** provide mnemonic support.
- [ ] **3.9** The SDK **should** provide onchain multi-sig support.
- [ ] **3.10** The SDK **should** provide resource account support.
- [ ] **3.10** The SDK **should** provide Object support for deriving known objects and object ownership.

### 4. Transaction

- [ ] **4.1** The SDK **must** support entry function payload transaction submission.
- [ ] **4.2** The SDK **must** support script payload transaction submission.
- [ ] **4.3** The SDK **must** support simulation of transactions.
- [ ] **4.4** The SDK **must** support view function payload.
- [ ] **4.5** The SDK **should** use the gas estimation API to determine the gas price when building transaction payloads.
  - [ ] **4.5.1** The SDK **must** cache the response from the gas estimation API for a set period of time (e.g. 1 minute).

### 5. Coin Management

- [ ] **5.1** The SDK **must** support APT coin transfer.
- [ ] **5.1** The SDK **should** support other coin transfer.

## Maintenance Requirements

### 6. Source Control

- [ ] **6.1** The source code for the SDK **must** be maintained within Git version control.
- [ ] **6.2** The source code **must** be hosted publicly.
- [ ] **6.3** Development of new features **should** happen on feature branches.
- [ ] **6.4** Feature branches **should** pass all tests and linting before they can be merged into the `main` branch.
- [ ] **6.5** Source control **should** contain tags for each release of the SDK.
- [ ] **6.6** The `main` branch **should** be kept in a condition that allows for direct use through checkout.
- [ ] **6.7** The source code **should** use GitHub for public hosting.

### 7. Releases & Versioning

- [ ] **7.1** The SDK **must** use [Semantic Versioning](http://semver.org/) to increment the version number as changes are made.
- [ ] **7.2** For every new release the `CHANGELOG` file **must** to be updated with the `Major`, `Minor` and `Patch` changes.
- [ ] **7.3** A release package **must** include the documentation `README` file.
- [ ] **7.4** A release package **must** include the `LICENSE` file.
- [ ] **7.5** A release package **must** include the `CHANGELOG` file.

- [ ] **7.6** A release package **should** not include unnecessary source code files or intermediary files for the SDK.

- [ ] **7.7** The name of the SDK **should** follow language best practices, and be one of `aptos` or `Aptos`.
- [ ] **7.8** If the preferred name of the SDK is not available, it **could** be one of `aptos-sdk`, `AptosSDK`, or `aptosdev`.
- [ ] **7.9** As soon as the first public version of the library has been signed off, the version **should** be bumped to `1.0.0`.
- [ ] **7.10** New releases **could** be deployed automatically to the package manager using the CI server.

### 8. CI Server

- [ ] **8.1** A Continuous Integration (CI) server **must** be used to automatically test any branch of the Git repository.
- [ ] **8.2** The CI server **could** test on different platforms, including Windows, Linux, and macOS.
- [ ] **8.3** The CI server **could** test new Git tags, and build and push the package to the package manager.

## Content Requirements

### 9. Documentation

- [ ] **9.1** The SDK **must** include a `README` file.

  - [ ] **9.1.1** The `README` file **must** have instructions on how to install the SDK using a package manager.
  - [ ] **9.1.2** The `README` file **must** link to the `LICENSE` file.
  - [ ] **9.1.3** The `README` file **must** document any installation requirements and prerequisites.
  - [ ] **9.1.4** The `README` file **should** be written in Markdown.
  - [ ] **9.1.5** The `README` file **should** include a version badge.
  - [ ] **9.1.6** The `README` file **should** include a test status badge.
  - [ ] **9.1.7** The `README` file **should** document all the different ways the SDK can be initialized.
  - [ ] **9.1.8** The `README` file **should** include official support channels.
  - [ ] **9.1.9** The `README` file **could** have instructions on how to install the SDK from version control.

- [ ] **9.2** The SDK **must** include a `CHANGELOG` file.
- [ ] **9.3** The SDK **must** include a `CODE_OF_CONDUCT` file.
- [ ] **9.4** The SDK **must** include a `CONTRIBUTING` file.
  - [ ] **9.4.1** The Contribution Guidelines **should** include instructions on how to run the SDK in development/testing mode.
- [ ] **9.5** The SDK **should** include a `ISSUE_TEMPLATE` file.
- [ ] **9.6** The SDK **should** include a `PULL_REQUEST_TEMPLATE` file.
- [ ] **9.7** The SDK **should** include a `SUPPORT` file.
- [ ] **9.8** The GitHub repository **should** have a title in the format, e.g. "Typescript library for the Aptos network"
- [ ] **9.9** The GitHub repository **should** have the following tags: `aptos`, `blockchain`, `web3`, `sdk`, `library`.

## Dependencies & Infrastructure Requirements

### 10. Testing

- [ ] **10.1** The SDK **must** be thoroughly tested.
- [ ] **10.2** For any real API calls, the tests **must** use the Aptos testnet or devnet network.
- [ ] **10.3** The tests **should** have integration tests to make the network calls.
- [ ] **10.4** The tests **should** test responses.

### 11. Dependencies

- [ ] **11.1** The SDK **must** limit its runtime dependencies.
- [ ] **11.2** The SDK **should** have no runtime dependencies.
- [ ] **11.3** The SDK **could** use any amount of development and test dependencies.

### 12. HTTP Client

- [ ] **12.1** The SDK **must** use a well supported HTTP client.
- [ ] **12.2** The SDK **should** use a HTTP2 supported client.
- [ ] **12.3** A HTTP client from the standard libraries **should** be used.
- [ ] **12.4** The SDK **could** allow a developer to provide an alternative HTTP client.

### 13. Logging

- [ ] **13.1** The SDK **must** be able to log activities to a logger.
- [ ] **13.2** The logger **must** allow enabling/disabling of debug mode.
- [ ] **13.3** The logger **should** use the default runtime log.
- [ ] **13.4** The logger **should** allow a developer to provide an alternative logger.
- [ ] **13.5** When debugging is enabled, the logger **should** log (and only log) the request object, response object, and optionally any raw HTTP response object of no response object could be formed.

### 14. Reporting

- [ ] **14.1** The SDK **should** pass a custom header `x-aptos-client` with the format `<sdk-id>/<sdk-version>`.
  - Example with known sdk version: `aptos-ts-sdk/1.8.4`

## Initialization & Interaction Requirements

### 15. Initialization

- [ ] **15.1** The SDK client **must** allow selection of the base URL by name (`devnet` , `tesnet` , `mainnet`).
- [ ] **15.2** The SDK client **must** allow for setting a custom base URL directly (e.g `http://localhost:8080`).

### 16. Error Handling

- [ ] **16.1** The SDK **should** raise a `ApiError` for any request that did not result a HTTP 200 or 201 response code.
- [ ] **16.4** The response error object **should** contain a `message` attribute containing the message of the error, e.g. `account_not_found`.
- [ ] **16.5** The response error object **should** contain a `error_code` attribute containing the error code, e.g. `404`.
- [ ] **16.5** The response error object **should** contain a `vm_error_code` attribute containing the vm error code, e.g. `0`.
