Typescript SDK Architecture
This document describes the main features and components of the Aptos Typescript SDK.
The Aptos Typescript SDK provides APIs and interfaces you can use to interact with the Aptos blockchain by connecting to the Aptos REST API. The REST API is the means for sending your transaction to the Aptos blockchain and reading the blockchain's state.
See below a high-level architecture diagram of the Aptos Typescript SDK.
Key SDK features
The following are a few key features of the Aptos SDK:
- Key generation: The Aptos SDK provides convenient methods for generating Ed25519 key pairs. The Ed25519 public keys can be used to derive the chain account addresses, while the private keys should be kept private for transaction signing. See the class TransactionBuilderEd25519.
- Transaction signing and submission: Although the Aptos REST APIs support signing a raw transaction on the server-side, signing the transactions on the client side, using the Aptos SDK, is more secure and should be the preferred choice.
- Transaction status querying: The Aptos SDK supports transaction status queries (success, failure, pending), by transaction hash.
- BCS library: The Aptos SDK implements a BCS (Binary Canonical Serialization) library for transaction signing and submission. The Aptos blockchain uses BCS for data serialization and deserialization. See Aptos SDK BCS.
- Methods for information retrieval: Resources, modules, and transactions under a specific account can be retrieved with the Aptos SDK.
- Faucet client: The Aptos FaucetClient is for minting test coins that are used for development.
- Token client: Aptos SDK provides built-in support for NFT minting and querying. See TokenClient.
Components of the Typescript SDK
The Aptos Typescript SDK has three logical layers. Refer to the above high-level architecture diagram:
- The transport layer.
- The core SDK layer.
- An optional application layer.
The transportation layer is responsible for sending payloads to the REST API endpoints.
The core SDK layer exposes the functionalities needed by most applications, including:
- The key generation.
- Transaction signing and submission.
- Transaction status querying, and
- Various kinds of information retrieval.
The optional application layer provides built-in support for NFT token API.
You can also use this TokenClient API as an example of NFT token API before you start developing your own application APIs using the SDK.
The OpenAPI client is a set of classes that are generated based on the Aptos REST API spec. See the Typescript SDK OpenAPI definition.
The class AptosAccount has a constructor that creates a new account instance or retrieves an existing account instance; in addition, this class provides the methods for:
- Generating Ed25519 key pairs.
- Signing a bytes buffer with an Ed25519 public key, and
- Deriving initial account addresses from the public keys.
- Retrieving a resource account address by source address and seeds
- Derives account address, public key and private key
A subset of BCS standards implemented in Typescript.
The TS SDK exposes five transaction builder classes:
- TransactionBuilder that takes in a Signing Message (serialized raw transaction) and returns a signature.
- TransactionBuilderEd25519 extends the TransactionBuilder class and provides a signing method for raw transactions with a single public key.
- TransactionBuilderMultiEd25519 extends the TransactionBuilder class and provides a signing method for signing a raw transaction with a multisig public key.
- TransactionBuilderABI builds raw transactions based on ABI.
- TransactionBuilderRemoteABI downloads JSON ABIs from the fullnodes. It then translates the JSON ABIs to the format that is accepted by TransactionBuilderABI.
The transaction builder contains the Typescript types for constructing the transaction payloads. The transaction builder within the Typescript SDK supports the following transaction payloads:
The class AptosClient exposes the methods for retrieving the account resources, transactions, modules and events.
In addition, the
AptosClient component supports submitting transactions in BCS format, which prepares and signs the raw transactions on the client-side. This method leverages the BCS Library and Transaction Builder for constructing the transaction payloads. See the guide Creating a Signed Transaction.
The class TokenClient provides methods for creating and querying the NFT collections and tokens. It covers (1) write methods that support creating, transferring, mutating and burning tokens on-chain and (2) read methods performing deserialization and returning data in TS objects.
The main write methods supported by the token SDK are:
- Create Collection
- Create Token
- Offer Token
- Claim Token
- Directly Transfer Token
- Transfer Token with Opt-in
- Mutate Token Properties
- Burn Token by Owner or Creator
The main read methods deserializing on-chain data to TS objects are:
- Get CollectionData
- Get TokenData
- Get Token of an Account
Validation for the Transaction Builder and BCS
The BCS is used to assemble and serialize the transaction payloads for signing and submission.
Given that different programming languages have different primitive type constraints (e.g., byte length, value range, etc.) and various composite types support (e.g., enum, struct, class, etc.), the code for data serialization is hard to validate.
The Aptos SDK validates the Transaction Builder and BCS in two ways:
- First, with the unit tests and end-to-end (e2e) tests.
- The second level of validation is fuzzing tests with test vectors. The test vectors are produced by the same code used by the Aptos blockchain. The test vectors are arrays of JSON objects. Each JSON object contains randomized inputs and the expected outputs. These test vectors can be parsed and loaded by Aptos SDKs to validate their implementations of Transaction Builder and BCS.
There are a total of three test vectors. Each covers one type of transaction payload.
Vector items are self-explanatory. However, special serialization method is used to save space and avoid data overflow. Details are described below:
- All account address are hex-coded.
argsin EntryFunction is hex-coded.
- U64 and U128 numbers are serialized as string literals to avoid data truncation.
- U8 is serialized as a number (not a string).
codein Script and ModuleBundle are hex-coded.
See this code example for how Typescript SDK does vector validation.