Aptos Sign and Verify Message

{connected ? (

Connected to: {account?.address}

setMessage(e.target.value)}                placeholder="Enter your message here"                className="border rounded p-2"              />              <input                type="text"                value={nonce}                onChange={(e) => setNonce(e.target.value)}                placeholder="Enter nonce (random string) here"                className="border rounded p-2 mt-2"              />              <button onClick={handleSignMessage} className="bg-blue-500 text-white rounded p-2 mt-2">                Sign Message              </button>              {signedMessage && (                <div>                  <h4>Signed Message</h4>                  <pre>{JSON.stringify(signedMessage, null, 2)}</pre>                  <button onClick={handleVerifyMessage} className="bg-green-500 text-white rounded p-2 mt-2">                    Verify Message                  </button>                </div>              )}              {verificationResult !== null && (                <div>                  <h4>Verification Result</h4>                  <p>{verificationResult ? 'Message is verified!' : 'Failed to verify message.'}</p>                </div>              )}              {error && (                <div className="text-red-600">                  <p>{error}</p>                </div>              )}            </div>          </div>        ) : (          <p>Please connect your wallet to sign and verify messages.</p>        )}      </div>    </div>  );};
export default SignMessageDemo;
```

{signedMessage && (

#### Signed Message

{JSON.stringify(signedMessage, null, 2)}

)} {verificationResult !== null && (

#### Verification Result

{verificationResult ? 'Message is verified!' : 'Failed to verify message.'}

)} {error && (

{error}

)}

) : (

Please connect your wallet to sign and verify messages.

)}   );};export default SignMessageDemo;">

### `changeNetwork` (Not supported by all wallets)

[](#changenetwork-not-supported-by-all-wallets)

Some wallets only support mainnet, so they will not support `changeNetwork`. If you are relying on this feature, ensure that you implement error handling for if a wallet that does not support `changeNetwork`. [Nightly](https://chromewebstore.google.com/detail/nightly/fiikommddbeccaoicoejoniammnalkfa?hl=en) is an example of a wallet which **does** support `changeNetwork`.

```
import React from 'react';import { useWallet } from '@aptos-labs/wallet-adapter-react';import { Network } from '@aptos-labs/ts-sdk';
const ChangeNetworkDemo = () => {  const { network, changeNetwork, wallet } = useWallet();  const isNetworkChangeSupported = wallet?.name === "Nightly";
  const isValidNetworkName = () => {    return network && Object.values<string>(Network).includes(network.name);  };
  return (    <div>      <h4>Network Info</h4>      <div>        <div><strong>Network name</strong></div>        <div>          <span style={{ color: isValidNetworkName() ? 'green' : 'red' }}>            {network?.name ?? 'Not Present'}          </span>          {` (Expected: ${Object.values<string>(Network).join(', ')})`}        </div>        <div><strong>URL</strong></div>        <div>          {network?.url ? (            <a href={network.url} target="_blank" rel="noreferrer">              {network.url}            </a>          ) : (            'Not Present'          )}        </div>        <div><strong>Chain ID</strong></div>        <div>{network?.chainId ?? 'Not Present'}</div>      </div>      <div>        <h4>Change Network</h4>        <div>          <label>            <input              type="radio"              name="network"              value={Network.DEVNET}              checked={network?.name === Network.DEVNET}              onChange={() => changeNetwork(Network.DEVNET)}              disabled={!isNetworkChangeSupported}            />            Devnet          </label>          <label>            <input              type="radio"              name="network"              value={Network.TESTNET}              checked={network?.name === Network.TESTNET}              onChange={() => changeNetwork(Network.TESTNET)}              disabled={!isNetworkChangeSupported}            />            Testnet          </label>          <label>            <input              type="radio"              name="network"              value={Network.MAINNET}              checked={network?.name === Network.MAINNET}              onChange={() => changeNetwork(Network.MAINNET)}              disabled={!isNetworkChangeSupported}            />            Mainnet          </label>        </div>        {!isNetworkChangeSupported && (          <div>            * {wallet?.name ?? 'This wallet'} does not support network change requests          </div>        )}      </div>    </div>  );};
export default ChangeNetworkDemo;
```

### `signAndSubmitBCSTransaction(payload)` (Not supported by all wallets)

[](#signandsubmitbcstransactionpayload-not-supported-by-all-wallets)

Caution

This feature is not part of the AIP-62 standard, so it will not be supported by all Wallets. Verify with error handling before calling it.

This is similar to the `signAndSubmit` logic, but uses a BCS format for the transaction `data`.

```
const onSignAndSubmitBCSTransaction = async () => {  const response = await signAndSubmitTransaction({    sender: account.address,    data: {      function: "0x1::aptos_account::transfer",      functionArguments: [AccountAddress.from(account.address), new U64(1)],    },  });  // if you want to wait for transaction  try {    await aptos.waitForTransaction({ transactionHash: response.hash });  } catch (error) {    console.error(error);  }};
<button onClick={onSignAndSubmitTransaction}>  Sign and submit BCS transaction</button>;
```

;">

## Mobile support

[](#mobile-support)

Since Chrome extensions are not supported in mobile browsers by default, the adapter maintains a `registry` of undetected wallets, including a `deeplinkProvider` property for wallets that support deep linking. This allows the dapp to display wallets that aren’t detectable in a mobile browser view but can still be connected to by redirecting the user to an in-app browser view.

```
{  name: "Petra",  url: "https://chromewebstore.google.com/detail/petra-aptos-wallet/ejjladinnckdgjemekebdpeokbikhfci?hl=en",  icon: "data:image/png;base64,iVBOR...QmCC",  readyState: WalletReadyState.NotDetected,  isAIP62Standard: true,  deeplinkProvider: "https://petra.app/explore?link=",}
```

To render wallets with `deeplinkProvider` support in your dapp—assuming you're not using the official adapter wallet selector UI—follow these steps:

1.  Retrieve all compatible wallets and group them by wallet type
    
    ```
    import { useWallet, groupAndSortWallets } from '@aptos-labs/wallet-adapter-react';
    const displayAllWalletsDemo = () => {
      const { wallets = [], notDetectedWallets = [] } = useWallet();
      const { aptosConnectWallets, availableWallets, installableWallets } =    groupAndSortWallets(      [...wallets, ...notDetectedWallets]    );
      return (    <div>      /** Wallets that use social login to create an account on the blockchain */      {aptosConnectWallets.map((aptosConnectwallet) => (        <WalletItemComponent wallet={aptosConnectwallet}/>      ))}      /** Wallets that are currently installed or loadable. */      {availableWallets.map((availableWallet) => (        <WalletItemComponent wallet={availableWallets}/>      ))}      /** Wallets that are NOT currently installed or loadable. */      {installableWallets.map((installableWallet) => (        <WalletItemComponent wallet={installableWallets}/>      ))}    </div>  )}
    ```
    
    This code snippet retrieves all wallets in the Aptos ecosystem that are supported by the wallet adapter.
    
2.  Display uninstalled wallets with deep link support in mobile view.
    
    To ensure we display only wallets that support deep linking on mobile, we can check both for `deepLinkProvider` support and the current view type.
    
    In the component that renders each wallet:
    
    ```
    import { useWallet, WalletReadyState } from '@aptos-labs/wallet-adapter-react';
    const WalletItemComponent = (wallet) => {
      const { connect } = useWallet();
      // On mobile, extension wallets will never have a state of `Installed`  const isWalletReady = wallet.readyState === WalletReadyState.Installed;
      // Check if the wallet supports mobile deep linking.  const mobileSupport =    "deeplinkProvider" in wallet && wallet.deeplinkProvider;
      // If the wallet is not installed, the user is in a redirectable view (i.e., mobile browser but not an in-app browser),  // and the wallet does not support deep linking—do not display the wallet.  if (!isWalletReady && isRedirectable() && !mobileSupport) return null;
      // Otherwise, display the wallet  return (    <Button onClick={connect(wallet)}>{wallet.name}</Button>  )}
    ```
    
     )}">
    
    This code snippet ensures that the correct `wallet` object is displayed in the appropriate view.

# Aptos Wallet Standard

> Guidelines for wallet interoperability ensuring consistent dapp integration across all Aptos wallet types

Legacy wallet APIs have been removed

Direct wallet access via browser globals (such as `window.aptos` or `window.petra`) has been **removed**. These legacy APIs are no longer available in modern wallet versions (e.g. Petra has fully removed them). All dapps must use the [Aptos Wallet Adapter](/build/sdks/wallet-adapter/dapp) with the [AIP-62](https://github.com/aptos-foundation/AIPs/blob/main/aips/aip-62.md) standard for wallet integration.

The wallet standard provides guidelines for interoperability between wallet types. This ensures dapp developers do not need to change their applications to handle different wallets. This standard offers a single interface for all dapp developers, allowing easy additions of new wallets and more users to each application. This interoperability allows users to choose which wallet they want without worrying about whether apps support their use cases.

In order to ensure interoperability across Aptos wallets, the following is required:

1.  Mnemonics - a set of words that can be used to derive account private keys
2.  dapp API - entry points into the wallet to support access to identity managed by the wallet
3.  Key rotation - the feature handling both the relationship around mnemonics and the recovery of accounts in different wallets

## Mnemonics phrases

[](#mnemonics-phrases)

A mnemonic phrase is a multiple word phrase that can be used to generate account addresses. We recommend one mnemonic per account in order to handle key rotation better. However, some wallets may want to support one mnemonic to many accounts coming from other chains. To support both of these use cases, the Aptos wallet standard uses a [Bitcoin Improvement Proposal (BIP44)](https://github.com/bitcoin/bips/blob/master/bip-0044.mediawiki) to derive path for mnemonics to accounts.

### Creating an Aptos account

[](#creating-an-aptos-account)

Aptos account creation can be supported across wallets in the following manner:

1.  Generate a mnemonic phrase, for example with BIP39.
2.  Get the master seed from that mnemonic phrase.
3.  Use the BIP44-derived path to retrieve an account address (e.g. `m/44'/637'/0'/0'/0'`)

*   See the [Aptos TypeScript SDK's implementation for the derive path](https://github.com/aptos-labs/aptos-ts-sdk/blob/main/src/account/Account.ts#L181-L202)
*   For example, Petra Wallet always uses the path `m/44'/637'/0'/0'/0'` since there is one mnemonic per one account.

```
/**  * Creates new account with bip44 path and mnemonics,  * @param path. (e.g. m/44'/637'/0'/0'/0')  * Detailed description: {@link https://github.com/bitcoin/bips/blob/master/bip-0044.mediawiki}  * @param mnemonics.  * @returns AptosAccount  */  static fromDerivePath(path: string, mnemonics: string): AptosAccount {   if (!AptosAccount.isValidPath(path)) {     throw new Error("Invalid derivation path");   }
   const normalizeMnemonics = mnemonics     .trim()     .split(/\s+/)     .map((part) => part.toLowerCase())     .join(" ");
   const { key } = derivePath(path, bytesToHex(bip39.mnemonicToSeedSync(normalizeMnemonics)));
   return new AptosAccount(new Uint8Array(key));}
```

### Supporting one mnemonic per multiple account wallets

[](#supporting-one-mnemonic-per-multiple-account-wallets)

This is not recommended because the one-mnemonic-to-many-accounts paradigm makes it harder to handle rotated keys (the mnemonic changes for one account but not others). However, many wallets from other ecosystems use this paradigm, and take these steps to generate accounts

1.  Generate a mnemonic phrase, for example with BIP39.
2.  Get the master seed from that mnemonic phrase.
3.  Use the BIP44-derived path to retrieve private keys (e.g. `m/44'/637'/i'/0'/0'`) where `i` is the account index.

*   See the [Aptos TypeScript SDK's implementation for the derive path](https://github.com/aptos-labs/aptos-core/blob/1bc5fd1f5eeaebd2ef291ac741c0f5d6f75ddaef/ecosystem/typescript/sdk/src/aptos_account.ts#L49-L69)

4.  Increase `i` until all the accounts the user wants to import are found.

*   Note: The iteration should be limited, if an account doesn't exist during iteration, keep iterating for a constant `address_gap_limit` (10 for now) to see if there are any other accounts. If an account is found we will continue to iterate as normal.

i.e.

```
const gapLimit = 10;let currentGap = 0;
for (let i = 0; currentGap < gapLimit; i += 1) {  const derivationPath = `m/44'/637'/${i}'/0'/0'`;  const account = fromDerivePath(derivationPath, mnemonic);  const response = account.getResources();  if (response.status !== 404) {    wallet.addAccount(account);    currentGap = 0;  } else {    currentGap += 1;  }}
```

## Wallet and dapp communication

[](#wallet-and-dapp-communication)

More important than account creation, is how wallets and dapps communicate.

[Following AIP-62](https://github.com/aptos-foundation/AIPs/blob/main/aips/aip-62.md), the Wallet standard defines an API for wallet and application interactions.

### Wallet Interface Standard

[](#wallet-interface-standard)

A wallet must implement a [AptosWallet interface](https://github.com/aptos-labs/wallet-standard/blob/main/src/wallet.ts) with the wallet provider info and features:

```
class MyWallet implements AptosWallet {  url: string;  version: "1.0.0";  name: string;  icon:    | `data:image/svg+xml;base64,${string}`    | `data:image/webp;base64,${string}`    | `data:image/png;base64,${string}`    | `data:image/gif;base64,${string}`;  chains: AptosChain;  features: AptosFeatures;  accounts: readonly AptosWalletAccount[];}
```

A wallet must implement a [AptosWalletAccount interface](https://github.com/aptos-labs/wallet-standard/blob/main/src/account.ts) that represents the accounts that have been authorized by the dapp.

```
enum AptosAccountVariant {  Ed25519,  MultiEd25519,  SingleKey,  MultiKey,}
class AptosWalletAccount implements WalletAccount {  address: string;
  publicKey: Uint8Array;
  chains: AptosChain;
  features: AptosFeatures;
  variant: AptosAccountVariant;
  label?: string;
  icon?:    | `data:image/svg+xml;base64,${string}`    | `data:image/webp;base64,${string}`    | `data:image/png;base64,${string}`    | `data:image/gif;base64,${string}`    | undefined;}
```

If the wallet is a web extension wallet (i.e installed through the chrome extension store), the wallet must register itself using the [registerWallet](https://github.com/wallet-standard/wallet-standard/blob/master/packages/core/wallet/src/register.ts#L25) method to notify the dapp it is ready to be used.

```
const myWallet = new MyWallet();
registerWallet(myWallet);
```

A wallet is considered a valid Aptos wallet if it implements the standard [required features](https://github.com/aptos-labs/wallet-standard/blob/main/src/detect.ts#L16).

A wallet must throw a [AptosWalletError](https://github.com/aptos-labs/wallet-standard/blob/main/src/errors.ts). The standard requires to support `Unauthorized` and `InternalError` but a wallet can throw a custom `AptosWalletError` error

```
// Using the default messageif (error) {  throw new AptosWalletError(AptosWalletErrorCode.Unauthorized);}// Using a custom messageif (error) {  throw new AptosWalletError(    AptosWalletErrorCode.Unauthorized,    "My custom unauthorized message"  );}// Using a custom errorif (error) {  throw new AptosWalletError(-32000, "Invalid Input");}
```

### Dapp API

[](#dapp-api)

Note

For a dapp to easily integrate with a wallet, it encouraged to use the [Aptos Wallet Adapter Standard](/build/sdks/wallet-adapter).

If for some reason, a dapp decides to implement a custom wallet integration:

A dapp uses the [getAptosWallets()](https://github.com/aptos-labs/wallet-standard/blob/main/src/detect.ts#L40) function which gets all the Aptos standard compatible wallets.

```
import { getAptosWallets } from "@aptos-labs/wallet-standard";
let { aptosWallets, on } = getAptosWallets();
```

On first load, and before the dapp has been loaded, it gets all the wallets that have been registered so far. To keep getting all the registered wallets after this point, the dapp must add an event listener for new wallets that get registered receiving an unsubscribe function, which it can later use to remove the listener.

```
const removeRegisterListener = on("register", function () {  // The dapp can add new aptos wallets to its own state context as they are registered  let { aptosWallets } = getAptosWallets();});
const removeUnregisterListener = on("unregister", function () {  let { aptosWallets } = getAptosWallets();});
```

The dapp has an event listener now, so it sees new wallets immediately and doesn't need to poll or list them again. This also works if the dapp loads before any wallets (it will initialize, see no wallets, then see wallets as they load)

A dapp makes a wallet request by calling the feature name that corresponds to the desired action. For example, to use the `connect` feature:

```
const onConnect = () => {  this.wallet.features["aptos:connect"].connect();};
```

## Key rotation

[](#key-rotation)

Key rotation is currently not implemented in any wallets. Mapping of rotated keys has been [implemented](https://github.com/aptos-labs/aptos-core/pull/2972), but SDK integration is in progress.

Wallets that import a private key will have to do the following:

1.  Derive the authentication key.
2.  Lookup the authentication key on-chain in the Account origination table.

*   If the account doesn't exist, it's a new account. The address to be used is the authentication key.
*   If the account does exist, it's a rotated key account, and the address to be used will come from the table.

# Wallet Adapter Plugin for SDK Wallet Builders

> Create wallet adapter plugins for SDK wallets to enable dapp integration through the AIP-62 wallet standard

A wallet adapter plugin allows dapps to use your wallet. With the AIP-62 Wallet standard, dapps can simply update their version of `aptos-wallet-adapter` to connect to newly added Wallet plugins.

Implementing a wallet plugin for an SDK wallet which can be imported via npm has three main steps:

1.  Implement a wallet adapter plugin for your SDK wallet.
2.  Publish your plugin on npm.
3.  Update the `aptos-wallet-adapter` package to let dapps know about your wallet.

## 1\. Implement the Wallet Adapter Plugin.

[](#1-implement-the-wallet-adapter-plugin)

You can use the [`wallet-standard`](https://github.com/aptos-labs/wallet-standard) repo’s example to implement an [AIP-62](https://github.com/aptos-foundation/AIPs/blob/main/aips/aip-62.md) compatible wallet adapter plugin that dapps can automatically recognize.

Note

For an example of how to implement the Wallet Adapter plugin, see the [Wallet Adapter Demo dapp](https://github.com/aptos-labs/aptos-wallet-adapter/tree/main/apps/nextjs-example). Specifically, [`standardWallet.ts`](https://github.com/aptos-labs/aptos-wallet-adapter/blob/main/apps/nextjs-example/src/utils/standardWallet.ts) contains the plugin implementation, and [`page.tsx`](https://github.com/aptos-labs/aptos-wallet-adapter/blob/main/apps/nextjs-example/src/app/page.tsx) has the React components.

1.  Create a new typescript repository.
    
2.  Copy the into that new repo.
    
3.  Follow the instructions in that example to make it use your wallet to execute the AIP-62 functions.
    
    Note
    
    The full list of required functions for AIP-62 compatible wallets can be found [here](https://github.com/aptos-labs/wallet-standard/blob/38defe159b8641ff1763c4db61827c78ab448dab/src/detect.ts#L16).

## Test your changes by:

[](#test-your-changes-by)

1.  Clone the repository.
    
2.  Navigate to in the example dapp.
    
3.  Replace with your implementation of the AIP-62 standard.
    
    1.  You will have to update the import in [`aptos-wallet-adapter/apps/nextjs-example/src/app/page.tsx`](https://github.com/aptos-labs/aptos-wallet-adapter/blob/main/apps/nextjs-example/src/app/page.tsx) to use your Wallet instead of `MyWallet`.
    2.  For local testing purposes, you can leave the `registerWallet` code, but SDK wallets do not need that once they have been added to the `aptos-wallet-standard` core package.
4.  Run a local version of the dapp by following the instructions in the .
    
5.  Click “Connect a Wallet”
    
    You should see your wallet on the list of connections.
    
6.  Connect to your wallet.
    
    1.  You can then use the demo dapp features to verify your other wallet features work as expected.
    2.  This simulates how a real dapp will interact with your wallet.

## 2\. Once tested, publish a new npm package for your SDK wallet code by following [this guide](https://docs.npmjs.com/creating-and-publishing-scoped-public-packages). (Ex. [AptosConnect](https://www.npmjs.com/package/@aptos-connect/wallet-adapter-plugin))

[](#2-once-tested-publish-a-new-npm-package-for-your-sdk-wallet-code-by-following-this-guide-ex-aptosconnect)

## 3\. Update [`wallet-adapter-core`](https://github.com/aptos-labs/aptos-wallet-adapter/tree/main/packages/wallet-adapter-core) to know about your extension.

[](#3-update-wallet-adapter-core-to-know-about-your-extension)

In order for dapp users who are not already using your wallet to get the option to create an account with your wallet, you need to update [`wallet-adapter-core`](https://github.com/aptos-labs/aptos-wallet-adapter/tree/main/packages/wallet-adapter-core) with your browser extension’s download link.

1.  Fork the monorepo. ()
    
2.  Open your fork in a local editor such as VSCode.
    
3.  Create a new branch for your changes.
    
    ```
    git checkout -b your-wallet
    ```
    
4.  Navigate to .
    
5.  Import your SDK wallet npm package.
    
    ```
    pnpm i @yourpackage
    ```
    
6.  Import your wallet in .
    
    For example with AptosConnect:
    
    ```
    import { AptosConnectWallet } from "@aptos-connect/wallet-adapter-plugin";
    ```
    
7.  Add code to push an instance of your wallet to sdkWallets inside getSDKWallets (in sdkWallets.ts).
    
    ```
    sdkWallets.push(new YourWallet(dappConfig));
    ```
    
    Caution
    
    Some wallets may have custom logic required to make sure the right wallet is connected when the user clicks to “sign in” with your Wallet.
    
    Ex. T Wallet has different Wallet plugins for mainnet and devnet connections.
    
8.  In type.ts, update the type AvailableWallets to include your wallet’s name.
    
    ```
    export type AvailableWallets = "Nightly" | "Petra" | "T wallet" | "Your Wallet's Name";
    ```
    
9.  Update the at the top-level of the aptos-wallet-adapter to include your wallet in the list of AIP-62 compatible wallets.
    
10.  Commit and push your changes to your fork.
     
     Note
     
     If you have pushed your changes to your fork, a green button should appear at the top of the [`aptos-wallet-adapter`](https://github.com/aptos-labs/aptos-wallet-adapter) repo asking if you would like to create a pull request.
     
11.  Follow to open a pull request for the repo.
     
     Note
     
     Once the changes are merged, dapps that update their `aptos-wallet-adapter` package versions will now be able to see your Wallet.

## Resources

[](#resources)

*   Wallet Adapter Demo App
    *   [Live site](https://aptos-wallet-adapter-example.vercel.app/)
    *   [Source code](https://github.com/aptos-labs/aptos-wallet-adapter/tree/main/apps/nextjs-example)
    *   See [`standardWallet.ts`](https://github.com/aptos-labs/aptos-wallet-adapter/blob/main/apps/nextjs-example/src/utils/standardWallet.ts) for an example implementation of an AIP-62 compatible wallet-adapter plugin.
*   [`wallet-standard`](https://github.com/aptos-labs/wallet-standard) source code.
*   [`wallet-adapter-core`](https://github.com/aptos-labs/aptos-wallet-adapter/tree/main/packages/wallet-adapter-core) source code.
*   [AIP-62 standard](https://github.com/aptos-foundation/AIPs/blob/main/aips/aip-62.md).

# X-Chain Accounts

> Enable cross-chain wallet integration on Aptos using Derivable Account Abstraction for seamless multi-chain user experiences

Thanks to [AIP-113 Derivable Account Abstraction](https://github.com/aptos-foundation/AIPs/blob/main/aips/aip-113.md), we can manage x-chain signatures flexibly and securely on the Aptos network. This means that any wallet with an authentication function implementation on the Aptos chain can submit transactions to the Aptos network.

This functionality enables a variety of use cases for dApps, enhancing user experience and onboarding.

### High level flow

[](#high-level-flow)

When a user enters a dApp that supports x-chain accounts, the interaction and experience feel the same as with any Aptos wallet. The user connects with a x-chain account (e.g., Phantom for Solana) and can view their Derivable Abstracted Account (DAA) details, sign messages, and submit transactions to the Aptos chain.

When a dapp submits a transaction using a x-chain account, the wallet adapter utilizes the `signIn` function (defined in the x-chain account standard) for domain verification and security. If a specific wallet does not support the `signIn` method, the adapter falls back to using the default `signMessage`. The wallet is requested to sign a message to submit a transaction on the Aptos network. Once the wallet approves the transaction, it is submitted to the Aptos chain, where it undergoes a signature verification process.

### How does DAA work in a x-chain account?

[](#how-does-daa-work-in-a-x-chain-account)

When a user connects to a dApp using the x-chain account adapter, the adapter computes the user's Derivable Abstracted Account (DAA) address and converts the x-chain account to follow the Aptos wallet standard interface. This ensures a seamless interaction with the wallet for both developers and end users.

The computation of the DAA address is done using the `authenticationFunction` and the `accountIdentity`, both of which are defined in the wallet adapter:

*   `authenticationFunction`: This is a function that exists on-chain and is used to verify the signature of the x-chain account.
*   `accountIdentity`: This represents the identity of the account used in the on-chain authentication function to verify the signature of the x-chain account. In the Wallet Adapter, the `accountIdentity` is based on the original x-chain account's public key and the dApp domain (e.g., mydomain.com). The format is: `${originWalletAddress}${domain}`

Note

Since the account identity is based on the dApp domain, it is scoped to the dApp context. As a result, each account has a different DAA address on different dApps.

### How to integrate x-chain accounts in my dApp?

[](#how-to-integrate-x-chain-accounts-in-my-dapp)

Note

It is highly recommended to use the `@aptos-labs/wallet-adapter-react` package for the best experience. Make sure you integrate with the Aptos Wallet Adapter by following these [steps](/build/sdks/wallet-adapter/dapp)

*   [Solana](#tab-panel-87)
*   [EVM](#tab-panel-88)
*   [Sui](#tab-panel-89)

The wallet adapter follows the [Solana Wallet Standard](https://github.com/wallet-standard/wallet-standard/blob/master/DESIGN.md) to discover wallets. Currently, the wallets that have been tested and support cross-chain accounts are:

| | Aptos Devnet | Aptos Testnet | Aptos Mainnet | | -------- | ------------ | ------------- | ------------- | | Phantom | ✅ | ✅ | ✅ | | Solflare | ✅ | ✅ | ✅ | | Backpack | ✅ | ✅ | ✅ | | OKX | ✅ | ✅ | ✅ |

Caution

Ledger hardware wallets do not currently support off-chain message signing required for Solana-derived Aptos accounts. This is a known limitation of the Ledger Solana app. Users should use software wallets (Phantom, Solflare, etc.) without a hardware device connected

Supporting x-chain accounts in a dApp requires only a 2-step installation process.

1.  Install the @aptos-labs/derived-wallet-solana package
    
    ```
    npm install @aptos-labs/derived-wallet-solana
    ```
    
2.  Import the setupAutomaticSolanaWalletDerivation function
    
    Once you have installed the `@aptos-labs/derived-wallet-solana` package, you can import and use it. In the same file where you import the other wallets, such as `WalletProvider.tsx`, you can add the following:
    
    ```
    import { setupAutomaticSolanaWalletDerivation } from "@aptos-labs/derived-wallet-solana";
    setupAutomaticSolanaWalletDerivation({ defaultNetwork: Network.TESTNET }); // this is the Aptos network your dapp is working with
    ...
    <AptosWalletAdapterProvider dappConfig={{    network: Network.TESTNET,  }}>  {children}</AptosWalletAdapterProvider>
    ```
    
3.  Set crossChainWallets dapp config prop to true for the AptosWalletAdapterProvider
    
    ```
    <AptosWalletAdapterProvider dappConfig={{    network: Network.TESTNET,    crossChainWallets: true,  }}>  {children}</AptosWalletAdapterProvider>
    ```

The wallet adapter follows the [EIP-1193](https://eips.ethereum.org/EIPS/eip-1193) to discover wallets. Currently, the wallets that have been tested and support cross-chain accounts are:

| | Aptos Devnet | Aptos Testnet | Aptos Mainnet | | -------- | ------------ | ------------- | ------------- | | Metamask | ✅ | ✅ | ✅ | | Phantom | ✅ | ✅ | ✅ | | Coinbase | ✅ | ✅ | ✅ | | OKX | ✅ | ✅ | ✅ | | Exodus | ✅ | ✅ | ✅ | | Backpack | ✅ | ✅ | ✅ |

Supporting x-chain accounts in a dApp requires only a 2-step installation process.

1.  Install the @aptos-labs/derived-wallet-ethereum package
    
    ```
    npm install @aptos-labs/derived-wallet-ethereum
    ```
    
2.  Import the setupAutomaticEthereumWalletDerivation function
    
    Once you have installed the `@aptos-labs/derived-wallet-ethereum` package, you can import and use it. In the same file where you import the other wallets, such as `WalletProvider.tsx`, you can add the following:
    
    ```
    import { setupAutomaticEthereumWalletDerivation } from "@aptos-labs/derived-wallet-ethereum";
    setupAutomaticEthereumWalletDerivation({ defaultNetwork: Network.TESTNET }); // this is the Aptos network your dapp is working with
    ...
    <AptosWalletAdapterProvider dappConfig={{    network: Network.TESTNET,  }}>  {children}</AptosWalletAdapterProvider>
    ```
    
3.  Set crossChainWallets dapp config prop to true fot the AptosWalletAdapterProvider
    
    ```
    <AptosWalletAdapterProvider dappConfig={{    network: Network.TESTNET,    crossChainWallets: true,  }}>  {children}</AptosWalletAdapterProvider>
    ```

The wallet adapter follows the [Sui Wallet Standard](https://docs.sui.io/standards/wallet-standard) to discover wallets. Currently, the wallets that have been tested and support cross-chain accounts are:

| | Aptos Devnet | Aptos Testnet | Aptos Mainnet | | ------------ | ------------ | ------------- | ------------- | | Backpack | ✅ | ✅ | ✅ | | Bitget | ✅ | ✅ | ✅ | | Ethos | ✅ | ✅ | ✅ | | Nightly | ✅ | ✅ | ✅ | | OKX | ✅ | ✅ | ✅ | | Phantom | ✅ | ✅ | ✅ | | Slush | ✅ | ✅ | ✅ | | Trust Wallet | ✅ | ✅ | ✅ |

Supporting x-chain accounts in a dApp requires only a 2-step installation process.

1.  Install the @aptos-labs/derived-wallet-sui package
    
    ```
    npm install @aptos-labs/derived-wallet-sui
    ```
    
2.  Import the setupAutomaticSuiWalletDerivation function
    
    Once you have installed the `@aptos-labs/derived-wallet-sui` package, you can import and use it. In the same file where you import the other wallets, such as `WalletProvider.tsx`, you can add the following:
    
    ```
    import { setupAutomaticSuiWalletDerivation } from "@aptos-labs/derived-wallet-sui";
    setupAutomaticSuiWalletDerivation({ defaultNetwork: Network.TESTNET }); // this is the Aptos network your dapp is working with
    ...
    <AptosWalletAdapterProvider dappConfig={{    network: Network.TESTNET,  }}>  {children}</AptosWalletAdapterProvider>
    ```
    
3.  Set crossChainWallets dapp config prop to true fot the AptosWalletAdapterProvider
    
    ```
    <AptosWalletAdapterProvider dappConfig={{    network: Network.TESTNET,    crossChainWallets: true,  }}>  {children}</AptosWalletAdapterProvider>
    ```

That will handle the logic and implementation to include the x-chain accounts as if they were Aptos wallets.

### Submitting a transaction

[](#submitting-a-transaction)

In most cases, allowing users to submit a transaction with a x-chain account to the Aptos chain requires using a sponsor transaction. This is because the x-chain account might not have APT to pay for gas. Therefore, the dApp should consider maintaining a sponsor account to sponsor the transactions.

*   [Local Sponsor Account](#tab-panel-85)
*   [Gas Station](#tab-panel-86)

```
import React from 'react';import { useWallet } from '@aptos-labs/wallet-adapter-react';import { Aptos, AptosConfig, Network, Ed25519PrivateKey, PrivateKey, PrivateKeyVariants, Account } from '@aptos-labs/ts-sdk';
// Initialize an Aptos clientconst config = new AptosConfig({ network: Network.TESTNET });const aptos = new Aptos(config);
// Generate a sponsor account or use an existing accountconst privateKey = new Ed25519PrivateKey(  PrivateKey.formatPrivateKey(    "0x123",    PrivateKeyVariants.Ed25519  ));const sponsor = Account.fromPrivateKey({ privateKey });
const SignAndSubmit = () => {  const { account, signTransaction } = useWallet();
  const onSignAndSubmitTransaction = async () => {    if(!account) {      throw new Error("Account is not connected and unable to sign transaction")    }
    try {      // Build the transaction      const rawTransaction = await aptos.transaction.build.simple({        data: {          function: "0x1::aptos_account::transfer",          functionArguments: [account.address.toString(), 1],        },        sender: account.address,        withFeePayer: true,      });
      // Send it to the wallet to sign      const walletSignedTransaction = await signTransaction({        transactionOrPayload: rawTransaction,      });
      // Sponsor account signs the transaction to pay for the gas fees      const sponsorAuthenticator = aptos.transaction.signAsFeePayer({        signer: sponsor,        transaction: rawTransaction,      });
      // Submit the transaction to chain      const txnSubmitted = await aptosClient(network).transaction.submit.simple(        {          transaction: rawTransaction,          senderAuthenticator: walletSignedTransaction.authenticator,          feePayerAuthenticator: sponsorAuthenticator,        }      );
      // if you want to wait for transaction      await aptos.waitForTransaction({ transactionHash: txnSubmitted.hash });    } catch (error) {      console.error(error);    }  };
  return (    <button onClick={onSignAndSubmitTransaction}>      Sign and submit transaction    </button>  );};
export default SignAndSubmit;
```

);};export default SignAndSubmit;">

1.  Follow the [Gas Station docs](https://geomi.dev/docs/gas-stations) to set up a Gas Station service to obtain a gas station API key.
    
2.  Integrate a Gas Station instance in your application
    
    ```
      import {    GasStationClient,    GasStationTransactionSubmitter,  } from "@aptos-labs/gas-station-client";  import { Network } from "@aptos-labs/ts-sdk";
      const network = Network.TESTNET;  const gasStationClient = new GasStationClient({    network,    apiKey: process.env.GAS_STATION_API_KEY,  });  const transactionSubmitter = new GasStationTransactionSubmitter(gasStationClient);
    ```
    
3.  Then, you can use the `transactionSubmitter` to sponsor only x-chain account transactions
    
    ```
    const { signAndSubmitTransaction, wallet } = useWallet();
    const transactionInput = {  data: {    function:"0x1::aptos_account::transfer",    functionArguments: [account.address, 717],  },  sender: account.address,  transactionSubmitter: null};
    // If wallet is NOT an Aptos native walletif (!wallet.isAptosNativeWallet) {  transactionInput.transactionSubmitter = transactionSubmitter;}
    const txn = await signAndSubmitTransaction(transactionInput);
    ```

### Considerations

[](#considerations)

*   Since the origin wallet creates an x-chain account and is most likely not integrated with Aptos, simulation is not available in the wallet.
*   While the x-chain account prioritizes DAA, each account also retains the origin wallet, so developers should be able to use it and interact with it

### Resources

[](#resources)

*   X-Chain Accounts Adapter Demo App
    *   [Live site](https://x-chain-accounts.vercel.app/)
    *   [Source code](https://github.com/aptos-labs/aptos-wallet-adapter/tree/main/apps/nextjs-x-chain)
*   [AIP-113 Derivable Account Abstraction](https://github.com/aptos-foundation/AIPs/blob/main/aips/aip-113.md)

# Aptos Coin Standard (Legacy)

> Learn about aptos coin for Move smart contract development on Aptos blockchain.

[Coin](https://github.com/aptos-labs/aptos-core/blob/main/aptos-move/framework/aptos-framework/sources/coin.move) provides a standard, type-safe framework for simple, fungible tokens or coins.

Note

Coin is stored in `0x1::coin`.

## Structures

[](#structures)

### Reusability

[](#reusability)

A coin is defined in Move as:

```
module 0x1::coin {  struct Coin<phantom CoinType> has store {    /// Amount of coin this address has.    value: u64,  }}
```

A Coin uses the `CoinType` to support re-usability of the Coin framework for distinct Coins. For example, `Coin<A>` and `Coin<B>` are two distinct coins.

### Global store

[](#global-store)

Coin also supports a resource for storing coins in global store:

```
module 0x1::coin {  struct CoinStore<phantom CoinType> has key {    coin: Coin<CoinType>,    frozen: bool,    deposit_events: EventHandle<DepositEvent>,    withdraw_events: EventHandle<WithdrawEvent>,  }}
```

Coin information or metadata is stored in global store under the coin creators account:

```
module 0x1::coin {  struct CoinInfo<phantom CoinType> has key {    name: string::String,    /// Symbol of the coin, usually a shorter version of the name.    /// For example, Singapore Dollar is SGD.    symbol: string::String,    /// Number of decimals used to get its user representation.    /// For example, if `decimals` equals `2`, a balance of `505` coins should    /// be displayed to a user as `5.05` (`505 / 10 ** 2`).    decimals: u8,    /// Amount of this coin type in existence.    supply: Option<OptionalAggregator>,  }}
```

## Primitives

[](#primitives)

Coin provides the primitives for users creating and managing the coin and the users who use it.

### Creators

[](#creators)

Coin creators and managers can:

*   Initialize a coin and set its metadata and supply monitoring.
*   Minting and burning Coin value.
*   Burning coins from a `CoinStore`.
*   Freezing mobility into and out of a `CoinStore`.

### Users

[](#users)

Coin users can:

*   Merging two Coin structs of the same type.
*   Extracting value from a Coin struct into a new Coin struct.
*   Ability to deposit and withdraw from a `CoinStore` and emit events as a result.
*   Allows for users to register a `CoinStore<CoinType>` in their account to handle coin.

### Coin module key struct

[](#coin-module-key-struct)

The following tables describe fields at the struct level. For the definitive list, see the [Aptos Framework](https://github.com/aptos-labs/aptos-core/blob/main/aptos-move/framework/aptos-framework/doc/overview.md) containing [`coin`](https://github.com/aptos-labs/aptos-core/blob/main/aptos-move/framework/aptos-framework/doc/coin.md).

##### [`Coin`](https://github.com/aptos-labs/aptos-core/blob/744c2def47cddced878fda9bbd5633022fdb083a/aptos-move/framework/aptos-framework/sources/coin.move#L68)

[](#coin)

| Field | Type | Description | | ------- | ---- | ---------------------------------- | | `value` | u64 | Value of the token, eg: 1000000000 |

##### [`CoinInfo`](https://github.com/aptos-labs/aptos-core/blob/744c2def47cddced878fda9bbd5633022fdb083a/aptos-move/framework/aptos-framework/sources/coin.move#L92)

[](#coininfo)

| Field | Type | Description | | ---------- | --------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | | `name` | String | Name of the token, eg: Aptos Coin | | `symbol` | String | Symbol for the token, eg: APT | | `decimals` | u8 | Determines how the value of coin is represented; for example APT’s decimal is 8, so a value of 100000000 is represented by 1 APT | | `supply` | Option<OptionalAggregator> | option::some(optional\_aggregator::new(MAX\_U128, parallelizable)) |

### Creating a new CoinType

[](#creating-a-new-cointype)

A coin creator can publish to an on-chain account a new module that defines a struct to represent a new `CoinType`. The coin creator will then call `coin:initialize<CoinType>` from that account to register this as a valid coin, and in return receive back structs that enable calling the functions to burn and mint coins and freeze `CoinStore`s. These will need to be stored in global storage by the creator to manage the use of the coin.

```
module 0x1::coin {  public fun initialize<CoinType>(    account: &signer,    name: string::String,    symbol: string::String,    decimals: u8,    monitor_supply: bool,  ): (BurnCapability<CoinType>, FreezeCapability<CoinType>, MintCapability<CoinType>) {    // ...  }}
```

The creator has the opportunity to define a name, symbol, decimals, and whether the total supply for the coin is monitored. The following applies:

*   The first three of the above (`name`, `symbol`, `decimals`) are purely metadata and have no impact for on-chain applications. Some applications may use decimal to equate a single Coin from fractional coin.
*   Monitoring supply (`monitor_supply`) helps track total coins in supply. However, due to the way the parallel executor works, turning on this option will prevent any parallel execution of mint and burn. If the coin will be regularly minted or burned, consider disabling `monitor_supply`.

### Minting Coins

[](#minting-coins)

If the creator or manager would like to mint coins, they must retrieve a reference to their `MintCapability`, which was produced in the `initialize`, and call:

```
module 0x1::coin {  public fun mint<CoinType>(    amount: u64,    _cap: &MintCapability<CoinType>,  ): Coin<CoinType> acquires CoinInfo {    // ...  }}
```

This will produce a new Coin struct containing a value as dictated by the `amount`. If supply is tracked, then it will also be adjusted.

### Burning Coins

[](#burning-coins)

If the creator or manager would like to burn coins, they must retrieve a reference to their `BurnCapability`, which was produced in the `initialize`, and call:

```
module 0x1::coin {  public fun burn<CoinType>(    coin: Coin<CoinType>,    _cap: &BurnCapability<CoinType>,  ) acquires CoinInfo {    // ...  }}
```

The creator or manager can also burn coins from a `CoinStore`:

```
module 0x1::coin {  public fun burn_from<CoinType>(    account_addr: address,    amount: u64,    burn_cap: &BurnCapability<CoinType>,  ) acquires CoinInfo, CoinStore {   // ...  }}
```

Note

### burn vs burn\_from

[](#burn-vs-burn_from)

The function `burn` eliminates the total value stored in the coin, while `burn_from` only eliminates a given amount of value from a `CoinStore`. If supply is tracked, then it will also be adjusted.

Burning coins from an account does not emit a `WithdrawEvent` as the `withdraw` function does.

### Freezing Accounts

[](#freezing-accounts)

If the creator or manager would like to freeze a `CoinStore` on a specific account, they must retrieve a reference to their `FreezeCapability`, which was produced in `initialize`, and call:

```
module 0x1::coin {  public entry fun freeze_coin_store<CoinType>(    account_addr: address,    _freeze_cap: &FreezeCapability<CoinType>,  ) acquires CoinStore {    // ...  }}
```

### Merging Coins

[](#merging-coins)

Two coins of the same type can be merged into a single Coin struct that represents the accumulated value of the two coins independently by calling:

```
module 0x1::coin {  public fun merge<CoinType>(    dst_coin: &mut Coin<CoinType>,    source_coin: Coin<CoinType>,  ) {    // ...  }}
```

### Extracting Coins

[](#extracting-coins)

A Coin can have value deducted to create another Coin by calling:

```
module 0x1::coin {  public fun extract<CoinType>(    coin: &mut Coin<CoinType>,    amount: u64,  ): Coin<CoinType> {    // ...  }}
```

### Withdrawing Coins from CoinStore

[](#withdrawing-coins-from-coinstore)

A holder of a `CoinStore` can extract a Coin of a specified value by calling:

```
module 0x1::coin {  public fun withdraw<CoinType>(    account: &signer,    amount: u64,  ): Coin<CoinType> acquires CoinStore {    // ...  }}
```

Note

This function will emit a `WithdrawEvent`.

### Depositing Coins into CoinStore

[](#depositing-coins-into-coinstore)

Any entity can deposit coins into an account’s `CoinStore` by calling:

```
module 0x1::coin {  public fun deposit<CoinType>(    account_addr: address,    coin: Coin<CoinType>,  ) acquires CoinStore {    // ...  }}
```

Note

This function will emit a `DepositEvent`.

### Transferring Coins

[](#transferring-coins)

A holder of a `CoinStore` can directly transfer coins from their account to another account’s `CoinStore` by calling:

```
module 0x1::coin {  public entry fun transfer<CoinType>(    from: &signer,    to: address,    amount: u64,  ) acquires CoinStore {    // ...  }}
```

Note

This will emit both a `WithdrawEvent` and `DepositEvent` on the respective `CoinStore`s.

## Events

[](#events)

```
module 0x1::coin {  struct DepositEvent has drop, store {    amount: u64,  }}
```

```
module 0x1::coin {  struct WithdrawEvent has drop, store {    amount: u64,  }}
```

# Aptos Standards

> Learn about aptos standards for Move smart contract development on Aptos blockchain.

Standards define a common interoperable interface for all developers to build upon. They consist of rules to ensure compatibility across applications and wallets on the Aptos blockchain. See a [list of known coin resource addresses](https://github.com/hippospace/aptos-coin-list) on Aptos provided by hippospace.

## Move Standards

[](#move-standards)

### [Aptos Object](/build/smart-contracts/objects)

[](#aptos-object)

The [Object model](https://github.com/aptos-labs/aptos-core/blob/main/aptos-move/framework/aptos-framework/sources/object.move) allows Move to represent a complex type as a set of resources stored within a single address and offers a rich capability model that allows for fine-grained resource control and ownership management.

## Asset Standards

[](#asset-standards)

### [Digital Asset (DA)](/build/smart-contracts/digital-asset)

[](#digital-asset-da)

The new [Aptos Digital Asset Standard](https://github.com/aptos-labs/aptos-core/blob/main/aptos-move/framework/aptos-token-objects/sources/token.move) allows:

*   Rich, flexible assets and collectibles.
*   Easy enhancement of base functionality to provide richer custom functionalities. An example of this is the [aptos\_token module](https://github.com/aptos-labs/aptos-core/blob/main/aptos-move/framework/aptos-token-objects/sources/aptos_token.move)

Digital Asset (DA) is recommended for any new collections or protocols that want to build NFT or semi-fungible tokens.

### [Fungible Asset (FA)](/build/smart-contracts/fungible-asset)

[](#fungible-asset-fa)

The new [Aptos Fungible Asset Standard](https://github.com/aptos-labs/aptos-core/blob/main/aptos-move/framework/aptos-framework/sources/fungible_asset.move) is a standard meant for simple, type-safe, and fungible assets based on object model intending to replace Aptos coin. Fungible Asset (FA) offers more features and flexibility to Aptos move developers on creating and managing fungible assets.

## Legacy Standards

[](#legacy-standards)

### [Aptos Token](/build/smart-contracts/aptos-token)

[](#aptos-token)

The old existing [Token module](https://github.com/aptos-labs/aptos-core/blob/main/aptos-move/framework/aptos-token/sources/token.move), on the other hand:

*   Encapsulates rich, flexible assets and collectibles. These assets are discrete (non-decimal) and can be fungible, semi-fungible, or non-fungible.
*   The token standard is in its own `AptosToken` package at the Address `0x3` to allow for rapid iteration based on feedback from the community.

### [Aptos Coin](/build/smart-contracts/aptos-coin)

[](#aptos-coin)

The [Coin module](https://github.com/aptos-labs/aptos-core/blob/main/aptos-move/framework/aptos-framework/sources/coin.move) is a lightweight standard meant for simple, type-safe, and fungible assets. The coin standard is separated out into its own Move module to ensure that:

*   Applications and users can create and use simple tokens, with high performance and low gas overhead.
*   The Coin standard is part of the Aptos core framework, so it can be used for currencies, including the gas currency.

# Aptos Token Standard (Legacy)

> Learn about aptos token for Move smart contract development on Aptos blockchain.

## Overview of NFT

[](#overview-of-nft)

An [NFT](https://en.wikipedia.org/wiki/Non-fungible_token) is a non-fungible [token](https://github.com/aptos-labs/aptos-core/blob/main/aptos-move/framework/aptos-token/sources/token.move) or data stored on a blockchain that uniquely defines ownership of an asset. NFTs were first defined in [EIP-721](https://eips.ethereum.org/EIPS/eip-721) and later expanded upon in [EIP-1155](https://eips.ethereum.org/EIPS/eip-1155). NFTs are typically defined using the following properties:

*   `name`: The name of the asset. It must be unique within a collection.
*   `description`: The description of the asset.
*   `uri`: A URL pointer to off-chain for more information about the asset. The asset could be media such as an image or video or more metadata.
*   `supply`: The total number of units of this NFT. Many NFTs have only a single supply, while those that have more than one are referred to as editions.

Additionally, most NFTs are part of a collection or a set of NFTs with a common attribute, for example, a theme, creator, or minimally contract. Each collection has a similar set of attributes:

*   `name`: The name of the collection. The name must be unique within the creator's account.
*   `description`: The description of the collection.
*   `uri`: A URL pointer to off-chain for more information about the asset. The asset could be media such as an image or video or more metadata.
*   `supply`: The total number of NFTs in this collection.
*   `maximum`: The maximum number of NFTs that this collection can have. If `maximum` is set to 0, then supply is not tracked.

## Design principles

[](#design-principles)

The [Aptos token standard](https://github.com/aptos-labs/aptos-core/blob/main/aptos-move/framework/aptos-token/sources/token.move) is developed with the following principles:

*   **Interoperability**: Provide a standard implementation to improve interoperability across the ecosystem projects. Moreover, Move being a static language without dynamic dispatch makes this principle even more imperative.
*   **Liquidity**: Achieve maximal liquidity by defining the NFT, fungible (non-decimal) and semi-fungible tokens in one contract. These different types of tokens can be easily stored, transferred and transacted in the same way. As a consequence, it becomes easier to achieve maximal interoperability across the marketplaces, exchanges, and other methods of exchange.
*   **Rich on-chain token properties**: Enable the customization of on-chain token properties. Users can define their own properties and store them on-chain. This can potentially eliminate the need for the off-chain metadata.
*   **Reduced overhead**: Reduce the cost of creating large amounts of NFTs from fungible tokens. This can lead to, for example, reduced overhead for similar tokens by the reuse of on-chain metadata for certain fungible tokens.

Note

**Fungible token → NFT**  
The Aptos token standard supports [mutation of a fungible token to an NFT](#evolving-from-fungible-token-to-nft).

### Storing customized token properties on-chain

[](#storing-customized-token-properties-on-chain)

The Aptos token standard uses the [`PropertyMap`](https://github.com/aptos-labs/aptos-core/blob/main/aptos-move/framework/aptos-token/sources/property_map.move) module to store on-chain properties of tokens. `PropertyMap` maps a string key to a property value on-chain, which stores the value in Binary Canonical Serialization (BCS) format and its type. Currently, only primitive types (bool, u8, u64, u128, address and String) are supported in `PropertyMap`. Applications, such as [Aptos Names](https://www.aptosnames.com/), define application specific properties that are read and written by the applications smart contract.

#### Default properties

[](#default-properties)

You can add your properties to [`default_properties`](https://github.com/aptos-labs/aptos-core/blob/e62fd09cb1c916d857fa655b3f174991ef8698b3/aptos-move/framework/aptos-token/sources/token.move#L98) in the TokenData. The properties defined here are shared by all tokens by default.

The `default_properties` field is a key-value store with type information. It leverages the PropertyMap module which contain functions for serializing and deserializing different primitive types to the property value.

#### Token properties

[](#token-properties)

You can also use the `token_properties` defined in the token itself for customization on-chain. You can create customized values for a property of this specific token, thereby allowing a token to have a different property value from its default.

Note that limits exist to storing customized token properties on-chain, namely 1000 properties per token with field names limited to 128 characters.

### Evolving from fungible token to NFT

[](#evolving-from-fungible-token-to-nft)

Fungible tokens share the same default property values. However, these property values can evolve over time and become different from each other. To support such evolution of token properties, the Aptos token standard provides the `property_version` field. Here is how it works:

*   During the token creation (minting), all tokens initially have `property_version` set to `0` and these tokens can be stacked together as fungible token.
*   When the creators mutate the default properties of a token, the mutated token will be assigned a unique `property_version` to create a new [`token_id`](https://github.com/aptos-labs/aptos-core/blob/bba1690d7268759bd86ccd7459d7967172f1da24/aptos-move/framework/aptos-token/sources/token.move#L288) to differentiate it from other fungible tokens. This unique `token_id` allows the token to have its own property values, and all further mutation of this token does **not** change the `property_version` again. This token essentially becomes an NFT now.

#### Configuring mutability

[](#configuring-mutability)

To make mutability explicit for both the creator and owner, the Aptos token standard provides [`mutability_config`](https://github.com/aptos-labs/aptos-core/blob/bba1690d7268759bd86ccd7459d7967172f1da24/aptos-move/framework/aptos-token/sources/token.move#L100) at both the collection level and the token level to control which fields are mutable. Configurable here means the creator can configure this field to be mutable or immutable during creation.

### Storing metadata off-chain

[](#storing-metadata-off-chain)

Follow the standard below to ensure your NFT can be correctly displayed by various wallets.

You should store the metadata in a JSON file located in an onchain data solution like [Irys](https://docs.irys.xyz/), and provide the URL to the JSON file in the `uri` field of the token or the collection. We recommend the developers follow the [ERC-1155 off-chain data](https://eips.ethereum.org/EIPS/eip-1155) schema to format their JSON files.

```
{  "image": "https://gateway.irys.xyz/QH3rksVhbFg5L9vvjGzb4POUibCEG-TGPInmofp-O-o",  "animation_url": "https://gateway.irys.xyz/QH3rksVhbFg5L9vvjHzb4POUibCEG-TGPInmofp-O-o",  "external_url": "https://petra.app/",  "attributes": [    {      "trait_type": "web",      "value": "yes"    },    {      "trait_type": "mobile",      "value": "yes"    },    {      "trait_type": "extension",      "value": "yes"    }  ],  "properties": {    "files": [      {        "uri": "https://gateway.irys.xyz/QH3rksVhbFg5L9vvjGzb4POUibCEG-ENXUnmofp-O-o",        "type": "image/png"      },      {        "uri": "https://gateway.irys.xyz/QH3rksVhbFg5L9vvjGzb4POUibCEG-UENCnmofp-O-o",        "type": "unknown",        "cdn": true      },      {        "uri": "https://gateway.irys.xyz/QH3rksVhbFg5L9vvjGzb4POUibCEG-DJHUUnmofp-O-o",        "type": "video/mp4"      }    ],    "category": "video"  }}
```

*   `image`: URL to the image asset. You may use the `?ext={file_extension}` query to provide information on the file type.
*   `animation_url`: URL to the multimedia attachment of the asset. You may use the same `file_extension` query to provide the file type.
*   `external_url`: URL to an external website where the user can also view the image.
*   `attributes` - Object array, where an object should contain `trait_type` and `value` fields. `value` can be a string or a number.
*   `properties.files`: Object array, where an object should contain the URI and type of the file that is part of the asset. The type should match the file extension. The array should also include files specified in `image` and `animation_url` fields, as well as any other files associated with the asset. You may use the `?ext={file_extension}` query to provide information on the file type.
*   `properties.category`: Has supported categories:
*   `image` - PNG, GIF, JPG
*   `video` - MP4, MOV
*   `audio` - MP3, FLAC, WAV
*   `vr` - 3D models; GLB, GLTF
*   `html` - HTML pages; scripts and relative paths within the HTML page are also supported

You can also host your files on CDN to provide faster loading time by using the `cdn` flag in the file object. When the file exists, this should be the primary location to read the media file (`video`, `audio`, `vr`) by wallet. If the file is no longer available, the wallet can fall back to use the `animation_url` to load the file.

```
{  "properties": {    "files": [      {        "uri": "https://watch.videodelivery.net/52a52c4a261c88f19d267931426c9be6",        "type": "unknown",        "cdn": true      }    ]  }}
```

## Token data model

[](#token-data-model)

The following diagram depicts the flow of token data through Aptos:

![Signed Transaction Flow](/_astro/aptos-token-standard-flow.Bpdeog-M.svg) ![Signed Transaction Flow](/_astro/aptos-token-standard-flow-dark.Bn_ol96l.svg)

## Token resources

[](#token-resources)

As shown in the diagram above, token-related data are stored at both the creator’s account and the owner’s account.

### Struct-level resources

[](#struct-level-resources)

The following tables describe fields at the struct level. For the definitive list, see the [Aptos Token Framework](https://github.com/aptos-labs/aptos-core/blob/main/aptos-move/framework/aptos-token/doc/overview.md).

#### Resource stored at the creator’s address

[](#resource-stored-at-the-creators-address)

| Field | Description | | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [`Collections`](https://github.com/aptos-labs/aptos-core/blob/main/aptos-move/framework/aptos-token/doc/token.md#resource-collections) | Maintains a table called `collection_data`, which maps the collection name to the `CollectionData`. It also stores all the `TokenData` that this creator creates. | | [`CollectionData`](https://github.com/aptos-labs/aptos-core/blob/main/aptos-move/framework/aptos-token/doc/token.md#struct-collectiondata) | Stores the collection metadata. The supply is the number of tokens created for the current collection. The maximum is the upper bound of tokens in this collection. | | [`CollectionMutabilityConfig`](https://github.com/aptos-labs/aptos-core/blob/main/aptos-move/framework/aptos-token/doc/token.md#0x3_token_CollectionMutabilityConfig) | Specifies which field is mutable. | | [`TokenData`](https://github.com/aptos-labs/aptos-core/blob/main/aptos-move/framework/aptos-token/doc/token.md#0x3_token_TokenData) | Acts as the main struct for holding the token metadata. Properties is a where users can add their own properties that are not defined in the token data. Users can mint more tokens based on the `TokenData`, and those tokens share the same `TokenData`. | | [`TokenMutabilityConfig`](https://github.com/aptos-labs/aptos-core/blob/main/aptos-move/framework/aptos-token/doc/token.md#0x3_token_TokenMutabilityConfig) | Controls which fields are mutable. | | [`TokenDataId`](https://github.com/aptos-labs/aptos-core/blob/main/aptos-move/framework/aptos-token/doc/token.md#0x3_token_TokenDataId) | An ID used for representing and querying `TokenData` on-chain. This ID mainly contains three fields including creator address, collection name and token name. | | [`Royalty`](https://github.com/aptos-labs/aptos-core/blob/main/aptos-move/framework/aptos-token/doc/token.md#0x3_token_Royalty) | Specifies the denominator and numerator for calculating the royalty fee. It also has the payee account address for depositing the royalty. | | `PropertyValue` | Contains both value of a property and type of property. |

#### Resource stored at the owner’s address

[](#resource-stored-at-the-owners-address)

For more detailed descriptions, see [Aptos Token Framework](https://github.com/aptos-labs/aptos-core/blob/main/aptos-move/framework/aptos-token/doc/overview.md).

## Token lifecycle

[](#token-lifecycle)

### Token creation

[](#token-creation)

Every Aptos token belongs to a collection. The developer first needs to create a collection through `create_collection_script` and then create the token belonging to the collection `create_token_script`. To achieve parallel `TokenData` and `Token` creation, a developer can create unlimited collection and `TokenData` where the `maximum` of the collection and `TokenData` are set as `0`. With this setting, the token contract won’t track the supply of types of token (`TokenData` count) and supply of token within each token type. As the result, the `TokenData` and token can be created in parallel.

Aptos also enforces simple validation of the input size and prevents duplication:

*   Token name - unique within each collection
*   Collection name - unique within each account
*   Token and collection name length - smaller than 128 characters
*   URI length - smaller than 512 characters
*   Property map - can hold at most 1000 properties, and each key should be smaller than 128 characters

### Token mutation

[](#token-mutation)

Our standard supports mutation with a principle that the mutable fields are specified during the token creation. This allows the token owner to be informed which fields are mutable when they get the token from the creator. Our contract uses `CollectionMutabilityConfig` to check if a field is mutable. Our contract uses `TokenMutabilityConfig` to check if a `TokenData` field is mutable.

For mutation of properties, we have both

*   `default_properties` stored in `TokenData` shared by all tokens belonging to the `TokenData`
*   `token_properties` stored in the token itself

To mutate `default_properties`, developers can use `mutate_tokendata_property` to mutate the properties when `TokenMutabilityConfig` is set to `true`.

> **CAUTION: Set the `TokenMutabilityConfig` field to `false` unless it is absolutely necessary. Allowing `default_properties` to be mutable provides creators too much power; creators can change the burnable config to provide themselves the authority to burn tokens after token creation.**

To mutate `token_properties` stored in the token, our standard uses the `TOKEN_PROPERTY_MUTABLE` property stored in `default_properties`. When the creator creates the `TokenData` with the `TOKEN_PROPERTY_MUTABLE` property set to `true`, the creator can mutate `token_properties`. Note that if the `mutate_tokendata_property` is set to `true`, creators can mutate the `token_properties` anyway since they can overwrite the setting in `default_properties`.

### Token burn

[](#token-burn)

We provide `burn` and `burn_by_creator` functions for token owners and token creators to burn (or destroy) tokens. However, these two functions are also guarded by configs that are specified during the token creation so that both creator and owner are clear on who can burn the token. Burn is allowed only when the `BURNABLE_BY_OWNER` property is set to `true` in `default_properties`. Burn by creator is allowed when `BURNABLE_BY_CREATOR` is `true` in `default_properties`. Once all the tokens belonging to a `TokenData` are burned, the `TokenData` will be removed from the creator’s account. Similarly, if all `TokenData` belonging to a collection are removed, the `CollectionData` will be removed from the creator’s account.

### Token transfer

[](#token-transfer)

We provide three different modes for transferring tokens between the sender and receiver.

#### Two-step transfer

[](#two-step-transfer)

To protect users from receiving undesired NFTs, they must be first offered NFTs, and then accept the offered NFTs. Then only the offered NFTs will be deposited in the users' token stores. This is the default token transfer behavior. For example:

1.  If Alice wants to send Bob an NFT, she must first offer Bob this NFT. This NFT is still stored under Alice’s account.
2.  Only when Bob claims the NFT, will the NFT be removed from Alice’s account and stored in Bob’s token store.

Note

**Token transfer module**  
The token transfer is implemented in the [`token_transfers`](https://github.com/aptos-labs/aptos-core/blob/main/aptos-move/framework/aptos-token/sources/token_transfers.move) module.

#### Transfer with opt-in

[](#transfer-with-opt-in)

If a user wants to receive direct transfer of the NFT, skipping the initial steps of offer and claim, then the user can call [`opt_in_direct_transfer`](https://github.com/aptos-labs/aptos-core/blob/main/aptos-move/framework/aptos-token/doc/token.md#0x3_token_opt_in_direct_transfer) to allow other people to directly transfer the NFTs into the user's token store. After opting into direct transfer, the user can call [`transfer`](https://github.com/aptos-labs/aptos-core/blob/main/aptos-move/framework/aptos-token/doc/token.md#0x3_token_transfer) to transfer tokens directly. For example, Alice and anyone can directly send a token to Bob's token store once Bob opts in.

Note

**Turning off direct transfer**  
The user can also turn off this direct transfer behavior by calling the same `opt_in_direct_transfer` function to reset to the default behavior.

#### Multi-agent transfer

[](#multi-agent-transfer)

The sender and receiver can both sign a transfer transaction to directly transfer a token from the sender to receiver [`direct_transfer_script`](https://github.com/aptos-labs/aptos-core/blob/main/aptos-move/framework/aptos-token/doc/token.md#function-direct_transfer_script). For example, once Alice and Bob both sign the transfer transaction, the token will be directly transferred from Alice's account to Bob.

# Binary Canonical Serialization (BCS)

> Learn about bcs for Move smart contract development on Aptos blockchain.

Binary Canonical Serialization (BCS) is the serialization format used on the Aptos blockchain. It is a binary canonical non-self-describing serialization format that is used to serialize data structures. BCS is used to serialize all data on-chain, provide binary responses on the REST API, and encode input arguments to transactions.

## Overview

[](#overview)

Because BCS is not a self describing format, the reader must know the format of the bytes ahead of time.

## Primitive Types

[](#primitive-types)

8-bit, 16-bit, 32-bit, 64-bit, 128-bit, and 256-bit unsigned integers are supported. They are serialized in little-endian byte order.

### Bool (boolean)

[](#bool-boolean)

Booleans are serialized as a single byte. `true` is serialized as `0x01` and `false` is serialized as `0x00`. All other values are invalid.

| Value | Bytes | | ------- | ------ | | `true` | `0x01` | | `false` | `0x00` |

*   [Move](#tab-panel-90)
*   [Rust](#tab-panel-91)
*   [TypeScript](#tab-panel-92)
*   [Go](#tab-panel-93)

```
#[test_only]module 0x42::example {  use std::bcs;  use std::from_bcs;
  #[test]  fun test_bool() {    // Serialize    let val: bool = true;    let bytes: vector<u8> = bcs::to_bytes(&val);    assert!(bytes == vector[0x01]);
    // Deserialize    let val_des = from_bcs::to_bool(bytes);    assert!(val_des == true);  }}
```

```
// Serializelet val: bool = true;let bytes: Vec<u8> = bcs::to_bytes(&val).unwrap();assert_eq!(bytes, vec![0x01]);
// Deserializelet val_des = bcs::from_bytes::<bool>(&bytes).unwrap();assert_eq!(val_des, true);
```

```
import { Serializer, Deserializer } from "@aptos-labs/ts-sdk";
// Serializeconst ser = new Serializer();ser.serializeBool(true);const bytes = ser.toUint8Array();console.log(bytes == Uint8Array.from([1]));
// Deserializeconst des = new Deserializer(bytes);const val = des.deserializeBool();console.log(val == true);
```

```
import (  "github.com/aptos-labs/aptos-go-sdk")
func main() {  // Serialize  ser := bcs.Serializer{}  ser.Bool(true)  trueBytes := ser.ToBytes()  trueBytes == []byte{0x01}
  // Deserialize  des := bcs.NewDeserializer(trueBytes)  val := des.Bool()  val == true}
```

### U8 (unsigned 8-bit integer)

[](#u8-unsigned-8-bit-integer)

Unsigned 8-bit integers are serialized as a single byte.

*   [Move](#tab-panel-94)
*   [Rust](#tab-panel-95)
*   [TypeScript](#tab-panel-96)
*   [Go](#tab-panel-97)

```
#[test_only]module 0x42::example {  use std::bcs;  use std::from_bcs;
  #[test]  fun test_u8() {    // Serialize    let val: u8 = 1;    let bytes: vector<u8> = bcs::to_bytes(&val);    assert!(bytes == vector[0x01]);
    // Deserialize    let val_des = from_bcs::to_u8(bytes);    assert!(val_des == 1);  }}
```

```
// Serializelet val: u8 = 1;let bytes: Vec<u8> = bcs::to_bytes(&val).unwrap();assert_eq!(bytes, vec![0x01]);
// Deserializelet val_des = bcs::from_bytes::<u8>(&bytes).unwrap();assert_eq!(val_des, 1);
```

```
import { Serializer, Deserializer } from "@aptos-labs/ts-sdk";
// Serializeconst ser = new Serializer();ser.serializeU8(1);const bytes = ser.toUint8Array();console.log(bytes == Uint8Array.from([1]));
// Deserializeconst des = new Deserializer(bytes);const val = des.deserializeU8();console.log(val == 1);
```

```
import (  "github.com/aptos-labs/aptos-go-sdk")
func main() {  // Serialize  ser := bcs.Serializer{}  ser.U8(1)  trueBytes := ser.ToBytes()  trueBytes == []byte{0x01}
  // Deserialize  des := bcs.NewDeserializer(trueBytes)  val := des.U8()  val == 1}
```

### U16 (unsigned 16-bit integer)

[](#u16-unsigned-16-bit-integer)

Unsigned 16-bit integers are serialized as 2 bytes in little-endian byte order.

*   [Move](#tab-panel-98)
*   [Rust](#tab-panel-99)
*   [TypeScript](#tab-panel-100)
*   [Go](#tab-panel-101)

```
#[test_only]module 0x42::example { use std::bcs; use std::from_bcs;
 #[test] fun test_u16() {   // Serialize   let val: u16 = 1000;   let bytes: vector<u8> = bcs::to_bytes(&val);   assert!(bytes == vector[0xe8, 0x03]);
   // Deserialize   let val_des = from_bcs::to_u16(bytes);   assert!(val_des == 1000); }}
```

```
// Serializelet val: u16 = 1000;let bytes: Vec<u8> = bcs::to_bytes(&val).unwrap();assert_eq!(bytes, vec![0xe8, 0x03]);
// Deserializelet val_des = bcs::from_bytes::<u16>(&bytes).unwrap();assert_eq!(val_des, 1000);
```

```
import { Serializer, Deserializer } from "@aptos-labs/ts-sdk";
// Serializeconst ser = new Serializer();ser.serializeU16(1000);const bytes = ser.toUint8Array();console.log(bytes == Uint8Array.from([0xe8, 0x03]));
// Deserializeconst des = new Deserializer(bytes);const val = des.deserializeU16();console.log(val == 1000);
```

```
import (  "github.com/aptos-labs/aptos-go-sdk")
func main() {  // Serialize  ser := bcs.Serializer{}  ser.U16(1000)  bytes := ser.ToBytes()  bytes == []byte{0xe8, 0x03}
  // Deserialize  des := bcs.NewDeserializer(bytes)  val := des.U16()  val == 1000}
```

### U32 (unsigned 32-bit integer)

[](#u32-unsigned-32-bit-integer)

Unsigned 32-bit integers are serialized as 4 bytes in little-endian byte order.

*   [Move](#tab-panel-102)
*   [Rust](#tab-panel-103)
*   [TypeScript](#tab-panel-104)
*   [Go](#tab-panel-105)

```
#[test_only]module 0x42::example {  use std::bcs;  use std::from_bcs;
  #[test]  fun test_u32() {    // Serialize    let val: u32 = 1000000000;    let bytes: vector<u8> = bcs::to_bytes(&val);    assert!(bytes == vector[0x00, 0xca, 0x9a, 0x3b]);
    // Deserialize    let val_des = from_bcs::to_u32(bytes);    assert!(val_des == 1000000000);  }}
```

```
// Serializelet val: u32 = 1000000000;let bytes: Vec<u8> = bcs::to_bytes(&val).unwrap();assert_eq!(bytes, vec![0x00, 0xca, 0x9a, 0x3b]);
// Deserializelet val_des = bcs::from_bytes::<u32>(&bytes).unwrap();assert_eq!(val_des, 1000000000);
```

```
import { Serializer, Deserializer } from "@aptos-labs/ts-sdk";
// Serializeconst ser = new Serializer();ser.serializeU32(1000000000);const bytes = ser.toUint8Array();console.log(bytes == Uint8Array.from([0x00, 0xca, 0x9a, 0x3b]));
// Deserializeconst des = new Deserializer(bytes);const val = des.deserializeU32();console.log(val == 1000000000);
```

```
import (  "github.com/aptos-labs/aptos-go-sdk")
func main() {  // Serialize  ser := bcs.Serializer{}  ser.U32(1000000000)  bytes := ser.ToBytes()  bytes == []byte{0x00, 0xca, 0x9a, 0x3b}
  // Deserialize  des := bcs.NewDeserializer(bytes)  val := des.U32()  val == 1000000000}
```

### U64 (unsigned 64-bit integer)

[](#u64-unsigned-64-bit-integer)

Unsigned 64-bit integers are serialized as 8 bytes in little-endian byte order.

*   [Move](#tab-panel-106)
*   [Rust](#tab-panel-107)
*   [TypeScript](#tab-panel-108)
*   [Go](#tab-panel-109)

```
#[test_only]module 0x42::example {  use std::bcs;  use std::from_bcs;
  #[test]  fun test_u64() {    // Serialize    let val: u64 = 10000000000000000;    let bytes: vector<u8> = bcs::to_bytes(&val);    assert!(bytes == vector[0x00, 0x40, 0x9c, 0x4f, 0x2c, 0x68, 0x00, 0x00]);
    // Deserialize    let val_des = from_bcs::to_u64(bytes);    assert!(val_des == 10000000000000000);  }}
```

```
// Serializelet val: u64 = 10000000000000000;let bytes: Vec<u8> = bcs::to_bytes(&val).unwrap();assert_eq!(bytes, vec![0x00, 0x40, 0x9c, 0x4f, 0x2c, 0x68, 0x00, 0x00]);
// Deserializelet val_des = bcs::from_bytes::<u64>(&bytes).unwrap();assert_eq!(val_des, 10000000000000000);
```

```
import { Serializer, Deserializer } from "@aptos-labs/ts-sdk";
// Serializeconst ser = new Serializer();ser.serializeU64(10000000000000000n);const bytes = ser.toUint8Array();console.log(bytes == Uint8Array.from([0x00, 0x40, 0x9c, 0x4f, 0x2c, 0x68, 0x00, 0x00]));
// Deserializeconst des = new Deserializer(bytes);const val = des.deserializeU64();console.log(val == 10000000000000000n);
```

```
import (  "github.com/aptos-labs/aptos-go-sdk")
func main() {  // Serialize  ser := bcs.Serializer{}  ser.U64(10000000000000000)  bytes := ser.ToBytes()  bytes == []byte{0x00, 0x40, 0x9c, 0x4f, 0x2c, 0x68, 0x00, 0x00}
  // Deserialize  des := bcs.NewDeserializer(bytes)  val := des.U64()  val == 10000000000000000}
```

### U128 (unsigned 128-bit integer)

[](#u128-unsigned-128-bit-integer)

Unsigned 128-bit integers are serialized as 16 bytes in little-endian byte order.

*   [Move](#tab-panel-110)
*   [Rust](#tab-panel-111)
*   [TypeScript](#tab-panel-112)
*   [Go](#tab-panel-113)

```
#[test_only]module 0x42::example {  use std::bcs;  use std::from_bcs;
  #[test]  fun test_u128() {    // Serialize    let val: u128 = 10000000000000000;    let bytes: vector<u8> = bcs::to_bytes(&val);    assert!(bytes == vector[0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x40, 0x9c, 0x4f, 0x2c, 0x68, 0x00, 0x00]);
    // Deserialize    let val_des = from_bcs::to_u128(bytes);    assert!(val_des == 10000000000000000);  }}
```

```
// Serializelet val: u128 = 10000000000000000;let bytes: Vec<u8> = bcs::to_bytes(&val).unwrap();assert_eq!(bytes, vec![0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x40, 0x9c, 0x4f, 0x2c, 0x68, 0x00, 0x00]);
// Deserializelet val_des = bcs::from_bytes::<u128>(&bytes).unwrap();assert_eq!(val_des, 10000000000000000);
```

```
import { Serializer, Deserializer } from "@aptos-labs/ts-sdk";
// Serializeconst ser = new Serializer();ser.serializeU128(10000000000000000n);const bytes = ser.toUint8Array();console.log(bytes == Uint8Array.from([0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x40, 0x9c, 0x4f, 0x2c, 0x68, 0x00, 0x00]));
// Deserializeconst des = new Deserializer(bytes);const val = des.deserializeU128();console.log(val == 10000000000000000n);
```

```
import (  "github.com/aptos-labs/aptos-go-sdk"  "math/big")
func main() {  // Serialize  ser := bcs.Serializer{}  val := new(big.Int)  val.SetString("10000000000000000", 10)  ser.U128(val)  bytes := ser.ToBytes()  bytes == []byte{0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x40, 0x9c, 0x4f, 0x2c, 0x68, 0x00, 0x00}
  // Deserialize  des := bcs.NewDeserializer(bytes)  val_des := des.U128()  val_des.String() == "10000000000000000"}
```

### U256 (unsigned 256-bit integer)

[](#u256-unsigned-256-bit-integer)

Unsigned 256-bit integers are serialized as 32 bytes in little-endian byte order.

*   [Move](#tab-panel-114)
*   [Rust](#tab-panel-115)
*   [TypeScript](#tab-panel-116)
*   [Go](#tab-panel-117)

```
#[test_only]module 0x42::example {  use std::bcs;  use std::from_bcs;
  #[test]  fun test_u256() {    // Serialize    let val: u256 = 10000000000000000;    let bytes: vector<u8> = bcs::to_bytes(&val);    assert!(bytes == vector[0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x40, 0x9c, 0x4f, 0x2c, 0x68, 0x00, 0x00]);
    // Deserialize    let val_des = from_bcs::to_u256(bytes);    assert!(val_des == 10000000000000000);  }}
```

```
// Serializelet val: U256 = U256::from(10000000000000000u64);let bytes: Vec<u8> = bcs::to_bytes(&val).unwrap();assert_eq!(bytes, vec![0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x40, 0x9c, 0x4f, 0x2c, 0x68, 0x00, 0x00]);
// Deserializelet val_des = bcs::from_bytes::<U256>(&bytes).unwrap();assert_eq!(val_des, U256::from(10000000000000000u64));
```

```
import { Serializer, Deserializer } from "@aptos-labs/ts-sdk";
// Serializeconst ser = new Serializer();ser.serializeU256(10000000000000000n);const bytes = ser.toUint8Array();console.log(bytes == Uint8Array.from([0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x40, 0x9c, 0x4f, 0x2c, 0x68, 0x00, 0x00]));
// Deserializeconst des = new Deserializer(bytes);const val = des.deserializeU256();console.log(val == 10000000000000000n);
```

```
import (  "github.com/aptos-labs/aptos-go-sdk"  "math/big")
func main() {  // Serialize  ser := bcs.Serializer{}  val := new(big.Int)  val.SetString("10000000000000000", 10)  ser.U256(val)  bytes := ser.ToBytes()  bytes == []byte{0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x40, 0x9c, 0x4f, 0x2c, 0x68, 0x00, 0x00}
  // Deserialize  des := bcs.NewDeserializer(bytes)  val_des := des.U256()  val_des.String() == "10000000000000000"}
```

### Uleb128 (unsigned 128-bit variable length integer)

[](#uleb128-unsigned-128-bit-variable-length-integer)

Unsigned 128-bit variable length integers are serialized as a variable number of bytes. The most significant bit of each byte is used to indicate if there are more bytes to read. The remaining 7 bits are used to store the value.

This is common used for variable lengths of vectors, or for enums.

*   [Move](#tab-panel-118)
*   [Rust](#tab-panel-119)
*   [TypeScript](#tab-panel-120)
*   [Go](#tab-panel-121)

```
// Currently not supported by itself in Move
```

```
// Currently not supported by itself in Rust with serde
```

```
import { Serializer, Deserializer } from "@aptos-labs/ts-sdk";
// Serializeconst ser = new Serializer();ser.serializeU32AsUleb128(127);const bytes = ser.toUint8Array();console.log(bytes == Uint8Array.from([0x7f]));
const ser = new Serializer();ser.serializeU32AsUleb128(128);const bytes2 = ser.toUint8Array();console.log(bytes2 == Uint8Array.from([0x80, 0x01]));
// Deserializeconst des = new Deserializer(bytes2);const val = des.deserializeUleb128AsU32();console.log(val == 128);
```

```
import (  "github.com/aptos-labs/aptos-go-sdk"  "math/big")
func main() {  // Serialize  ser := bcs.Serializer{}  val := new(big.Int)  val.SetInt64(127)  ser.Uleb128(val)  bytes := ser.ToBytes()  bytes == []byte{0x7f}
  // Deserialize  des := bcs.NewDeserializer(bytes)  val_des := des.Uleb128()  val_des.Int64() == 127}
```

### Sequence and FixedSequence

[](#sequence-and-fixedsequence)

Sequences are serialized as a variable length vector of an item. The length of the vector is serialized as a Uleb128 followed by repeated items. FixedSequences are serialized without the leading size byte. The reader must know the number of bytes prior to deserialization.

*   [Move](#tab-panel-122)
*   [Rust](#tab-panel-123)
*   [TypeScript](#tab-panel-124)
*   [Go](#tab-panel-125)

```
#[test_only]module 0x42::example {  use std::bcs;  use std::from_bcs;
  #[test]  fun test_vector() {    // Serialize    let val = vector[1u8, 2u8, 3u8];    let bytes = bcs::to_bytes(&val);    assert!(bytes == vector[3, 1, 2, 3]);
    // Deserialize, only supports bytes for now    let val_des = from_bcs::to_bytes(bytes);    assert!(val_des == vector[1, 2, 3]);  }}
```

```
// Serializelet val = vec![1u8, 2u8, 3u8];let bytes = bcs::to_bytes(&val).unwrap();assert_eq!(bytes, vec![3, 1, 2, 3]);
// Deserializelet val_des = bcs::from_bytes::<Vec<u8>>(&bytes).unwrap();assert_eq!(val_des, vec![1, 2, 3]);
```

```
import { Serializer, Deserializer } from "@aptos-labs/ts-sdk";
// Serializeconst ser = new Serializer();ser.serializeVector([1, 2, 3], (s, item) => s.serializeU8(item));const bytes = ser.toUint8Array();console.log(bytes == Uint8Array.from([3, 1, 2, 3]));
// Deserializeconst des = new Deserializer(bytes);const val = des.deserializeVector((d) => d.deserializeU8());console.log(val == [1, 2, 3]);
```

```
import (  "github.com/aptos-labs/aptos-go-sdk")
func main() {  // Serialize  ser := bcs.Serializer{}  ser.SerializeVector([]uint8{1, 2, 3}, func(s *bcs.Serializer, item uint8) {    s.U8(item)  })  bytes := ser.ToBytes()  bytes == []byte{3, 1, 2, 3}
  // Deserialize  des := bcs.NewDeserializer(bytes)  val := des.DeserializeVector(func(d *bcs.Deserializer) uint8 {    return d.U8()  })  val == []uint8{1, 2, 3}}
```

## Complex types

[](#complex-types)

### String

[](#string)

Strings are serialized as a vector of bytes, however the bytes are encoded as UTF-8.

```
// Note that this string has 10 characters but has a byte length of 24let utf8_str = "çå∞≠¢õß∂ƒ∫";let expecting = vec![    24, 0xc3, 0xa7, 0xc3, 0xa5, 0xe2, 0x88, 0x9e, 0xe2, 0x89, 0xa0, 0xc2,    0xa2, 0xc3, 0xb5, 0xc3, 0x9f, 0xe2, 0x88, 0x82, 0xc6, 0x92, 0xe2, 0x88, 0xab,];assert_eq!(to_bytes(&utf8_str)?, expecting);
```

### AccountAddress

[](#accountaddress)

AccountAddress is serialized as a fixed 32 byte vector of bytes.

```
@0x1 => [0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x01]
```

### Struct

[](#struct)

Structs are serialized as an ordered set of fields. The fields are serialized in the order they are defined in the struct.

```
struct Color {  r: u8 = 1,  g: u8 = 2,  b: u8 = 3,} => [0x01, 0x02, 0x03]
```

### Option

[](#option)

Options are serialized as a single byte to determine whether it's filled. If the option is `None`, the byte is `0x00`. If the option is `Some`, the byte is `0x01` followed by the serialized value.

```
let some_data: Option<u8> = Some(8);assert_eq!(to_bytes(&some_data)?, vec![1, 8]);
let no_data: Option<u8> = None;assert_eq!(to_bytes(&no_data)?, vec![0]);
```

### Enum

[](#enum)

Enums are serialized as a uleb128 to determine which variant is being used. The size is followed by the serialized value of the variant.

```
#[derive(Serialize)]enum E {    Variant0(u16),    Variant1(u8),    Variant2(String),}
let v0 = E::Variant0(8000);let v1 = E::Variant1(255);let v2 = E::Variant2("e".to_owned());
assert_eq!(to_bytes(&v0)?, vec![0, 0x40, 0x1F]);assert_eq!(to_bytes(&v1)?, vec![1, 0xFF]);assert_eq!(to_bytes(&v2)?, vec![2, 1, b'e']);
```

### Maps

[](#maps)

Maps are stored as a sequence of tuples. The length of the map is serialized as a Uleb128 followed by repeated key-value pairs.

```
let mut map = HashMap::new();map.insert(b'e', b'f');map.insert(b'a', b'b');map.insert(b'c', b'd');
let expecting = vec![(b'a', b'b'), (b'c', b'd'), (b'e', b'f')];
assert_eq!(to_bytes(&map)?, to_bytes(&expecting)?);
```

## Reference

[](#reference)

*   [BCS Specification](https://github.com/diem/bcs)

# Move On Aptos Compiler

> Learn about compiler_v2 for Move smart contract development on Aptos blockchain.

The Move on Aptos compiler (codename 'compiler v2') translates Move source code into Move bytecode. It unifies the architectures of the Move compiler and the Move Prover, enabling faster innovation in the Move language. It also offers new tools for defining code optimizations which can be leveraged to generate more gas efficient code for Move programs.

The Move on Aptos compiler supports Move 2, the latest revision of the Move language. Head over to the [release page in the book](https://aptos-labs.github.io/move-book/move-versions.html) to learn more about the new features in Move 2. Starting at Aptos CLI v6.0.0, this language version and the Move on Aptos compiler are the default. Note that Move 2 is generally backwards compatible with Move 1.

## Move on Aptos Release State

[](#move-on-aptos-release-state)

Move on Aptos is in production and is now the default compiler, with Move 2 being the default language version.

## Reporting an Issue

[](#reporting-an-issue)

If you run into issues, please use [this link to create a github issue](https://github.com/aptos-labs/aptos-core/issues/new?title=%5Bcompiler-v2%5D%20%3CPLEASE%20NAME%20IT%3E&body=%3CPLEASE%20DESCRIBE%20IT%3E&labels=compiler-v2&projects=aptos-labs/16). If you are able to provide a small piece of Move code which reproduces the issue, debugging and fixing it will be easier for us.

## Using Move on Aptos Compiler

[](#using-move-on-aptos-compiler)

Ensure to have installed the latest version of the Aptos CLI:

```
aptos update aptos # on supported OSbrew upgrade aptos # on MacOS
```

Move on Aptos compiler and Move 2 are now the default, requiring no changes to your usage. Examples:

```
aptos move compileaptos move testaptos move prove
```

# Compiling (Move)

> Learn about compiling for Move smart contract development on Aptos blockchain.

Note

Ensure that your [CLI](/build/cli) is up to date before compiling.

## `aptos move compile`

[](#aptos-move-compile)

Once you have a package set up, you can compile your Move code by doing:

```
aptos move compile
```

If run successfully, you should receive a Terminal output like so

```
{  "Result": [    "<PUBLISHING_ADDRESS>::<MODULE_NAME>"  ]}
```

Note

You may need to add named addresses, especially for examples. For example, with the Hello Blockchain Move example, you will need to add the `hello_blockchain` named address:

```
aptos move compile --named-addresses hello_blockchain=default
```

## Unpacking Build

[](#unpacking-build)

Compiled Move packages contain a folder structure that resembles the one below.

*   build/
    
    *   package\_name/
        
        *   bytecode\_modules/
            
            *   dependencies/
                
                *   …
                
            *   module\_name.mv
            
        *   source\_maps/
            
            *   dependencies/
                
                *   …
                
            *   module\_name.mvsm
            
        *   sources/
            
            *   dependencies/
                
                *   …
                
            *   module\_name.move
            
        *   BuildInfo.yaml
        
    
*   scripts/
    
    *   …
    
*   sources/
    
    *   module\_name.move
    
*   tests/
    
    *   …
    
*   Move.toml

### `bytecode_modules`

[](#bytecode_modules)

The bytecode modules folder contains the compiled Move bytecode for your module(s) (such as `module_name.mv`). To learn more about the bytecode and its security features, see [why move?](/build/smart-contracts/why-move)

### `source_maps`

[](#source_maps)

The source maps folder contains source maps (such as `module_name.mvsm`) which allow users to map the compiled bytecode back to the source code and relevant dependencies.

# Confidential Asset (CA)

> Learn about confidential asset for Move smart contract development on Aptos blockchain.

The Confidential Asset Standard (also known as "Confidential Asset" or "CA") is a privacy-focused protocol for managing Fungible Assets (FA). It allows users to perform transactions with hidden FA amounts while keeping sender and recipient addresses publicly visible.

This standard allows any FA to be wrapped into a corresponding Confidential Asset, ensuring compatibility with existing tokens. It supports 64-bit transfers, and balances of up to 128 bits.

Operations on Confidential Asset balances (confidential balances), require zero-knowledge proofs (ZKPs) to verify transaction correctness without revealing hidden amounts and other sensitive data.

Note

Interacting directly with Confidential Asset's smart contracts is highly complex. Developers are encouraged to create external services to manage tasks like generating ZKPs, recovering keys, and decrypting balances. To assist with this, we've developed a TypeScript SDK, with full documentation available [here](/build/sdks/ts-sdk/confidential-asset).

Note

This documentation explains the contract's operations and offers insights into the protocol core processes. Cryptographic and mathematical details are explained superficially.

## Confidential Asset Store

[](#confidential-asset-store)

For every confidential asset a user registers, they generate a unique keypair:

*   An encryption key (EK) stored on-chain.
*   A decryption key (DK) kept securely by the user.

These keys are standalone and should not be confused with the user's Aptos account keys.

Each confidential balance is split into two parts:

*   `pending_balance` - accumulates all incoming transactions.
*   `actual_balance` - used exclusively for outgoing transactions.

Both balances are encrypted with the same user's EK, ensuring underlying amounts remain private.

Note

This separation protects against "front-running" attacks. Specifically, if there was a single balance, an attacker could revert a user's transaction by sending a small payment, altering the balance and, consequently, invalidating the user's ZKP.

The confidential balance and its associated encryption key are stored in the `ConfidentialAssetStore` resource. The `ConfidentialAssetStore` is instantiated for each confidential asset the user has and managed by the `confidential_asset` module:

```
struct ConfidentialAssetStore has key {    pending_balance: confidential_balance::CompressedConfidentialBalance,    actual_balance: confidential_balance::CompressedConfidentialBalance,    ek: twisted_elgamal::CompressedPubkey,    // ...}
```

## Confidential Balance

[](#confidential-balance)

Confidential balances handle token amounts by splitting them into smaller units called chunks. Each chunk represents a portion of the total amount and is encrypted individually using the user’s EK. This design ensures efficient management of balances.

### Chunks

[](#chunks)

The pending balance consists of four chunks that hold all incoming transfers. It can handle up to 2^16 64-bit transfers before requiring a rollover to the actual balance. During this accumulation, the pending balance chunks can grow up to 32 bits each.

The actual balance consists of eight chunks, supporting 128-bit values. After any operation the actual balance should be [normalized](#normaliztion) back to 16-bit chunks to maintain efficient decryption.

The `ConfidentialBalance` struct from the `confidential_balance` module is used to represent both the pending and actual balances:

```
struct ConfidentialBalance has drop {    chunks: vector<twisted_elgamal::Ciphertext>,}
```

### Encryption and Decryption

[](#encryption-and-decryption)

Encryption involves:

*   Splitting the total amount into 16-bit chunks.
*   Applying the user's EK to encrypt each chunk individually.

Decryption involves:

*   Applying the user’s DK to decrypt each chunk.
*   Solving a discrete logarithm (DL) problem for each chunk to recover the original values.
*   Combining the recovered values to reconstruct the total amount.

### Normalization

[](#normalization)

Normalization ensures chunks are always reduced to manageable sizes (16 bits). Without normalization, chunks can grow too large, making the decryption process (solving DL) significantly slower or even impractical. This mechanism is automatically applied to the actual balance after each operation, ensuring that users can always decrypt their balances, even as balances grow through multiple transactions. Only after a rollover, users are required to normalize the actual balance [manually](#normalization).

### Homomorphic Encryption

[](#homomorphic-encryption)

The protocol utilizes Homomorphic encryption, allowing arithmetic operations on confidential balances without their decryption. This capability is essential for updating the receiver's pending balance during transfers and for rollovers, where the user's pending balance is added to the actual one.

## Architecture

[](#architecture)

The diagram below shows the relationship between Confidential Asset modules:

![CA Modules Relationship](/_astro/ca-diagram-light.CXM4rZpp.png) ![CA Modules Relationship](/_astro/ca-diagram-dark.WFjNxHwJ.png)

Users interact with the `confidential_asset` module to perform operations on their confidential balances. The `confidential_asset` module calls the `confidential_balance` module to manage the confidential balances and the `confidential_proof` module to verify ZKPs. Under the hood, the `confidential_balance` module uses the `twisted_elgamal` module for operations on chunks.

## Entry functions

[](#entry-functions)

### Register

[](#register)

```
public entry fun register(sender: &signer, token: Object<Metadata>, ek: vector<u8>)
```

```
#[view]public fun has_confidential_asset_store(user: address, token: Object<Metadata>): bool
```

Users must register a `ConfidentialAssetStore` for each token they intend to transact with. As part of this process, users are required to generate a keypair (EK and DK) on their end.

When a `ConfidentialAssetStore` is first registered, the confidential balance is set to zero, represented as zero ciphertexts for both the `pending_balance` and `actual_balance`.

You can also check if a user has a `ConfidentialAssetStore` for a specific token using the `has_confidential_asset_store` function.

Note

Although it is recommended to generate a unique keypair for each token to enhance security, it's not restricted to reuse the same encryption key across multiple tokens if preferred.

Caution

This operation is expensive as it initializes a new storage and storage fees far exceed execution fees. However, users call it only once per token.

```
#[test_only]module confidential_asset_example::register_example {    /// ...
    fun register(bob: &signer, token: Object<Metadata>) {        let bob_addr = signer::address_of(bob);
        // It's a test-only function, so we don't need to worry about the security of the keypair.        let (_bob_dk, bob_ek) = twisted_elgamal::generate_twisted_elgamal_keypair();
        let bob_ek = twisted_elgamal::pubkey_to_bytes(&bob_ek);
        confidential_asset::register(bob, token, bob_ek);
        print(&utf8(b"Bob's pending balance is zero:"));        print(&confidential_asset::pending_balance(bob_addr, token));
        print(&utf8(b"Bob's actual balance is zero:"));        print(&confidential_asset::actual_balance(bob_addr, token));
        print(&utf8(b"Bob's encryption key is set:"));        print(&confidential_asset::encryption_key(bob_addr, token));    }}
```

### Deposit

[](#deposit)

```
public entry fun deposit(sender: &signer, token: Object<Metadata>, amount: u64)
```

```
public entry fun deposit_to(sender: &signer, token: Object<Metadata>, to: address, amount: u64)
```

The `deposit` and `deposit_to` functions bring tokens into the protocol, transferring the passed amount from primary FA store of the sender to the pending balance of the recipient.

The amount in this function is publicly visible, as adding new tokens to the protocol requires a normal transfer. However, tokens within the protocol become obfuscated through confidential transfers, ensuring privacy in subsequent transactions.

Note

If you want to have a hidden amount from the beginning, use the `confidential_transfer` function instead.

```
#[test_only]module confidential_asset_example::deposit_example {    /// ...
    fun deposit(bob: &signer, alice: &signer, token: Object<Metadata>) {        let bob_addr = signer::address_of(bob);        let alice_addr = signer::address_of(alice);
        // It's a test-only function, so we don't need to worry about the security of the keypair.        let (bob_dk, bob_ek) = twisted_elgamal::generate_twisted_elgamal_keypair();        let (alice_dk, alice_ek) = twisted_elgamal::generate_twisted_elgamal_keypair();
        let bob_ek = twisted_elgamal::pubkey_to_bytes(&bob_ek);        let alice_ek = twisted_elgamal::pubkey_to_bytes(&alice_ek);
        confidential_asset::register(bob, token, bob_ek);        confidential_asset::register(alice, token, alice_ek);
        print(&utf8(b"Bob's FA balance before the deposit is 500:"));        print(&primary_fungible_store::balance(bob_addr, token));
        assert!(primary_fungible_store::balance(bob_addr, token) == 500);
        let bob_amount = 100;        let alice_amount = 200;
        // The balance is not hidden yet, because we explicitly pass the amount to the function.        confidential_asset::deposit(bob, token, bob_amount);        confidential_asset::deposit_to(bob, token, alice_addr, alice_amount);
        print(&utf8(b"Bob's FA balance after the deposit is 200:"));        print(&primary_fungible_store::balance(bob_addr, token));
        assert!(primary_fungible_store::balance(bob_addr, token) == 200);
        print(&utf8(b"Bob's pending balance is not zero:"));        print(&confidential_asset::pending_balance(bob_addr, token));
        // In real world, we would not be able to see the someone else's balance as it requires        // the knowledge of the decryption key.        // The balance decryption requires solving the discrete logarithm problem,        // so we just check if the passed amount is correct for simplicity.        assert!(confidential_asset::verify_pending_balance(bob_addr, token, &bob_dk, bob_amount));
        print(&utf8(b"Alice's pending balance is not zero:"));        print(&confidential_asset::pending_balance(alice_addr, token));
        assert!(confidential_asset::verify_pending_balance(alice_addr, token, &alice_dk, alice_amount));    }}
```

### Rollover Pending Balance

[](#rollover-pending-balance)

```
public entry fun rollover_pending_balance(sender: &signer, token: Object<Metadata>)
```

The `rollover_pending_balance` function adds the pending balance to the actual one, resetting the pending balance to zero. It works with no additional proofs as this function utilizes properties of the [Homomorphic encryption](#homomorphic-encryption) used in the protocol.

Note

You cannot spend money from the pending balance directly. It must be rolled over to the actual balance first.

Caution

The actual balance must be [normalized](#normalization) before performing a rollover. If it is not normalized, you can use the [`normalize`](#normalize) function to do so.

Caution

Calling the `rollover_pending_balance` function in a separate transaction is crucial for preventing "front-running" attacks.

```
#[test_only]module confidential_asset_example::rollover_example {    /// ...
    fun rollover(bob: &signer, token: Object<Metadata>) {        let bob_addr = signer::address_of(bob);
        // It's a test-only function, so we don't need to worry about the security of the keypair.        let (bob_dk, bob_ek) = twisted_elgamal::generate_twisted_elgamal_keypair();
        let bob_ek = twisted_elgamal::pubkey_to_bytes(&bob_ek);
        let bob_amount = 100;
        confidential_asset::register(bob, token, bob_ek);        confidential_asset::deposit(bob, token, bob_amount);
        print(&utf8(b"Bob's pending balance is NOT zero:"));        print(&confidential_asset::pending_balance(bob_addr, token));
        print(&utf8(b"Bob's actual balance is zero:"));        print(&confidential_asset::actual_balance(bob_addr, token));
        assert!(confidential_asset::verify_pending_balance(bob_addr, token, &bob_dk, bob_amount));        assert!(confidential_asset::verify_actual_balance(bob_addr, token, &bob_dk, 0));
        // No explicit normalization is required, as the actual balance is already normalized.        assert!(confidential_asset::is_normalized(bob_addr, token));
        confidential_asset::rollover_pending_balance(bob, token);
        print(&utf8(b"Bob's pending balance is zero:"));        print(&confidential_asset::pending_balance(bob_addr, token));
        print(&utf8(b"Bob's actual balance is NOT zero:"));        print(&confidential_asset::actual_balance(bob_addr, token));
        assert!(confidential_asset::verify_pending_balance(bob_addr, token, &bob_dk, 0));        assert!(confidential_asset::verify_actual_balance(bob_addr, token, &bob_dk, (bob_amount as u128)));    }}
```

### Confidential Transfer

[](#confidential-transfer)

```
public entry fun confidential_transfer(    sender: &signer,    token: Object<Metadata>,    to: address,    new_balance: vector<u8>,    sender_amount: vector<u8>,    recipient_amount: vector<u8>,    auditor_eks: vector<u8>,    auditor_amounts: vector<u8>,    zkrp_new_balance: vector<u8>,    zkrp_transfer_amount: vector<u8>,    sigma_proof: vector<u8>)
```

The `confidential_transfer` function transfers tokens from the sender's actual balance to the recipient's pending balance. The sender encrypts the transferred amount using the recipient's encryption key, enabling the recipient's confidential balance to be updated [homomorphically](#homomorphic-encryption).

To ensure transparency, the sender could also encrypt the transferred amount using the auditors' EKs, allowing the auditors to decrypt the transferred amount on their end.

Caution

If the global auditor is set, it must be included in the `auditor_eks` list as the FIRST element (see the example below).

Note

Once a user has participated in at least one transfer, their balance becomes "hidden". This means that neither the transferred amount nor the updated balances of the sender and recipient are visible to external observers.

```
#[test_only]module confidential_asset_example::transfer_example {    /// ...
    fun transfer(bob: &signer, alice: &signer, token: Object<Metadata>) {        let bob_addr = signer::address_of(bob);        let alice_addr = signer::address_of(alice);
        // It's a test-only function, so we don't need to worry about the security of the keypair.        let (bob_dk, bob_ek) = twisted_elgamal::generate_twisted_elgamal_keypair();        let (alice_dk, alice_ek) = twisted_elgamal::generate_twisted_elgamal_keypair();
        // Note: If the asset-specific auditor is set, we need to include it in the `auditor_eks` vector as the FIRST element.        //        // let asset_auditor_ek = confidential_asset::get_auditor(token);        // let auditor_eks = vector[];        // if (asset_auditor_ek.is_some()) {        //     auditor_eks.push_back(asset_auditor_ek.extract());        // };
        let (_, auditor_ek) = twisted_elgamal::generate_twisted_elgamal_keypair();        let auditor_eks = vector[auditor_ek];
        let bob_ek_bytes = twisted_elgamal::pubkey_to_bytes(&bob_ek);        let alice_ek_bytes = twisted_elgamal::pubkey_to_bytes(&alice_ek);
        confidential_asset::register(bob, token, bob_ek_bytes);        confidential_asset::register(alice, token, alice_ek_bytes);
        // Bob's current balance is 300, and he wants to transfer 50 to Alice, whose balance is zero.        let bob_current_amount = 300;        let bob_new_amount = 250;        let transfer_amount = 50;        let alice_current_amount = 0;        let alice_new_amount = 50;
        confidential_asset::deposit(bob, token, bob_current_amount);        confidential_asset::rollover_pending_balance(bob, token);
        print(&utf8(b"Bob's actual balance is 300"));        assert!(confidential_asset::verify_actual_balance(bob_addr, token, &bob_dk, (bob_current_amount as u128)));
        print(&utf8(b"Alice's pending balance is zero"));        assert!(confidential_asset::verify_pending_balance(alice_addr, token, &alice_dk, alice_current_amount));
        let current_balance = confidential_balance::decompress_balance(            &confidential_asset::actual_balance(bob_addr, token)        );
        let (            proof,            // New balance is the balance after the transfer encrypted with the sender's encryption key.            // It will be set as the new actual balance for the sender.            new_balance,            // Transfer amount encrypted with the sender's encryption key.            // Used for indexing purposes only.            sender_amount,            // Transfer amount encrypted with the recipient's encryption key.            // It will be Homomorphically added to the recipient's pending balance.            recipient_amount,            // Transfer amount encrypted with the auditors' encryption keys.            // It won't be stored on-chain, but an auditor can decrypt the transfer amount with its dk.            auditor_amounts        ) = confidential_proof::prove_transfer(            &bob_dk,            &bob_ek,            &alice_ek,            transfer_amount,            bob_new_amount,            ¤t_balance,            &auditor_eks,        );
        let (            sigma_proof,            zkrp_new_balance,            zkrp_transfer_amount        ) = confidential_proof::serialize_transfer_proof(&proof);
        confidential_asset::confidential_transfer(            bob,            token,            alice_addr,            confidential_balance::balance_to_bytes(&new_balance),            confidential_balance::balance_to_bytes(&sender_amount),            confidential_balance::balance_to_bytes(&recipient_amount),            confidential_asset::serialize_auditor_eks(&auditor_eks),            confidential_asset::serialize_auditor_amounts(&auditor_amounts),            zkrp_new_balance,            zkrp_transfer_amount,            sigma_proof        );
        print(&utf8(b"Bob's actual balance is 250"));        assert!(confidential_asset::verify_actual_balance(bob_addr, token, &bob_dk, bob_new_amount));
        print(&utf8(b"Alice's pending balance is 50"));        assert!(confidential_asset::verify_pending_balance(alice_addr, token, &alice_dk, alice_new_amount));    }}
```

### Withdraw

[](#withdraw)

```
public entry fun withdraw(    sender: &signer,    token: Object<Metadata>,    amount: u64,    new_balance: vector<u8>,    zkrp_new_balance: vector<u8>,    sigma_proof: vector<u8>)
```

```
public entry fun withdraw_to(    sender: &signer,    token: Object<Metadata>,    to: address,    amount: u64,    new_balance: vector<u8>,    zkrp_new_balance: vector<u8>,    sigma_proof: vector<u8>)
```

The `withdraw` and `withdraw_to` allow a user to withdraw tokens from the protocol, transferring the passed amount from the actual balance of the sender to the primary FA store of the recipient. This function enables users to release tokens while not revealing their remaining balances.

Caution

Attempting to withdraw more tokens than available will cause an error.

```
#[test_only]module confidential_asset_example::withdraw_example {    /// ...
    fun withdraw(bob: &signer, alice: &signer, token: Object<Metadata>) {        let bob_addr = signer::address_of(bob);        let alice_addr = signer::address_of(alice);
        // It's a test-only function, so we don't need to worry about the security of the keypair.        let (bob_dk, bob_ek) = twisted_elgamal::generate_twisted_elgamal_keypair();        let (_alice_dk, alice_ek) = twisted_elgamal::generate_twisted_elgamal_keypair();
        let bob_ek_bytes = twisted_elgamal::pubkey_to_bytes(&bob_ek);        let alice_ek_bytes = twisted_elgamal::pubkey_to_bytes(&alice_ek);
        confidential_asset::register(bob, token, bob_ek_bytes);        confidential_asset::register(alice, token, alice_ek_bytes);
        let bob_current_amount = 500;        let bob_new_amount = 450;        let transfer_amount = 50;
        // Bob withdraws all available tokens        confidential_asset::deposit(bob, token, (bob_current_amount as u64));        confidential_asset::rollover_pending_balance(bob, token);
        print(&utf8(b"Alice's FA balance before the withdrawal is zero:"));        print(&primary_fungible_store::balance(alice_addr, token));
        assert!(primary_fungible_store::balance(alice_addr, token) == 0);
        print(&utf8(b"Bob's actual balance before the withdrawal is 500"));        assert!(confidential_asset::verify_actual_balance(bob_addr, token, &bob_dk, bob_current_amount));
        let current_balance = confidential_balance::decompress_balance(            &confidential_asset::actual_balance(bob_addr, token)        );
        let (proof, new_balance) = confidential_proof::prove_withdrawal(            &bob_dk,            &bob_ek,            transfer_amount,            bob_new_amount,            ¤t_balance        );
        let new_balance = confidential_balance::balance_to_bytes(&new_balance);        let (sigma_proof, zkrp_new_balance) = confidential_proof::serialize_withdrawal_proof(&proof);
        confidential_asset::withdraw_to(            bob,            token,            alice_addr,            transfer_amount,            new_balance,            zkrp_new_balance,            sigma_proof        );
        print(&utf8(b"Alice's FA balance after the withdrawal is 50:"));        print(&primary_fungible_store::balance(alice_addr, token));
        assert!(primary_fungible_store::balance(alice_addr, token) == 50);
        print(&utf8(b"Bob's actual balance after the withdrawal is 450"));        assert!(confidential_asset::verify_actual_balance(bob_addr, token, &bob_dk, bob_new_amount));    }}
```

### Rotate Encryption Key

[](#rotate-encryption-key)

```
public entry fun rotate_encryption_key(    sender: &signer,    token: Object<Metadata>,    new_ek: vector<u8>,    new_balance: vector<u8>,    zkrp_new_balance: vector<u8>,    sigma_proof: vector<u8>)
```

```
public entry fun rotate_encryption_key_and_unfreeze(    sender: &signer,    token: Object<Metadata>,    new_ek: vector<u8>,    new_confidential_balance: vector<u8>,    zkrp_new_balance: vector<u8>,    rotate_proof: vector<u8>)
```

```
public entry fun rollover_pending_balance_and_freeze(sender: &signer, token: Object<Metadata>)
```

The `rotate_encryption_key` function modifies the user's EK and re-encrypts the actual balance with the new EK. This function checks that the pending balance is zero before proceeding, guaranteeing that the user does not lose funds during the rotation.

To facilitate the rotation process:

*   The pending balance must first be rolled over and frozen by calling `rollover_pending_balance_and_freeze`. This prevents new transactions from being processed during the key rotation.
*   Then the EK can be rotated and unfrozen using `rotate_encryption_key_and_unfreeze`.

Caution

Calling `rotate_encryption_key` with a non-zero pending balance will cause an error.

```
#[test_only]module confidential_asset_example::rotate_example {    /// ...
    fun rotate(bob: &signer, token: Object<Metadata>) {        let bob_addr = signer::address_of(bob);
        // It's a test-only function, so we don't need to worry about the security of the keypair.        let (bob_current_dk, bob_current_ek) = twisted_elgamal::generate_twisted_elgamal_keypair();        let (bob_new_dk, bob_new_ek) = twisted_elgamal::generate_twisted_elgamal_keypair();
        let bob_current_ek_bytes = twisted_elgamal::pubkey_to_bytes(&bob_current_ek);        let bob_new_ek_bytes = twisted_elgamal::pubkey_to_bytes(&bob_new_ek);
        let bob_amount = 100;
        confidential_asset::register(bob, token, bob_current_ek_bytes);        confidential_asset::deposit(bob, token, (bob_amount as u64));
        // We need to rollover the pending balance and freeze the token to prevent any new deposits being come.        confidential_asset::rollover_pending_balance_and_freeze(bob, token);
        print(&utf8(b"Bob's encryption key before the rotation:"));        print(&confidential_asset::encryption_key(bob_addr, token));
        assert!(confidential_asset::verify_actual_balance(bob_addr, token, &bob_current_dk, bob_amount));
        let current_balance = confidential_balance::decompress_balance(            &confidential_asset::actual_balance(bob_addr, token)        );
        let (proof, new_balance) = confidential_proof::prove_rotation(            &bob_current_dk,            &bob_new_dk,            &bob_current_ek,            &bob_new_ek,            bob_amount,            ¤t_balance        );
        let (            sigma_proof,            zkrp_new_balance        ) = confidential_proof::serialize_rotation_proof(&proof);
        // After rotating the encryption key, we unfreeze the token to allow new deposits.        confidential_asset::rotate_encryption_key_and_unfreeze(            bob,            token,            bob_new_ek_bytes,            confidential_balance::balance_to_bytes(&new_balance),            zkrp_new_balance,            sigma_proof        );
        print(&utf8(b"Bob's encryption key after the rotation:"));        print(&confidential_asset::encryption_key(bob_addr, token));
        // Note that here we use the new decryption key to verify the actual balance.        assert!(confidential_asset::verify_actual_balance(bob_addr, token, &bob_new_dk, bob_amount));    }}
```

### Normalize

[](#normalize)

```
public entry fun normalize(    sender: &signer,    token: Object<Metadata>,    new_balance: vector<u8>,    zkrp_new_balance: vector<u8>,    sigma_proof: vector<u8>)
```

```
public fun is_normalized(user: address, token: Object<Metadata>): bool
```

The `normalize` function ensures that the actual balance is reduced to 16-bit chunks for [efficient decryption](#normalization). This is necessary only before the `rollover_pending_balance` operation, which requires the actual balance to be normalized beforehand.

All other functions, such as `withdraw` or `confidential_transfer`, handle normalization implicitly, making manual normalization unnecessary in those cases.

Note

All functions except `rollover_pending_balance` perform implicit normalization.

Caution

Calling a `rollover_pending_balance` when the actual balance is already normalized will cause an error. You can check if the actual balance is normalized using the `is_normalized` function.

```
#[test_only]module confidential_asset_example::normalize_example {    /// ...
    fun normalize(bob: &signer, token: Object<Metadata>) {        let bob_addr = signer::address_of(bob);
        // It's a test-only function, so we don't need to worry about the security of the keypair.        let (bob_dk, bob_ek) = twisted_elgamal::generate_twisted_elgamal_keypair();
        let bob_ek_bytes = twisted_elgamal::pubkey_to_bytes(&bob_ek);
        let bob_amount = 500;
        confidential_asset::register(bob, token, bob_ek_bytes);        confidential_asset::deposit(bob, token, (bob_amount as u64));
        // The rollover function is the only function that requires the actual balance to be normalized        // beforehand and leaves it unnormalized after execution, no matter what the pending balance was.        confidential_asset::rollover_pending_balance(bob, token);
        assert!(!confidential_asset::is_normalized(bob_addr, token));
        confidential_asset::deposit(bob, token, (bob_amount as u64));
        // Before performing a second rollover, the actual balance must be normalized.        // You will get an error if you try to rollover an unnormalized balance:        // confidential_asset::rollover_pending_balance(bob, token);
        let current_balance = confidential_balance::decompress_balance(            &confidential_asset::actual_balance(bob_addr, token)        );
        let (            proof,            new_balance        ) = confidential_proof::prove_normalization(            &bob_dk,            &bob_ek,            bob_amount,            ¤t_balance        );
        let (sigma_proof, zkrp_new_balance) = confidential_proof::serialize_normalization_proof(&proof);
        confidential_asset::normalize(            bob,            token,            confidential_balance::balance_to_bytes(&new_balance),            zkrp_new_balance,            sigma_proof        );
        assert!(confidential_asset::is_normalized(bob_addr, token));        assert!(confidential_asset::verify_actual_balance(bob_addr, token, &bob_dk, bob_amount));
        // A rollover can be performed once the balance is normalized.        // Note that functions like `withdraw` and `confidential_transfer` do not require the actual balance        // to be normalized beforehand, as zk-proofs guarantee that the actual balance is normalized after        // their execution.        confidential_asset::rollover_pending_balance(bob, token);    }}
```

## Useful Resources

[](#useful-resources)

*   [Confidential Asset SDK](/build/sdks/ts-sdk/confidential-asset)

# Create Package (Move)

> Learn about create package for Move smart contract development on Aptos blockchain.

Note

We recommend installing the Aptos CLI before beginning. If you haven't already installed the Aptos CLI, see the [CLI section](/build/cli)

1.  aptos move init
    
    In a new project directory, initialize a Move package by running:
    
    ```
    aptos move init --name <PROJECT_NAME>
    ```
    
    You should now have a Move project that looks like so:
    
    *   scripts/
        
        *   …
        
    *   sources/
        
        *   …
        
    *   tests/
        
        *   …
        
    *   Move.toml
    
    Note
    
    You can also create a Move package from a [template](/build/cli/start-from-template).
    
2.  Update Move.toml
    
    In `Move.toml`, fill in the following key information:
    
    1.  `name`: name of your package
    2.  `version`: package version (default is `"0.0.0"`)
    3.  `addresses`: Describes which address the module will be deployed to. These are named addresses that can be used as aliases. In the below example, we will use `hello_blockchain` as the named address.
    4.  `dependencies`: You will likely want to use `AptosFramework` and other [Third Party Dependencies](/build/smart-contracts/third-party-dependencies)
    
    Below is an example
    
    ```
    [package]name = "Examples"version = "0.0.0"
    [addresses]hello_blockchain = "_"
    [dependencies.AptosFramework]git = "https://github.com/aptos-labs/aptos-framework.git"rev = "mainnet"subdir = "aptos-framework"
    ```
    
3.  Add to sources directory
    
    Add your code in the `sources` directory. Here we have a `hello_blockchain.move` example.
    
    hello\_blockchain.move
    
    ```
    module hello_blockchain::message {    use std::error;    use std::signer;    use std::string;    use aptos_framework::event;    #[test_only]    use std::debug;
        //:!:>resource    struct MessageHolder has key {        message: string::String,    }    //<:!:resource
        #[event]    struct MessageChange has drop, store {        account: address,        from_message: string::String,        to_message: string::String,    }
        /// There is no message present    const ENO_MESSAGE: u64 = 0;
        #[view]    public fun get_message(addr: address): string::String acquires MessageHolder {        assert!(exists<MessageHolder>(addr), error::not_found(ENO_MESSAGE));        borrow_global<MessageHolder>(addr).message    }
        public entry fun set_message(account: signer, message: string::String)    acquires MessageHolder {        let account_addr = signer::address_of(&account);        if (!exists<MessageHolder>(account_addr)) {            move_to(&account, MessageHolder {                message,            })        } else {            let old_message_holder = borrow_global_mut<MessageHolder>(account_addr);            let from_message = old_message_holder.message;            event::emit(MessageChange {                account: account_addr,                from_message,                to_message: copy message,            });            old_message_holder.message = message;        }    }
        #[test(account = @0x1)]    public entry fun sender_can_set_message(account: signer) acquires MessageHolder {        let msg: string::String = string::utf8(b"Running test for sender_can_set_message...");        debug::print(&msg);
            let addr = signer::address_of(&account);        aptos_framework::account::create_account_for_test(addr);        set_message(account, string::utf8(b"Hello, Blockchain"));
            assert!(            get_message(addr) == string::utf8(b"Hello, Blockchain"),            ENO_MESSAGE        );    }}
    ```

# Cryptography

> Learn about cryptography for Move smart contract development on Aptos blockchain.

Cryptography plays an integral role in ensuring the security, integrity, confidentiality, and immutability of data in blockchain systems. The Aptos adapter for Move provides developers with an array of cryptographic primitives to cater to this need. This document delves into the cryptographic functionalities offered by Move on Aptos and elucidates the principles that drive their design.

## Cryptographic primitives

[](#cryptographic-primitives)

Move, through the Aptos adapter, encompasses several fundamental cryptographic tools:

1.  [Cryptographic Hash Functions](#cryptographic-hash-functions) – Algorithms that produce a fixed-size output (hash) from variable-sized input data. Supported functions include SHA2-256, SHA3-256, Keccak256, and Blake2b-256.
2.  [Digital Signature Verification](#digital-signature-verification) – Algorithms for signing a message to ensure its integrity, authenticate its sender, ensure non-repudiation, or any combination thereof. Supported signature schemes include Ed25519, ECDSA, and BLS.
3.  [Elliptic Curve Arithmetic](#elliptic-curve-arithmetic) – Elliptic curves are one of the building blocks of advanced cryptographic primitives, such as digital signatures, public-key encryption or verifiable secret sharing. Supported curves include Ristretto255, BN254 and BLS12-381.
4.  [Zero-Knowledge Proofs (ZKP)](#building-powerful-cryptographic-applications) – These cryptographic techniques enable a party to prove that a relation R(x;w)R(x; w)R(x;w) is satisfied on a public statement xxx without leaking the secret witness www that makes it hold. Currently, we support Groth16 ZKP verification and Bulletproofs ZK range proof verification.

Three fundamental principles guide the design and integration of the Aptos cryptographic extensions into Move:

1.  **Economic Gas Usage** – Striving to minimize gas costs for Move developers by implementing key primitives as [Move native functions](https://aptos-labs.github.io/move-book/functions.html#native-functions). For example, see the module for [BLS signatures over BLS12-381 elliptic curves](https://github.com/aptos-labs/aptos-core/blob/main/aptos-move/framework/aptos-stdlib/sources/cryptography/bls12381.move).
2.  **Type-Safe APIs** – Ensuring that APIs are resistant to common mistakes, type-safety enhances code reliability and promotes an efficient development process. For an example, see the [Ed25519 signature module](https://github.com/aptos-labs/aptos-core/blob/main/aptos-move/framework/aptos-stdlib/sources/cryptography/ed25519.move).
3.  **Empowerment of Developers** – In instances where native functions are unavailable, we empower developers to build their own cryptographic primitives on top of abstract cryptographic building blocks such as _finite fields_ and _Abelian groups_. Refer to the [`aptos_std::crypto_algebra`](https://github.com/aptos-labs/aptos-core/blob/main/aptos-move/framework/aptos-stdlib/sources/cryptography/crypto_algebra.move) module for more insights.

Continue reading to delve a bit deeper and uncover some of the intricacies behind these extensions, as well as the range of applications they empower. For the most comprehensive understanding of this subject, refer to the [cryptography Move modules code](https://github.com/aptos-labs/aptos-core/tree/main/aptos-move/framework/aptos-stdlib/sources/cryptography).

## Cryptographic hash functions

[](#cryptographic-hash-functions)

Developers can now use more cryptographic hash functions in Move via the [`aptos_std::aptos_hash`](https://github.com/aptos-labs/aptos-core/blob/main/aptos-move/framework/aptos-stdlib/sources/hash.move) module:

| Hash function | Hash size (bits) | Cost for hashing 1KiB (in internal gas units) | Collision-resistance security (bits) | | ------------- | ---------------- | --------------------------------------------- | ------------------------------------ | | Keccak256 | 256 | 1,001,600 | 128 | | SHA2-256 | 256 | 1,084,000 | 128 | | SHA2-512 | 512 | 1,293,600 | 256 | | SHA3-256 | 256 | 1,001,600 | 128 | | SHA3-512 | 512 | 1,114,000 | 256 | | RIPEMD160 | 160 | 1,084,000 | 80 (**weak**) | | Blake2b-256 | 256 | 342,200 | 128 |

All hash functions have the same security properties (e.g., one-wayness, collision resistance, etc.), but their security levels are different.

Caution

RIPEMD160 should be avoided as a collision-resistant function due to its 80-bit security level. It is mainly supported for backward-compatibility reasons: e.g., Bitcoin address derivation relies on RIPEMD160.

Some of these functions can be used for interoperability with other chains (e.g., verifying Ethereum Merkle proofs via [`aptos_std::aptos_hash::keccak256`](https://github.com/aptos-labs/aptos-core/blob/137acee4c6dddb1c86398dce25b041d78a3028d3/aptos-move/framework/aptos-stdlib/sources/hash.move#L35)). Others, have lower gas costs, such as [`aptos_std::aptos_hash::blake2b_256`](https://github.com/aptos-labs/aptos-core/blob/137acee4c6dddb1c86398dce25b041d78a3028d3/aptos-move/framework/aptos-stdlib/sources/hash.move#L69). In general, a wider variety of hash functions give developers additional freedom in terms of both security and interoperability with other off-chain cryptographic systems.

## Digital signature verification

[](#digital-signature-verification)

Developers can now use a _type-safe_ API for verifying many kinds of digital signatures in Move:

| Signature scheme | Curve | Sig. size (bytes) | PK size (bytes) | Malleability | Assumptions | Pros | Cons | | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | ----------------- | --------------- | ------------ | ----------- | ------------- | ------------------- | | [ECDSA](https://github.com/aptos-labs/aptos-core/blob/main/aptos-move/framework/aptos-stdlib/sources/cryptography/secp256k1.move) | secp256k1 | 64 | 64 | Yes | GGM | Wide adoption | Security proof | | [Ed25519](https://github.com/aptos-labs/aptos-core/blob/main/aptos-move/framework/aptos-stdlib/sources/cryptography/ed25519.move) | Edwards 25519 | 64 | 32 | No | DLA, ROM | Fast | Subtleties | | [MultiEd25519](https://github.com/aptos-labs/aptos-core/blob/main/aptos-move/framework/aptos-stdlib/sources/cryptography/multi_ed25519.move) | Edwards 25519 | 4+t⋅644 + t \\cdot 644+t⋅64 | n⋅32n \\cdot 32n⋅32 | No | DLA, ROM | Easy-to-adopt | Large sig. size | | [MinPK BLS](https://github.com/aptos-labs/aptos-core/blob/main/aptos-move/framework/aptos-stdlib/sources/cryptography/bls12381.move) | BLS12-381 | 96 | 48 | No | CDH, ROM | Versatile | Slower verification | | [MinSig BLS](https://github.com/aptos-labs/aptos-core/blob/7d4fb98c6604c67e526a96f55668e7add7aaebf6/aptos-move/move-examples/drand/sources/drand.move#L57) | BLS12-381 | 48 | 96 | No | CDH, ROM | Versatile | Slower verification |

Note

*   CDH stands for the _"Computational Diffie-Hellman Assumption"_
*   DLA stands for the _"Discrete Log Assumption"_
*   GGM stands for the _"Generic Group Model"_
*   ROM stands for the _"Random Oracle Model"_

The digital signature modules above can be used to build smart contract-based wallets, secure claiming mechanisms for airdrops, or any digital-signature-based access-control mechanism for dapps.

The right choice of a signature scheme in your dapp could depend on many factors:

1.  **Backwards-compatibility**
    *   If your dapp's user base predominantly uses a particular signing mechanism, it would be prudent to support that mechanism for ease of transition and adoption.
        *   Example: If users mainly sign using Ed25519, it becomes a logical choice.
2.  **Ease-of-implementation**
    *   While theoretically sound, complex protocols may be challenging to implement in practice.
        *   Example: Even though ttt\-out-of-nnn threshold protocols for Ed25519 exist, their intricacy on the signer's side might push developers toward MultiEd25519 due to its more straightforward signing implementation.
3.  **Efficiency**
    *   Depending on the dapp's requirements, you might prioritize one aspect of efficiency over another.
        *   Signature size vs. public key size: Some applications might prioritize a smaller signature footprint, while others might emphasize a compact PK.
        *   Signing time vs. verification time: For certain dapps, the signing speed might be more crucial, while for others, rapid signature verification could be the priority.
4.  **Security analysis**
    *   It is essential to consider the underlying assumptions and potential vulnerabilities of a signature scheme.
        *   Example: ECDSA's security is proven under strong assumptions such as the Generic Group Model (GGM).
        *   Malleability concerns: Some signature schemes are susceptible to malleability, where a valid signature, σ\\sigmaσ, can be mauled into a different yet still valid signature, σ\\sigmaσ, for the same message mmm.
5.  **Versatility**
    *   The adaptability and flexibility of signature schemes are important to consider, so you may properly accommodate the cryptographic needs of your dapp.
        *   Example: ttt\-out-of-nnn threshold BLS signatures are very simple to implement.

Caution

Despite its careful, principled design\[^ed25519\], Ed25519 has known implementation subtleties. For example, different implementations could easily disagree on the validity of signatures, especially when batch verification is employed\[^devalence\],^,,\[^eddsa\].

Note

Our [`aptos_std::bls12381`](https://github.com/aptos-labs/aptos-core/blob/main/aptos-move/framework/aptos-stdlib/sources/cryptography/bls12381.move) module for [MinPK BLS](https://datatracker.ietf.org/doc/html/draft-irtf-cfrg-bls-signature-05#name-variants) supports verification of individual signatures, **multi**\-signatures, **aggregate** signatures and **threshold** signatures.

## Elliptic curve arithmetic

[](#elliptic-curve-arithmetic)

While the [hash function](#cryptographic-hash-functions) and [digital signature](#digital-signature-verification) modules should provide enough functionality for most applications, some applications will require more powerful cryptography. Normally, developers of such applications would have to wait until their desired cryptographic functionality is implemented efficiently as a [Move native function](https://aptos-labs.github.io/move-book/functions.html#native-functions) in the [Aptos Move framework](/network/blockchain/move). Instead, we expose basic building blocks that developers can use to implement their own cryptographic primitives directly in the Move language and do so **efficiently**.

Specifically, we currently expose low-level arithmetic operations on two popular elliptic curve groups and their associated finite fields:

1.  Ristretto255, via [`aptos_std::ristretto255`](https://github.com/aptos-labs/aptos-core/blob/main/aptos-move/framework/aptos-stdlib/sources/cryptography/ristretto255.move)
2.  BLS12-381, via [`aptos_std::crypto_algebra`](https://github.com/aptos-labs/aptos-core/blob/main/aptos-move/framework/aptos-stdlib/sources/cryptography/crypto_algebra.move) and the marker types in [`aptos_std::bls12381_algebra`](https://github.com/aptos-labs/aptos-core/blob/main/aptos-move/framework/aptos-stdlib/sources/cryptography/bls12381_algebra.move)
3.  BN254, similarly via `aptos_std::crypto_algebra` and the marker types in [`aptos_std::bls12381_algebra`](https://github.com/aptos-labs/aptos-core/blob/main/aptos-move/framework/aptos-stdlib/sources/cryptography/bn254_algebra.move)

These modules support low-level operations such as:

*   scalar multiplication of elliptic curve points
*   multi-scalar multiplications (MSMs)
*   pairings
*   scalar addition, multiplication, inversion
*   hashing to a scalar or to a point
*   and many more

Examples of powerful applications that can be built on top include:

1.  **Validity rollups** – See the [`groth16` zkSNARK verifier example](#groth16-zksnark-verifier).
2.  **Randomness-based games** – See the [`drand` verifier example](#verifying-randomness-from-the-drand-beacon).
3.  **Privacy-preserving applications** – See the [`veiled_coin` example](#veiled-coins).

### Ristretto255 arithmetic

[](#ristretto255-arithmetic)

The [`aptos_std::ristretto255`](https://github.com/aptos-labs/aptos-core/blob/main/aptos-move/framework/aptos-stdlib/sources/cryptography/ristretto255.move) module provides support for elliptic curve arithmetic on the popular [Ristretto255 curve](https://ristretto.group/). One of the main advantages of Ristretto255 is that it is a prime order group (unlike the Edwards 25519 curve), which obviates small-subgroup attacks on higher-level cryptosystems built on top of it. Furthermore, Ristretto255 serialization is canonical and deserialization only accepts canonical encodings, which obviates malleability issues in higher-level protocols.

This module has proven useful for implementing several cryptographic primitives:

1.  **Zero-knowledge Σ\\SigmaΣ\-protocols** – See the [`veiled_coin` example](#veiled-coins).
2.  **ElGamal** encryption – See [`aptos_std::ristretto255_elgamal`](https://github.com/aptos-labs/aptos-core/blob/main/aptos-move/framework/aptos-stdlib/sources/cryptography/ristretto255_elgamal.move)
3.  **Pedersen** commitments – See [`aptos_std::ristretto255_pedersen`](https://github.com/aptos-labs/aptos-core/blob/main/aptos-move/framework/aptos-stdlib/sources/cryptography/ristretto255_pedersen.move)
4.  **Bulletproofs** ZK range proofs\[^bulletproofs\] – See [`aptos_std::ristretto255_bulletproofs`](https://github.com/aptos-labs/aptos-core/blob/main/aptos-move/framework/aptos-stdlib/sources/cryptography/ristretto255_bulletproofs.move)

Need ideas for a cryptosystem to build on top of `ristretto255`? A popular primitive that you could easily build would be the [schnorrkel](https://github.com/w3f/schnorrkel) signature scheme, which is a hardened version of Schnorr signatures over Ristretto255 groups.

### Generic elliptic curve arithmetic

[](#generic-elliptic-curve-arithmetic)

What is better than one curve? More curves!

The [`aptos_std::crypto_algebra`](https://github.com/aptos-labs/aptos-core/blob/main/aptos-move/framework/aptos-stdlib/sources/cryptography/crypto_algebra.move) provides elliptic curve arithmetic operations for **any** supported elliptic curve, including pairing-friendly curves. As a consequence, Move developers can implement a cryptosystem generically over **any** curve that is or will be supported in the future. Compared to fixing a particular curve in the code (e.g., by implementing against the [Ristretto255 module](#ristretto255-arithmetic)), this approach provides more flexibility and lowers development time when migrating to a different curve.

Although currently the `crypto_algebra` module only supports arithmetic over BN254 and BLS12-381 curves (via the marker types declared in [`aptos_std::bls12381_algebra`](https://github.com/aptos-labs/aptos-core/blob/main/aptos-move/framework/aptos-stdlib/sources/cryptography/bls12381_algebra.move) and in [`aptos_std::bn254_algebra`](https://github.com/aptos-labs/aptos-core/blob/main/aptos-move/framework/aptos-stdlib/sources/cryptography/bn254_algebra.move)), more curves will be supported into the future (e.g., Ristretto255, BLS12-377, BW6-761, secp256k1, secp256r1).

As an example, a Move developer can implement the popular Boneh-Lynn-Shacham (BLS) signature scheme generically over **any** curve by using [type arguments](https://aptos-labs.github.io/move-book/functions.html#type-parameters) for the curve type in their implementation:

```
use std::option;use aptos_std::crypto_algebra::{eq, pairing, one, deserialize, hash_to};
/// Example of a BLS signature verification function that works over any pairing-friendly/// group triple `Gr1`, `Gr2`, `GrT` where signatures are in `Gr1` and PKs in `Gr2`./// Points are serialized using the format in `FormatG1` and `FormatG2` and the hashing/// method is `HashMethod`.////// WARNING: This example is type-unsafe and probably not a great fit for production code.public fun bls_verify_sig<Gr1, Gr2, GrT, FormatG1, FormatG2, HashMethod>(    dst:        vector<u8>,    signature:  vector<u8>,    message:    vector<u8>,    public_key: vector<u8>): bool{    let sig  = option::extract(&mut deserialize<Gr1, FormatG1>(&signature));    let pk   = option::extract(&mut deserialize<Gr2, FormatG2>(&public_key));    let hash = hash_to<Gr1, HashMethod>(&dst, &message);
    // Checks if $e(H(m), pk) = e(sig, g_2)$, where $g_2$ generates $\mathbb{G}_2$    eq(        &pairing<Gr1, Gr2, GrT>(&hash, &pk),        &pairing<Gr1, Gr2, GrT>(&sig, &one<Gr2>())    )}
```

Using the `bls_verify_sig` _generic_ function from above, developers can verify BLS signatures over **any** of the supported (pairing-friendly) curves. For example, one can verify [MinSig BLS](https://datatracker.ietf.org/doc/html/draft-irtf-cfrg-bls-signature-05#name-variants) signatures over BLS12-381 curves by calling the function above with the right BLS12-381 marker types as its type arguments:

```
use aptos_std::bls12381_algebra::{    G1, G2, Gt, FormatG1Compr, FormatG2Compr, HashG1XmdSha256SswuRo};
// Aborts with code 1 if the MinSig BLS signature over the BLS12-381 curve fails to verify.assert(    bls_verify_sig<G1, G2, Gt, FormatG1Compr, FormatG2Compr, HashG1XmdSha256SswuRo>(        dst, signature, message, public_key    ),    1);
```

For more use cases of the `crypto_algebra` module, check out some Move examples:

1.  [Verifying Groth16 zkSNARK proofs](#groth16-zksnark-verifier) over **any** curve
2.  [Verifying randomness from the `drand` beacon](#verifying-randomness-from-the-drand-beacon)

## Building powerful cryptographic applications

[](#building-powerful-cryptographic-applications)

### Veiled coins

[](#veiled-coins)

The [`veiled_coin` example](https://github.com/aptos-labs/aptos-core/blob/main/aptos-move/framework/aptos-experimental/sources/veiled_coin/) demonstrates how to use [the Ristretto255 modules from above](#ristretto255-arithmetic) to add a reasonable layer of confidentiality to coin balances and transactions.

Specifically, users can **veil** their balance, keeping it hidden from everyone, including validators. Furthermore, a user can send a **veiled transaction** that hides the transaction amount from everybody, including validators. An important caveat is that veiled transactions do **not** hide the identities of the sender or the recipient.

Danger

This module is educational. It is **not** production-ready. Using it could lead to loss of funds.

### Groth16 zkSNARK verifier

[](#groth16-zksnark-verifier)

The [`groth16` example](https://github.com/aptos-labs/aptos-core/blob/main/aptos-move/move-examples/groth16_example/sources/groth16.move) demonstrates how to verify Groth16 zkSNARK proofs\[^groth16\], which are the shortest, fastest-to-verify, general-purpose zero-knowledge proofs. Importantly, as explained [above](#generic-elliptic-curve-arithmetic), this implementation is _generic_ over **any** curve, making it very easy for Move developers to use it with their favorite (supported) curves.

If you need help converting your `snarkjs` Groth16 VK, proof and public inputs to the expected format for the Move verifier above, you can use [this community tool](https://github.com/zjma/snarkjs-to-aptos).

Note

This code has not been audited by a third-party organization. If using it in a production system, proceed at your own risk.

### Verifying randomness from the `drand` beacon

[](#verifying-randomness-from-the-drand-beacon)

The [`drand` example](https://github.com/aptos-labs/aptos-core/tree/main/aptos-move/move-examples/drand/sources) shows how to verify public randomness from the [drand](https://drand.love) randomness beacon. This randomness can be used in games or any other chance-based smart contract. We give a simple example of a lottery implemented on top of `drand` randomness in [`lottery.move`](https://github.com/aptos-labs/aptos-core/tree/main/aptos-move/move-examples/drand/sources/lottery.move).

Note

This code has not been audited by a third-party organization. If using it in a production system, proceed at your own risk.

Another application that can be built on top of `drand` is time-lock encryption\[^tlock\], which allows users to encrypt information such that it can only be decrypted in a future block. We do not currently have an implementation but the reader is encouraged to write one!

\[^bulletproofs\]: _bulletproofs:_ **Bulletproofs: Short Proofs for Confidential Transactions and More**; by B. Bünz and J. Bootle and D. Boneh and A. Poelstra and P. Wuille and G. Maxwell; in 2018 IEEE Symposium on Security and Privacy

\[^devalence\]: _devalence:_ **It’s 255:19AM. Do you know what your validation criteria are?**, by Henry de Valence, [https://hdevalence.ca/blog/2020-10-04-its-25519am](https://hdevalence.ca/blog/2020-10-04-its-25519am)

\[^ed25519\]: _ed25519:_ **Ed25519: high-speed high-security signatures**, by Daniel J. Bernstein, Niels Duif, Tanja Lange, Peter Schwabe, Bo-Yin Yang, [https://ed25519.cr.yp.to/](https://ed25519.cr.yp.to/)

\[^eddsa\]: _eddsa:_ **Taming the Many EdDSAs**, by Konstantinos Chalkias, François Garillot, Valeria Nikolaenko, in SSR 2020, [https://dl.acm.org/doi/abs/10.1007/978-3-030-64357-7\_4](https://dl.acm.org/doi/abs/10.1007/978-3-030-64357-7_4)

\[^groth16\]: _groth16:_ **On the Size of Pairing-Based Non-interactive Arguments**; by Groth, Jens; in EUROCRYPT 2016

\[^tlock\]: _tlock:_ **tlock: Practical Timelock Encryption from Threshold BLS**; by Nicolas Gailly and Kelsey Melissaris and Yolan Romailler; [https://eprint.iacr.org/2023/189](https://eprint.iacr.org/2023/189)

# Debugging Move

> Learn about debugging for Move smart contract development on Aptos blockchain.

Move was designed to be simple and safe, but like with all programming languages, bugs can still occur. This guide will help you debug your Move code and figure out what went wrong.

Please feel free to contribute with additional tooling and information that can help others in the community.

## Debugging with the Aptos CLI

[](#debugging-with-the-aptos-cli)

### Simulation on transaction submission

[](#simulation-on-transaction-submission)

You can use the Aptos CLI to simulate entry functions prior to executing them.

Normally, a transaction will fail in simulation if it won't work on-chain. For example:

```
aptos move run --function-id 0x1::aptos_account::transfer --args address:0x1 u64:1000000000000000000{  "Error": "Simulation failed with status: Move abort in 0x1::coin: EINSUFFICIENT_BALANCE(0x10006): Not enough coins to complete transaction"}
```

The same applies to Move scripts as well. For example:

```
 aptos move run-script --script-path <script_path> ...
```

### Local Simulation

[](#local-simulation)

Additionally, for some situations, local simulation, may give additional information and [print out any debug statements you have in your code](/build/cli/working-with-move-contracts#printing-debugging-information).

```
aptos move run --function-id 0x1::aptos_account::transferred --args address:0x1 u64:1000000000000000000 --local
Simulating transaction locally...{  "Result": {    "transaction_hash": "0x4115316915d409ba4106632c82d4b09220035ffdbd0b86bbe29a586d03d06318",    "gas_used": 3,    "gas_unit_price": 100,    "sender": "78077fe8db589e1a3407170cf8af3bd60a8c95737918c15dd6f49dcbecc7900a",    "success": false,    "version": 56634003,    "vm_status": "status FUNCTION_RESOLUTION_FAILURE of type Verification with message Function 0x1::aptos_account::transferred does not exist"  }}
```

### Gas Profiling and Tracing

[](#gas-profiling-and-tracing)

Adding the gas profile will additionally add the ability to trace how much gas is used in computation:

```
aptos move run --function-id 0x1::aptos_account::transferred --args address:0x1 u64:1000000000000000000 --profile-gas
Simulating transaction locally using the gas profiler...Gas report saved to gas-profiling/txn-a90ca655-0x1-aptos_account-transferred.{  "Result": {    "transaction_hash": "0xa90ca6550dcdd7f514f4cdcdee7dc1fbee17082fcf68f3db3e5755a93b89bcfc",    "gas_used": 3,    "gas_unit_price": 100,    "sender": "78077fe8db589e1a3407170cf8af3bd60a8c95737918c15dd6f49dcbecc7900a",    "success": false,    "version": 56651618,    "vm_status": "status FUNCTION_RESOLUTION_FAILURE of type Verification with message Function 0x1::aptos_account::transferred does not exist"  }}
```

And this will generate a gas report viewable in HTML format:

```
open  gas-profiling/txn-a90ca655-0x1-aptos_account-transferred/index.html
```

## Evaluating performance

[](#evaluating-performance)

```
aptos move run --function-id 0x1::aptos_account::transfer --args address:0x1 u64:1 --benchmark
Benchmarking transaction locally...Running time (cold code cache): 22.144458msRunning time (warm code cache): 669.5µs{  "Result": {    "transaction_hash": "0x7cdf37ff4d798b3ac3f1e860a40428853e381598a511b9291f2a49e5ff6262a0",    "gas_used": 11,    "gas_unit_price": 100,    "sender": "78077fe8db589e1a3407170cf8af3bd60a8c95737918c15dd6f49dcbecc7900a",    "success": true,    "version": 56679764,    "vm_status": "status EXECUTED of type Execution"  }}
```

# Object Code Deployment

> Learn about deployment for Move smart contract development on Aptos blockchain.

This document goes through how you can deploy code to [Objects](/build/smart-contracts/objects). This is the recommended way to deploy code to the blockchain, as this reduces deployment complexity, and safely manages access control policies for the code owner. Note that in this context, code refers to [packages](https://aptos-labs.github.io/move-book/modules-and-packages.html).

Deploying code to objects will guarantee the following:

*   Each deployment publishes to a new address.
*   Only the **owner of the code object** can upgrade and freeze the code.

This means you can transfer the object to a new owner, and they will have full ownership of the code. You are granting them the rights to upgrade and freeze the code. There is no need to manage seeds, or deploy to a new address on each deployment. Object code deployment greatly simplifies the deployment process.

## Instructions

[](#instructions)

Below are the instructions on how to compile, deploy and upgrade code to objects.

1.  Compile code
    
    Make sure `<named_address>` is left as a placeholder `_`. This is needed as the CLI command will override the address. `<named_address>` value represents the owner of the code, or the owner of the object to deploy the code to. Here is an example as `<named_address>` with the value `my_address`.
    
    ```
    [addresses]my_address = "_"
    ```
    
    Compile your move code running the below command.
    
    *   Replace `<named_address>` with the named address.
    *   Replace `<your_address>` with the address of your account.
    
    ```
    aptos move compile --named-addresses <named_address>=<your_address>
    ```
    
2.  Deploy code to an object
    
    Deploy the compiled code to an object via the command:
    
    *   Replace `<named_address>` with the named address.
    
    ```
    aptos move deploy-object --address-name <named_address>
    ```
    
    **An example can be found below:**
    
    ```
    aptos move deploy-object --address-name my_address
    ```
    
    This will ask if you want to publish the code under the specified object address.
    
    **Example output:**
    
    ```
    Do you want to publish this package at object address 0x8d6eb306bcf6c61dbaa0dbf8daa8252e121b63e95991afcab3b12d3be7f001ab [yes/no] >
    ```
    
    **Congrats, you have deployed your code to a new object with a unique address!**
    
    Take note of the object address as you will need it later for upgrades.
    
3.  Transfer and upgrade code in an existing package
    
    First, you may want to transfer the object from the deployer account to an admin account. The admin account will have rights to upgrade the code.
    
    Here's how you can do it via CLI, here your `deployer_account` should be the current owner of the object.
    
    ```
    aptos move run --function-id 0x1::object::transfer --type-args 0x1::object::ObjectCore --args address:<object_address> address:<new_owner_address> --profile <deployer_account_profile>
    ```
    
    Here's how you can do it via the typescript SDK:
    
    ```
    const transaction = await aptos.transaction.build.simple({  sender: deployerAccount.accountAddress,  data: {    function: "0x1::object::transfer",      typeArguments: [`0x1::object::ObjectCore`],    functionArguments: [object_address, new_owner_address],  },});
    ```
    
    Now you can upgrade the code with the designated admin account, as shown below.
    
    If you wish to upgrade the code in the object deployed, run the following:
    
    *   Replace `<named_address>` with the existing named address.
    *   Replace `<code_object_addr>` with the address of the object hosting the code.
    
    Note: the value for the account name should now be the object address, as the package containing the module(s) is now deployed to that address.
    
    ```
    aptos move upgrade-object --address-name <named_address> --object-address <code_object_addr>
    ```
    
    Example of the command above:
    
    ```
    aptos move upgrade-object --address-name my_address --object-address 0x8d6eb306bcf6c61dbaa0dbf8daa8252e121b63e95991afcab3b12d3be7f001ab
    ```
    
    This will ask if you want to upgrade the existing code deployed at the object address.
    
    **Example output:**
    
    ```
    Do you want to upgrade the package 'MyPackage' at object address 0x8d6eb306bcf6c61dbaa0dbf8daa8252e121b63e95991afcab3b12d3be7f001ab [yes/no]
    ```
    
    **Congrats, you have upgraded your code in the existing object!**

# Aptos Digital Asset Standard

> Learn about digital asset for Move smart contract development on Aptos blockchain.

The Digital Asset (DA) standard is a modern Non-Fungible Token (NFT) standard for Aptos. NFTs represent unique assets on-chain, and are stored in collections. These NFTs can be customized to later be transferred, soulbound, burned, mutated, or customized via your own smart contracts.

This standard replaces the legacy [Aptos Token Standard](/build/smart-contracts/aptos-token). The most important improvements to note are:

| **Improvement** | **Description** | | ----------------------- | -------------------------------------------------------------------------------------------------------------- | | **Token Extension** | Tokens can be easily extended since they are implemented using Move [Objects](/build/smart-contracts/objects). | | **Direct NFT Transfer** | You can now directly transfer NFTs without the recipient “opting-in” on-chain. | | **NFT Composability** | NFTs can own other NFTs for easy composability. |

If you want a simple way to mint NFTs without the ability to customize or extend their functionality, you can use the `aptos_token` module which implements the DA standard (see the section on how to use it below).

Note

Note that all Digital Asset modules are deployed at the reserved address `0x4`.

## Using the Digital Asset Standard

[](#using-the-digital-asset-standard)

This standard is implemented with two Objects:

1.  `Collection`s - A set of NFTs with a name and a bit of context for the group.
2.  `Token`s - Digital assets which represent unique assets. These are often used to represent NFTs and usually use a `uri` link to point to more info about the asset (ex. a link to an image, video, etc.).

![Digital Asset token and collection relationship](/_astro/digital-asset-light.BBAgrDGD.svg) ![Digital Asset token and collection relationship](/_astro/digital-asset-dark.CiA8jopp.svg)

All `Token`s are required to have a reference to a parent `Collection`, but the parent `Collection` does **not** own the `Token`. Newly minted `Token`s are usually owned by the creator. From there, they can be transferred to other accounts.

## Collections

[](#collections)

| **Field** | **Description** | | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Description** | An optional string smaller than 2048 characters (modifiable with a `MutatorRef`). | | **Name** | A required string to identify the `Collection`. The name must be unique within each account. That means a single creator account cannot create more than one `Collection` with the same name. | | **Royalty** | An optional [`Royalty`](https://aptos-labs.github.io/framework-book/aptos-token-objects/royalty.html#resource-royalty) struct indicating what % of the sale price goes to the creator of the `Collection`. This can be changed with a `MutatorRef` generated by the [Royalty module](https://github.com/aptos-labs/aptos-core/blob/main/aptos-move/framework/aptos-token-objects/sources/royalty.move). The Royalty module is an extension for the DA standard. See example usage in [`aptos_token.move`](https://github.com/aptos-labs/aptos-core/blob/main/aptos-move/framework/aptos-token-objects/sources/aptos_token.move). | | **URI length** | An optional string that is smaller than 512 characters which links to relevant content for the `Collection` (modifiable with a `MutatorRef`). |

### Creating a `Collection`

[](#creating-a-collection)

There are two ways to create a `Collection` depending on whether you want there to be a maximum supply of `Token`s it can hold.

#### Fixed Maximum Supply

[](#fixed-maximum-supply)

To make a `Collection` with a fixed supply you can use `collection::create_fixed_collection` like so:

```
use aptos_token_objects::collection;use std::option::{Self, Option};use aptos_framework::string;
public entry fun create_collection(creator: &signer) {    let max_supply = 1000;    let royalty = option::none();
    // Maximum supply cannot be changed after collection creation    collection::create_fixed_collection(        creator,        string::utf8(b"My Collection Description"),        max_supply,        string::utf8(b"My Collection"),        royalty,        string::utf8(b"https://mycollection.com"),    );}
```

#### Unlimited Supply

[](#unlimited-supply)

To create a `Collection` with unlimited supply you can use `collection::create_unlimited_collection`:

```
use std::option::{Self, Option};use aptos_framework::string;
public entry fun create_collection(creator: &signer) {    let royalty = option::none();
    collection::create_unlimited_collection(        creator,        string::utf8(b"My Collection Description"),        string::utf8(b"My Collection"),        royalty,        string::utf8(b"https://mycollection.com"),    );}
```

Caution

A `Collection`'s maximum supply cannot be changed after creation.

### Customizing a `Collection`

[](#customizing-a-collection)

Since each `Collection` is a [Move Object](/build/smart-contracts/objects), you can customize it by generating permissions called `Ref`s. Each `Ref` allows you to modify an aspect of the Object later on. Beyond the normal [Object Refs](/build/smart-contracts/object/creating-objects), `Collection`s can also get a `MutatorRef` by calling `get_mutator_ref` like so:

```
use std::option::{Self, Option};use aptos_framework::string;
public entry fun create_collection(creator: &signer) {    let royalty = option::none();    let collection_constructor_ref = &collection::create_unlimited_collection(        creator,        string::utf8(b"My Collection Description"),        string::utf8(b"My Collection"),        royalty,        string::utf8(b"https://mycollection.com"),    );    let mutator_ref = collection::get_mutator_ref(collection_constructor_ref);    // Store the mutator ref somewhere safe}
```

Caution

Refs **must** be generated at creation time of an Object. The `ConstructorRef` used to generate other `Ref`s expires as soon as the transaction to create the Object is finished.

You can further customize your `Collection` by adding more resources or functionalities via smart contract. For example, a `Collection` can track when it was created in order to limit when `Token`s can be minted like so:

```
use std::option::{Self, Option};use aptos_framework::string;
struct MyCollectionMetadata has key {    creation_timestamp_secs: u64,}
public entry fun create_collection(creator: &signer) {    let royalty = option::none();    // Constructor ref is a non-storable struct returned when creating a new object.    // It can generate an object signer to add resources to the collection object.    let collection_constructor_ref = &collection::create_unlimited_collection(creator,        string::utf8(b"My Collection Description"),        string::utf8(b"My Collection"),        royalty,        string::utf8(b"https://mycollection.com"),    );    // Constructor ref can be exchanged for signer to add resources to the collection object.    let collection_signer = &object::generate_signer(collection_constructor_ref);    move_to(collection_signer, MyCollectionMetadata { creation_timestamp_secs: timestamp::now_seconds() } })}
```

## Tokens

[](#tokens)

| **Field** | **Description** | | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Description** | An optional string smaller than 2048 characters (modifiable with a `MutatorRef`). | | **Name** | A required string to identify the `Token` that is unique within each `Collection`. This means a single `Collection` account cannot have more than one `Token` with the same name. | | **Royalty** | An optional [`Royalty`](https://aptos-labs.github.io/framework-book/aptos-token-objects/royalty.html#resource-royalty) struct indicating what % of the sale price goes to the creator of the `Collection`. This can be changed with a `MutatorRef` generated by the [Royalty module](https://github.com/aptos-labs/aptos-core/blob/main/aptos-move/framework/aptos-token-objects/sources/royalty.move) (an extension for the DA standard. See example usage in [`aptos_token.move`](https://github.com/aptos-labs/aptos-core/blob/main/aptos-move/framework/aptos-token-objects/sources/aptos_token.move)). Usually royalty is set on collections, but setting it on `Token`s allows the individual `Token` to have a custom royalty amount. | | **URI length** | An optional string that is smaller than 512 characters which links to relevant content for the `Collection` (modifiable with a `MutatorRef`). |

### Creating Tokens

[](#creating-tokens)

There are a few ways to create a `Token`:

1.  Named tokens. These use the name of the `Token` to generate a named Object. This makes it easy to find the address for the token if you know the token and `Collection` name, but named Objects are not deletable. Trying to delete the a named token will only delete the data, not the Object itself.

```
use aptos_token_objects::token;use std::option::{Self, Option};
public entry fun mint_token(creator: &signer) {    let royalty = option::none();    token::create_named_token(        creator,        "Collection Name",        "Description",        "Token Name",        royalty,        "https://mycollection.com/my-named-token.jpeg",    );}
```

Note

You can derive the address for named tokens by:

1.  Concatenating the creator address, collection name and token name.
2.  Doing a sha256 hash of that new string.

2.  “Unnamed” tokens. These create unnamed _Objects_ (which **are** deletable) but still have a `Token` name. Because the Object address is not deterministic, you must use an Indexer to find the address for them.

```
use aptos_token_objects::token;use std::option::{Self, Option};use aptos_framework::string;
public entry fun mint_token(creator: &signer) {    let royalty = option::none();    token::create(        creator,        string::utf8(b"Collection Name"),        string::utf8(b"Description"),        string::utf8(b"Token Name"),        royalty,        string::utf8(b"https://mycollection.com/my-named-token.jpeg"),    );}
```

### Finding Unnamed Token Addresses via Indexer

[](#finding-unnamed-token-addresses-via-indexer)

You can find the addresses of your recently created “unnamed” `Token`s by using the [Aptos Indexer](/build/indexer/indexer-api) with queries like the following:

1.  Looking up the collection id by using your account address and the name of the `Collection`.

2.  Then look up the address (`token_data_id`) of the `Token` by using the `collection_id` (from above) and the name of the token:

Note

In general, using unnamed tokens give you the most flexibility because the Object can be deleted later, but named tokens simplify looking up addresses.

### Using Tokens

[](#using-tokens)

#### Transfer Tokens

[](#transfer-tokens)

Transferring a `Token` can be done by calling [`object::transfer`](https://aptos-labs.github.io/framework-book/aptos-framework/object.html#function-transfer).

```
public entry fun transfer<T: key>(owner: &signer, object: object::Object<T>, to: address)
```

#### Burning Tokens

[](#burning-tokens)

Burning / deleting a `Token` requires storing a `BurnRef` with `token::generate_burn_ref`, then calling `token::burn`.

```
module 0x42::example {  use std::option;  use aptos_token_objects::token::{Self, BurnRef, Token};  use std::string::utf8;  use aptos_framework::object::{Self, Object};
  struct CustomData has key, drop {    burn_ref: BurnRef,  }
  public entry fun mint_token(creator: &signer) {    let token_constructor_ref = &token::create(      creator,      utf8(b"My Collection"),      utf8(b"My named Token description"),      utf8(b"My named token"),      option::none(),      utf8(b"https://mycollection.com/my-named-token.jpeg"),    );
    let token_signer = &object::generate_signer(token_constructor_ref);
    let burn_ref = token::generate_burn_ref(token_constructor_ref);
    // Store the burn ref somewhere safe    move_to(token_signer, CustomData {      burn_ref,    });  }
  public entry fun burn_token(token: Object<Token>) acquires CustomData {    let token_address = object::object_address(&token);    // Remove all custom data from the token object.    // Retrieve the burn ref from storage    let CustomData { burn_ref } = move_from<CustomData>(token_address);    // Burn the token    token::burn(burn_ref);  }}
```

Caution

If any custom resources were moved onto the Token, those must be removed / deleted first before`token::burn` can delete the Token. For named tokens which cannot be deleted, `token::burn` will For named Tokens `token::burn` will remove all Token content instead.

#### Modifying Tokens After Creation

[](#modifying-tokens-after-creation)

Mutating a `Token`’s `URI` or `description` requires a `MutatorRef` (which must be generated when creating the `Token`, then stored for later).

```
module 0x42::example {  use std::option;  use aptos_token_objects::token::{Self, MutatorRef, Token};  use std::string::utf8;  use aptos_framework::object::{Self, Object};
  struct CustomData has key, drop {    mutator_ref: MutatorRef,  }
  public entry fun mint_token(creator: &signer) {    // Constructor ref is a non-storable struct returned when creating a new object.    // It can be exchanged for signer to add resources to the token object.    let token_constructor_ref = &token::create(      creator,      utf8(b"My Collection"),      utf8(b"My named Token description"),      utf8(b"My named Token"),      option::none(),      utf8(b"https://mycollection.com/my-named-token.jpeg"),    );
    let token_signer = &object::generate_signer(token_constructor_ref);
    let mutator_ref = token::generate_mutator_ref(token_constructor_ref);
    // Store the mutator ref somewhere safe    move_to(token_signer, CustomData {      mutator_ref,    });  }
  public entry fun mutate_token(token: Object<Token>) acquires CustomData {    let token_address = object::object_address(&token);    // Retrieve the mutator ref from storage    let CustomData { mutator_ref } = move_from<CustomData>(token_address);    // Change token description    token::set_description(&mutator_ref, utf8(b"This is my named Token description"));  }}
```

Caution

Changing the royalty requires generating a _separate_ `MutatorRef` from the [Royalty module](https://github.com/aptos-labs/aptos-core/blob/main/aptos-move/framework/aptos-token-objects/sources/royalty.move).

#### Extending Tokens

[](#extending-tokens)

`Token`s can be extended either by adding additional resources (since they are an Object) or using `Ref`s to modify the Object.

## Aptos Token

[](#aptos-token)

For NFT creators who want to avoid writing their own logic for how your NFT should work, you can use the [`aptos_token`](https://github.com/aptos-labs/aptos-core/blob/main/aptos-move/framework/aptos-token-objects/sources/aptos_token.move) module to mint an NFT. This module is already deployed at `0x4` and allows you to:

1.  Mint a `Token` you can transfer with royalties.
2.  Mint a soulbound `Token`.
3.  Manage the resources your NFT has.

See the `aptos_token` [reference docs](https://aptos-labs.github.io/framework-book/aptos-token-objects/aptos_token.html) for all the helper functions you can use.

Caution

The main drawback of using the `aptos_token` module is that the Tokens are not extensible (the `mint` function does not return a `ConstructorRef`).

### Minting with `aptos_token`

[](#minting-with-aptos_token)

Minting a `Token` using `aptos_token` requires the same parameters as any token that implements the DA standard. In addition though, the `aptos_token` module allows you to specify a property map of key/value pairs for any other properties your specific NFT may require.

You can mint your `Token` by calling `aptos_token::mint` like so:

```
public entry fun mint(    creator: &signer,    collection: String,    description: String,    name: String,    uri: String,    property_keys: vector<String>,    property_types: vector<String>,    property_values: vector<vector<u8>>,) acquires AptosCollection, AptosToken
```

#### Soulbound Tokens

[](#soulbound-tokens)

To mint a soul bound `Token`, you can call [`aptos_token::mint_soul_bound`](https://aptos-labs.github.io/framework-book/aptos-token-objects/aptos_token.html#function-mint_soul_bound) instead:

```
public entry fun mint_soul_bound(    creator: &signer,    collection: String,    description: String,    name: String,    uri: String,    property_keys: vector<String>,    property_types: vector<String>,    property_values: vector<vector<u8>>,    soul_bound_to: address,) acquires AptosCollection
```

Caution

In the near future, a new module `TokenMinter` will be released to replace `aptos_token`. You can follow the status of that proposal [here](https://github.com/aptos-foundation/AIPs/blob/main/aips/aip-72.md).

## Examples and Useful Links

[](#examples-and-useful-links)

*   [Digital Asset Examples](https://github.com/aptos-labs/aptos-core/tree/main/aptos-move/move-examples/token_objects)
*   [Digital Asset Marketplace Example](https://github.com/aptos-labs/aptos-core/tree/main/aptos-move/move-examples/marketplace)
*   [Source code](https://github.com/aptos-labs/aptos-core/blob/main/aptos-move/framework/aptos-token-objects/sources/token.move)
*   [`aptos_token` source code](https://github.com/aptos-labs/aptos-core/blob/main/aptos-move/framework/aptos-token-objects/sources/aptos_token.move)

# Aptos Error Codes

> Learn about error codes for Move smart contract development on Aptos blockchain.

This page catalogs common errors encountered in the Aptos blockchain and explains how to resolve them wherever possible. As with all software, the code itself is the source of truth for error handling and will always contain entries not found here. Instead, this matrix aims to help you address those errors most typically found, misunderstood, or both.

For the sources of these errors, see:

*   [vm\_status.rs](https://github.com/aptos-labs/aptos-core/blob/main/third_party/move/move-core/types/src/vm_status.rs)
*   [error.move](https://github.com/aptos-labs/aptos-core/blob/main/aptos-move/framework/move-stdlib/sources/error.move)
*   [account.move](https://github.com/aptos-labs/aptos-core/blob/main/aptos-move/framework/aptos-framework/sources/account/account.move)
*   [coin.move](https://github.com/aptos-labs/aptos-core/blob/main/aptos-move/framework/aptos-framework/sources/coin.move)
*   [token.move](https://github.com/aptos-labs/aptos-core/blob/main/aptos-move/framework/aptos-token/sources/token.move)
*   [token\_transfers.move](https://github.com/aptos-labs/aptos-core/blob/main/aptos-move/framework/aptos-token/sources/token_transfers.move)

Help us update this list by sending pull requests containing the errors you encounter. If you don't know how to resolve the error, as described int the _Action_ column, simply leave it blank.

## Frequent Errors

[](#frequent-errors)

### INSUFFICIENT\_BALANCE\_FOR\_TRANSACTION\_FEE

[](#insufficient_balance_for_transaction_fee)

This means that the highest possible gas used for the transaction is greater than the balance of APT in the transaction sender's (or fee payer's) account. To resolve, please submit with a lower max gas amount, and try again.

For example, if the max gas amount is 1000 gas units, and the gas unit price is `100` octas, the total APT required in the account would be `0.00100000` APT (`1000 * 100 / 100000000`). The default is often `200000` gas units which would end up requiring `0.20000000` APT. If you are having issues with this, please reach out to your wallet provider.

### OUT\_OF\_GAS

[](#out_of_gas)

This means that the transaction used more gas than the sender specified as the max gas amount for the transaction, and aborted as a result. To resolve, please try to increase the max gas amount, and submit the transaction again.

### SEQUENCE\_NUMBER\_TOO\_OLD

[](#sequence_number_too_old)

This means that the transaction's sequence number in the sender's account has already been used and committed to the blockchain. In order to submit a new transaction to the blockchain, please try and submit it again with a new sequence number.

### SEQUENCE\_NUMBER\_TOO\_NEW

[](#sequence_number_too_new)

This only occurs in simulation, but means that the sequence number being submitted is greater than the next sequence number for the account. Please reduce the sequence number and try again.

## Move Virtual Machine (VM)

[](#move-virtual-machine-vm)

| Error | Meaning | Possible Resolution | | --------------------------------------------------------------- | :-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | LOOKUP\_FAILED | A function that is being called isn't present on the network being used | Check that your dependencies on-chain have the same version | | UNKNOWN\_VALIDATION\_STATUS | We don't want the default value to be valid. | N/A | | INVALID\_SIGNATURE | The transaction has a bad signature. | Submit a new transaction with a new signature | | INVALID\_AUTH\_KEY | Bad account authentication key. | Submit a new transaction with a new signature, check that the account matches the authentication key and hasn't been rotated | | SEQUENCE\_NUMBER\_TOO\_OLD | Sequence number is too old. | Submit a new transaction with a newer sequence number from the account | | SEQUENCE\_NUMBER\_TOO\_NEW | Sequence number is too new. | Submit a new transaction with a new signature | | INSUFFICIENT\_BALANCE\_FOR\_TRANSACTION\_FEE | Insufficient balance to pay for max\_gas specified in the transaction. Balance needs to be above max\_gas\_amount \* gas\_unit\_price to proceed. | Fund the account with more APT to pay for the gas fee | | TRANSACTION\_EXPIRED | The transaction has expired. | Submit a new transaction with an expiration time further in the future | | SENDING\_ACCOUNT\_DOES\_NOT\_EXIST | The sending account does not exist. | Create the account prior to sending the transaction again | | REJECTED\_WRITE\_SET | This write set transaction was rejected because it did not meet the requirements for one. | N/A | | INVALID\_WRITE\_SET | This write set transaction cannot be applied to the current state. | N/A | | EXCEEDED\_MAX\_TRANSACTION\_SIZE | Length of program field in raw transaction exceeded max length. | The transaction is too large for a single transaction; if this is a package publish, try to break it into multiple packages | | UNKNOWN\_SCRIPT | This script is not in our allowlist of scripts. | N/A | | UNKNOWN\_MODULE | Transaction is trying to publish a new module. | N/A | | MAX\_GAS\_UNITS\_EXCEEDS\_MAX\_GAS\_UNITS\_BOUND | Max gas units submitted with transaction exceeds max gas units bound in VM. | Decrease the max gas amount in the transaction below the maximum value in the gas schedule | | MAX\_GAS\_UNITS\_BELOW\_MIN\_TRANSACTION\_GAS\_UNITS | Max gas units submitted with transaction not enough to cover the intrinsic cost of the transaction. | Increase the max gas amount above the minimum value in the gas schedule | | GAS\_UNIT\_PRICE\_BELOW\_MIN\_BOUND | Gas unit price submitted with transaction is below minimum gas price set in the VM. | Increase the gas unit price below the minimum gas unit price in the gas schedule | | GAS\_UNIT\_PRICE\_ABOVE\_MAX\_BOUND | Gas unit price submitted with the transaction is above the maximum gas price set in the VM. | Decrease the gas unit price below the maximum gas unit price in the gas schedule | | INVALID\_GAS\_SPECIFIER | Gas specifier submitted is either malformed (not a valid identifier), or does not refer to an accepted gas specifier. | N/A | | SENDING\_ACCOUNT\_FROZEN | The sending account is frozen. | N/A | | UNABLE\_TO\_DESERIALIZE\_ACCOUNT | Unable to deserialize the account blob. | N/A | | CURRENCY\_INFO\_DOES\_NOT\_EXIST | The currency info was unable to be found. | N/A | | INVALID\_MODULE\_PUBLISHER | The account sender doesn't have permissions to publish modules. | N/A | | NO\_ACCOUNT\_ROLE | The sending account has no role. | N/A | | BAD\_CHAIN\_ID | The transaction's chain\_id does not match the one published on-chain. | Verify that your chain ID matches the chain ID for your network | | SEQUENCE\_NUMBER\_TOO\_BIG | The sequence number is too large and would overflow if the transaction were executed. | N/A | | BAD\_TRANSACTION\_FEE\_CURRENCY | The gas currency is not registered as a TransactionFee currency. | N/A | | FEATURE\_UNDER\_GATING | The feature requested is intended for a future Aptos version instead of the current one. | N/A | | SECONDARY\_KEYS\_ADDRESSES\_COUNT\_MISMATCH | The number of secondary signer addresses is different from the number of secondary public keys provided. | Verify the multi-agent or multi-ed25519 secondary signer addresses match the secondary public keys | | SIGNERS\_CONTAIN\_DUPLICATES | There are duplicates among signers, including the sender and all the secondary signers. | Remove any duplicate signers | | SEQUENCE\_NONCE\_INVALID | The sequence nonce in the transaction is invalid (too new, too old, or already used). | N/A | | CHAIN\_ACCOUNT\_INFO\_DOES\_NOT\_EXIST | There was an error when accessing chain-specific account information. | N/A | | MODULE\_ADDRESS\_DOES\_NOT\_MATCH\_SENDER | the module publisher is not the account that will eventually hold the module. | Confirm the module address in the move contract matches the sender of the transaction | | ZERO\_SIZED\_STRUCT | Reported when a struct has zero fields. | N/A | | DUPLICATE\_MODULE\_NAME | The sender is trying to publish two modules with the same name in one transaction. | Confirm every module has a unique name | | BACKWARD\_INCOMPATIBLE\_MODULE\_UPDATE | The sender is trying to publish a module that breaks the compatibility checks. | Confirm your new modules being published don't break backwards compatibility | | CYCLIC\_MODULE\_DEPENDENCY | The updated module introduces a cyclic dependency (i.e., A uses B and B also uses A). | Check for loops in your module dependencies in the modules being published | | INVALID\_FRIEND\_DECL\_WITH\_SELF | Cannot mark the module itself as a friend. | Confirm no module has itself marked as a friend in the modules being published | | INVALID\_FRIEND\_DECL\_WITH\_MODULES\_OUTSIDE\_ACCOUNT\_ADDRESS | Cannot declare modules outside of account address as friends. | Confirm all friends are in the same account address in the modules being published | | INVALID\_FRIEND\_DECL\_WITH\_MODULES\_IN\_DEPENDENCIES | Cannot declare modules that this module depends on as friends. | Check friend declarations of the modules being published | | CYCLIC\_MODULE\_FRIENDSHIP | The updated module introduces a cyclic friendship (i.e., A friends B and B also friends A). | Check friend declarations of the modules being published | | INVALID\_PHANTOM\_TYPE\_PARAM\_POSITION | A phantom type parameter was used in a non-phantom position. | Confirm phantom types are used only with generics | | LOOP\_MAX\_DEPTH\_REACHED | Loops are too deeply nested. | Check for many nested loops | | TYPE\_RESOLUTION\_FAILURE | Failed to resolve type due to linking being broken after verification. | N/A | | RESOURCE\_DOES\_NOT\_EXIST | We tried to access a resource that does not exist under the account. | Check the contract and possibly change it to handle resources that don't exist | | RESOURCE\_ALREADY\_EXISTS | We tried to create a resource under an account where that resource already exists. | Check the contract and possibly change it to handle resources that already exist | | UNKNOWN\_STATUS | A reserved status to represent an unknown vm status. This is std::u64::MAX, but we can't pattern match on that, so put the hardcoded value in. | N/A | | LINKER\_ERROR | This may be due to the function has not been published on chain or by trying to call an invalid function as the result of either an incorrect account address, module name, or function name. This might not happen locally if the sources are available locally but have yet to be published on-chain. | There are many reasons, but you should check your account addresses, module names, and function names to determine that they're correct and published | | FAILED\_TO\_DESERIALIZE\_ARGUMENT | This error in deserializing argument is triggered by one of the following validation checks. 1) It exceeds the limit on the number of nested or unpacked structs (including in a vector). The maximum overall args equals to depth \* number of args. The max depth is currently 10. 2) The nested struct exceeds the aforementioned max depth. 3) The serialized arguments to constructor contained extra data. 4) It was derializing utf8 but struct\_constructors are disabled. 5) The string argument is too long. 6) BCS deserialization fails for utf8. | N/A |

## Move Standard Library (stdlib)

[](#move-standard-library-stdlib)

| Error | Meaning | | ------------------- | :---------------------------------------------------------------------------------------------: | | INVALID\_ARGUMENT | Caller specified an invalid argument (HTTP: 400). | | OUT\_OF\_RANGE | An input or result of a computation is out of range (HTTP: 400). | | INVALID\_STATE | The system is not in a state where the operation can be performed (HTTP: 400). | | UNAUTHENTICATED | Request not authenticated due to missing, invalid, or expired authentication token (HTTP: 401). | | PERMISSION\_DENIED | The client does not have sufficient permission (HTTP: 403). | | NOT\_FOUND | A specified resource is not found (HTTP: 404). | | ABORTED | Concurrency conflict, such as read-modify-write conflict (HTTP: 409). | | ALREADY\_EXISTS | The resource that a client tried to create already exists (HTTP: 409). | | RESOURCE\_EXHAUSTED | Out of gas or other forms of quota (HTTP: 429). | | CANCELLED | Request cancelled by the client (HTTP: 499). | | INTERNAL | Internal error (HTTP: 500). | | NOT\_IMPLEMENTED | Feature not implemented (HTTP: 501). | | UNAVAILABLE | The service is currently unavailable. Indicates that a retry could solve the issue (HTTP: 503). |

## Aptos accounts

[](#aptos-accounts)

| Error | Meaning | Possible Resolution | | ---------------------------------------- | :-----------------------------------------------------------------------------------------------------------------------------------: | -------------------------------------------------------------------------------- | | EACCOUNT\_ALREADY\_EXISTS | Account already exists. | N/A | | EACCOUNT\_DOES\_NOT\_EXIST | Account does not exist. | Create the account first | | ESEQUENCE\_NUMBER\_TOO\_BIG | Sequence number exceeds the maximum value for a u64. | Provide a smaller sequence number | | EMALFORMED\_AUTHENTICATION\_KEY | The provided authentication key has an invalid length. | Check your authentication key; it should be a 32-byte vector | | ECANNOT\_RESERVED\_ADDRESS | Cannot create account because address is reserved. | N/A | | EOUT\_OF\_GAS | Transaction exceeded its allocated max gas. | Increase the max gas amount | | EWRONG\_CURRENT\_PUBLIC\_KEY | Specified current public key is not correct. | Confirm the public key matches the account | | EINVALID\_PROOF\_OF\_KNOWLEDGE | Specified proof of knowledge required to prove ownership of a public key is invalid. | Check your proof of knowledge in key rotation to ensure it has proper signatures | | ENO\_CAPABILITY | The caller does not have a digital-signature-based capability to call this function. | Confirm you have the capability for the called functions | | EINVALID\_ACCEPT\_ROTATION\_CAPABILITY | The caller does not have a valid rotation capability offer from the other account. | Confirm the account being rotated is correct | | ENO\_VALID\_FRAMEWORK\_RESERVED\_ADDRESS | Address to create is not a valid reserved address for Aptos framework. | N/A | | EINVALID\_SCHEME | Specified scheme required to proceed with the smart contract operation - can only be ED25519\_SCHEME(0) OR MULTI\_ED25519\_SCHEME(1). | Confirm the transaction was signed correctly when creating the account | | EINVALID\_ORIGINATING\_ADDRESS | Abort the transaction if the expected originating address is different from the originating address on-chain. | Confirm you are rotating the correct account's key | | ENO\_SUCH\_SIGNER\_CAPABILITY | The signer capability doesn't exist at the given address. | Confirm the address is correct |

## Aptos coins

[](#aptos-coins)

| Error | Meaning | Possible Resolution | | -------------------------------------- | :----------------------------------------------------------------------------------------------------: | ------------------------------------------------------------------------- | | ECOIN\_INFO\_ADDRESS\_MISMATCH | Address of account which is used to initialize a coin `CoinType` doesn't match the deployer of module. | Create the coin using a `CoinType` in the same account creating the coin. | | ECOIN\_INFO\_ALREADY\_PUBLISHED | `CoinType` is already initialized as a coin. | N/A | | ECOIN\_INFO\_NOT\_PUBLISHED | `CoinType` hasn't been initialized as a coin. | Create the coin with `CoinType` first before using it | | ECOIN\_STORE\_ALREADY\_PUBLISHED | Account already has `CoinStore` registered for `CoinType`. | N/A | | ECOIN\_STORE\_NOT\_PUBLISHED | Account hasn't registered `CoinStore` for `CoinType`. | Register the account for the `CoinType` | | EINSUFFICIENT\_BALANCE | Not enough coins to complete transaction. | Transfer less coins, or acquire more coins prior to the transfer | | EDESTRUCTION\_OF\_NONZERO\_TOKEN | Cannot destroy non-zero coins. | N/A | | EZERO\_COIN\_AMOUNT | Coin amount cannot be zero. | Don't burn coins or conduct other actions with zero coins | | EFROZEN | CoinStore is frozen. Coins cannot be deposited or withdrawn. | Account is frozen for this token; talk to the coin owner | | ECOIN\_SUPPLY\_UPGRADE\_NOT\_SUPPORTED | Cannot upgrade the total supply of coins to different implementation. | N/A | | ECOIN\_NAME\_TOO\_LONG | Name of the coin is too long. | Coin name must be less than or equal to 32 characters | | ECOIN\_SYMBOL\_TOO\_LONG | Symbol of the coin is too long. | Coin symbol must be less than or equal to 10 characters |

## Aptos tokens

[](#aptos-tokens)

| Error | Meaning | | -------------------------------------------------- | :------------------------------------------------------------: | | EALREADY\_HAS\_BALANCE | The token has balance and cannot be initialized. | | ECOLLECTIONS\_NOT\_PUBLISHED | There isn't any collection under this account. | | ECOLLECTION\_NOT\_PUBLISHED | Cannot find collection in creator's account. | | ECOLLECTION\_ALREADY\_EXISTS | The collection already exists. | | ECREATE\_WOULD\_EXCEED\_COLLECTION\_MAXIMUM | Exceeds the collection's maximal number of token\_data. | | EINSUFFICIENT\_BALANCE | Insufficient token balance. | | EINVALID\_TOKEN\_MERGE | Cannot merge the two tokens with different token IDs. | | EMINT\_WOULD\_EXCEED\_TOKEN\_MAXIMUM | Exceed the token data maximal allowed. | | ENO\_BURN\_CAPABILITY | No burn capability. | | ETOKEN\_DATA\_ALREADY\_EXISTS | TokenData already exists. | | ETOKEN\_DATA\_NOT\_PUBLISHED | TokenData not published. | | ETOKEN\_STORE\_NOT\_PUBLISHED | TokenStore doesn't exist. | | ETOKEN\_SPLIT\_AMOUNT\_LARGER\_THAN\_TOKEN\_AMOUNT | Cannot split token to an amount larger than its amount. | | EFIELD\_NOT\_MUTABLE | The field is not mutable. | | ENO\_MUTATE\_CAPABILITY | Not authorized to mutate. | | ENO\_TOKEN\_IN\_TOKEN\_STORE | Token not in the token store. | | EUSER\_NOT\_OPT\_IN\_DIRECT\_TRANSFER | User didn't opt-in direct transfer. | | EWITHDRAW\_ZERO | Cannot withdraw 0 token. | | ENFT\_NOT\_SPLITABLE | Cannot split a token that only has 1 amount. | | ENO\_MINT\_CAPABILITY | No mint capability | | ECOLLECTION\_NAME\_TOO\_LONG | The collection name is too long. | | ENFT\_NAME\_TOO\_LONG | The NFT name is too long. | | EURI\_TOO\_LONG | The URI is too long. | | ENO\_DEPOSIT\_TOKEN\_WITH\_ZERO\_AMOUNT | Cannot deposit a token with 0 amount. | | ENO\_BURN\_TOKEN\_WITH\_ZERO\_AMOUNT | Cannot burn 0 token. | | EWITHDRAW\_PROOF\_EXPIRES | Withdraw proof expires. | | EOWNER\_CANNOT\_BURN\_TOKEN | Token is not burnable by owner. | | ECREATOR\_CANNOT\_BURN\_TOKEN | Token is not burnable by creator. | | ECANNOT\_UPDATE\_RESERVED\_PROPERTY | Reserved fields for token contract. Cannot be updated by user. | | EURI\_TOO\_SHORT | URI too short. | | ETOKEN\_OFFER\_NOT\_EXIST | Token offer doesn't exist. |

# Aptos Fungible Asset (FA) Standard

> Learn about the Aptos Fungible Asset standard for creating and managing fungible tokens on Aptos blockchain with enhanced security and functionality.

The Aptos Fungible Asset Standard (also known as “Fungible Asset” or “FA”) provides a standard, type-safe way to define fungible assets in the Move ecosystem. It is a modern replacement for the `coin` module that allows for seamless minting, transfer, and customization of fungible assets for any use case.

This standard is important because it allows fungible assets on Aptos (such as Currencies and Real World Assets (RWAs)) to represent and transfer ownership in a consistent way dApps can recognize. This standard also allows for more extensive customization than the `coin` module did by leveraging [Move Objects](/build/smart-contracts/objects) to represent fungible asset data.

The FA standard provides all the functionality you need to create, mint, transfer, and burn fungible assets (as well as automatically allowing recipients of the fungible asset to store and manage any fungible assets they receive).

It does so by using two Move Objects:

1.  `Object<Metadata>` - This represents details about the fungible asset itself, including information such as the `name`, `symbol`, and `decimals`.
2.  `Object<FungibleStore>` - This stores a count of fungible asset units owned by this account. Fungible assets are interchangeable with any other fungible asset that has the same metadata. An account _may_ own more than one `FungibleStore` for a single Fungible Asset, but that is only for advanced use cases.

The diagram below shows the relationship between these Objects. The `Metadata` Object is owned by the Fungible Asset creator, then referenced in FA holders' `FungibleStore`s to indicate which FA is being tracked:

![FA Object Relationship](/_astro/fa-diagram-light.B10v_Nr_.png) ![FA Object Relationship](/_astro/fa-diagram-dark.BlQJwMl6.png)

[This implementation](https://github.com/aptos-labs/aptos-core/blob/main/aptos-move/framework/aptos-framework/sources/fungible_asset.move) is an improvement on the `coin` Standard because Move Objects are more customizable and extensible via smart contract. See the advanced guides on writing [Move Objects](/build/smart-contracts/objects) for more details. The FA standard also automatically handles tracking how much of a fungible asset an account owns, as opposed to requiring the recipient to register a `CoinStore` resource separate from the transfer.

## Creating a new Fungible Asset (FA)

[](#creating-a-new-fungible-asset-fa)

At a high level, this is done by:

1.  Creating a non-deletable Object to own the newly created Fungible Asset `Metadata`.
2.  Generating `Ref`s to enable any desired permissions.
3.  Minting Fungible Assets and transferring them to any account you want to.

To start with, the Fungible Asset standard is implemented using Move Objects. Objects by default are transferable, can own multiple resources, and can be customized via smart contract. For full details on Objects and how they work, please read [this guide](/build/smart-contracts/objects).

To create an FA, first you need to create a **non-deletable Object** since destroying the metadata for a Fungible Asset while there are active balances would not make sense. You can do that by either calling `object::create_named_object(caller_address, NAME)` or `object::create_sticky_object(caller_address)` to create the Object on-chain.

When you call these functions, they will return a `ConstructorRef`. `Ref`s allow Objects to be customized immediately after they are created. You can use the `ConstructorRef` to generate other permissions that may be needed based on your use case.

Note

Note that the `ConstructorRef` cannot be stored and is destroyed by the end of the transaction used to create this Object, so any `Ref`s must be generated during Object creation.

One use for the `ConstructorRef` is to generate the FA `Metadata` Object. The standard provides a generator function called `primary_fungible_store::create_primary_store_enabled_fungible_asset` which will allow your fungible asset to be transferred to any account. This method makes it so the primary `FungibleStore` for recipients is automatically created or re-used so you don't need to create or index the store directly.

This is what `create_primary_store_enabled_fungible_asset` looks like:

```
public fun create_primary_store_enabled_fungible_asset(    constructor_ref: &ConstructorRef,    // This ensures total supply does not surpass this limit - however,    // Setting this will prevent any parallel execution of mint and burn.    maximum_supply: Option<u128>,    // The fields below here are purely metadata and have no impact on-chain.    name: String,    symbol: String,    decimals: u8,    icon_uri: String,    project_uri: String,)
```

Note

Alternatively, you can use `add_fungibility` which uses the same parameters, but requires recipients to keep track of their `FungibleStore` addresses to keep track of how many units of your FA they have.

Once you have created the Metadata, you can also use the `ConstructorRef` to generate additional `Ref`s. In addition to the usual [Object Refs](/build/smart-contracts/object/creating-objects), FAs define three additional permissions you can generate:

1.  `MintRef` offers the capability to mint new FA units.
2.  `TransferRef` offers the capability to freeze accounts from transferring this FA, or to bypass an existing freeze. (This can be important when trying to be compliant with some regulations).
3.  `BurnRef` offers the capability to burn or delete FA units.

Caution

Note: All `Ref`s must be generated when the Object is created as that is the only time you can generate an Object's `ConstructorRef`.

To generate an Object with all FA permissions, you could deploy a contract like this:

```
module my_addr::my_fungible_asset_example {    use aptos_framework::fungible_asset::{Self, MintRef, TransferRef, BurnRef, Metadata, FungibleAsset};    use aptos_framework::object::{Self, Object};    use aptos_framework::primary_fungible_store;    use std::error;    use std::signer;    use std::string::utf8;    use std::option;
  const ASSET_SYMBOL: vector<u8> = b"FA";
  // Make sure the `signer` you pass in is an address you own.  // Otherwise you will lose access to the Fungible Asset after creation.  entry fun initialize(admin: &signer) {    // Creates a non-deletable object with a named address based on our ASSET_SYMBOL    let constructor_ref = &object::create_named_object(admin, ASSET_SYMBOL);
    // Create the FA's Metadata with your name, symbol, icon, etc.    primary_fungible_store::create_primary_store_enabled_fungible_asset(        constructor_ref,        option::none(),        utf8(b"FA Coin"), /* name */        utf8(ASSET_SYMBOL), /* symbol */        8, /* decimals */        utf8(b"http://example.com/favicon.ico"), /* icon */        utf8(b"http://example.com"), /* project */    );
    // Generate the MintRef for this object    // Used by fungible_asset::mint() and fungible_asset::mint_to()    let mint_ref = fungible_asset::generate_mint_ref(constructor_ref);
    // Generate the TransferRef for this object    // Used by fungible_asset::set_frozen_flag(), fungible_asset::withdraw_with_ref(),    // fungible_asset::deposit_with_ref(), and fungible_asset::transfer_with_ref().    let transfer_ref = fungible_asset::generate_transfer_ref(constructor_ref);
    // Generate the BurnRef for this object    // Used by fungible_asset::burn() and fungible_asset::burn_from()    let burn_ref = fungible_asset::generate_burn_ref(constructor_ref);
    // Add any other logic required for your use case.    // ...  }}
```

Note

For a full example of how to create your own Fungible Asset module, please see [fa\_coin.move](https://github.com/aptos-labs/aptos-core/blob/main/aptos-move/move-examples/fungible_asset/fa_coin/sources/FACoin.move). Alternatively, you can explore the collection of [FA example code here](https://github.com/aptos-labs/aptos-core/tree/main/aptos-move/move-examples/fungible_asset).

Now you can use the `MintRef` to mint via:

```
public fun mint(ref: &MintRef, amount:u64): FungibleAsset
```

Or burn FA units using the `BurnRef` like so:

```
public fun burn(ref: &BurnRef, fa: FungibleAsset)
```

At this point, you can mint, transfer, and burn Fungible Assets using the `Ref`s you generated. See the above example Move scripts for how to implement those entry functions.

## Reference Docs

[](#reference-docs)

You can find the complete set of functions that the Fungible Asset Standard provides [here](https://aptos-labs.github.io/framework-book/aptos-framework/fungible_asset.html).

The basic features owners of Fungible Assets can use include the following.

### Withdraw

[](#withdraw)

An owner can withdraw FA from their primary store by calling:

```
public fun primary_fungible_store::withdraw<T: key>(owner: &signer, metadata: Object<T>, amount:u64): FungibleAsset
```

This function will emit a `WithdrawEvent`.

### Deposit

[](#deposit)

An owner can deposit FA to their primary store by calling:

```
public fun primary_fungible_store::deposit(owner: address, fa: FungibleAsset)
```

This function will emit a `DepositEvent`.

### Transfer

[](#transfer)

An owner can deposit FA from their primary store to that of another account by calling:

```
public entry fun primary_fungible_store::transfer<T: key>(sender: &signer, metadata: Object<T>, recipient: address, amount:u64)
```

This will emit both `WithdrawEvent` and `DepositEvent` on the respective `FungibleStore`s.

### Check Balance

[](#check-balance)

To check the balance of a primary store, call:

```
public fun primary_fungible_store::balance<T: key>(account: address, metadata: Object<T>): u64
```

### Check Frozen Status

[](#check-frozen-status)

To check whether the given account's primary store is frozen, call:

```
public primary_fungible_store::fun is_frozen<T: key>(account: address, metadata: Object<T>): bool
```

### Events

[](#events)

FAs have three events emitted from the above basic functions:

1.  `Deposit`: Emitted when FAs are deposited into a store.

```
struct Deposit has drop, store {    store: address,    amount: u64,}
```

2.  `Withdraw`: Emitted when FAs are withdrawn from a store.

```
struct Withdraw has drop, store {    store: address,    amount: u64,}
```

3.  `Frozen`: Emitted when the frozen status of a fungible store is updated.

```
struct Frozen has drop, store {    store: address,    frozen: bool,}
```

## Dispatchable Fungible Asset (Advanced)

[](#dispatchable-fungible-asset-advanced)

Aside from the default managed fungible asset functionality provided by the Aptos Framework, fungible asset issuers can implement their own deposit/withdraw logic using the dispatchable fungible asset standard. This is done by registering custom hook functions to be invoked at withdrawal/deposit time. These hook functions are stored in the metadata of a fungible asset class, and the Aptos Framework will automatically invoke them instead of the default logic. This allows issuers to implement complex logic, such as customized access control. For more details, refer to the corresponding [AIP](https://github.com/aptos-foundation/AIPs/blob/main/aips/aip-73.md).

### Implementing the Hook Function

[](#implementing-the-hook-function)

To implement a custom hook function, build a module with functions that have the following signature:

```
module my_addr::my_fungible_asset_example {    // ...    public fun withdraw<T: key>(        store: Object<T>,        amount: u64,        transfer_ref: &TransferRef,    ): FungibleAsset {        // Your custom logic here    }
    public fun deposit<T: key>(        store: Object<T>,        fa: FungibleAsset,        transfer_ref: &TransferRef,    ) {        // Your custom logic here    }    // ...}
```

### Limitations

[](#limitations)

*   **Reentrancy Prevention**: Only call `with_ref` APIs in your custom hooks for deposit/withdraw operations.
    *   Use `fungible_asset::deposit_with_ref` instead of `fungible_asset::deposit`.
    *   Use `fungible_asset::withdraw_with_ref` instead of `fungible_asset::withdraw`.
*   Avoid calling functions defined in `dispatchable_fungible_asset` and `primary_fungible_store`, _except_ for inline functions, to prevent errors during transfers.
*   Note that calling `fungible_asset::withdraw` and `fungible_asset::deposit` will NOT work for assets with registered hooks. See more information in Interacting with dispatchable fungible asset.

For more details on these limitations, refer to the [AIP](https://github.com/aptos-foundation/AIPs/blob/main/aips/aip-73.md).

### Registering the Hook Function

[](#registering-the-hook-function)

Once the functions are implemented, use the API defined in `dispatchable_fungible_asset::register_dispatch_functions` to bind the functions with your fungible asset.

```
module 0x1::dispatchable_fungible_asset {    public fun register_dispatch_functions(        constructor_ref: &ConstructorRef,        withdraw_function: Option<FunctionInfo>,        deposit_function: Option<FunctionInfo>,        derived_balance_function: Option<FunctionInfo>,    )}
```

Note

The `register_dispatch_functions` function takes `Option<FunctionInfo>` as input to specify whether to use custom or default logic for withdraw/deposit/balance operations. If `option::none()` is passed, the default logic is used. A `FunctionInfo` identifies the function to be used as a custom hook. The `constructor_ref` is a reference for the metadata object of your fungible asset.

To construct a `FunctionInfo`, use either of:

```
module 0x1::function_info {    public fun new_function_info(module_signer: &signer, module_name: String, function_name: String): FunctionInfo    // or if you do not have the signer:    public fun new_function_info_from_address(module_address: address, module_name: String, function_name: String): FunctionInfo}
```

The registration can look like this:

```
module my_addr::my_fungible_asset_example {    use aptos_framework::string;    use aptos_framework::object;    use aptos_framework::primary_fungible_store;    use aptos_framework::dispatchable_fungible_asset;    use aptos_framework::function_info;
    fun create_fungible_asset(module_signer: &signer, /* ... */) {        // Make the deposit override function info        let deposit_override = function_info::new_function_info(            module_signer,            string::utf8(b"my_fungible_asset_example"),            string::utf8("deposit")        );
        // Create the fungible asset        let constructor_ref = object::create_sticky_object( /* ... */);
        primary_fungible_store::create_primary_store_enabled_fungible_asset(&constructor_ref, ...);        // or below if not having primary stores        // fungible_asset::add_fungibility(&constructor_ref, /* ... */);
        // Override default functionality for deposit        dispatchable_fungible_asset::register_dispatch_functions(            &constructor_ref,            option::none(),            option::some(deposit_override),            option::none()        );
        // ...    }
    // ...}
```

### Interacting with dispatchable fungible asset

[](#interacting-with-dispatchable-fungible-asset)

For users using `primary_fungible_store` to manage assets, no changes are required to interact with assets with dispatchable hooks. The Aptos Framework automatically invokes the dispatch logic if a hook is set up.

For users using secondary `FungibleStore` to interact with assets, use `dispatchable_fungible_asset::withdraw/deposit` instead of `fungible_asset::withdraw/deposit` to handle assets with registered hooks.

The `dispatchable_fungible_asset::withdraw/deposit` functions are replacements, and also work with functions that do not have hooks registered.

## Managing Stores (Advanced)

[](#managing-stores-advanced)

Behind the scenes, the Fungible Asset Standard needs to manage how the asset balances are stored on each account. In the vast majority of circumstances, users will store all FA balances in their Primary `FungibleStore`. Sometimes though, additional “Secondary Stores” can be created for advanced DeFi applications.

*   Each account owns only one non-deletable primary store for each type of FA, the address of which is derived in a deterministic manner from the account address and metadata object address. If primary store does not exist, it will be created if FA is going to be deposited by calling functions defined in `primary_fungible_store.move`
*   Secondary stores do not have deterministic addresses and are deletable when empty. Users are able to create as many secondary stores as they want using the provided functions but there is a caveat that addressing secondary stores on-chain may be more complex.

You can look up a primary store via the following function:

```
public fun primary_store<T: key>(owner: address, metadata: Object<T>): Object<FungibleStore>
```

And if you want to create a primary store manually you can use this function:

```
public fun create_primary_store<T: key>(owner_addr: address, metadata: Object<T>): Object<FungibleStore>
```

The primary reason to use a secondary store is for assets managed by a smart contract. For example, an asset pool may have to manage multiple fungible stores for one or more types of FA.

To create a secondary store, you must:

1.  Create an Object to get its `ConstructorRef`.
2.  Call:

```
public fun create_store<T: key>(constructor_ref: &ConstructorRef, metadata: Object<T>): Object<FungibleStore>
```

This will create a secondary store owned by the newly created Object. Sometimes an object can be reused as a store. For example, a metadata object can also be a store to hold some FA of its own type or a liquidity pool object can be a store of the issued liquidity pool's coin.

It is crucial to set the correct owner of a `FungibleStore` object for managing the FA stored inside. By default, the owner of a newly created object is the creator whose `signer` is passed into the creation function. For `FungibleStore` objects managed by smart contract itself, the owner should usually be an Object address controlled by the contract. For those cases, those objects should keep their `ExtendRef` at the proper place to create `signer` as needed to modify the `FungibleStore` via contract logic.

## Migration from `Coin` to the Fungible Asset Standard

[](#migration-from-coin-to-the-fungible-asset-standard)

### Smart Contract Migration

[](#smart-contract-migration)

**Projects utilizing the `coin` module do not need to modify their contracts.** The `coin` module has been enhanced to handle migration automatically. Whenever a paired FA is required for a `coin`, it will be automatically created if it doesn't already exist. The mapping between coins and FAs is immutable and stored in an on-chain table:

```
struct CoinConversionMap has key {    coin_to_fungible_asset_map: Table<TypeInfo, address>,}
```

A `#[view]` function is available to retrieve metadata for the paired FA if it exists:

```
#[view]public fun paired_metadata<CoinType>(): Option<Object<Metadata>>
```

Similarly, a function exists for reverse lookup:

```
#[view]public fun paired_coin(metadata: Object<Metadata>): Option<TypeInfo>
```

### Off-chain Migration

[](#off-chain-migration)

There are two changes needed for off-chain services:

1.  Balances should reflect that a user may have **both** a `coin` balance and a paired FA balance.
2.  Event listeners should listen for both `coin` and FA events.

Since a user may possess **both** a `coin` balance and a paired FA balance, off-chain applications should be updated to reflect the **sum** of both the `coin` balance and its paired FA balance.

*   For Aptos Indexer users, you may utilize the table called `current_fungible_asset_balances` to obtain the latest sum of coin balance and FA balance representing the same asset type. If the FA has a paired coin type, the asset type would be set to the coin type, such as `0x1::aptos_coin::AptosCoin`. Otherwise, for FA not paired from a coin, the asset type would be the metadata address. Users could filter by this field to get the FA balance of their interest.
*   For users employing Node API or other customized indexing, they should add the balance of the paired FA in users' `FungibleStore` and `ConcurrentFungibleBalance` if any of them exist to the coin balance.

To retrieve the balance of the `PrimaryFungibleStore` for a paired FA to an existing `coin` of type `CoinType`:

1.  Call `paired_metadata<CoinType>()` to obtain the paired FA metadata object address (the address is immutable).
2.  Retrieve the balance of the paired FA:
    *   Call [getCurrentFungibleAssetBalances](https://github.com/aptos-labs/aptos-ts-sdk/blob/c01a26ff899235fac1c31c6cc3fe504b764e5b91/src/api/fungibleAsset.ts#L115).
    *   Alternatively, determine the address of the primary `FungibleStore`, which can be deterministically calculated with the following formula:
        *   `sha3_256(32-byte account address | 32-byte metadata object address | 0xFC)`
    *   Then use that address to obtain the `FungibleStore` resource to fetch the balance.
        *   If the balance is non-zero, this is the final balance of this FA.
        *   Otherwise, try to get `ConcurrentFungibleBalance` resource at the same address and get the balance there instead.
        *   If neither exist, the FA balance for this account is 0.

**Post-migration, both coin events and FA events could be emitted for an activity, depending on whether the user has migrated or not.** Dapps relying on events should update their business logic accordingly.

### Migration FAQs

[](#migration-faqs)

What is the Aptos Fungible Asset (FA) standard?

The FA standard introduces a new way to represent fungible tokens as [Move objects](/build/smart-contracts/objects), replacing the legacy Coin resource model. Fungible Assets are more composable and developer-friendly compared to legacy Coins.

APT will be migrated starting on June 30, 2025.

How exactly does the new FA standard differ from legacy Coins?

With legacy Coins, each account directly holds a `CoinStore\<CoinType>` resource that tracks balances (in u64), includes flags like "frozen," and emits basic events on deposits or withdrawals. Transfers, mints, and burns are performed via `0x1::coin` module functions.

Under the FA Standard, token balances are held in FungibleStore objects (instead of each account directly holding a CoinStore resource). Each asset has metadata that defines its properties (name, symbol, etc.). For any account that owns that token, the balance lives in a FungibleStore object belonging to that account and linked to the Metadata object.

The primary way an account holds a fungible asset is via a primary fungible store; the address of this object is deterministically derived from the user's account address and the token's metadata address.

FAs come in two flavors:

1.  **Vanilla FA**: Tokens that primarily manage simple balance updates.
    
2.  **Dispatchable FA (DFA)**: Tokens that embed custom Move logic automatically executed upon transfers.

How will this migration impact me?

As an end user, you don't need to do anything. Your tokens remain safe, exactly where they should be in their new form. The migration does not affect ownership or usability in any way.

If you're a developer, your existing smart contract code remains functional, but you should immediately start using the FA SDK for all new work. Existing coin API calls will continue working by silently routing to FA. After the migration, the coin module will be kept as it is, with minimal maintenance. Please note that you will no longer be able to look up coin balance by resource. Move to the `0x1::coin::balance` view function, or the balance REST API instead.

What is the migration timeline?

All tokens on Aptos will begin migrating automatically from Coin v1 to the FA standard. All the coins except APT will be migrated from June 23 to 30. APT will transition from June 30 to July 8, 2025. The process involves continuously running batched transactions until every valid CoinStore has been fully converted into the new FungibleStore.

Why is the upgrade to the Fungible Asset standard necessary?

Short answer: It unlocks powerful functionalities that the legacy Coin module simply cannot support.

Modern DeFi and RWA apps increasingly demand sophisticated features like automated yield claims, custom fee structures, and built-in compliance checks. These are difficult to implement on legacy Coins. Attempting to bolt these capabilities onto the old standard rapidly creates composability issues, integration headaches and rising complexity.

Beyond functionality, builders can also use a unified asset standard across all tokens, including stablecoins. Imagine designing a payment kiosk: if it accepts only digital payments, you avoid the complexity of cash slots, coin dispensers, and change mechanisms altogether. Similarly, adopting a single streamlined token standard reduces complexity in platform development. It improves developer productivity and delivers more consistent user experience.

In short, the FA standard is clean and elegant. Developers can launch tokens that immediately integrate seamlessly across wallets, explorers, and DeFi applications from day one.

What are some new and unique functionalities I can build with Fungible Assets?

Fungible Assets open the door to a range of advanced features that weren't possible with the legacy Coin model. Some notable capabilities include:

*   Tokens that automatically collect fees (like a percentage charge on transfers).
    
*   Interest-bearing tokens that accrue yield directly to the holders without manual claims.
    
*   Tokens with built-in vesting or time-locks that automatically release funds when certain conditions are met, a la escrow.
    
*   Tokens that dispense loyalty points on-chain when they're spent.
    
*   Tokens that can dynamically adjust supply; burning or minting based on usage patterns.

The possibilities are endless.

A great real-world example is xLPT from [Thala Labs](https://www.thalalabs.xyz/), which uses built-in DFA hooks to automate staking & unstaking LP tokens, updating positions and rewards automatically upon each transfer, without any user intervention.

We know there is always a paired FA of a coin type. How can we query the supply and balance of this asset after the migration?

After the migration, querying resource `0x1::coin::CoinStore<0x1::aptos_coin::AptosCoin>` at account address will be unavailable. Instead, you can query the account balance by the following three ways:

1.  [Balance Node API](/build/apis/fullnode-rest-api#tag/accounts/GET/accounts/%7Baddress%7D/balance/%7Basset_type%7D), the asset\_type can be either coin\_type, such as 0x1::aptos\_coin::AptosCoin or FA metadata address such as 0xa, either way should return the same value.
    
2.  `#[view] function primary_fungible_store::balance<T: key>(account: address, metadata: Object<T>): u64`
    
3.  `#[view] function balance<CoinType>(owner: address): u64`. This method is deprecated and not applicable to pure FA tokens (e.g., USDt); it applies only to migrated coins such as APT. Due to its limitations and higher gas costs, it is not recommended.

Before migration, I could query all the assets a user has by getting all the resources at their address using API. How do I do it after migration?

You can [use the Indexer API](/build/indexer/indexer-api/indexer-reference#current_fungible_asset_balances) to query all the fungible assets the user owns.

Querying raw resources to get the asset balance and types is not recommended and will not be well-supported by fullnode API.

What if I have more questions?

Join the [Aptos Discord](https://discord.com/invite/aptosnetwork)! Aptos Labs engineers will be available throughout migration week to answer questions and offer support.

# Aptos Move Lint

> Learn about linter for Move smart contract development on Aptos blockchain.

The "Aptos Move Lint" tool runs on a Move package to find and warn about common issues in Move programs, helping improve your Move code.

You can run it with the aptos CLI command: `aptos move lint`.

If you find any issues, please submit [bugs and feedback](https://github.com/aptos-labs/aptos-core/issues/new?title=%5Blinter%5D%20%3CDescriptive%20Title%3E&body=%3CDetailed%20description%20of%20the%20issue%20or%20feature%20request%3E&labels=move-linter&projects=aptos-labs/16). Also, we are tracking ideas and prioritization requests for new lint rules [here](https://github.com/aptos-labs/aptos-core/issues/15221), we welcome your contributions.

## Lint Checks

[](#lint-checks)

### `aborting_overflow_checks`

[](#aborting_overflow_checks)

Checks for patterns that resemble overflow checks done in C code:

```
// Overflow checkif (x > x + y) {  abort 1;};
// Underflow checkif (x < x - y) {  abort 1;};
```

Such checks in Move do not make sense, as they either abort immediately or always return true/false.

### `almost_swapped`

[](#almost_swapped)

Checks for expression patterns that look like a failed swap attempt and notifies the user. These patterns are likely erroneous code. This currently only detects simple access patterns such as assignments to a variable or a field of a struct. Examples include:

*   `a = b; b = a;` which can be correctly swapped with `(a, b) = (b, a);`
*   `a.x = b.x; b.x = a.x;` which can be correctly swapped with `(a.x, b.x) = (b.x, a.x);`

### `assert_const`

[](#assert_const)

Checks for trivial assertions, including `assert!(true)` and `assert!(false)`. The former can be replaced by an abort, while the latter is equivalent to a no-op, which can be removed entirely.

### `avoid_copy_on_identity_comparison`

[](#avoid_copy_on_identity_comparison)

Checks for identity comparisons (`==` or `!=`) between copied values of type `vector` or `struct` (i.e., types for which copy can be expensive). It instead suggests to use reference-based identity comparison instead (i.e., use `&x == &y` instead of `x == y`, when the above mentioned conditions meet).

[This recommendation](https://aptos-labs.github.io/move-book/equality-and-comparison.html#avoid-extra-copies) is also given in the Move book. Due to automatic copy inference, it may not be obvious when a copy is being made while using `==` or `!=` on values with types that have the `copy` ability. This lint identifies cases where extra copies on vectors or structs could be skipped by using reference-based identity comparisons.

### `blocks_in_conditions`

[](#blocks_in_conditions)

Checks for use of blocks in conditions (e.g., in `if`, `match`, and `while` conditions), which can make code hard to read. An example coding pattern caught by this lint is:

```
if ({let x = foo(); !x}) { // uses a block in condition  bar();}
```

Such code can usually be rewritten to hoist the block out and above the condition, usually making it more readable.

It is a common Move pattern to provide inline specifications in conditions, especially loop invariants, which requires creating blocks in conditions. We exclude this pattern in the lint check to continue to allow for this specification pattern.

Note that an `assert!` is translated to a conditional abort, so blocks in `assert!` condition also are reported by this lint.

### `empty_if`

[](#empty_if)

Checks for `if` statements that have no body, such as:

```
if (x) {}
```

### `equal_operands_in_bin_op`

[](#equal_operands_in_bin_op)

Checks for binary operations with identical operands. For example, `x % x`, `x ^ x`, `x > x`, `x >= x`, `x == x`, `x | x`, `x & x`, `x / x`, and `x != x` are all caught by this lint. The lint also suggests replacing these with a simplified value or expression, such as `0`, `true`, or `false`.

### `empty_range`

[](#empty_range)

Checks for empty ranges in `for` loops, such as `for i in 0..0 { ... }`, which do not execute the loop body. This can happen when the start of the range is greater than or equal to the end of the range, resulting in an empty iteration.

### `unnecessary_cast`

[](#unnecessary_cast)

Checks for unnecessary type casts where the source expression already has the target type. These casts are redundant and can be removed to improve code readability.

For example:

```
let x: u64 = 42;let y = x as u64; // unnecessary cast, x is already u64
```

can be simplified to:

```
let x: u64 = 42;let y = x; // cast removed
```

### `known_to_abort`

[](#known_to_abort)

Checks for expressions where the use of constant values will violate runtime constraints and abort the execution.

Specifically, the following patterns are detected:

*   **Bit shifts with excessive shift amounts**: `x << n` or `x >> n` where `n` is a constant that is greater than or equal to the bit width of `x`'s type. For example, `value << 64`, when `value` has type `u64`, will always abort.
*   **Division or modulo by zero**: `x / 0` or `x % 0` operations will always abort at runtime.
*   **Out-of-range type casting**: `constant as type` where the `constant` value is outside the representable range of the target `type`. For example, `300 as u8` will abort since `u8` can only represent values 0-255.

### `needless_bool`

[](#needless_bool)

Checks for patterns of the form (where `x` is any arbitrary boolean expression):

*   `if (x) true else false`, which can be replaced with just `x`.
*   `if (x) false else true`, which can be replaced with just `!x`.
*   `if (x) { return true } else { return false }`, which can be replaced with just `return x`.
*   `if (x) { return false } else { return true }`, which can be replaced with just `return !x`.
*   `if (x) true else true` or `if (x) false else false`, which should be rewritten to remove the redundant branch.

### `needless_deref_ref`

[](#needless_deref_ref)

Checks for patterns where references taken are immediately dereferenced, and suggests removing the pair of dereference-reference operators:

*   `*&x.f` can be simplified to `x.f`
*   `*&mut x.f` can be simplified to `x.f`
*   `*&mut x.f = 5;` can be simplified to `x.f = 5;`

### `needless_loops`

[](#needless_loops)

Checks for loops that always exit on their first iteration, making the loop construct unnecessary. This lint detects loops that immediately return, abort, or break without performing any meaningful iteration.

The linter identifies these patterns:

*   Loops where the first instruction is `return`, `abort`, or `break`
*   Loops where the first instruction is a conditional branch where both paths immediately exit the loop

Examples of needless loops:

```
// Always returns on first iterationloop {    return 42;}
// Always aborts on first iterationloop {    abort 1;}
```

These can be simplified by removing the loop construct entirely and using just the exit statement directly.

This lint uses conservative analysis to avoid false positives, only flagging cases where the exit behavior is immediately obvious from the loop's structure.

### `needless_mutable_reference`

[](#needless_mutable_reference)

Checks for mutable references or borrows (currently: mutable reference parameters, mutable borrow of locals, `borrow_global_mut`) that are not used mutably, and suggests to use the immutable reference or borrow instead.

For example, in the function `foo` below, `&mut` can be replaced by `&` because the reference is not mutably used.

```
fun foo(x: u64): u64 {  let y = &mut x;  *y}
```

### `needless_ref_deref`

[](#needless_ref_deref)

Checks for patterns where immutable reference are taken for a dereference, and suggests removing the pair of reference-dereference operators: `&*x` can be simplified to `x`.

### `needless_ref_in_field_access`

[](#needless_ref_in_field_access)

Checks for patterns where there are needless references taken when accessing a field of a struct or an enum, and suggests removing the explicit reference taken:

*   `(&s).f` can be simplified to `s.f`
*   `(&mut s).f = 42;` can be simplified to `s.f = 42;`

### `needless_return`

[](#needless_return)

Checks for unnecessary `return` statements. This lint detects unnecessary return statements where the value can be returned directly without using the `return` keyword. For example, the following function:

```
public fun foo(): bool {  // ...  return true;}
```

can be simplified to:

```
public fun foo(): bool {  // ...  true}
```

### `nested_if`

[](#nested_if)

Checks for nested if statements that can be simplified using the `&&` operator. This lint identifies patterns where an inner if statement with no else branch is contained within an outer if statement that also has no else branch.

```
if (a) {    if (b) {        // some code    }}
```

This pattern can be simplified to:

```
if (a && b) {    // some code}
```

The simplified version is more readable and avoids unnecessary nesting while maintaining the same logical behavior.

### `nonminimal_bool`

[](#nonminimal_bool)

Check for boolean expressions that can be simplified when a boolean literal (either `true` or `false`) is part of a binary or unary boolean operator. Examples:

*   `x && true` is logically equivalent to `x`
*   `x || true` is logically equivalent to `true`
*   `x => false` is logically equivalent to `!x`
*   `x <==> true` is logically equivalent to `x`
*   `! true` is logically equivalent to `false`

Does NOT consider side-effects/short-circuiting in the recommended simplifications. Example:

*   `1/0 || true` is logically equivalent to `true`, but applying this simplification affects program semantics.

### `no_op`

[](#no_op)

Checks for statements that can be removed without changing program behavior. Examples:

*   `42;`
*   `*(&mut 0) = /*...*/;`
*   `x << 4;`

Note that the linter does not take into account possible aborts due to arithmetic errors. If a statement is flagged it's almost definitely a programmer mistake, but you should evaluate the code in question to understand the intent. Sometimes the proper fix is to remove the statement, sometimes the statement should be changed.

### `self_assignment`

[](#self_assignment)

Checks for patterns where a variable or a field of a struct is assigned to itself and suggests removing the assignment. These assignments do not affect the state of the program. Examples include:

*   `let x = x;`
*   `x = x;`
*   `a.x = a.x;`

### `simpler_bool_expression`

[](#simpler_bool_expression)

Checks for boolean patterns that can be simplified through different boolean algebra laws. Examples include:

*   Absorption law:
    *   `a && b || a` can be simplified to `a`
    *   `a || a && b` can be simplified to `a`
*   Idempotence:
    *   `a && a` can be simplified to `a`
    *   `a || a` can be simplified to `a`
*   Contradiction
    *   `a && !a` can be simplified to `false`
    *   `!a && a` can be simplified to `false`
*   Tautology:
    *   `a || !a` can be simplified to `true`
    *   `!a || a` can be simplified to `true`
*   Distributive law:
    *   `(a && b) || (a && c)` can be simplified to `a && (b || c)`
    *   `(a || b) && (a || c)` can be simplified to `a || (b && c)`

where `a`, `b` and `c` can either be simple or composed expressions.

### `simpler_numeric_expression`

[](#simpler_numeric_expression)

Checks for various patterns where a simpler numeric expression can be used instead. In all these cases, the code must already type check, and `x` can be any numeric expression.

*   `x & 0`, `x * 0`, `0 & x`, `0 * x`, `0 << x`, `0 >> x`, `x % 1` can all be replaced with just `0`.
*   `x | 0`, `x ^ 0`, `x >> 0`, `x << 0`, `x + 0`, `x - 0`, `x / 1`, `x * 1`, `0 | x`, `0 ^ x`, `0 + x`, `1 * x` can all be replaced with just `x`.

### `unnecessary_boolean_identity_comparison`

[](#unnecessary_boolean_identity_comparison)

Checks for boolean identity comparisons of the form:

*   `x == true`, `true == x`, which can be replaced with just `x`.
*   `x == false`, `false == x`, which can be replaced with just `!x`.

In all these cases, `x` can be any arbitrary boolean expression.

### `unnecessary_numerical_extreme_comparison`

[](#unnecessary_numerical_extreme_comparison)

Checks if there are any numerical comparisons with extreme values (i.e., min and max value representable by that numeric type) that are unnecessary or can be made more precise and clear. Depending on the comparison, various recommendations are made.

Consider the following example expressions that are caught by the lint, and the corresponding recommendations made (in all these cases, `x` is a place holder for a numerical expression of type `u8`, `u16`, `u32`, `u64`, `u128`, or `u256`, and `MAX` is a place holder for the max value representable for that numeric type):

*   `x < 0`, `0 > x`, `x > MAX`, `MAX < x`, are always false, rewrite code to remove this comparison
*   `x >= 0`, `0 <= x`, `x <= MAX`, `MAX >= x`, are always true, rewrite code to remove this comparison
*   `x <= 0`, `0 >= x`, `x >= MAX`, `MAX <= x`, can all be simplified to use `==` instead
*   `x > 0`, `0 < x`, `x < MAX`, `MAX > x`, can all be clarified to use `!=` instead

### `while_true`

[](#while_true)

Checks for `while (true) { .... }` patterns and suggests using the more explicit `loop { .... }` construct instead.

## Suppressing Lint Warnings

[](#suppressing-lint-warnings)

To suppress one or more lint checks named `check1`, `check2`, ... (and so on), you can add the attribute `#[lint::skip(check1, check2, ...)]` to a function or a module. The linter will then not perform the checks named `check1`, `check2`, ... (and so on) for that function or module.

For example, the function below would usually get a warning from the linter about a `needless_bool`, but due to the attribute on the function, the linter does not emit a warning.

```
#[lint::skip(needless_bool)]fun violation(): bool {    if (foo()) true else false}
```

## Experimental Checks

[](#experimental-checks)

### `cyclomatic_complexity`

[](#cyclomatic_complexity)

Cyclomatic complexity measures the number of linearly independent execution paths through a function. A high value generally correlates with code that is harder to test and maintain.

This linter performs an approximation while traversing the Move expression tree:

1.  The complexity score starts at **1**.
2.  The score is incremented for each control-flow decision point found:
    *   +1 for each `if`
    *   +1 for each `else if`
    *   +1 for each `loop`, `while`, or `for`
    *   +1 for each `break` or `continue`
    *   +1 for each `return` statement that is not the final expression in the function
    *   +n where n = (number of match arms - 1)

When the accumulated score exceeds the default threshold (currently **10**), the linter emits a diagnostic suggesting that the function be simplified or decomposed.

# Maps

> Learn about maps for Move smart contract development on Aptos blockchain.

There are multiple different implementations of key-value maps inside the framework, suited for different usecases. We will go over their differences and similarities, and how to choose which one to use.

## Aptos Blockchain performance and gas cost considerations

[](#aptos-blockchain-performance-and-gas-cost-considerations)

Aptos Blockchain state is kept in **storage slots**. Furthermore, transaction performance and gas cost is heavily influenced by how these **slots** are read and written. Breaking down the gas costs further, we have:

1.  Storage fee, which are determined by the number and size of **slots** (i.e., writing to a new **slot** incurs the highest storage fee, whereas deleting an existing **slot** provides the largest refund.)
2.  IO gas costs —generally much lower— which depend on the number and size of resources read and modified.
3.  execution gas costs are based on the computation needed, and are generally in the similar scale as io gas costs.

Transactions that modify the same **slot** cannot be executed concurrently (with some exceptions, like aggregators and resources as a part of the same resource group), as they conflict with one another.

One useful analogy is thinking about each **slot** being a file on a disk, then performance of smart contract would correlate well to a program that operates on files in the same way.

## Different Map implementations

[](#different-map-implementations)

| Implementation | Size Limit | Storage Structure | Key Features | | ----------------- | ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `OrderedMap` | Bounded (fits in a single **slot**) | Stored entirely within the resource that contains it | Supports ordered access (front/back, prev/next), implemented as sorted vector, but operations are effectively O(log(n)) due to internal optimizations | | `Table` | Unbounded | Each (key, value) stored in a separate **slot** | Supports basic operations, like `add`, `remove`, `contains`, but **not iteration**, and **cannot be destroyed**; useful for large/unbounded keys/values and where high-concurrency is needed | | `TableWithLength` | Unbounded | same as `Table` | Variant of `Table`, with additional length tracking, which adds `length`, `empty`, and `destroy_empty` methods; Adding or removing elements **cannot** be done concurrently, modifying existing elements can. | | `BigOrderedMap` | Unbounded | Combines multiple keys into a single **slot**, initially stored within resource that contains it, and grows into multiple **slots** dynamically | Implemented as B+ tree; **opportunistically concurrent** for non-adjacent keys; supports ordered access (front/back, prev/next); configurable node capacities to balance storage and performance |

Note:

*   `SimpleMap` has been deprecated, and replaced with `OrderedMap`.
*   `SmartTable` has been deprecated, and replaced with `BigOrderedMap`.

#### Performance comparison

[](#performance-comparison)

We measured performance at small scale, measuring microseconds taken for a single pair of `insert` + `remove` operation, into a map of varied size.

| num elements | OrderedMap | BigOrderedMap max\_degree>10000 | BigOrderedMap max\_degree=16 | | ------------ | ---------- | ------------------------------- | ---------------------------- | | 10 | 65 | 123 | 123 | | 100 | 85 | 146 | 455 | | 1000 | 105 | 168 | 567 | | 10000 | 142 | 210 | 656 |

You can see that overhead of `BigOrderedMap` compared to `OrderedMap`, when both are in the single **slot**, is around 1.5-2x. So you can generally used `BigOrdredMap` when it is unknown if data will be too large to be stored in a single **slot**.

## Common map operations:

[](#common-map-operations)

Most maps above support the same set of functions (for actual signatures and restrictions, check out the corresponding implementations):

#### Creating Maps

[](#creating-maps)

*   `new<K, V>(): Self`: creates an empty map

#### Destroying Maps

[](#destroying-maps)

*   `destroy_empty<K, V>(self: Self<K, V>)`: Destroys an empty map. (**not** supported by `Table`)
*   `destroy<K, V>(self: Self<K, V>, dk: |K|, dv: |V|)`: Destroys a map with given functions that destroy corresponding elements. (**not** supported by `Table` and `TableWithLength`)

#### Managing Entries

[](#managing-entries)

*   `add<K, V>(self: &mut Self<K, V>, key: K, value: V)`: Adds a key-value pair to the map.
*   `remove<K, V>(self: &mut Self<K, V>, key: K): V`: Removes and returns the value associated with a key.
*   `upsert<K, V>(self: &mut Self<K, V>, key: K, value: V): Option<V>`: Inserts or updates a key-value pair.
*   `add_all<K, V>(self: &mut Self<K, V>, keys: vector<K>, values: vector<V>)`: Adds multiple key-value pairs to the map. (**not** supported by `Table` and `TableWithLength`)

#### Retrieving Entries

[](#retrieving-entries)

*   `contains<K, V>(self: &Self<K, V>, key: &K): bool`: Checks whether key exists in the map.
*   `borrow<K, V>(self: &Self<K, V>, key: &K): &V`: Returns an immutable reference to the value associated with a key.
*   `borrow_mut<K: drop, V>(self: &mut Self<K, V>, key: K): &mut V`: Returns a mutable reference to the value associated with a key. (`BigOrderedMap` only allows `borrow_mut` when value type has a static constant size, due to modification being able to break it's invariants otherwise. Use `remove()` and `add()` combination instead)

#### Order-dependant functions

[](#order-dependant-functions)

These set of functions are only implemented by `OrderedMap` and `BigOrderedMap`.

*   `borrow_front<K, V>(self: &Self<K, V>): (&K, &V)`
*   `borrow_back<K, V>(self: &Self<K, V>): (&K, &V)`
*   `pop_front<K, V>(self: &mut Self<K, V>): (K, V)`
*   `pop_back<K, V>(self: &mut Self<K, V>): (K, V)`
*   `prev_key<K: copy, V>(self: &Self<K, V>, key: &K): Option<K>`
*   `next_key<K: copy, V>(self: &Self<K, V>, key: &K): Option<K>`

#### Utility Functions

[](#utility-functions)

*   `length<K, V>(self: &Self<K, V>): u64`: Returns the number of entries in the map. (not supported by `Table`)

#### Traversal Functions

[](#traversal-functions)

These set of functions are not implemented by `Table` and `TableWithLength`.

*   `keys<K: copy, V>(self: &Self<K, V>): vector<K>`
    
*   `values<K, V: copy>(self: &Self<K, V>): vector<V>`
    
*   `to_vec_pair<K, V>(self: Self<K, V>): (vector<K>, vector<V>)`
    
*   `for_each_ref<K, V>(self: &Self<K, V>, f: |&K, &V|)`
    
*   `to_ordered_map<K, V>(self: &BigOrderedMap<K, V>): OrderedMap<K, V>`: Converts `BigOrderedMap` into `OrderedMap`

## Example Usage

[](#example-usage)

### Creating and Using a OrderedMap

[](#creating-and-using-a-orderedmap)

```
module 0x42::map_usage {    use aptos_framework::ordered_map;
    public entry fun main() {        let map = ordered_map::new<u64, u64>();        map.add(1, 100);        map.add(2, 200);
        let length = map.length();        assert!(length == 2, 0);
        let value1 = map.borrow(&1);        assert!(*value1 == 100, 0);
        let value2 = map.borrow(&2);        assert!(*value2 == 200, 0);
        let removed_value = map.remove(&1);        assert!(removed_value == 100, 0);
        map.destroy_empty();    }}
```

## Additional details for `BigOrderedMap`

[](#additional-details-for-bigorderedmap)

Its current implementation is B+ tree, which is chosen as it is best suited for the onchain storage layout - where the majority of cost comes from loading and writing to storage items, and there is no partial read/write of them.

Implementation has few characteristics that make it very versatile and useful across wide range of usecases:

*   When it has few elements, it stores all of them within the resource that contains it, providing comparable performance to OrderedMap itself, while then dynamically growing to multiple resources as more and more elements are added
*   It reduces amount of conflicts: modifications to a different part of the key-space can be generally done concurrently, and it provides knobs for tuning between concurrency and size
*   All operations have guaranteed upper-bounds on performance (how long they take, as well as how much execution and io gas they consume), allowing for safe usage across a variety of use cases.
    *   One caveat, is refundable storage fee. By default, operation that requires map to grow to more resources needs to pay for storage fee for it. Implementation here has an option to pre-pay for storage slots, and to reuse them as elements are added/removed, allowing applications to achieve fully predictable overall gas charges, if needed.
*   If key/value is within the size limits map was configured with, inserts will never fail unpredictably, as map internally understands and manages maximal **slot** size limits.

### `BigOrderedMap` structure

[](#bigorderedmap-structure)

`BigOrderedMap` is represented as a tree, where inner nodes split the "key-space" into separate ranges for each of it's children, and leaf nodes contain the actual key-value pairs. Internally it has `inner_max_degree` representing largest number of children an inner node can have, and `leaf_max_degree` representing largest number of key-value pairs leaf node can have.

#### Creating `BigOrderedMap`

[](#creating-bigorderedmap)

Because it's layout affects what can be inserted and performance, there are a few ways to create and configure it:

*   `new<K, V>(): Self<K, V>`: Returns a new `BigOrderedMap` with the default configuration. Only allowed to be called with constant size types. For variable sized types, another constructor is needed, to explicitly select automatic or specific degree selection.
    
*   `new_with_type_size_hints<K, V>(avg_key_bytes: u64, max_key_bytes: u64, avg_value_bytes: u64, max_value_bytes: u64): Self<K, V>`: Returns a map that is configured to perform best when keys and values are of given `avg` sizes, and guarantees to fit elements up to given `max` sizes.
    
*   `new_with_config<K, V>(inner_max_degree: u16, leaf_max_degree: u16, reuse_slots: bool): Self<K, V>`: Returns a new `BigOrderedMap` with the provided max degree consts (the maximum # of children a node can have, both inner and leaf). If 0 is passed for either, then it is dynamically computed based on size of first key and value, and keys and values up to 100x times larger will be accepted. If non-0 is passed, sizes of all elements must respect (or their additions will be rejected):
    
    *   `key_size * inner_max_degree <= MAX_NODE_BYTES`
    *   `entry_size * leaf_max_degree <= MAX_NODE_BYTES`
    
    `reuse_slots` means that removing elements from the map doesn't free the storage slots and returns the refund. Together with `allocate_spare_slots`, it allows to preallocate slots and have inserts have predictable gas costs. (otherwise, inserts that require map to add new nodes, cost significantly more, compared to the rest)

## Source Code

[](#source-code)

*   [ordered\_map.move](https://github.com/aptos-labs/aptos-core/blob/main/aptos-move/framework/aptos-framework/sources/datastructures/ordered_map.move)
*   [table.move](https://github.com/aptos-labs/aptos-core/blob/6f5872b567075fe3615e1363d35f89dc5eb45b0d/aptos-move/framework/aptos-stdlib/sources/table.move)
*   [table\_with\_length.move](https://github.com/aptos-labs/aptos-core/blob/6f5872b567075fe3615e1363d35f89dc5eb45b0d/aptos-move/framework/aptos-stdlib/sources/table.move)
*   [big\_ordered\_map.move](https://github.com/aptos-labs/aptos-core/blob/main/aptos-move/framework/aptos-framework/sources/datastructures/big_ordered_map.move)

## Additional details of (deprecated) SmartTable

[](#additional-details-of-deprecated-smarttable)

The Smart Table is a scalable hash table implementation based on linear hashing. This data structure aims to optimize storage and performance by utilizing linear hashing, which splits one bucket at a time instead of doubling the number of buckets, thus avoiding unexpected gas costs. Unfortunately, it's implementation makes every addition/removal be a conflict, making such transactions fully sequential. The Smart Table uses the SipHash function for faster hash computations while tolerating collisions. Unfortunately, this also means that collisions are predictable, which means that if end users can control the keys being inserted, it can have large number of collisions in a single bucket.

### SmartTable Structure

[](#smarttable-structure)

The `SmartTable` struct is designed to handle dynamic data efficiently:

*   `buckets`: A table with a length that stores vectors of entries.
*   `num_buckets`: The current number of buckets.
*   `level`: The number of bits representing `num_buckets`.
*   `size`: The total number of items in the table.
*   `split_load_threshold`: The load threshold percentage that triggers bucket splits.
*   `target_bucket_size`: The target size of each bucket, which is not strictly enforced.

### SmartTable usage examples

[](#smarttable-usage-examples)

*   [Move Spiders Smart Table](https://movespiders.com/courses/modules/datastructures/lessonId/7)
*   [Move Spiders Querying Smart Table via FullNode APIs](https://movespiders.com/courses/modules/datastructures/lessonId/9)
*   [Move Spiders Querying Smart Table via View Function](https://movespiders.com/courses/modules/datastructures/lessonId/10)

# Modules on Aptos

> Learn about modules on aptos for Move smart contract development on Aptos blockchain.

Aptos allows for permissionless publishing of [modules](https://aptos-labs.github.io/move-book/modules-and-packages.html) within a [package](https://aptos-labs.github.io/move-book/modules-and-packages.html) as well as [upgrading](https://aptos-labs.github.io/move-book/cli-deploy.html) those that have appropriate compatibility policy set.

A module contains several structs and functions, much like Rust.

During package publishing time, a few constraints are maintained:

*   Both Structs and public function signatures are published as immutable.
*   The `init_module` function plays a crucial role in module initialization:
    *   When a module is published for the first time (i.e., the module does not exist on-chain), the VM will search for and execute the `init_module(account: &signer)` function.
    *   When upgrading an existing module that is already on-chain, the `init_module` function will NOT be called.
    *   The signer of the account that is publishing the module is passed into the `init_module` function.
    *   **This function must be private and not return any value.**
    *   The `init_module` function can have at most one parameter, and its type must be `&signer`
    *   The `init_module` function should not have generic parameters
    *   The `init_module` function is commonly used to initialize module-specific data structures or set initial states.

Note

`init_module` is optional. You only need to implement it if you want to:

*   Initialize module data when publishing a module for the first time
*   Set up initial states or configurations
*   Create resource accounts or other module-specific setup tasks

Tip

Remember: The `init_module` function will only be called once in a module's lifecycle - when it is first published. Subsequent upgrades to the module will not trigger the `init_module` function again.

# Move Security Guidelines

> Learn about move security guidelines for Move smart contract development on Aptos blockchain.

The Move language is designed with security and inherently offers several features including a type system and a linear logic. Despite this, its novelty and the intricacies of some business logic mean that developers might not always be familiar with Move's secure coding patterns, potentially leading to bugs.

This guide addresses this gap by detailing common anti-patterns and their secure alternatives. It provides practical examples to illustrate how security issues can arise and recommends best practices for secure coding. This guide aims to sharpen developers' understanding of Move's security mechanisms and ensure the robust development of smart contracts.

## Access Control

[](#access-control)

### Object Ownership Check

[](#object-ownership-check)

Every `Object<T>` can be accessed by anyone, which means any `Object<T>` can be passed to any function, even if the caller doesn't own it. It's important to verify that the `signer` is the rightful owner of the object.

#### Example Insecure Code

[](#example-insecure-code)

In this module, a user must purchase a subscription before performing certain actions. The user invokes the registration function to acquire an `Object<Subscription>`, which they can later use to execute operations.

```
module 0x42::example {
    struct Subscription has key {        end_subscription: u64    }
    entry fun registration(user: &signer, end_subscription: u64) {        let price = calculate_subscription_price(end_subscription);        payment(user,price);
        let user_address = address_of(user);        let constructor_ref = object::create_object(user_address);        let subscription_signer = object::generate_signer(&constructor_ref);        move_to(&subscription_signer, Subscription { end_subscription });    }
    entry fun execute_action_with_valid_subscription(        user: &signer, obj: Object<Subscription>    ) acquires Subscription {        let object_address = object::object_address(&obj);        let subscription = borrow_global<Subscription>(object_address);        assert!(subscription.end_subscription >= aptos_framework::timestamp::now_seconds(), 1);        // Use the subscription        [...]    }}
```

In this insecure example, `execute_action_with_valid_subscription` does not verify if the user owns the `obj` passed to it. Consequently, anyone can use another person's subscription, bypassing the payment requirement.

#### Example Secure Code

[](#example-secure-code)

Ensure that the signer owns the object.

```
module 0x42::example {
    struct Subscription has key {        end_subscription: u64    }
    entry fun registration(user: &signer, end_subscription: u64) {        let price = calculate_subscription_price(end_subscription);        payment(user,price);
        let user_address = address_of(user);        let constructor_ref = object::create_object(user_address);        let subscription_signer = object::generate_signer(&constructor_ref);        move_to(&subscription_signer, Subscription { end_subscription });    }
    entry fun execute_action_with_valid_subscription(        user: &signer, obj: Object<Subscription>    ) acquires Subscription {        //ensure that the signer owns the object.        assert!(object::owner(&obj) == address_of(user), ENOT_OWNWER);        let object_address = object::object_address(&obj);        let subscription = borrow_global<Subscription>(object_address);        assert!(subscription.end_subscription >= aptos_framework::timestamp::now_seconds(), 1);        // Use the subscription        [...]    }}
```

### Global Storage Access Control

[](#global-storage-access-control)

Accepting a `&signer` is not always sufficient for access control purposes. Be sure to assert that the signer is the expected account, especially when performing sensitive operations.

Users without proper authorization can execute privileged actions.

#### Example Insecure Code

[](#example-insecure-code-1)

This code snippet allows any user invoking the `delete` function to remove an `Object`, without verifying that the caller has the necessary permissions.

```
module 0x42::example {  struct Object has key{    data: vector<u8>  }
  public fun delete(user: &signer, obj: Object) {    let Object { data } = obj;  }}
```

#### Example Secure Code

[](#example-secure-code-1)

A better alternative is to use the global storage provided by Move, by directly borrowing data off of `signer::address_of(signer)`. This approach ensures robust access control, as it exclusively accesses data contained within the address of the signer of the transaction. This method minimizes the risk of access control errors, ensuring that only the data owned by the `signer` can be manipulated.

```
module 0x42::example {  struct Object has key{    data: vector<u8>  }
  public fun delete(user: &signer) {    let Object { data } = move_from<Object>(signer::address_of(user));  }}
```

### Function visibility

[](#function-visibility)

Adhere to the principle of least privilege:

*   Always start with private functions, change their visibility as it is needed by the business logic.
*   Utilize `entry` for functions intended for use solely from the Aptos CLI or SDK.
*   Utilize `friend` for functions that can only be accessible by specific modules.
*   Utilize the `#[view]` decorator with functions that read data from storage without altering state. #\[view\] functions can be invoked indirectly and in this case they might change the storage.

Function visibility determines who can call a function. It's a way to enforce access control and is critical for smart contract security:

*   private functions are only callable within the module they are defined in. They're not accessible from other modules or from the CLI/SDK, which prevents unintended interactions with contract internals.

```
module 0x42::example {  fun sample_function() { /* ... */ }}
```

*   `public(friend)` functions expand on this by allowing specified _friends_ modules to call the function, enabling controlled interaction between different contracts while still restricting general access.

```
module 0x42::example {  friend package::mod;
  public(friend) fun sample_function() { /* ... */ }}
```

*   `public` functions are callable by any published module or script.

```
module 0x42::example {  public fun sample_function() { /* ... */ }}
```

*   `#[view]` decorated functions cannot alter storage; they only read data, providing a safe way to access information without risking state modification.

```
module 0x42::example {  #[view]  public fun read_only() { /* ... */ }}
```

*   The `entry` modifier in Move is used to indicate entry points for transactions. Functions with the `entry` modifier serve as the starting point of execution when a transaction is submitted to the blockchain.

```
module 0x42::example {  entry fun f(){}}
```

To summarize:

| | Module itself | Other Modules | Aptos CLI/SDK | | -------------- | ------------- | ---------------------------- | ------------- | | private | ✅ | ⛔ | ⛔ | | public(friend) | ✅ | ✅ if friend  
⛔ otherwise | ⛔ | | public | ✅ | ✅ | ⛔ | | entry | ✅ | ⛔ | ✅ |

This layered visibility ensures that only authorized entities can execute certain functions, greatly reducing the risk of bugs or attacks that compromise contract integrity.

Note that it’s possible to combine `entry` with `public` or `public(friend)`

```
module 0x42::example {  public(friend) entry fun sample_function() { /* ... */ }}
```

In this case `sample_function` can be called by both the Aptos CLI/SDK by any module declared as a friend.

#### Impact

[](#impact)

Adhering to this principle ensures that functions are not over-exposed, restricting the scope of function access to only what is necessary for the business logic.

## Types and Data Structures

[](#types-and-data-structures)

### Generics type check

[](#generics-type-check)

Generics can be used to define functions and structs over different input data types. When using them, ensure that the generic types are valid and what’s expected. [Read more](https://aptos-labs.github.io/move-book/generics-and-abilities.html) about generics.

Unchecked generics can lead to unauthorized actions or transaction aborts, potentially compromising the integrity of the protocol.

#### Example Insecure Code

[](#example-insecure-code-2)

The code below outlines a simplified version of a flash loan.

In the `flash_loan<T>` function, a user can borrow a given amount of coins type **`T`** along with a `Receipt` that records the borrowed amount plus a fee that should be returned to the protocol before the end of the transaction.

The `repay_flash_loan<T>` function accepts a `Receipt` and a `Coin<T>` as parameters. The function extracts the repayment amount from the `Receipt` and asserts that the value of the returned `Coin<T>` is greater than or equal to the amount specified in the `Receipt`, however there’s no check to ensure that the `Coin<T>` returned is the same as the `Coin<T>`that was initially loaned out, giving the ability to repay the loan with a coin of lesser value.

```
module 0x42::example {  struct Coin<T> {    amount: u64  }
  struct Receipt {    amount: u64  }
  public fun flash_loan<T>(user: &signer, amount: u64): (Coin<T>, Receipt) {    let (coin, fee) = withdraw(user, amount);    ( coin, Receipt {amount: amount + fee} )  }
  public fun repay_flash_loan<T>(rec: Receipt, coins: Coin<T>) {    let Receipt{ amount } = rec;    assert!(coin::value<T>(&coins) >= rec.amount, 0);    deposit(coins);  }}
```

#### Example Secure Code

[](#example-secure-code-2)

The Aptos Framework sample below creates a key-value table consisting of two generic types `K` and `V` . Its related `add` functions accepts as parameters a `Table<K, V>` object, a `key`, and a `value` of types `K` and `V` . The `phantom` syntax ensures that the key and value types cannot be different than those in the table, preventing type mismatches. [Read more](https://aptos-labs.github.io/move-book/generics-and-abilities.html#phantom-type-parameters) about `phantom` type parameters.

```
module 0x42::example {  struct Table<phantom K: copy + drop, phantom V> has store {    handle: address,  }
  public fun add<K: copy + drop, V>(table: &mut Table<K, V>, key: K, val: V) {    add_box<K, V, Box<V>>(table, key, Box { val })  }}
```

Given the by-design type checking provided by the Move language, we can refine the code of our flash loan protocol. The code below ensures that the coins passed to `repay_flash_loan` match the originally-loaned coins.

```
module 0x42::example {  struct Coin<T> {    amount: u64  }  struct Receipt<phantom T> {    amount: u64  }
  public fun flash_loan<T>(_user: &signer, amount:u64): (Coin<T>, Receipt<T>) {    let (coin, fee) = withdraw(_user, amount);    (coin,Receipt { amount: amount + fee})  }
  public fun repay_flash_loan<T>(rec: Receipt<T>, coins: Coin<T>) {    let Receipt{ amount } = rec;    assert!(coin::value<T>(&coins) >= rec.amount, 0);    deposit(coins);  }}
```

### Resource management and Unbounded Execution

[](#resource-management-and-unbounded-execution)

Effective resource management and unbounded execution prevention are important for maintaining security and gas efficiency in protocol. It's essential to consider these aspects in contract design:

1.  Avoid iterating over a publicly accessible structure that allows for unlimited entries, where any number of users can contribute without constraints.
2.  Store user-specific assets, such as coins and NFTs, within individual user accounts.
3.  Keep module or package-related information within Objects, separate from user data.
4.  Instead of combining all user operations in a single shared global space, separating them by individual users.

#### Impact

[](#impact-1)

The negligence of these aspects allowing an attacker to deplete the gas and abort the transaction. This can block application functionalities.

#### Example Insecure Code

[](#example-insecure-code-3)

The code below shows a loop iterating over every open order and could potentially be blocked by registering many orders:

```
module 0x42::example {  public fun get_order_by_id(order_id: u64): Option<Order> acquires OrderStore {    let order_store = borrow_global_mut<OrderStore>(@admin);    let i = 0;    let len = vector::length(&order_store.orders);    while (i < len) {      let order = vector::borrow<Order>(&order_store.orders, i);      if (order.id == order_id) {        return option::some(*order)      };      i = i + 1;    };    return option::none<Order>()  }  //O(1) in time and gas operation.  public entry fun create_order(buyer: &signer) { /* ... */ }}
```

#### Example Secure Code

[](#example-secure-code-3)

It's recommended to structure the order management system in a way that each user's orders are stored in their respective account rather than in a single global order store. This approach not only enhances security by isolating user data but also improves scalability by distributing the data load. Instead of using **`borrow_global_mut<OrderStore>(@admin)`** which accesses a global store, the orders should be accessed through the individual user's account.

```
module 0x42::example {  public fun get_order_by_id(user: &signer, order_id: u64): Option<Order> acquires OrderStore {    let order_store = borrow_global_mut<OrderStore>(signer::address_of(user));    if (smart_table::contains(&order_store.orders, order_id)) {      let order = smart_table::borrow(&order_store.orders, order_id);      option::some(*order)    } else {      option::none<Order>()    }  }}
```

It is also advisable to utilize efficient data structures tailored to the specific needs of the operations being performed. For instance, a **`SmartTable`** can be particularly effective in this context.

### Move Abilities

[](#move-abilities)

Move's abilities are a set of permissions that control the possible actions on data structures within the language. Smart contract developers must handle these capabilities with care, ensuring they're only assigned where necessary and understanding their implications to prevent security vulnerabilities.

| Ability | Description | | ------- | ---------------------------------------------------------------------------------------------------------------------- | | copy | Permits the duplication of values, allowing them to be used multiple times within the contract. | | drop | Allows values to be discarded from memory, which is necessary for controlling resources and preventing leaks. | | store | Enables data to be saved in the global storage, critical to persist data across transactions. | | key | Grants data the ability to serve as a key in global storage operations, important for data retrieval and manipulation. |

[Read more](https://aptos-labs.github.io/move-book/generics-and-abilities.html) about abilities.

Incorrect usage of abilities can lead to security issues such as unauthorized copying of sensitive data (`copy`), resource leaks (`drop`), and global storage mishandling (`store`).

#### Example Insecure Code

[](#example-insecure-code-4)

```
module 0x42::example {  struct Token has copy { }  struct FlashLoan has drop { }}
```

*   `copy` capability for a `Token` allows tokens to be replicated, potentially enabling double-spending and inflation of the token supply, which could devalue the currency.
*   Allowing the `drop` capability in a `FlashLoan` struct could permit borrowers to get out of their loan by destroying it before repayment.

### Mutable References (`&mut`) passed to untrusted code

[](#mutable-references-mut-passed-to-untrusted-code)

Passing `&mut T` across a trust boundary should be treated as an **access control decision**: `&mut T` is a capability that lets the callee change the value behind the reference.

This does **not** break module encapsulation—outside code still can’t access `T`’s private fields or pack/unpack `T`. The risk is **whole-value replacement**: if the callee can obtain _another_ `T` value (e.g. a different `FungibleAsset`), it can swap it into your `&mut T`, changing private fields “indirectly” without ever reading or writing them.

With `mem::swap` now public, this whole-value replacement becomes easy to express. This risk exists for normal cross-module calls and **with function values (callbacks)** in scenarios where callers supply the untrusted function value. See the [`mem::swap` discussion in AIP-105](https://github.com/aptos-foundation/AIPs/issues/529#issuecomment-2605266224).

#### Impact

[](#impact-2)

If you validate an invariant (e.g. “this `FungibleAsset` is the token I expect”) and then pass `&mut` to untrusted code, you must assume the invariant may no longer hold afterward. This can enable **token substitution** attacks: the callee swaps a “good” asset out for a “worthless” one and tricks the caller into thinking it is the original asset.

#### Example Insecure Code

[](#example-insecure-code-5)

```
module example::payments {    use aptos_framework::fungible_asset::{Self, FungibleAsset};    use aptos_framework::primary_fungible_store;
    const EUSED_TOO_MUCH: u64 = 1;    const EUNEXPECTED_ASSET: u64 = 2;
    fun check_metadata(asset: &FungibleAsset) {        // Check it is the asset class the protocol expects.        // e.g. assert!(fungible_asset::metadata(asset) == expected, EUNEXPECTED_ASSET);    }
    public fun do_with_fa(        user: address, asset: FungibleAsset, hook: |&mut FungibleAsset|    ) {        check_metadata(&asset); // check it is type we expect
        // Attacker-supplied function value receives `&mut FungibleAsset`.        hook(&mut asset);
        // Previously, protocols assumed the asset "identity" (metadata) couldn't change here.        // With `mem::swap` (or any future whole-value replacement API), that is not a safe assumption:        // `asset` may now be a different asset class.
        assert!(fungible_asset::amount(&asset) > 10, EUSED_TOO_MUCH);        // Get asset value        let value = fungible_asset::amount(&asset);        // BUG: without re-checking metadata here, this could now be a worthless asset.        primary_fungible_store::deposit(@treasury, asset);        // Mint the pool tokens to the user        mint_to(user, value);    }
    fun mint_to(_user: address, _value: u64) { /* ... */ }}
module attacker::exploit {    use std::mem;    use aptos_framework::fungible_asset::FungibleAsset;    use aptos_framework::primary_fungible_store;    use example::payments;
    // In practice this would come from attacker-controlled state / a withdraw.    fun worthless_asset(): FungibleAsset { /* ... */ }
    public fun exploit(good: FungibleAsset) {        let junk = worthless_asset();        payments::do_with_fa(            @attacker,            good,            |asset| {                let kept = junk;                mem::swap(asset, &mut kept); // replace the entire value behind `asset`                // `kept` now holds the original ("good") asset; deposit it back to the attacker.                // `asset` now holds the worthless replacement.                primary_fungible_store::deposit(@attacker, kept);            }        );    }}
```

#### Example Secure Code

[](#example-secure-code-4)

*   Don't pass `&mut` references to untrusted code.
*   If you must cross a trust boundary, **re-validate invariants after the call** (or snapshot and enforce that critical fields did not change).
*   Prefer restricting mutation-heavy APIs to trusted modules (`public(friend)`) instead of exposing them as `public`.

## Arithmetic Operations

[](#arithmetic-operations)

* * *

### Division Precision

[](#division-precision)

Arithmetic operations that decrease precision by rounding down could lead protocols to underreport the outcome of these computations.

Move includes six unsigned integer data types: `u8`, `u16`, `u32`, `u64`, `u128`, and `u256`. Division operations in Move truncate any fractional part, effectively rounding down to the nearest whole number, potentially causing protocols to underrepresent the result of such calculations.

Rounding errors in calculations can have wide-ranging impacts, potentially causing financial imbalances, data inaccuracies, and flawed decision-making processes. These errors can result in a loss of revenue, give undue benefits, or even pose safety risks, depending on the context. Accurate and precise computation is essential to maintain system reliability and user confidence.

#### Example Insecure Code

[](#example-insecure-code-6)

```
module 0x42::example {  public fun calculate_protocol_fees(size: u64): (u64) {    return size * PROTOCOL_FEE_BPS / 10000  }}
```

If `size` is less than `10000 / PROTOCOL_FEE_BPS`, the fee will round down to 0, effectively enabling a user to interact with the protocol without incurring any fees.

#### Example Secure Code

[](#example-secure-code-5)

The following examples outlines two distinct strategies to mitigate the issue in the code:

*   Set a minimum order size threshold that is greater than `10000 / PROTOCOL_FEE_BPS`, ensuring that the fee will never round down to zero.

```
module 0x42::example {  const MIN_ORDER_SIZE: u64 = 10000 / PROTOCOL_FEE_BPS + 1;
  public fun calculate_protocol_fees(size: u64): (u64) {    assert!(size >= MIN_ORDER_SIZE, 0);    return size * PROTOCOL_FEE_BPS / 10000  }}
```

*   Check that fees are non-zero and handle the situation specifically, for example by set a minimum fee or rejecting the transaction.

```
module 0x42::example {  public fun calculate_protocol_fees(size: u64): (u64) {    let fee = size * PROTOCOL_FEE_BPS / 10000;    assert!(fee > 0, 0);    return fee;  }}
```

### Integer Considerations

[](#integer-considerations)

In Move, the security around integer operations is designed to prevent overflow and underflow which can cause unexpected behavior or vulnerabilities. Specifically:

*   Additions (`+`) and multiplications (`*`) cause the program to abort if the result is too large for the integer type. An abort in this context means that the program will terminate immediately.
*   Subtractions (`-`) abort if the result is less than zero.
*   Division (`/`) abort if the divisor is zero.
*   Left Shift (`<<`), uniquely, does not abort in the event of an overflow. This means if the shifted bits exceed the storage capacity of the integer type, the program will not terminate, resulting in incorrect values or unpredictable behavior.

[Read more](https://aptos-labs.github.io/move-book/primitive-types.html#operations) about operations.

Bad operations could unexpectedly alter the correct execution of the smart contract, either by causing an unwanted abort or by calculating inaccurate data.

## Aptos Objects

[](#aptos-objects)

* * *

### ConstructorRef leak

[](#constructorref-leak)

When creating objects ensure to never expose the object’s `ConstructorRef` as it allows adding resources to an object. A `ConstructorRef` can also be used to generate other capabilities (or "Refs") that are used to alter or transfer the ownership the object. [Read more](/build/smart-contracts/object/creating-objects) about Objects capabilities.

#### Example Vulnerable code

[](#example-vulnerable-code)

For example, if a `mint` function returns the `ConstructorRef` for an NFT, it can be transformed to a `TransferRef`, stored in global storage, and can allow the original owner to transfer the NFT back after it’s being sold.

```
module 0x42::example {  use std::string::utf8;
  public fun mint(creator: &signer): ConstructorRef {    let constructor_ref = token::create_named_token(        creator,        string::utf8(b"Collection Name"),        string::utf8(b"Collection Description"),        string::utf8(b"Token"),        option::none(),        string::utf8(b"https://mycollection/token.jpeg"),    );    constructor_ref  }}
```

#### Example Secure Code

[](#example-secure-code-6)

Don’t return `CostructorRef` in the `mint` function:

```
module 0x42::example {  use std::string::utf8;
  public fun mint(creator: &signer) {    let constructor_ref = token::create_named_token(        creator,        string::utf8(b"Collection Name"),        string::utf8(b"Collection Description"),        string::utf8(b"Token"),        option::none(),        string::utf8(b"https://mycollection/token.jpeg"),    );  }}
```

### Object Accounts

[](#object-accounts)

In the Aptos Framework, multiple `key`\-able resources can be stored at a single object account.

However, objects should be isolated to different account, otherwise modifications to one object within an account can influence the entire collection.

For example, transferring one resource implies the transfer of all group members, since the transfer function operates on `ObjectCore`, which is essentially a general tag for all resources at the account.

[Read more](/build/smart-contracts/objects) about Aptos Objects.

#### Example Insecure Code

[](#example-insecure-code-7)

The `mint_two` function lets `sender` create a `Monkey` for themselves and send a `Toad` to `recipient`.

As `Monkey` and `Toad` belong to the same object account the result is that both objects’ are now owned by the `recipient`.

```
module 0x42::example {  #[resource_group(scope = global)]  struct ObjectGroup { }
  #[resource_group_member(group = 0x42::example::ObjectGroup)]  struct Monkey has store, key { }
  #[resource_group_member(group = 0x42::example::ObjectGroup)]  struct Toad has store, key { }
  fun mint_two(sender: &signer, recipient: &signer) {    let constructor_ref = &object::create_object_from_account(sender);    let sender_object_signer = object::generate_signer(constructor_ref);    let sender_object_addr = object::address_from_constructor_ref(constructor_ref);
    move_to(sender_object_signer, Monkey{});    move_to(sender_object_signer, Toad{});    let monkey_object: Object<Monkey> = object::address_to_object<Monkey>(sender_object_addr);    object::transfer<Monkey>(sender, monkey_object, signer::address_of(recipient));  }}
```

#### Example Secure Code

[](#example-secure-code-7)

In this example, objects should be stored at separate object accounts:

```
module 0x42::example {  #[resource_group(scope = global)]  struct ObjectGroup { }
  #[resource_group_member(group = 0x42::example::ObjectGroup)]  struct Monkey has store, key { }
  #[resource_group_member(group = 0x42::example::ObjectGroup)]  struct Toad has store, key { }
  fun mint_two(sender: &signer, recipient: &signer) {    let sender_address = signer::address_of(sender);
    let constructor_ref_monkey = &object::create_object(sender_address);    let constructor_ref_toad = &object::create_object(sender_address);    let object_signer_monkey = object::generate_signer(&constructor_ref_monkey);    let object_signer_toad = object::generate_signer(&constructor_ref_toad);
    move_to(object_signer_monkey, Monkey{});    move_to(object_signer_toad, Toad{});
    let object_address_monkey = signer::address_of(&object_signer_monkey);
    let monkey_object: Object<Monkey> = object::address_to_object<Monkey>(object_address_monkey);    object::transfer<Monkey>(sender, monkey_object, signer::address_of(recipient));  }}
```

## Business logic

[](#business-logic)

### Front-running

[](#front-running)

Front-running involves executing transactions ahead of others by exploiting knowledge of future actions already made by others. This tactic gives front-runners an unfair advantage, as they can anticipate and benefit from the outcomes of these pending transactions.

Front-running can undermine the fairness and integrity of a decentralized application. It can lead to loss of funds, unfair advantages in games, manipulation of market prices, and a general loss of trust in the platform

#### Example Insecure Code

[](#example-insecure-code-8)

In a lottery scenario, users participate by selecting a number from 1 to 100. At a certain point, the game administrator invokes the function `set_winner_number` to set the winning number. Subsequently, in a separate transaction, the administrator reviews all player bets to determine the winner via `evaluate_bets_and_determine_winners`.

A front-runner observing the winning number set by `set_winner_number` could attempt to submit a late bet or modify an existing bet to match the winning number before `evaluate_bets_and_determine_winners` executes.

```
module 0x42::example {  struct LotteryInfo {    winning_number: u8,    is_winner_set: bool,  }
  struct Bets { }
  public fun set_winning_number(admin: &signer, winning_number: u8) {    assert!(signer::address_of(admin) == @admin, 0);    assert!(winning_number < 10, 0);    let lottery_info = LotteryInfo { winning_number, is_winner_set: true };    move_to<LotteryInfo>(admin, lottery_info);  }
  public fun evaluate_bets_and_determine_winners(admin: &signer) acquires LotteryInfo, Bets {    assert!(signer::address_of(admin) == @admin, 0);    let lottery_info = borrow_global<LotteryInfo>(admin);    assert(lottery_info.is_winner_set, 1);
    let bets = borrow_global<Bets>(admin);    let winners: vector<address> = vector::empty();
    let winning_bets_option = smart_table::borrow_with_default(&bets.bets, lottery_info.winning_number, &vector::empty());
    vector::iter(winning_bets_option, |bet| {       vector::push_back(&mut winners, bet.player);    });    distribute_rewards(&winners);  }}
```

#### Example Secure Code

[](#example-secure-code-8)

An effective strategy to avoid front-running could be implementing a `finalize_lottery` function that reveals the answer and concludes the game within a single transaction, and making the other functions private. This approach guarantees that as soon as the answer is disclosed, the system no longer accepts any new answers, thereby eliminating the chance for front-running.

```
module 0x42::example {  public fun finalize_lottery(admin: &signer, winning_number: u64) {    set_winner_number(admin, winning_number);    evaluate_bets_and_determine_winners(admin);  }
  fun set_winning_number(admin: &signer, winning_number: u64) { }
  fun evaluate_bets_and_determine_winners(admin: &signer) acquires LotteryInfo, Bets { }}
```

### Price Oracle Manipulation

[](#price-oracle-manipulation)

In Defi applications, price oracles that utilize the liquidity ratio of tokens in a pair to determine prices for transactions can be vulnerable to manipulation. This susceptibility arises from the fact that the liquidity ratio can be influenced by market participants who hold a significant amount of tokens. When these participants strategically increase or decrease their token holdings, it can impact the liquidity ratio and consequently affect the prices determined by the price oracle, potentially draining the pool.

We recommend to use multiple oracles to determine prices.

#### Secure Code Example

[](#secure-code-example)

Thala, for example, utilizes a tiered-oracle design. The system has a primary and a secondary oracle. Should one of the oracles fail, the other one serves as a backup based on a sophisticated switching logic. The system is designed with adversarial situations in mind, and strives to provide highly accurate price feeds with minimal governance interaction all the time.

For more in-depth information, refer to [Thala's documentation](https://docs.thala.fi/thala-protocol-design/move-dollar-mod/oracles).

### Token Identifier Collision

[](#token-identifier-collision)

When dealing with tokens, ensure that the method for comparing token structs to establish a deterministic ordering does not lead to collisions. Concatenating the address, module, and struct names into a vector is insufficient, as it does not differentiate between similar names that should be treated as unique.

As a consequence, the protocol may erroneously reject legitimate swap pairs due to collisions in token struct comparisons. This oversight could compromise the integrity of swap operations, leading to a loss of funds.

#### Example Insecure Code

[](#example-insecure-code-9)

The `get_pool_address` function creates a unique address for a liquidity pool associated with trading pairs of fungible assets. It generates and returns an address that serves as a distinct identifier for the liquidity pool of the specified two tokens.

However, users have the freedom to create an `Object<Metadata>` with any symbol they choose. This flexibility could lead to the creation of `Object<Metadata>` instances that mimic other existing instances. This issue might result in a seed collision, which in turn could cause a collision in the generation of the pool address.

```
module 0x42::example {  public fun get_pool_address(token_1: Object<Metadata>, token_2: Object<Metadata>): address {    let token_symbol = string::utf8(b"LP-");    string::append(&mut token_symbol, fungible_asset::symbol(token_1));    string::append_utf8(&mut token_symbol, b"-");    string::append(&mut token_symbol, fungible_asset::symbol(token_2));    let seed = *string::bytes(&token_symbol);    object::create_object_address(&@swap, seed)  }}
```

#### Example Secure Code

[](#example-secure-code-9)

`object::object_address` returns an unique identifier for each `Object<Metadata>`

```
module 0x42::example {  public fun get_pool_address(token_1: Object<Metadata>, token_2: Object<Metadata>): address {    let seeds = vector[];    vector::append(&mut seeds, bcs::to_bytes(&object::object_address(&token_1)));    vector::append(&mut seeds, bcs::to_bytes(&object::object_address(&token_2)));    object::create_object_address(&@swap, seeds)  }}
```

## Operations

[](#operations)

* * *

### Pausing functionality

[](#pausing-functionality)

Protocols should have the ability to pause operations effectively. For immutable protocols, a built-in pause functionality is necessary. Upgradable protocols can achieve pausing either through smart contract functionality or via protocol upgrades. Teams should be equipped with automation for the quick and efficient execution of this process.

The absence of a pausing mechanism can lead to prolonged exposure to vulnerabilities, potentially resulting in significant losses. An efficient pausing functionality allows for prompt response to security threats, bugs, or other critical issues, minimizing the risk of exploitation and ensuring the safety of user assets and protocol integrity.

#### Example Secure Code

[](#example-secure-code-10)

Example of how to integrate a pause functionality

```
module 0x42::example {  struct State {    is_paused: bool,  }
  public entry fun pause_protocol(admin: &signer) {    assert!(signer::address_of(admin) == @protocol_address, ERR_NOT_ADMIN);    let state = borrow_global_mut<State>(@protocol_address);    state.is_paused = true;  }
  public entry fun resume_protocol(admin: &signer) {    assert!(signer::address_of(admin) == @protocol_address, ERR_NOT_ADMIN);    let state = borrow_global_mut<State>(@protocol_address);    state.is_paused = false;  }
  public fun main(user: &signer) {    let state = borrow_global<State>(@protocol_address);    assert!(!state.is_paused, 0);    // ...  }}
```

### Smart contract publishing key management

[](#smart-contract-publishing-key-management)

Using the same account for testnet and mainnet poses a security risk, as testnet private keys, often stored in less secure environments (ex. laptops), can be more easily exposed or leaked. An attacker that can obtain the private key for the testnet smart contract would be able to upgrade the mainnet one.

## Randomness

[](#randomness)

For more information on randomness and why it is crucial for preventing the predictability of random numbers, please refer to this page: [Randomness Guide](/build/smart-contracts/randomness).

* * *

### Randomness - test-and-abort

[](#randomness---test-and-abort)

> At Aptos, We are always security-first. During compilation, we ensure that no randomness API is invoked from a public function. However, we still allow users to make this choice by adding the attribute `#[lint::allow_unsafe_randomness]` to the public function.

If a `public` function directly or indirectly invokes the randomness API, a malicious user can abuse the composability of this function and abort the transaction if the result is not as desired. This allows the user to keep trying until they achieve a beneficial outcome, undermining the randomness.

#### Example Vulnerable code

[](#example-vulnerable-code-1)

```
module user::lottery {    fun mint_to_user(user: &signer) {        move_to(user, WIN {});    }
    #[lint::allow_unsafe_randomness]    public entry fun play(user: &signer) {        let random_value = aptos_framework::randomness::u64_range(0, 100);        if (random_value == 42) {            mint_to_user(user);        }    }}
```

In this example, the `play` function is `public`, allowing it to be composed with other modules. A malicious user can invoke this function and then check if they have won. If they have not won, they can abort the transaction and try again.

```
module attacker::exploit {    entry fun exploit(attacker: &signer) {        @user::lottery::play(attacker);        assert!(exists<@user::lottery::WIN>(address_of(attacker)));    }}
```

To resolve the possible issue, is sufficient to set the visibility of all functions that invoke the randomness API, either directly or indirectly, to `entry` rather than `public` or `public entry`.

#### Example Secure Code

[](#example-secure-code-11)

```
module user::lottery {    fun mint_to_user(user: &signer) {        move_to(user, WIN {});    }
    #[lint::allow_unsafe_randomness]    entry fun play(user: &signer) {        let random_value = aptos_framework::randomness::u64_range(0, 100);        if (random_value == 42) {            mint_to_user(user);        }    }}
```

### Randomness - undergasing

[](#randomness---undergasing)

When different code paths in a function consume different amounts of gas, an attacker can manipulate the gas limit to bias the outcome. Let's look at an example of how different paths can consume different amounts of gas.

#### Example Vulnerable code

[](#example-vulnerable-code-2)

```
module user::lottery {
    //transfer 10 aptos from admin to user    fun win(user: &signer) {        let admin_signer = &get_admin_signer();        let aptos_metadata = get_aptos_metadata();        primary_fungible_store::transfer(admin_signer, aptos_metadata, address_of(user),10);    }
    //transfer 10 aptos from user to admin, then 1 aptos from admin to fee_admin    fun lose(user: &signer) {
        //user to admin        let aptos_metadata = get_aptos_metadata();        primary_fungible_store::transfer(user, aptos_metadata, @admin, 10);
        //admin to fee_admin        let admin_signer = &get_admin_signer();        primary_fungible_store::transfer(admin_signer, aptos_metadata, @fee_admin, 1);    }
    #[randomness]    entry fun play(user: &signer) {        let random_value = aptos_framework::randomness::u64_range(0, 100);        if (random_value == 42) {            win(user);        } else {            lose(user);        }    }}
```

In this lottery-example, `win` and `lose` consume different amounts of gas. The `lose` function consumes more gas than the `win` function. An attacker can set the max gas limit that is sufficient for `win` but not for `lose`. This forces the transaction to abort when the `lose` path is taken, ensuring that the user will never execute the `lose` path. Then, the user can call the function repeatedly until they win.

#### Example Secure Code

[](#example-secure-code-12)

There are different ways to secure the code:

1.  Ensure better outcomes use more or the same gas as worse outcomes.
2.  Allow only admin addresses to invoke the randomness API.
3.  Ensure entry functions work regardless of random outcomes. This can be handled by committing the random result, then using the random result to provide the action in a different transaction. Avoid immediate actions based on randomness for consistent gas use.

> We will be providing more functionality in the future, to allow for more complex code to be able to be safe against undergasing attacks.

## Reentrancy

[](#reentrancy)

A **reentrancy attack** occurs when a contract performs an external call that can invoke the original contract again _before it finishes updating its state_. This can let an attacker repeat state-dependent actions (e.g., multiple withdrawals) against **stale state**.

Historically, Move prevented reentrancy. With the introduction of **function values**, certain forms of reentrancy are now possible under specific conditions. By contrast, **dispatchable fungible assets** remain protected against reentrancy.

Dispatchable Fungible Assets

**No reentrancy permitted.** All native dispatchable functions are **locked against re-entering an active module** (a module already invoked within the current transaction).

* * *

## Function Values

[](#function-values)

Since language version **2.2**, Move supports **function values** (first-class functions). Function values can be stored, and passed around like any other value.

Caution

Function values are **not** locked against reentrancy. Callbacks via function values can re-enter the original module.

graph LR
  %% Stable: no quotes, no parentheses, no double colons, no special edge labels.

%% Left (no function values)
  A\[Without Function Values\]
  m1a\[m1\]
  m2a\[m2\]
  noteA\[acyclic usage -> no reentrancy\]
  A --- m1a
  m1a --> m2a
  m2a --- noteA

%% Right (with function values)
  B\[With Function Values\]
  m1b\[m1\]
  call1\[call m2.f passing FV\]
  m2b\[m2\]
  cb1\[callback to m1 via FV\]
  noteB\[closure dynamic dispatch -> reentrancy possible\]
  B --- m1b
  m1b --> call1 --> m2b
  m2b -.-> cb1 -.-> m1b
  m2b --- noteB

* * *

### Resource Locking

[](#resource-locking)

To preserve Move’s reference semantics and suppress side effects from reentrancy, **re-entered modules cannot access their own resources** during dynamic dispatch through a closure. Attempts to borrow or move such resources **abort**.

Examples that will abort on re-entry:

*   `borrow_global<m::R>(addr)`
*   `move_from<m::R>(addr)`

[Read more](https://aptos-labs.github.io/move-book/functions.html#reentrancy-check) about the function-value reentrancy checks.

### Time-of-Check vs Time-of-Use (TOCTOU)

[](#time-of-check-vs-time-of-use-toctou)

Function values (FVs) can be stored inside wrapper structs and moved to global storage. Because FVs can **capture local variables**, scenarios arise where a value is **checked now** but **used later** (after state changes), leading to TOCTOU bugs.

```
module example::function_value_struct {    struct S {        fn: |u64| u64    }}
```

**Guidance:**

*   If an **amount** (or any state-derived value) is validated before creating the FV, **re-validate it at invocation time**—especially if the FV (or a struct containing it) is stored in global storage and called later.
*   There is **no guarantee** that the state captured by an FV remains unchanged by the time the FV executes (or that it executes at all).

**Safer pattern—capture a concrete resource:**

Capturing a concrete value whose identity is stable and which has the `store` ability is generally safer for long-lived function values—especially when the function value must be stored in global storage. This avoids relying on state-derived values that can change between time-of-check and time-of-use.

Important: `FungibleAsset` does not have the `store` ability. Any function value that captures a `FungibleAsset` therefore cannot itself be storable. If you need a storable function value, capture a separate, concrete resource that records the intended action (for example, a voucher/grant) and then perform the FA operation at invocation time.

This approach assumes that the FA is acquired and stored under a controlled FungibleStore without any state changes. Only at the time of voucher use and destruction are state changes or operations performed.

Example: capturing a storable voucher resource, then currying a persistent function so the resulting function value is storable:

```
module example::vouchers {    use std::signer;
    // Concrete resource with store ability; identity and contents are fixed at capture time    struct Voucher has store {        metadata: Object<Metadata>,        amount: u64    }
    // Persistent, via public, function so the resulting FV can have `store`    public fun redeem(to: address, v: Voucher) {        // Redeem using the fixed metadata/amount in the voucher        // e.g., withdraw/deposit at this point    }
    // Produces a storable FV that closes over a concrete Voucher    public fun build_redeemer(v: Voucher): |address| {        |to| redeem(to, v)    }}
```

Case: `FungibleAsset` (non-storable capture). If you capture a `FungibleAsset`, the function value cannot be stored, it must be invoked immediately in the same transaction. For persistence, capture a storable description (such as a voucher) instead of the FA itself.

```
module example::fa_case {    // Pattern B: Pass FA as an argument to a function value (no capture)    public fun with_handler(        owner: &signer,        token: Object<Metadata>,        amount: u64,        handle: |FungibleAsset|    ) {        let fa = primary_fungible_store::withdraw(owner, token, amount);        handle(fa);    }}
```

### Immutable Parameters

[](#immutable-parameters)

If a function value has captured or lifted arguments, those arguments are not going to be overridden at the time of invocation. The following example demonstrates this intended behavior.

```
module example::example {    use std::signer;    use std::debug;
    fun foo(x: u64) {        debug::print(&x);    }
    public fun invoke(f: |u64|) {        f(1); // The captured value (10) is not overridden at the time of invocation.    }
    #[test(_att = @0x1337)]    fun run(_att: &signer) {        invoke(|_x| foo(10));    }}
```

To understand this behavior, we need to look at how closures are lifted into functions.

```
__lambda__1__run(_x: u64) /* def_idx: 3 */ {B0:  0: LdU64(10) // load the value 10 into the stack  1: Call foo(u64)  2: Ret}
```

You can see that the resulting function fixes the first argument to 10. So `x` is not overridden at the time of invocation.

### Arbitrary Function Value

[](#arbitrary-function-value)

Passing one or a chain of functions as a parameter to another function, or storing FVs in a table, e.g. to be used as custom hooks, are patterns that can lead to reentrancy.

**Example Vulnerable code:**

In this example, the `withdraw_operations` acts as a proxy to call into a series of functions. As `Grant` is not part of `0x42::example`, any operation on it is **allowed** during closure dynamic dispatch.

```
module example::account {    use std::signer;    friend example::example;
    const ENOT_ENOUGH_BALANCE: u64 = 1;
    public struct Grant has drop {}
    public(friend) fun grant(): Grant {        Grant {}    }
    public(friend) fun balance(_account: address): u64 {        1_000    }
    public(friend) fun transfer(        _from: address, _to: address, _amount: u64    ) {}
    public(friend) fun has_grant(_g: &Grant): bool {        true    }}
module example::example {    use std::signer::address_of;    use std::option::{Self as option, Option};    use example::account;
    const EGRANT_NOT_FOUND: u64 = 2;    const ENOT_ENOUGH_BALANCE: u64 = 3;
    public fun withdraw_operations(        user: &signer,        recipient: Option<address>,        amount: u64,        f: |address, Option<address>, &account::Grant, u64|    ) {        let account_addr = address_of(user);        let bal = account::balance(account_addr);        assert!(bal >= amount, ENOT_ENOUGH_BALANCE);        let g = account::grant();        f(account_addr, recipient, &g, amount);    }
    public fun withdraw(        account_addr: address,        recipient: Option<address>,        grant: &account::Grant,        amount: u64    ) {        assert!(account::has_grant(grant), EGRANT_NOT_FOUND);        let r = recipient;        if (option::is_some(&r)) {            account::transfer(account_addr, option::destroy_some(r), amount);        } else {            option::destroy_none(r);        };        account::transfer(account_addr, account_addr, amount);    }}
```

An attacker can exploit this by calling `withdraw_operations` with a function value that calls `withdraw` and passes the `Grant` as a parameter. By altering, or [prefixing](/build/smart-contracts/move-security-guidelines#immutable-parameters), the amount of the transfer, which if pulled from a shared pool of funds, allows the attacker to overdraw the balance of the account.

```
module attacker::exploit {    use 0x42::example;    entry fun start(attacker: &signer) {        example::withdraw_operations(            attacker,            None,            10,            |account, recipient, grant, amount| example::withdraw(                attacker, recipient, grant, 100_000_000            )        );    }}
```

**Example Secure code:**

We've introduced the amount field into the grant structure to fix the amount at a specific moment. At the same time, we've finalized the status update. This can be thought of as a bank transfer that the bank is simply waiting to execute but has already recorded.

```
module example::account {    use std::signer;    friend example::example;
    const ENOT_ENOUGH_BALANCE: u64 = 1;
    // Notice that the grant is not droppable to ensure it used, but we can allow it to be stored.    public struct Grant {        account: address,        amount: u64    } // might capture other information like the asset type.
    public(friend) fun grant(account: address, amount: u64): Grant {        update_balance_withdraw(account, amount);        Grant { account, amount }    }
    fun update_balance_withdraw(account: address, amount: u64) { /* retrieve the account and update the balance */ } // The state update is done here.
    public(friend) fun balance(_account: address): u64 {        1_000    }
    public(friend) fun transfer(_to: address, _grant: Grant) {        /* transfer the amount of the grant to the recipient and destroy the grant */    }
    public(friend) fun has_grant(_g: &Grant): bool {        true    }}
module example::example {    use std::signer::address_of;    use std::option::{Self as option, Option};    use example::account;
    const EGRANT_NOT_FOUND: u64 = 2;    const ENOT_ENOUGH_BALANCE: u64 = 3;
    public fun withdraw_operations(        user: &signer,        recipient: Option<address>,        amount: u64,        f: |address, account::Grant|    ) {        let account_addr = address_of(user);        let bal = account::balance(account_addr);        assert!(bal >= amount, ENOT_ENOUGH_BALANCE);        let g = account::grant(account_addr, amount); // When the grant is created, the amount is fixed and verified to be available.        if (option::is_some(&recipient)) {            f(option::destroy_some(recipient), g); // By the time the function value is invoked, the state update is done, so reentrancy is not a problem.        } else {            f(account_addr, g);        };    }
    public fun withdraw(recipient: address, grant: account::Grant) {        assert!(account::has_grant(&grant), EGRANT_NOT_FOUND);        account::transfer(recipient, grant);    }}
```

# Move VSCode Extension

> Learn about move vscode extension for Move smart contract development on Aptos blockchain.

# Move on Aptos Language Extension

[](#move-on-aptos-language-extension)

This is the official Visual Studio Code (and Cursor) extension for [developing smart contracts in the Move language on the Aptos blockchain](/build/smart-contracts).

Built from the ground up, it delivers a modern and performant development experience, offering essential features like semantic highlighting, real-time diagnostics, auto-formatting and seamless integration with the rest of the Aptos toolchain - all designed to help developers build and test Move contracts with ease and confidence.

Actively maintained by the Aptos team, this extension is designed to evolve alongside the Move language and supports both developers who are new to Move, and those building more complex applications.

## Features

[](#features)

*   Semantic Highlighting
*   Go to Definition
*   Find All References & Symbol Renaming
*   Type and Documentation on Hover
*   Contextual Auto-Completion
*   Inlay Hints for Types and Function Parameters

![Inlay hints](/_vercel/image?url=_astro%2Finlay_hints.BW5LPY6A.png&w=1280&q=100&dpl=dpl_BVzupKm7aQfXg1N3qg98Mi3YEbWs)

*   Real-Time Diagnostics
*   [Code suggestions](#code-suggestions-with-fixes)
*   `movefmt` Integration

![Formatting with movefmt](/_vercel/image?url=_astro%2Fformat.DlVg5wNb.gif&w=1280&q=100&dpl=dpl_BVzupKm7aQfXg1N3qg98Mi3YEbWs)

*   Run `#[test]` functions
*   Check modules and functions with Move Prover

## Installation

[](#installation)

We publish releases both on [VSCode Marketplace](https://marketplace.visualstudio.com/items?itemName=AptosLabs.move-on-aptos) and [OpenVSX](https://open-vsx.org/extension/aptoslabs/move-on-aptos).

We also publish `nightly` pre-releases, which are built from `main` branch every night. To use those, select **Switch to Pre-Release Version** from your editor's Extensions View.

![Pre-releases selection](/_vercel/image?url=_astro%2Fpre-releases.5is53dbc.png&w=1280&q=100&dpl=dpl_BVzupKm7aQfXg1N3qg98Mi3YEbWs)

### Build from sources

[](#build-from-sources)

Clone the repo, then run:

```
cargo run -p xtask -- install --server --client
```

(or just `cargo xtask install --server --client`, see [https://github.com/matklad/cargo-xtask](https://github.com/matklad/cargo-xtask))

The command builds `move-on-aptos.vsix` extension file and installs it into your VSCode. Then it runs `cargo install` to build and install language server.

Put

```
"move-on-aptos.server.path": "~/.cargo/bin/aptos-language-server",
```

to your `settings.json` to point the extension to your locally built language server.

### Build from sources: Cursor AI editor

[](#build-from-sources-cursor-ai-editor)

If you use [https://www.cursor.com/](https://www.cursor.com/) AI editor, you need to do a bit more work.

Run the installation command above. The result would be a `./editors/code/move-on-aptos.vsix` vscode extension package. Then install it from the editor using the `"Install from VSIX..."` command.

## Configuration

[](#configuration)

Note

Extension by itself won't download your dependencies from the network.

If you see `unresolved reference` errors on the `AptosFramework` imports - try running `aptos move compile` once on your project to download your remote dependencies.

This extension provides configurations through VSCode's configuration settings. All configurations are under `move-on-aptos.*`.

### Recommended configuration for the Move package directories

[](#recommended-configuration-for-the-move-package-directories)

LSP is somewhat limited in what it can actually do, so some of the settings need to be specified manually.

#### Mark Move Library sources read-only

[](#mark-move-library-sources-read-only)

Add the following to your `settings.json`:

```
    "files.readonlyInclude": {        "**/build/*/sources/**/*.move": true,        "**/.move/**/*.move": true,    }
```

#### Auto-close `b"` and `x"` properly

[](#auto-close-b-and-x-properly)

```
    "[move]": {        "editor.wordSeparators": "`~!@#$%^&*()-=+[{]}\\|;:'\",.<>/?bx",    },
```

A bunch of symbols in the config value are the defaults, we're adding `b` and `x` symbols for the string prefixes.

#### Set `Organize Imports` command to a keyboard shortcut

[](#set-organize-imports-command-to-a-keyboard-shortcut)

```
    {        "key": "ctrl+alt+o",        "command": "move-on-aptos.organizeImports",        "when": "editorTextFocus && !editorReadonly"    }
```

## AdvancedConfiguration

[](#advancedconfiguration)

### Diagnostics

[](#diagnostics)

Extension provides a number of diagnostics, from hard errors like "unresolved reference" to style lints. Some of those might be less useful than others for different coding styles, so there's an escape hatch to disable those:

```
{    "move-on-aptos.diagnostics.disabled": [],}
```

where values are diagnostic codes from the error messages, like `unused-variable` here:

![Diagnostic code example](/_vercel/image?url=_astro%2Fdiag_code.CSXIW9WG.png&w=1280&q=100&dpl=dpl_BVzupKm7aQfXg1N3qg98Mi3YEbWs)

### Inlay hints

[](#inlay-hints)

Type hints for the let statements and lambda parameters are supported.

```
module 0x1::m {    fun main() {        let a/*: integer*/ = 1;        let f: |u8| u8 = |e/*: u8*/| e;    }}
```

To disable those, use:

```
{    "move-on-aptos.inlayHints.typeHints.enable": false,}
```

### Formatting (works with `movefmt` >= 1.2.1)

[](#formatting-works-with-movefmt--121)

Specify a path to the `movefmt` executable and extra args (like a `--config-path`) if necessary:

```
{    "move-on-aptos.movefmt.path": "~/code/movefmt/target/release/movefmt",    "move-on-aptos.movefmt.extraArgs": [],}
```

Formatting on Save can be enabled in VSCode with

```
{    "editor.formatOnSave": true,}
```

## Debugging

[](#debugging)

It's useful to enable INFO logging level, it's not very chatty and could provide with a valuable information to debug:

```
    "move-on-aptos.server.extraEnv": { "RA_LOG": "info" },
```

## Additional commands

[](#additional-commands)

### `aptos-language-server diagnostics`

[](#aptos-language-server-diagnostics)

Run server diagnostics on the file (or package directory). If `--apply-fixes` is provided, automatically applies available autofixes:

[See available diagnostics with auto-fixes](#code-suggestions-with-fixes)

```
  $ aptos-language-server diagnostics --apply-fixes replace-with-method-call ./aptos-stdlib/sources/cryptography/keyless.moveprocessing package 'aptos-stdlib', file: /home/mkurnikov/code/aptos-core/aptos-move/framework/aptos-stdlib/sources/cryptography/keyless.movenote[replace-with-method-call]: Can be replaced with method call   ┌─ /home/mkurnikov/code/aptos-core/aptos-move/framework/aptos-stdlib/sources/cryptography/keyless.move:67:17   │67 │         assert!(string::bytes(&iss).length() <= MAX_ISSUER_UTF8_BYTES_LENGTH, error::invalid_argument(E_INVALID_ISSUER_UTF8_BYTES_LENGTH));   │                 ^^^^^^^^^^^^^^^^^^^   │   ┌─ /home/mkurnikov/code/aptos-core/aptos-move/framework/aptos-stdlib/sources/cryptography/keyless.move:67:17   │67 │         assert!(iss.bytes().length() <= MAX_ISSUER_UTF8_BYTES_LENGTH, error::invalid_argument(E_INVALID_ISSUER_UTF8_BYTES_LENGTH));   │                 ^^^^^^^^^^^ after fix
```

## Code suggestions (with fixes)

[](#code-suggestions-with-fixes)

### Use method call notation

[](#use-method-call-notation)

**Code**: `replace-with-method-call`

![Replace with method call](/_vercel/image?url=_astro%2Freplace_with_method_call.Cb84GQz5.gif&w=1280&q=100&dpl=dpl_BVzupKm7aQfXg1N3qg98Mi3YEbWs)

### Use compound assignment expression

[](#use-compound-assignment-expression)

**Code**: `replace-with-compound-expr`

![Compound assignment expression](/_vercel/image?url=_astro%2Fcompound_expr.DK4SeUOx.gif&w=1280&q=100&dpl=dpl_BVzupKm7aQfXg1N3qg98Mi3YEbWs)

### Use vector index expr

[](#use-vector-index-expr)

**Code**: `replace-with-index-expr`

Detects expressions of form `*vector::borrow(&some_vector, index)` and `*some_vector.borrow(index)`, which can be converted to `some_vector[index]`.

![Vector index expression](/_vercel/image?url=_astro%2Fvector_index_expr.C4BNCuUr.gif&w=1280&q=100&dpl=dpl_BVzupKm7aQfXg1N3qg98Mi3YEbWs)

### Use field initialization shorthand

[](#use-field-initialization-shorthand)

**Code**: `use-struct-lit-field-shorthand`, `use-struct-pat-field-shorthand`, `use-schema-lit-field-shorthand`

Detects struct literal fields which could be written in shorthand form.

![Field initialization shorthand](/_vercel/image?url=_astro%2Ffield_shorthand.B2rB2rZs.gif&w=1280&q=100&dpl=dpl_BVzupKm7aQfXg1N3qg98Mi3YEbWs)

### Redundant integer type cast

[](#redundant-integer-type-cast)

**Code**: `remove-redundant-cast`

Detects expressions like `number as u8`, where `number` is already of type it's being casted to.

![Redundant integer type cast](/_vercel/image?url=_astro%2Fredundant_cast.D9Pyej7y.gif&w=1280&q=100&dpl=dpl_BVzupKm7aQfXg1N3qg98Mi3YEbWs)

### Add `_` prefix to the variable name

[](#add-_-prefix-to-the-variable-name)

**Code**: `rename-with-underscore-prefix`

Prefixes unused variable with `_`.

![Rename with underscore prefix](/_vercel/image?url=_astro%2Frename_fix.0n-EXSuE.gif&w=1280&q=100&dpl=dpl_BVzupKm7aQfXg1N3qg98Mi3YEbWs)

## Roadmap

[](#roadmap)

*   More error highlighting:
    
    *   Implement more errors from the Aptos Move compiler (like ability checking)
    *   Implement lints from the `aptos move lint` with extension-provided quickfixes.
*   Working with imports:
    
    *   Detect unused imports and remove them with "Organize Imports" VSCode feature.
    *   Show completion items not imported in the current module, create `use` statements for those automatically.
*   Integration with the `aptos-cli` commands: compile packages, publishing modules and executing transactions.
    
*   `Move.toml` support.
    
*   AI integration (via MCP server).

# Creating objects

> Master object creation patterns, ownership models, and lifecycle management in Aptos Move development.

Creating an Object involves two steps:

1.  Creating the `ObjectCore` resource group (which has an address you can use to refer to the Object later).
2.  Customizing how the Object will behave using permissions called `Ref`s.

Note

Configuring an Object by generating `Ref`s has to happen in the same transaction you create it. Later on it is impossible to change those settings.

## Creating an Object

[](#creating-an-object)

There are three types of Object you can create:

1.  A **normal Object.** This type is deletable and has a random address. You can create it using: `0x1::object::create_object(owner_address: address)`. For example:

```
module my_addr::object_playground {  use std::signer;  use aptos_framework::object;
  entry fun create_my_object(caller: &signer) {    let caller_address = signer::address_of(caller);    let constructor_ref = object::create_object(caller_address);    // ...  }}
```

2.  A **named Object.** This type is **not** deletable and has a deterministic address. You can create it by using: `0x1::object::create_named_object(creator: &signer, seed: vector<u8>)`. For example:

```
module my_addr::object_playground {  use std::signer;  use aptos_framework::object;
  /// Seed for my named object, must be globally unique to the creating account  const NAME: vector<u8> = b"MyAwesomeObject";
  entry fun create_my_object(caller: &signer) {    let caller_address = signer::address_of(caller);    let constructor_ref = object::create_named_object(caller, NAME);    // ...  }
  #[view]  fun has_object(creator: address): bool {    let object_address = object::create_object_address(&creator, NAME);    object::object_exists<0x1::object::ObjectCore>(object_address)  }}
```

3.  A **sticky Object.** This type is also **not** deletable and has a random address. You can create it by using `0x1::object::create_sticky_object(owner_address: address)`. For example:

## Customizing Object Features

[](#customizing-object-features)

Once you create your object, you will receive a `ConstructorRef` you can use to generate additional `Ref`s. `Ref`s can be used in future to enable / disable / execute certain Object functions such as transferring resources, transferring the object itself, or deleting the Object.

The following sections will walk through commonly used `Ref`s and the features they enable.

Note

Note: The `ConstructorRef` cannot be stored. It is destroyed at the end of the transaction used to create the Object, so any other `Ref`s **must** be generated during Object creation.

### Adding Resources

[](#adding-resources)

You can use the `ConstructorRef` with `object::generate_signer` to create a signer that allows you to transfer resources onto the Object. This uses `move_to`, the same function as for adding resources to an account.

```
module my_addr::object_playground {  use std::signer;  use aptos_framework::object;
  #[resource_group_member(group = aptos_framework::object::ObjectGroup)]  struct MyStruct has key {    num: u8  }
  entry fun create_my_object(caller: &signer) {    let caller_address = signer::address_of(caller);
    // Creates the object    let constructor_ref = object::create_object(caller_address);
    // Retrieves a signer for the object    let object_signer = object::generate_signer(&constructor_ref);
    // Moves the MyStruct resource into the object    move_to(&object_signer, MyStruct { num: 0 });
    // ...  }}
```

### Adding Extensibility (`ExtendRef`)

[](#adding-extensibility-extendref)

Sometimes you want an Object to be editable later on. In that case, you can generate an `ExtendRef` with `object::generate_extend_ref`. This ref can be used to generate a signer for the object.

You can control who has permission to use the `ExtendRef` via smart contract logic like in the below example.

```
module my_addr::object_playground {  use std::signer;  use std::string::{Self, String};  use aptos_framework::object::{Self, Object};
  /// Caller is not the owner of the object  const E_NOT_OWNER: u64 = 1;  /// Caller is not the publisher of the contract  const E_NOT_PUBLISHER: u64 = 2;
  #[resource_group_member(group = aptos_framework::object::ObjectGroup)]  struct MyStruct has key {    num: u8  }
  #[resource_group_member(group = aptos_framework::object::ObjectGroup)]  struct Message has key {    message: string::String  }
  #[resource_group_member(group = aptos_framework::object::ObjectGroup)]  struct ObjectController has key {    extend_ref: object::ExtendRef,  }
  entry fun create_my_object(caller: &signer) {    let caller_address = signer::address_of(caller);
    // Creates the object    let constructor_ref = object::create_object(caller_address);
    // Retrieves a signer for the object    let object_signer = object::generate_signer(&constructor_ref);
    // Moves the MyStruct resource into the object    move_to(&object_signer, MyStruct { num: 0 });
    // Creates an extend ref, and moves it to the object    let extend_ref = object::generate_extend_ref(&constructor_ref);    move_to(&object_signer, ObjectController { extend_ref });    // ...  }
  entry fun add_message(    caller: &signer,    object: Object<MyStruct>,    message: String  ) acquires ObjectController {    let caller_address = signer::address_of(caller);    // There are a couple ways to go about permissions
    // Allow only the owner of the object    assert!(object::is_owner(object, caller_address), E_NOT_OWNER);    // Allow only the publisher of the contract    assert!(caller_address == @my_addr, E_NOT_PUBLISHER);    // Or any other permission scheme you can think of, the possibilities are endless!
    // Use the extend ref to get a signer    let object_address = object::object_address(&object);    let extend_ref = &borrow_global<ObjectController>(object_address).extend_ref;    let object_signer = object::generate_signer_for_extending(extend_ref);
    // Extend the object to have a message    move_to(&object_signer, Message { message });  }}
```

### Disabling / Toggling Transfers (`TransferRef`)

[](#disabling--toggling-transfers-transferref)

By default, all Objects are transferable. This can be changed via a `TransferRef` which you can generate with `object::generate_transfer_ref`.

The example below shows how you could generate and manage permissions for determining whether an Object is transferrable.

```
module my_addr::object_playground {  use std::signer;  use aptos_framework::object::{Self, Object};
  /// Caller is not the publisher of the contract  const E_NOT_PUBLISHER: u64 = 1;
  #[resource_group_member(group = aptos_framework::object::ObjectGroup)]  struct ObjectController has key {    transfer_ref: object::TransferRef,  }
  entry fun create_my_object(    caller: &signer,    transferrable: bool,    controllable: bool  ) {    let caller_address = signer::address_of(caller);
    // Creates the object    let constructor_ref = object::create_object(caller_address);
    // Retrieves a signer for the object    let object_signer = object::generate_signer(&constructor_ref);
    // Creates a transfer ref for controlling transfers    let transfer_ref = object::generate_transfer_ref(&constructor_ref);
    // We now have a choice, we can make it so the object can be transferred    // and we can decide if we want to allow it to change later.  By default, it    // is transferrable    if (!transferrable) {      object::disable_ungated_transfer(&transfer_ref);    };
    // If we want it to be controllable, we must store the transfer ref for later    if (controllable) {      move_to(&object_signer, ObjectController { transfer_ref });    }    // ...  }
  /// In this example, we'll only let the publisher of the contract change the  /// permissions of transferring  entry fun toggle_transfer(    caller: &signer,    object: Object<ObjectController>  ) acquires ObjectController {    // Only let the publisher toggle transfers    let caller_address = signer::address_of(caller);    assert!(caller_address == @my_addr, E_NOT_PUBLISHER);
    // Retrieve the transfer ref    let object_address = object::object_address(&object);    let transfer_ref = &borrow_global<ObjectController>(      object_address    ).transfer_ref;
    // Toggle it based on its current state    if (object::ungated_transfer_allowed(object)) {      object::disable_ungated_transfer(transfer_ref);    } else {      object::enable_ungated_transfer(transfer_ref);    }  }}
```

### One-Time Transfers (`LinearTransferRef`)

[](#one-time-transfers-lineartransferref)

Additionally, if the creator wants to control all transfers, a `LinearTransferRef` can be created from the `TransferRef` to provide a one time use transfer functionality. This can be used to create “soulbound” objects by having a one-time transfer from the Object creator to the recipient. The `LinearTransferRef` must be used by the owner of the Object.

```
module my_addr::object_playground {  use std::signer;  use aptos_framework::object::{Self, Object};
  /// Caller is not the publisher of the contract  const E_NOT_PUBLISHER: u64 = 1;
  #[resource_group_member(group = aptos_framework::object::ObjectGroup)]  struct ObjectController has key {    transfer_ref: object::TransferRef,  }
  entry fun create_my_object(    caller: &signer,  ) {    let caller_address = signer::address_of(caller);
    // Creates the object    let constructor_ref = object::create_object(caller_address);
    // Retrieves a signer for the object    let object_signer = object::generate_signer(&constructor_ref);
    // Creates a transfer ref for controlling transfers    let transfer_ref = object::generate_transfer_ref(&constructor_ref);
    // Disable ungated transfer    object::disable_ungated_transfer(&transfer_ref);    move_to(&object_signer, ObjectController {      transfer_ref,    });    // ...  }
  /// In this example, we'll only let the publisher of the contract change the  /// permissions of transferring  /// Now only owner can transfer exactly once  entry fun transfer(    caller: &signer,    object: Object<ObjectController>,    new_owner: address  ) acquires ObjectController {    // Only let the publisher toggle transfers    let caller_address = signer::address_of(caller);    assert!(caller_address == @my_addr, E_NOT_PUBLISHER);
    let object_address = object::object_address(&object);
    // Retrieve the transfer ref    let transfer_ref = &borrow_global<ObjectController>(      object_address    ).transfer_ref;
    // Generate a one time use `LinearTransferRef`    let linear_transfer_ref = object::generate_linear_transfer_ref(      transfer_ref    );
    object::transfer_with_ref(linear_transfer_ref, new_owner);  }}
```

## Allowing Deletion of an Object (`DeleteRef`)

[](#allowing-deletion-of-an-object-deleteref)

For Objects created with the default method (allowing deletion) you can generate a `DeleteRef` which can be used later. This can help remove clutter as well as receive a storage refund.

You cannot create a `DeleteRef` for a non-deletable Object.

```
module my_addr::object_playground {  use std::signer;  use aptos_framework::object::{Self, Object};
  /// Caller is not the owner of the object  const E_NOT_OWNER: u64 = 1;
  #[resource_group_member(group = aptos_framework::object::ObjectGroup)]  struct ObjectController has key {    delete_ref: object::DeleteRef,  }
  entry fun create_my_object(    caller: &signer,    _transferrable: bool,    _controllable: bool  ) {    let caller_address = signer::address_of(caller);
    // Creates the object    let constructor_ref = object::create_object(caller_address);
    // Retrieves a signer for the object    let object_signer = object::generate_signer(&constructor_ref);
    // Creates and store the delete ref    let delete_ref = object::generate_delete_ref(&constructor_ref);    move_to(&object_signer, ObjectController {      delete_ref    });    // ...  }
  /// Now only let the owner delete the object  entry fun delete(    caller: &signer,    object: Object<ObjectController>,  ) acquires ObjectController {    // Only let caller delete    let caller_address = signer::address_of(caller);    assert!(object::is_owner(object, caller_address), E_NOT_OWNER);
    let object_address = object::object_address(&object);
    // Retrieve the delete ref, it is consumed so it must be extracted    // from the resource    let ObjectController {      delete_ref    } = move_from<ObjectController>(      object_address    );
    // Delete the object forever!    object::delete(delete_ref);  }}
```

## Making an Object Immutable

[](#making-an-object-immutable)

An object can be made immutable by making the contract associated immutable, and removing any ability to extend or mutate the object. By default, contracts are not immutable, and objects can be extended with an `ExtendRef`, and resources can be mutated if the contract allows for it.

## Further Reading

[](#further-reading)

You can find documentation for all possible `Refs` by looking at the Move reference docs for `0x1::object` [here](https://aptos-labs.github.io/framework-book/aptos-framework/object.html).

You can also explore how to use Objects once they are constructed [here](/build/smart-contracts/object/using-objects).

# Using objects

> Learn how to interact with and manipulate Aptos Objects in smart contracts for composable applications.

Once you've created your Object, you can use it in Move entry functions, structs, transfer it, and modify it using any refs you generated during [Object construction](/build/smart-contracts/object/creating-objects). Below are various ways to utilize, manage, and interact with Objects in Move.

## Using an Object as an entry function argument

[](#using-an-object-as-an-entry-function-argument)

Objects in move functions have the type `Object<T>`, where `T` is the type of a resource owned by the Object. All Objects have an `ObjectCore` type which contains the metadata for the Object.

To use an Object parameter, users can pass in the Object address or a reference to the Object. At runtime the contract will verify that the Object exists at that address, and has a resource of type T before executing the function.

```
module my_addr::object_playground {  use aptos_framework::object::{Object, ObjectCore};
  struct MyAwesomeStruct has key {}
  /// This will fail if the object doesn't have MyAwesomeStruct stored  entry fun do_something(object: Object<MyAwesomeStruct>) {    // ...  }
  /// All Objects have ObjectCore, so this will only fail if the  /// address is not an object  entry fun do_something_to_object_core(object: Object<ObjectCore>) {    // ...  }}
```

To let the user of the entry function specify the type of resource, you can keep the generic type `T` like so:

```
module my_addr::object_playground {  use aptos_framework::object::Object;
  /// This will fail if the object doesn't have the generic `T` stored  entry fun do_something<T>(object: Object<T>) {    // ...  }}
```

### Object types

[](#object-types)

You can refer to an Object by any type of resource that is owned by the Object. For convenience, you can convert an address to an Object, or convert an Object between types as long as the resources are available using `address_to_object` and `convert` like so:

```
module my_addr::object_playground {  use aptos_framework::object::{Self, Object, ObjectCore};
  struct MyAwesomeStruct has key {}
  fun convert_type(object: Object<ObjectCore>): Object<MyAwesomeStruct> {    object::convert<ObjectCore, MyAwesomeStruct>(object)  }
  fun address_to_type(object_address: address): Object<MyAwesomeStruct> {    object::address_to_object<MyAwesomeStruct>(object_address)  }}
```

Note

Objects can be owned by any address, including Objects, Accounts, and Resource accounts. This allows composability between objects and complex relationships between them.

## Using an Object as type of a field in struct

[](#using-an-object-as-type-of-a-field-in-struct)

Objects can help represent complicated types by using them in structs. For example,

```
module my_addr::object_playground {  use aptos_framework::object::{Self, Object};  use aptos_framework::fungible_asset::Metadata;  use aptos_framework::primary_fungible_store;  use std::signer;  use std::option;  use std::string::utf8;
  struct MyStruct has key {    fungible_asset_object: Object<Metadata>  }
  entry fun create_fungible_asset(creator: &signer) {    let fa_obj_constructor_ref = &object::create_sticky_object(@my_addr);    let fa_obj_signer = object::generate_signer(fa_obj_constructor_ref);    let fa_obj_addr = signer::address_of(&fa_obj_signer);    primary_fungible_store::create_primary_store_enabled_fungible_asset(        fa_obj_constructor_ref,        option::none(),        utf8(b"Asset name"),        utf8(b"Asset symbol"),        2,        utf8(b"Icon uri"),        utf8(b"Project uri")    );    move_to(creator, MyStruct {      fungible_asset_object: object::address_to_object(fa_obj_addr)    });  }}
```

## Looking up who owns an Object

[](#looking-up-who-owns-an-object)

When writing contracts for Objects, it is often important to verify ownership before modifying the Object. Because an Object can be owned by any address, verifying ownership needs to account for whether the owner is an Account, a Resource Account or another Object like so:

```
module my_addr::object_playground {  use std::signer;  use aptos_framework::object::{Self, Object};
  // Not authorized!  const E_NOT_AUTHORIZED: u64 = 1;
  fun check_owner_is_caller<T: key>(caller: &signer, object: Object<T>) {    assert!(      object::is_owner(object, signer::address_of(caller)),      E_NOT_AUTHORIZED    );  }
  fun check_is_owner_of_object<T: key>(addr: address, object: Object<T>) {    assert!(object::owner(object) == addr, E_NOT_AUTHORIZED);  }
  fun check_is_nested_owner_of_object<T: key, U: key>(    caller: &signer,    outside_object: Object<T>,    inside_object: Object<U>  ) {    // Ownership expected    // Caller account -> Outside object -> inside object
    // Check outside object owns inside object    let outside_address = object::object_address(&outside_object);    assert!(object::owns(inside_object, outside_address), E_NOT_AUTHORIZED);
    // Check that the caller owns the outside object    let caller_address = signer::address_of(caller);    assert!(object::owns(outside_object, caller_address), E_NOT_AUTHORIZED);
    // Check that the caller owns the inside object (via the outside object)    // This can skip the first two calls (and even more nested)    assert!(object::owns(inside_object, caller_address), E_NOT_AUTHORIZED);  }}
```

## Transfer of ownership

[](#transfer-of-ownership)

By default, all Objects are transferrable. Some Objects are configured to disable `ungated_transfer`s when they are constructed (see Constructing Objects for more details).

You can transfer an Object like so:

```
module my_addr::object_playground {  use aptos_framework::object::{Self, Object};
  /// Transfer to another address, this can be an object or account  fun transfer<T: key>(owner: &signer, object: Object<T>, destination: address) {    object::transfer(owner, object, destination);  }
  /// Transfer to another object  fun transfer_to_object<T: key, U: key>(    owner: &signer,    object: Object<T>,    destination: Object<U>  ) {    object::transfer_to_object(owner, object, destination);  }}
```

Caution

If `ungated_transfer` is **disabled**, then all transfers need to use a special permission given by a `TransferRef` or `LinearTransferRef`.

## Events

[](#events)

By default, Objects only have a `TransferEvent` which triggers whenever the Object is transferred.

Objects can be extended to have additional events.

You can use the following functions to create event handles for Objects:

```
module 0x1::object {  /// Create a guid for the object, typically used for events  public fun create_guid(object: &signer): guid::GUID {}
  /// Generate a new event handle.  public fun new_event_handle<T: drop + store>(object: &signer): event::EventHandle<T> {}}
```

Generated event handles can be transferred to the Object as long as you have the Object's `SignerRef`. For example:

```
module 0x42::example {  use aptos_framework::event;  use aptos_framework::fungible_asset::Metadata;  use aptos_framework::object::{Self, Object};
  #[resource_group_member(group = aptos_framework::object::ObjectGroup)]  struct LiquidityPoolResourceGroup has key {    pool: LiquidityPool,    event_store: LiquidityPoolEventStore,  }
  struct LiquidityPool has store {    metadata_token_a: Object<Metadata>,    metadata_token_b: Object<Metadata>,    reserves_a: u128,    reserves_b: u128,  }
  struct LiquidityPoolEventStore has store {    create_events: event::EventHandle<CreateLiquidityPoolEvent>,  }
  #[event]  struct CreateLiquidityPoolEvent has store, drop {    token_a: address,    token_b: address,    reserves_a: u128,    reserves_b: u128,  }
  public entry fun create_liquidity_pool_with_events(        account_signer: &signer,        metadata_token_a: Object<Metadata>,        metadata_token_b: Object<Metadata>,        reserves_a: u128,        reserves_b: u128  ) {    let liquidity_pool_constructor_ref = &object::create_object_from_account(      account_signer    );    let liquidity_pool_signer = &object::generate_signer(      liquidity_pool_constructor_ref    );    let event_handle = object::new_event_handle<CreateLiquidityPoolEvent>(      liquidity_pool_signer    );
    event::emit_event<CreateLiquidityPoolEvent>(&mut event_handle, CreateLiquidityPoolEvent {      token_a: object::object_address(&metadata_token_a),      token_b: object::object_address(&metadata_token_b),      reserves_a,      reserves_b,    });
    move_to(liquidity_pool_signer, LiquidityPoolResourceGroup {      pool: LiquidityPool {        metadata_token_a,        metadata_token_b,        reserves_a,        reserves_b      },      event_store: LiquidityPoolEventStore {        create_events: event_handle      }    });  }}
```

## Modifying Objects after creation

[](#modifying-objects-after-creation)

In general, Objects can only be modified with `Refs` generated during construction. See [Creating and Configuring Objects](/build/smart-contracts/object/creating-objects) for more details on what `Refs` are available, how to generate them, and how to use them. This is how you add additional resources to an Object, delete it, and extend it.

## Example contracts

[](#example-contracts)

Here are three real-world code snippets which use Objects:

*   [Digital Asset Marketplace Example](https://github.com/aptos-labs/aptos-core/tree/main/aptos-move/move-examples/marketplace)
*   [Digital Assets Examples](https://github.com/aptos-labs/aptos-core/tree/main/aptos-move/move-examples/token_objects)
*   [Fungible Asset Examples](https://github.com/aptos-labs/aptos-core/tree/main/aptos-move/move-examples/fungible_asset)

# Building with Objects

> Learn about objects for Aptos Objects in smart contract development.

In Move, Objects group resources together so they can be treated as a single entity on chain.

Objects have their own address and can own resources similar to an account. They are useful for representing more complicated data types on-chain as Objects can be used in entry functions directly, and can be transferred as complete packages instead of one resource at a time.

Here's an example of creating an Object and transferring it:

```
module my_addr::object_playground {  use std::signer;  use std::string::{Self, String};  use aptos_framework::object::{Self, ObjectCore};
  struct MyStruct1 has key {    message: String,  }
  struct MyStruct2 has key {    message: String,  }
  entry fun create_and_transfer(caller: &signer, destination: address) {    // Create object    let caller_address = signer::address_of(caller);    let constructor_ref = object::create_object(caller_address);    let object_signer = object::generate_signer(&constructor_ref);
    // Set up the object by creating 2 resources in it    move_to(&object_signer, MyStruct1 {      message: string::utf8(b"hello")    });    move_to(&object_signer, MyStruct2 {      message: string::utf8(b"world")    });
    // Transfer to destination    let object = object::object_from_constructor_ref<ObjectCore>(      &constructor_ref    );    object::transfer(caller, object, destination);  }}
```

During construction, Objects can be configured to be transferrable and extensible.

For example, you could use an Object to represent a soulbound NFT by making it only transferrable once, and have it own resources for an image link and metadata. Objects can also own other Objects, so you could implement your own NFT collection Object by transferring several of the soulbound NFTs to it.

## Learn how to

[](#learn-how-to)

*   [Create and configure a new Object.](/build/smart-contracts/object/creating-objects)
*   [Use Objects you created.](/build/smart-contracts/object/using-objects)

## Examples with Object contracts

[](#examples-with-object-contracts)

# Move Prover Overview

> Explore prover in Move Prover for formal verification of smart contracts.

The Move Prover supports formal [specification](https://aptos-labs.github.io/move-book/spec-lang.html) and [verification](https://aptos-labs.github.io/move-book/prover-guide.html) of Move code. The Move Prover can automatically validate logical properties of Move smart contracts while offering a user experience similar to a type checker or linter.

The Move Prover exists to make contracts more _trustworthy_; it:

*   Protects massive assets managed by the Aptos blockchain from smart contract bugs
*   Protects against well-resourced adversaries
*   Anticipates justified regulator scrutiny and compliance requirements
*   Allows domain experts with a mathematical background, but not necessarily a software engineering background, to understand what smart contracts do

For more information, refer to the documentation:

*   [Installation](/build/cli/setup-cli/install-move-prover)
*   [Move Prover User Guide](https://aptos-labs.github.io/move-book/prover-guide.html)
*   [Move Specification Language](https://aptos-labs.github.io/move-book/spec-lang.html)
*   [Compositional Specs](https://aptos-labs.github.io/move-book/spec-compositional.html)
*   [Proofs](https://aptos-labs.github.io/move-book/spec-proofs.html)
*   [Move Prover Supporting Resources](/build/smart-contracts/prover/supporting-resources)

# Supporting Resources

> Access supporting resources, documentation, and tools for Move Prover formal verification workflow.

## Standard Library and Framework Specifications

[](#standard-library-and-framework-specifications)

*   [Move Stdlib](https://github.com/aptos-labs/aptos-core/tree/main/aptos-move/framework/move-stdlib)
*   [Aptos Stdlib](https://github.com/aptos-labs/aptos-core/tree/main/aptos-move/framework/aptos-stdlib)
*   [Aptos Framework](https://github.com/aptos-labs/aptos-core/tree/main/aptos-move/framework/aptos-framework)
*   [Diem Framework](https://github.com/move-language/move/tree/main/language/documentation/examples/diem-framework/move-packages/DPN)

## Examples

[](#examples)

*   [`hello_prover` example](https://github.com/aptos-labs/aptos-core/tree/main/aptos-move/move-examples/hello_prover)
*   [`basic-coin` example](https://github.com/move-language/move/tree/main/language/documentation/examples/experimental/basic-coin)
*   [`math-puzzle` example](https://github.com/move-language/move/tree/main/language/documentation/examples/experimental/math-puzzle)
*   [`rounding-error` example](https://github.com/move-language/move/tree/main/language/documentation/examples/experimental/rounding-error)
*   [`verify-sort` example](https://github.com/move-language/move/tree/main/language/documentation/examples/experimental/verify-sort)
*   [Move Prover Examples by Zellic](https://github.com/zellic/move-prover-examples)

## Tutorials

[](#tutorials)

*   [The Move Tutorial, steps 7 and 8](https://github.com/aptos-labs/aptos-core/tree/main/aptos-move/move-examples/move-tutorial#step-7--use-the-move-prover)
*   [Verify Smart Contracts in Aptos with the Move Prover by MoveBit](https://www.movebit.xyz/blog/post/move-prover-tutorial-part-1.html)
*   [The Move Prover: A Practical Guide by OtterSec](https://osec.io/blog/2022-09-16-move-prover)
*   [Formal Verification, the Move Language, and the Move Prover by Certik](https://www.certik.com/resources/blog/2wSOZ3mC55AB6CYol6Q2rP-formal-verification-the-move-language-and-the-move-prover)
*   [The Move Prover: Quality Assurance of Formal Verification by Certik](https://www.certik.com/resources/blog/1NygvVeqIwhbUk1U1q3vJF-the-move-prover-quality-assurance-of-formal-verification)

## Presentations

[](#presentations)

*   [Verifying Smart Contracts with Move Prover by Wolfgang Grieskamp (video)](https://drive.google.com/file/d/1DpI-rQ25Kq1jqMGioLgVrG3YuCqJHVMm/view?usp=share_link)
*   [Formal verification of Move programs for the Libra blockchain by David Dill (video)](https://www.fields.utoronto.ca/talks/Formal-verification-Move-programs-Libra-blockchain)
*   [Move Prover - Best Practices & Tricks - A User’s Perspective by Xu-Dong@MoveBit (slides)](https://docs.google.com/presentation/d/1SuV0m5gGxSN9SaLdj9lLmTjspJ2xN1TOWgnwvdWbKEY/edit?usp=sharing)

## Conference papers

[](#conference-papers)

*   Zhong, Jingyi Emma, Kevin Cheang, Shaz Qadeer, Wolfgang Grieskamp, Sam Blackshear, Junkil Park, Yoni Zohar, Clark Barrett, and David L. Dill. "The move prover." In _International Conference on Computer Aided Verification_, pp. 137-150. Springer, Cham, 2020.Harvard
    *   [https://research.facebook.com/publications/the-move-prover/](https://research.facebook.com/publications/the-move-prover/)
*   Dill, David, Wolfgang Grieskamp, Junkil Park, Shaz Qadeer, Meng Xu, and Emma Zhong. "Fast and reliable formal verification of smart contracts with the Move prover." In _International Conference on Tools and Algorithms for the Construction and Analysis of Systems_, pp. 183-200. Springer, Cham, 2022.Harvard
    *   [https://research.facebook.com/publications/fast-and-reliable-formal-verification-of-smart-contracts-with-the-move-prover/](https://research.facebook.com/publications/fast-and-reliable-formal-verification-of-smart-contracts-with-the-move-prover/)
*   Park, Junkil, Teng Zhang, Wolfgang Grieskamp, Meng Xu, Gerardo Di Giacomo, Kundu Chen, Yi Lu, and Robert Chen. "Securing Aptos framework with formal verification." In _5th International Workshop on Formal Methods for Blockchains (FMBC 2024)_. Schloss Dagstuhl–Leibniz-Zentrum für Informatik, 2024.
    *   [https://drops.dagstuhl.de/storage/01oasics/oasics-vol118-fmbc2024/OASIcs.FMBC.2024.9/OASIcs.FMBC.2024.9.pdf](https://drops.dagstuhl.de/storage/01oasics/oasics-vol118-fmbc2024/OASIcs.FMBC.2024.9/OASIcs.FMBC.2024.9.pdf)

# Randomness API

> Learn about randomness for Move smart contract development on Aptos blockchain.

## What does it do: a quick example

[](#what-does-it-do-a-quick-example)

### How random numbers have been obtained, insecurely/awkwardly

[](#how-random-numbers-have-been-obtained-insecurelyawkwardly)

Building a lottery system and pick a random winner from `n` participants is trivial, at least in the centralized world with a trusted server: the backend simply calls a random integer sampling function (`random.randint(0, n-1)` in python, or `Math.floor(Math.random() * n)` in JS).

Unfortunately, without an equivalent of `random.randint()` in Aptos Move, building a dApp version of it was actually much harder.

One may have written a contract where the random numbers are sampled insecurely (e.g., from the blockchain timestamp):

```
module module_owner::lottery {    // ...
    struct LotteryState {        players: vector<address>,        winner_idx: std::option::Option<u64>,    }
    fun load_lottery_state_mut(): &mut LotteryState {        // ...    }
    entry fun decide_winner() {        let lottery_state = load_lottery_state_mut();        let n = std::vector::length(&lottery_state.players);        let winner_idx = aptos_framework::timestamp::now_microseconds() % n;        lottery_state.winner_idx = std::option::some(winner_idx);    }}
```

The implementation above is insecure in multiple ways:

*   a malicious user may bias the result by picking the transaction submission time;
*   a malicious validator can bias the result easily by selecting which block the `decide_winner` transaction goes to.

Other dApps may have chosen to use an external secure randomness source (e.g., [drand](https://drand.love/)), which is typically a complicated flow:

1.  The participants agree on using a future randomness seed promised by the randomness source to determine the winner.
2.  Once the randomness seed is revealed, the clients fetch it and derive the winner locally.
3.  One of the participants submits the seed and the winner on chain.

```
module module_owner::lottery {    // ...
    struct LotteryState {        players: vector<address>,        /// public info about the "future randomness", tyipcally a VRF public key and an input.        seed_verifier: vector<u8>,        winner_idx: std::option::Option<u64>,    }
    fun load_lottery_state_mut(): &mut LotteryState {        // ...    }
    fun is_valid_seed(seed_verifier: vector<u8>, seed: vector<u8>): bool {        // ...    }
    fun derive_winner(n: u64, seed: vector<u8>): u64 {        // ...    }
    entry fun update_winner(winner_idx: u64, seed: vector<u8>) {        let lottery_state = load_lottery_state_mut();        assert!(is_valid_seed(lottery_state.seed_verifier, seed), ERR_INVALID_SEED);        let n = std::vector::length(players);        let expected_winner_idx = derive_winner(n, seed);        assert!(expected_winner_idx == winner_idx, ERR_INCORRECT_DERIVATION);        lottery_state.winner_idx = std::option::some(winner_idx);    }}
```

### Achieve simplicity + security with Aptos randomness API

[](#achieve-simplicity--security-with-aptos-randomness-api)

Using Aptos randomness API, the implementation will look like this:

```
module module_owner::lottery {    // ...    use aptos_framework::randomness;
    struct LotteryState {        players: vector<address>,        winner_idx: std::option::Option<u64>,    }
    fun load_lottery_state_mut(): &mut Lottery {        // ...    }
    #[randomness]    entry fun decide_winner() {        let lottery_state = load_lottery_state_mut();        let n = vector::length(&lottery_state.players);        let winner_idx = aptos_framework::randomness::u64_range(0, n);        lottery_state.winner_idx = std::option::some(winner_idx);    }}
```

where:

*   `let winner_idx = aptos_framework::randomness::u64_range(0, n);` is the randomness API call that returns an u64 integer in range `[0, n)` uniformly at random.
*   `#[randomness]` is a required attribute to enable the API call at runtime.

Note

### Security Considerations

[](#security-considerations)

Compiler helps with test and abort attacks, requiring functions using randomness to be private. However, the randomness API currently does not prevent undergasing attacks. The smart contract will need to be written in a certain way to avoid it.

## How to use Aptos randomness API

[](#how-to-use-aptos-randomness-api)

### Prerequisites

[](#prerequisites)

Ensure you have the latest [aptos-cli](/build/cli) installed.

### Keep undergasing attacks in mind

[](#keep-undergasing-attacks-in-mind)

Caution

**The randomness API currently does not prevent undergasing attacks.** Carefully read the undergasing section to understand about undergasing attacks and how to prevent them. As a dApp developer, you will need to design applications using randomness with safety in mind.

### Identify randomness-dependent entry functions and make them compliant

[](#identify-randomness-dependent-entry-functions-and-make-them-compliant)

For safety (discussed with more details later), randomness API calls are only allowed from an entry function that is:

*   private, and
*   annotated with `#[randomness]`.

It's now a good time to think about what user actions need randomness API, write them down, and make sure they are private and have the right attribute, as shown in the example below.

```
module module_owner::lottery {    // ...
    #[randomness]    entry fun decide_winner() {        // ...    }}
```

At runtime, when randomness API is called, the VM checks whether the outermost of the callstack is a private entry function with `#[randomness]` attribute. **If not, the entire transaction is aborted.**

Note

NOTE: It also means randomness API calls are supported only in entry function-based transactions. (For example, using randomness API in a Move script is impossible.)

### Call the API

[](#call-the-api)

The APIs are public functions under `0x1::randomness` and can be referenced directly, as demonstrated in the lottery example above.

```
module module_owner::lottery {    // ...    use aptos_framework::randomness;
    #[randomness]    entry fun decide_winner() {        // ...        let winner_idx = aptos_framework::randomness::u64_range(0, n);        lottery_state.winner_idx = std::option::some(winner_idx);    }}
```

The above example uses function `u64_range()` but many other basic types are also supported. Here's a quick overview of all the API, where `T` can be one of `u8, u16, u32, u64, u128, u256`.

```
module aptos_framework::randomness {    /// Generates an number uniformly at random.    fun u8_integer(): u8 {}
    /// Generates an number uniformly at random.    fun u16_integer(): u16 {}
    // fun u32_integer(), fun u64_integer() ...
    /// Generates a number `[min_incl, max_excl)` uniformly at random.    fun u8_range(min_incl: u8, max_excl: u8): u8 {}
    /// Generates a number `[min_incl, max_excl)` uniformly at random.    fun u16_range(min_incl: u16, max_excl: u16): u16 {}
    // fun u32_range(), fun u64_range() ...
    /// Generates a sequence of bytes uniformly at random    /// n is the number of bytes    /// If n is 0, returns the empty vector.    fun bytes(n: u64): vector<u8> {}
    /// Generate a permutation of `[0, 1, ..., n-1]` uniformly at random.    /// n is the number of bytes    /// If n is 0, returns the empty vector.    fun permutation(n: u64): vector<u64> {}}
```

The full API function list and documentation can be found [here](https://github.com/aptos-labs/aptos-core/blob/main/aptos-move/framework/aptos-framework/doc/randomness.md).

## Security considerations

[](#security-considerations-1)

Randomness API is powerful in many ways: it unlocks new dApp designs; but if used incorrectly, it may leave your dApps open to attacks! Below are some common mistakes you should avoid.

### Randomness API calls in public functions

[](#randomness-api-calls-in-public-functions)

As your dApp gets more complicated, you may have multiple entry functions that need to share the same randomness-dependent logic, and want to pull the logic out as a separate helper function.

While this is supported as shown below, extra care must be taken.

```
module module_owner::lottery {    // ...    use aptos_framework::randomness;
    #[randomness]    entry fun decide_winner_v0() {        // ...        decide_winner_internal(lottery_state);    }
    #[randomness]    entry fun decide_winner_v1() {        // ...        decide_winner_internal(lottery_state);    }
    // A private helper function    fun decide_winner_internal(lottery_state: &mut lottery_state) {        let n = std::vector::length(&lottery_state.players);        let winner_idx = aptos_framework::randomness::u64_range(0, n);        lottery_state.winner_idx = std::option::some(winner_idx);    }}
```

If `decide_winner_internal()` were accidentally marked public, malicious players can deploy their own contract to:

1.  call`decide_winner_internal()`;
2.  read the lottery result (assuming the `lottery` module has some getter functions for the result);
3.  abort if the result is not in their favor. By repeatedly calling their own contract until a txn succeeds, malicious users can bias the uniform distribution of the winner (dApp developer's initial design). This is referred to as a [test-and-abort attack](https://github.com/aptos-foundation/AIPs/blob/main/aips/aip-41.md#test-and-abort-attacks).

The Aptos Move compiler has been updated to prevent this attack for your contract safety: a randomness-dependent public function is treated as a compile error. If you have finished the steps in the ["build Aptos CLI"](/build/cli) section, then your Aptos CLI are equipped with the updated compiler.

```
module module_owner::lottery {    // Compile error!    public fun decide_winner_internal(lottery_state: &mut lottery_state) {        let n = std::vector::length(&lottery_state.players);        let winner_idx = aptos_framework::randomness::u64_range(0, n);        lottery_state.winner_idx = std::option::some(winner_idx);    }}
```

Not recommended, but if you intend to expose such a randomness-dependent function to the public, you can bypass the compiler check by annotating your function with `#[lint::allow_unsafe_randomness]`.

```
module module_owner::lottery {    // Can compile, but use it at your own risk!    #[lint::allow_unsafe_randomness]    public fun decide_winner_internal(lottery_state: &mut lottery_state) {        let n = std::vector::length(&lottery_state.players);        let winner_idx = aptos_framework::randomness::u64_range(0, n);        lottery_state.winner_idx = std::option::some(winner_idx);    }}
```

### Undergasing attacks, and how to prevent

[](#undergasing-attacks-and-how-to-prevent)

Imagine such a dApp. It defines a private entry function for a user to:

1.  toss a coin (gas cost: 9), then
2.  get a reward (gas cost: 10) if coin=1, or do some cleanup (gas cost: 100) otherwise.

A malicious user can control its account balance, so it covers at most 108 gas units (or set transaction parameter `max_gas=108`), and the cleanup branch (total gas cost: 110) will always abort with an out-of-gas error. The user then repeatedly call the entry function until it gets the reward.

Formally, this is referred to as an [undergasing attack](https://github.com/aptos-foundation/AIPs/blob/main/aips/aip-41.md#undergasing-attacks), where an attacker can control how much gas is left for the entry function to execute, and so can arbitrarily decide to abort paths that cost more gas, biasing the outcome (i.e., effectively changing the distribution of random numbers).

Caution

**WARNING: randomness API currently does not prevent undergasing attacks.** As a dApp developer, you need to be very careful in your design to avoid this type of attack. Here are some ideas of how to prevent undergasing attack generally.

*   Make your entry function gas independent from the randomness outcome. The simplest example is to not "act" on the randomness outcome, i.e., read it and store it for later. Note that calling any other functions can have variable gas costs. For example, when calling randomness to decide which player should win, and then depositing the winnings to the winner might seem like a fixed gas cost. But, `0x1::coin::transfer` / `0x1::fungible_asset::transfer` can have a variable cost based on the user's on-chain state.
*   If your dApp involves a trusted admin/admin group, only allow the trusted to execute randomness transaction (i.e., require an admin signer).
*   Make the path that is most beneficial have the highest gas (as attacker can only abort paths with gas above a threshold he chooses. NOTE: that this can be tricky to get right, and gas schedule can change, and is even harder to get right when there are more than 2 possible outcomes.

Note that everything that does not fall in above categories can be susceptible to undergasing attack in a subtle ways. Reach out if you need help.

We will be providing more functionality in the future, to allow for more complex code to be able to be safe against undergasing attacks.

### It's random, but not a secret

[](#its-random-but-not-a-secret)

While the randomness API mimics the standard libraries you use to implement a private centralized server, keep in mind that **the seed is public, and so is your transaction execution**, and not every randomness-dependent logic in your private centralized server can be transferred on chain safely, **especially when it involves a secret that only the server should see**.

For example, in your contract, DO NOT try to do the following.

*   Use randomness API to generate an asymmetric key pair, discard the private key, then think the public key is safe.
*   Use randomness API to shuffle some opened cards, veil them, and think no one knows the permutation.

## Read more

[](#read-more)

[Aptogotchi Random Mint](https://github.com/aptos-labs/aptogotchi-random-mint/tree/main) is an official demo dApp built to demonstrate the use of randomness API.

The full API function list and documentation can be found [here](https://github.com/aptos-labs/aptos-core/blob/main/aptos-move/framework/aptos-framework/doc/randomness.md).

You can also find the partial implementation of the API functions and example unit tests [here](https://github.com/aptos-labs/aptos-core/blob/main/aptos-move/framework/aptos-framework/sources/randomness.move).

See [AIP-41](https://github.com/aptos-foundation/AIPs/blob/main/aips/aip-41.md) for the API design, and [AIP-79](https://github.com/aptos-foundation/AIPs/blob/main/aips/aip-79.md) if you are interested in system-level/cryptography details.

# Resource Accounts

> Learn about resource accounts for Move smart contract development on Aptos blockchain.

[Object Code Deployment](/build/smart-contracts/deployment) is the preferred method for deploying and upgrading smart contracts in Aptos. Resource accounts require developers to generate seeds each time a resource account is created, and upgrading contracts requires specific steps which is prone to error.

A [resource account](https://github.com/aptos-labs/aptos-core/blob/main/aptos-move/framework/aptos-framework/sources/resource_account.move) is a developer feature used to manage resources independent of an account managed by a user, specifically publishing modules and providing on-chain-only access control, e.g., signers.

Typically, a resource account is used for two main purposes:

*   Store and isolate resources; a module creates a resource account just to host specific resources.
*   Publish module as a standalone (resource) account, a building block in a decentralized design where no private keys can control the resource account. The ownership (SignerCap) can be kept in another module, such as governance.

## Restrictions

[](#restrictions)

In Aptos, a resource account is created based upon the SHA3-256 hash of the source's address and additional seed data. A resource account can be created only once; for a given source address and seed, there can be only one resource account. That is because the calculation of the resource account address is fully determined by the former.

An entity may call `create_account` in an attempt to claim an account ahead of the creation of a resource account. But if a resource account is found, Aptos will transition ownership of the account over to the resource account. This is done by validating that the account has yet to execute any transactions and that the `Account::signer_capbility_offer::for` is none. The probability of a collision where someone has legitimately produced a private key that maps to a resource account address is improbably low.

## Setup

[](#setup)

The easiest way to set up a resource account is by:

1.  Using Aptos CLI: `aptos account create-resource-account` creates a resource account, and `aptos move create-resource-account-and-publish-package` creates a resource account and publishes the specified package under the resource account's address.
2.  Writing custom smart contracts code: in the `resource_account.move` module, developers can find the resource account creation functions `create_resource_account`, `create_resource_account_and_fund`, and `create_resource_account_and_publish_package`. Developers can then call those functions to create resource accounts in their smart contracts.

Each of those options offers slightly different functionality:

*   `create_resource_account` - merely creates the resource account but doesn't fund it, retaining access to the resource account's signer until explicitly calling `retrieve_resource_account_cap`.
*   `create_resource_account_and_fund` - creates the resource account and funds it, retaining access to the resource account's signer until explicitly calling `retrieve_resource_account_cap`.
*   `create_resource_account_and_publish_package` - creates the resource account and results in loss of access to the resource account by design, because resource accounts are used to make contracts autonomous and immutable.

In this example, you will [initialize](https://github.com/aptos-labs/aptos-core/blob/2e9d8ee759fcd3f6e831034f05c1656b1c48efc4/aptos-move/move-examples/mint_nft/sources/minting.move#L73) the `mint_nft` module and retrieve the signer capability from both the resource account and module account. To do so, call `create_resource_account_and_publish_package` to publish the module under the resource account's address.

1.  Initialize the module as shown in the [`minting.move`](https://github.com/aptos-labs/aptos-core/blob/2e9d8ee759fcd3f6e831034f05c1656b1c48efc4/aptos-move/move-examples/mint_nft/sources/minting.move#L73) example.
2.  Call `create_resource_account_and_publish_package` to publish the module under the resource account's address, such as in the [`mint_nft.rs`](https://github.com/aptos-labs/aptos-core/blob/main/aptos-move/e2e-move-tests/src/tests/mint_nft.rs#L62) end-to-end example.
3.  Retrieve the signer cap from the resource account + module account as shown in the [`minting.move`](https://github.com/aptos-labs/aptos-core/blob/2e9d8ee759fcd3f6e831034f05c1656b1c48efc4/aptos-move/move-examples/mint_nft/sources/minting.move#L83) example.

Note, if the above `resource_account` signer is **not** already set up as a resource account, retrieving the signer cap will fail. The `source_addr` field in the `retrieve_resource_account_cap` function refers to the address of the source account, or the account that creates the resource account.

For an example, see the `SignerCapability` employed by the `mint_nft` function in [`minting.move`](https://github.com/aptos-labs/aptos-core/blob/2e9d8ee759fcd3f6e831034f05c1656b1c48efc4/aptos-move/move-examples/mint_nft/sources/minting.move#L143-L181).

For more details, see the "resource account" references in [`resource_account.move`](https://github.com/aptos-labs/aptos-core/blob/main/aptos-move/framework/aptos-framework/sources/resource_account.move) and [`account.move`](https://github.com/aptos-labs/aptos-core/blob/main/aptos-move/framework/aptos-framework/sources/account/account.move).

# Building with Move Scripts

> Guide to scripts in Move scripts for Aptos blockchain operations.

Move Scripts are a way to run multiple public functions on Aptos in a single transaction. This is similar to deploying a helper module that would do common tasks, but allows for the flexibility of not having to deploy beforehand.

An example would be a function to transfer a half of a user's balance to another account. This is something that is easily programmable, but likely would not need a module deployed for it:

```
script {  use std::signer;  use aptos_framework::coin;  use aptos_framework::aptos_account;
  fun transfer_half<Coin>(caller: &signer, receiver_address: address) {    // Retrieve the balance of the caller    let caller_address: address = signer::address_of(caller);    let balance: u64 = coin::balance<Coin>(caller_address);
    // Send half to the receiver    let half = balance / 2;    aptos_account::transfer_coins<Coin>(caller, receiver_address, half);  }}
```

# Learn more about using Move Scripts

[](#learn-more-about-using-move-scripts)

*   [Writing scripts](/build/smart-contracts/scripts/writing-scripts)
*   [Compiling scripts](/build/smart-contracts/scripts/compiling-scripts)
*   [Running scripts](/build/smart-contracts/scripts/running-scripts)

# More details

[](#more-details)

For more details on Move Scripts, checkout:

*   [Move Book on Scripts](https://aptos-labs.github.io/move-book/modules-and-packages.html)
*   [Tutorial on Scripts](/build/smart-contracts/scripts/script-tutorial)

# Compiling Move Scripts

> Understand how to compile Move scripts with proper configuration and deployment preparation.

Move scripts can be compiled with the already existing Aptos Move compiler in the Aptos CLI. For more on how to install and use the Aptos CLI with Move contracts, go to the [Working With Move Contracts](/build/cli/working-with-move-contracts) page.

Once you have the Aptos CLI installed, you can compile a script by running the following command from within the script package:

```
aptos move compile
```

There will then be compiled bytecode files under `build/` with the same name as the function in Move.

For example this script in package `transfer_half`, would compile to `build/transfer_half/bytecode_scripts/transfer_half.mv`

Additionally, there is a convenience function for a package with exactly one script with the below command:

```
aptos move compile-script
```

Providing output like below returning the exact location of the script and a hash for convenience

```
Compiling, may take a little while to download git dependencies...UPDATING GIT DEPENDENCY https://github.com/aptos-labs/aptos-framework.gitINCLUDING DEPENDENCY AptosFrameworkINCLUDING DEPENDENCY AptosStdlibINCLUDING DEPENDENCY MoveStdlibBUILDING transfer_half{  "Result": {    "script_location": "/opt/git/developer-docs/apps/docusaurus/static/move-examples/scripts/transfer_half/script.mv",    "script_hash": "9b57ffa952da2a35438e2cf7e941ef2120bb6c2e4674d4fcefb51d5e8431a148"  }}
```

# Running Move Scripts

> Learn how to execute Move scripts on Aptos blockchain for one-time operations and complex transactions.

Move scripts are supported in the Aptos TypeScript SDK, Aptos Wallet Adapter, and in the Aptos CLI.

## Running scripts with the TypeScript SDK

[](#running-scripts-with-the-typescript-sdk)

To use a script with the TypeScript SDK, add the `bytecode` directly to the transaction in place of an entry function name.

```
import { readFileSync } from "fs";import { Aptos, Account, AccountAddress } from "@aptos-labs/ts-sdk";
// Setup client, and account to signconst aptos = new Aptos();const account = Account.generate();
// Load script bytecodeconst buffer = readFileSync("./transfer_half.mv", "buffer");const bytecode = new Uint8Array.from(buffer);
// Build a transaction with the bytecode of the scriptconst transaction = await aptos.transaction.build.simple({  sender: account.accountAddress,  data: {    bytecode,    typeArguments: [parseTypeTag("0x1::aptos_coin::AptosCoin")],    functionArguments: [AccountAddress.from("0x1")],  },});
// Submit and wait for the transaction to completeconst pendingTxn = await aptos.signAndSubmitTransaction({  signer: account,  transaction,});await aptos.waitForTransaction({ transactionHash: pendingTxn.hash });
```

## Running scripts with the Aptos Wallet Adapter

[](#running-scripts-with-the-aptos-wallet-adapter)

Caution

Not all wallets support scripts, but when the wallet supports scripts, it can be provided as below

Similar to the TypeScript SDK, the same inputs are accepted as a transaction type on the wallet adapter. Just simply load the bytecode as a hex `string` or a `uint8array`.

```
import { useWallet } from "@aptos-labs/wallet-adapter-react";
//...
// Load the bytecode either as a uint8array or a hex encoded stringconst BYTECODE_IN_HEX = "0xa11ceb0b...78979";
export default function App() {  const { signAndSubmitTransaction } = useWallet();
  function submitScript() {    signAndSubmitTransaction({      data: {        bytecode: BYTECODE_IN_HEX,        typeArguments: [parseTypeTag("0x1::aptos_coin::AptosCoin")],        functionArguments: [AccountAddress.from("0x1")],      },    });  }
  // ...}
```

## Running scripts with the CLI

[](#running-scripts-with-the-cli)

Running scripts with the CLI can be run with the command

```
aptos move run-script
```

There are two ways to run it, with a pre-compiled script, or it will compile the script in-place similar to the compile step.

If you already have a compiled script, you can run it with `--compiled-script-path` like the example below:

```
aptos move run-script --compiled-script-path /opt/git/developer-docs/apps/docusaurus/static/move-examples/scripts/transfer_half/script.mv
```

Similarly, if it's not compiled, just use `--script-path`

```
aptos move run-script --script-path ./sources/transfer_half.move
```

# Move Scripts Tutorial

> Step-by-step tutorial for creating and deploying Move scripts with practical examples and best practices.

This tutorial explains how to write and execute a [Move script](https://aptos-labs.github.io/move-book/modules-and-packages.html). You can use Move scripts to execute a series of commands across published Move module interfaces.

For more information about scripts, see the [Move scripts docs](/build/smart-contracts/scripts)

## Example use case

[](#example-use-case)

The following example calls functions on the [aptos\_coin.move](https://github.com/aptos-labs/aptos-core/blob/main/aptos-move/framework/aptos-framework/sources/aptos_coin.move) module to confirm the balance of the destination account is less than `desired_balance`, and if so, tops it up to `desired_balance`.

```
script {    use std::signer;    use aptos_framework::aptos_account;    use aptos_framework::aptos_coin;    use aptos_framework::coin;
    fun main(src: &signer, dest: address, desired_balance: u64) {        let src_addr = signer::address_of(src);
        addr::my_module::do_nothing();
        let balance = coin::balance<aptos_coin::AptosCoin>(src_addr);        if (balance < desired_balance) {            aptos_account::transfer(src, dest, desired_balance - balance);        };    }}
```

## Execution

[](#execution)

Now that you know what you would like to accomplish, you need to determine:

*   Where do I put these files?
*   What do I name them?
*   Do I need a `Move.toml`?
*   How do I run my script with the CLI?

Let us run through how to execute a Move script with a step-by-step example using the [Aptos CLI](/build/cli/working-with-move-contracts).

1.  Make a new directory for your work:
    
    ```
    mkdir testingcd testing
    ```
    
2.  Set up the Aptos CLI and [create an account](/build/cli/setup-cli):
    
    ```
    aptos init --network devnet
    ```
    
    You may reuse an existing private key (which looks like this: `0xbd944102bf5b5dfafa7fe865d8fa719da6a1f0eafa3cd600f93385482d2c37a4`), or it can generate a new one for you, as part of setting up your account. Let's say your account looks like the example below:
    
    ```
    ---profiles:  default:    private_key: "0xbd944102bf5b5dfafa7fe865d8fa719da6a1f0eafa3cd600f93385482d2c37a4"    public_key: "0x47673ec83bb254cc9a8bfdb31846daacd0c96fe41f81855462f5fc5306312b1b"    account: cb265645385819f3dbe71aac266e319e7f77aed252cacf2930b68102828bf615    rest_url: "https://api.devnet.aptoslabs.com"    faucet_url: "https://faucet.devnet.aptoslabs.com"
    ```
    
3.  From this same directory, initialize a new Move project:
    
    ```
    aptos move init --name run_script
    ```
    
4.  Create a `my_script.move` file containing the example script above in a `sources/` subdirectory of your `testing/` directory. Also, create a `my_module.move` file as seen in the example below:
    
    ```
    module addr::my_module {    public entry fun do_nothing() { }}
    ```
    
    This results in the following file structure:

*   testing/
    
    *   Move.toml
    *   sources/
        
        *   my\_script.move
        *   my\_module.move

5.  Compile the script:
    
    ```
    $ aptos move compile --named-addresses addr=cb265645385819f3dbe71aac266e319e7f77aed252cacf2930b68102828bf615Compiling, may take a little while to download git dependencies...INCLUDING DEPENDENCY AptosFrameworkINCLUDING DEPENDENCY AptosStdlibINCLUDING DEPENDENCY MoveStdlibBUILDING run_script{  "Result": [    "cb265645385819f3dbe71aac266e319e7f77aed252cacf2930b68102828bf615::my_module"  ]}
    ```
    
    Note how we use the `--named-addresses` argument. This is necessary because in the code we refer to this named address called `addr`. The compiler needs to know what this refers to. Instead of using this CLI argument, you could put something like this in your `Move.toml`:
    
    ```
    [addresses]addr = "cb265645385819f3dbe71aac266e319e7f77aed252cacf2930b68102828bf615"
    ```
    
6.  Run the compiled script:
    
    ```
    $ aptos move run-script --compiled-script-path build/run_script/bytecode_scripts/main.mv --args address:b078d693856a65401d492f99ca0d6a29a0c5c0e371bc2521570a86e40d95f823 --args u64:5Do you want to submit a transaction for a range of [17000 - 25500] Octas at a gas unit price of 100 Octas? [yes/no] >yes{  "Result": {    "transaction_hash": "0xa6ca6275c73f82638b88a830015ab81734a533aebd36cc4647b48ff342434cdf",    "gas_used": 3,    "gas_unit_price": 100,    "sender": "cb265645385819f3dbe71aac266e319e7f77aed252cacf2930b68102828bf615",    "sequence_number": 4,    "success": true,    "timestamp_us": 1683030933803632,    "version": 3347495,    "vm_status": "Executed successfully"  }}
    ```

Note that the path of the compiled script is under `build/run_script/`, not `build/my_script/`. This is because it uses the name of the project contained in `Move.toml`, which is `run_script` from when we ran `aptos move init --name run_script`.

See the [code](https://github.com/banool/move-examples/tree/main/run_script) used for this document. The full example explains how to use a Move script that relies on a user-created Move module as well.

See also how to do this with the [Rust SDK](https://github.com/aptos-labs/aptos-developer-discussions/discussions/24) instead of the Aptos CLI in Aptos Developer Discussions.

## Advanced

[](#advanced)

You may execute a script in a more streamlined fashion; instead of running `aptos move compile` and then `aptos move run-script --compiled-script-path` separately, you can just do this:

```
$ aptos move run-script --script-path sources/my_script.move --args address:b078d693856a65401d492f99ca0d6a29a0c5c0e371bc2521570a86e40d95f823 --args u64:5
```

This will conduct both steps with a single CLI command yet has [issues](https://github.com/aptos-labs/aptos-core/issues/5733). For this reason, we recommend using the previous two-step approach for now.

# How can I write Move Scripts?

> Learn how to write Move scripts for batch operations, administrative tasks, and complex transaction flows.

Move scripts can be written in tandem with Move contracts, but it's highly suggested to use a separate Move package for it. This will make it easier for you to determine which bytecode file comes from the script.

## Package layout

[](#package-layout)

The package needs a Move.toml and a sources directory, similar to code modules.

For example, we may have a directory layout like:

*   my\_project/
    
    *   Move.toml
    *   sources/
        
        *   my\_script.move

## Script syntax

[](#script-syntax)

Scripts can be written exactly the same as modules on Aptos. Imports can be used for any dependencies in the Move.toml file, and all public functions, including entry functions, can be called from the contract. There are a few limitations:

*   There must be only one function in the contract, it will compile to that name.
*   Input arguments can only be one of \[`u8`, `u16`, `u32`, `u64`, `u256`, `address`, `bool`, `signer`, `&signer`, `vector<u8>`\]. There is no support for vectors of other types, or structs.

An example below:

For more specific details see: [Move Book on Scripts](https://aptos-labs.github.io/move-book/modules-and-packages.html)

# Smart Table

> Learn about smart table for Move smart contract development on Aptos blockchain.

## Core Features of SmartTable

[](#core-features-of-smarttable)

### Structure

[](#structure)

The `SmartTable` struct is designed to handle dynamic data efficiently:

### Constants

[](#constants)

The following constants define various error codes used within the module:

*   `ENOT_FOUND`: 1
*   `EZERO_CAPACITY`: 2
*   `ENOT_EMPTY`: 3
*   `EALREADY_EXIST`: 4
*   `EINVALID_LOAD_THRESHOLD_PERCENT`: 5
*   `EINVALID_TARGET_BUCKET_SIZE`: 6
*   `EEXCEED_MAX_BUCKET_SIZE`: 7
*   `EINVALID_BUCKET_INDEX`: 8
*   `EINVALID_VECTOR_INDEX`: 9

### API Overview

[](#api-overview)

#### Creating Tables

[](#creating-tables)

*   `new<K: copy + drop + store, V: store>(): SmartTable<K, V>`: Creates an empty table with default configurations.
*   `new_with_config<K: copy + drop + store, V: store>(num_initial_buckets: u64, split_load_threshold: u8, target_bucket_size: u64): SmartTable<K, V>`: Creates an empty table with custom configurations.

#### Destroying Tables

[](#destroying-tables)

*   `destroy_empty<K, V>(table: SmartTable<K, V>)`: Destroys an empty table.
*   `destroy<K: drop, V: drop>(table: SmartTable<K, V>)`: Destroys a table and its elements.
*   `clear<K: drop, V: drop>(table: &mut SmartTable<K, V>)`: Clears all elements from the table.

#### Managing Entries

[](#managing-entries)

*   `add<K, V>(table: &mut SmartTable<K, V>, key: K, value: V)`: Adds a key-value pair to the table.
*   `add_all<K, V>(table: &mut SmartTable<K, V>, keys: vector<K>, values: vector<V>)`: Adds multiple key-value pairs to the table.
*   `remove<K: copy + drop, V>(table: &mut SmartTable<K, V>, key: K): V`: Removes and returns the value associated with a key.
*   `upsert<K: copy + drop, V: drop>(table: &mut SmartTable<K, V>, key: K, value: V)`: Inserts or updates a key-value pair.

#### Retrieving Entries

[](#retrieving-entries)

*   `borrow<K: drop, V>(table: &SmartTable<K, V>, key: K): &V`: Returns an immutable reference to the value associated with a key.
*   `borrow_with_default<K: copy + drop, V>(table: &SmartTable<K, V>, key: K, default: &V): &V`: Returns the value associated with a key or a default value if the key is not found.
*   `borrow_mut<K: drop, V>(table: &mut SmartTable<K, V>, key: K): &mut V`: Returns a mutable reference to the value associated with a key.
*   `borrow_mut_with_default<K: copy + drop, V: drop>(table: &mut SmartTable<K, V>, key: K, default: V): &mut V`: Inserts a key-value pair if the key is not found, then returns a mutable reference to the value.

#### Utility Functions

[](#utility-functions)

*   `length<K, V>(table: &SmartTable<K, V>): u64`: Returns the number of entries in the table.
*   `load_factor<K, V>(table: &SmartTable<K, V>): u64`: Returns the load factor of the table.
*   `update_split_load_threshold<K, V>(table: &mut SmartTable<K, V>, split_load_threshold: u8)`: Updates the split load threshold.
*   `update_target_bucket_size<K, V>(table: &mut SmartTable<K, V>, target_bucket_size: u64)`: Updates the target bucket size.
*   `to_simple_map<K: store + copy + drop, V: store + copy>(table: &SmartTable<K, V>): SimpleMap<K, V>`: Converts the smart table to a simple map.

## Example Usage

[](#example-usage)

### Creating and Using a SmartTable

[](#creating-and-using-a-smarttable)

```
module 0x42::smart_table_usage {    use aptos_std::smart_table;
    public entry fun main() {        let table = smart_table::new<u64, u64>();        smart_table::add(&mut table, 1, 100);        smart_table::add(&mut table, 2, 200);
        let length = smart_table::length(&table);        assert!(length == 2, 0);
        let value1 = smart_table::borrow(&table, 1);        assert!(*value1 == 100, 0);
        let value2 = smart_table::borrow(&table, 2);        assert!(*value2 == 200, 0);
        let removed_value = smart_table::remove(&mut table, 1);        assert!(removed_value == 100, 0);
        smart_table::destroy_empty(table);    }}
```

### Adding Multiple Entries to a SmartTable

[](#adding-multiple-entries-to-a-smarttable)

```
module 0x42::smart_table_usage {    use aptos_std::smart_table;
    public fun add_multiple_entries() {        let table = smart_table::new<u64, u64>();        let keys = vector[1, 2, 3];        let values = vector[100, 200, 300];
        smart_table::add_all(&mut table, keys, values);
        let length = smart_table::length(&table);        assert!(length == 3, 0);
        let value1 = smart_table::borrow(&table, 1);        assert!(*value1 == 100, 0);
        let value2 = smart_table::borrow(&table, 2);        assert!(*value2 == 200, 0);
        let value3 = smart_table::borrow(&table, 3);        assert!(*value3 == 300, 0);
        smart_table::destroy_empty(table);    }}
```

### Updating and Clearing Table

[](#updating-and-clearing-table)

```
module 0x42::smart_table_usage {    use aptos_std::smart_table;
    public fun update_and_clear_table() {        let table = smart_table::new<u64, u64>();        smart_table::add(&mut table, 1, 100);        smart_table::add(&mut table, 2, 200);
        smart_table::upsert(&mut table, 2, 300);        let value2 = smart_table::borrow(&table, 2);        assert!(*value2 == 300, 0);
        smart_table::clear(&mut table);        let length = smart_table::length(&table);        assert!(length == 0, 0);
        smart_table::destroy_empty(table);    }}
```

### Converting to Simple Map

[](#converting-to-simple-map)

```
module 0x42::smart_table_usage {    use aptos_std::smart_table;    use aptos_std::simple_map;
    public fun convert_to_simple_map() {        let table = smart_table::new<u64, u64>();        smart_table::add(&mut table, 1, 100);        smart_table::add(&mut table, 2, 200);
        let map = smart_table::to_simple_map(&table);        let length = simple_map::length(&map);        assert!(length == 2, 0);
        let value1 = simple_map::borrow(&map, &1);        assert!(*value1 == 100, 0);
        let value2 = simple_map::borrow(&map, &2);        assert!(*value2 == 200, 0);
        smart_table::destroy(table);    }}
```

## Source Code

[](#source-code)

*   [smart\_table.move](https://github.com/aptos-labs/aptos-core/blob/main/aptos-move/framework/aptos-stdlib/sources/data_structures/smart_table.move)

## Other Examples

[](#other-examples)

# Smart Vector

> Learn about smart vector for Move smart contract development on Aptos blockchain.

The Smart Vector is a scalable vector implementation based on `tables`, where elements are grouped into buckets. This data structure allows for efficient handling of large data sets by combining the flexibility of small vectors with the scalability of larger structures.

## Core Features of `SmartVector`

[](#core-features-of-smartvector)

### Structure

[](#structure)

The `SmartVector` struct is designed to handle dynamic data with efficiency:

*   `inline_vec`: A small vector that stores elements directly.
*   `big_vec`: An optional large vector for scalable storage.
*   `inline_capacity`: An optional value defining the capacity of `inline_vec`.
*   `bucket_size`: An optional value defining the size of buckets in `big_vec`.

### Constants

[](#constants)

The following constants define various error codes used within the module:

*   `EINDEX_OUT_OF_BOUNDS`: 1
*   `EVECTOR_NOT_EMPTY`: 2
*   `EVECTOR_EMPTY`: 3
*   `EZERO_BUCKET_SIZE`: 4
*   `ESMART_VECTORS_LENGTH_MISMATCH`: 0x20005

## API Overview

[](#api-overview)

### Creating Vectors

[](#creating-vectors)

*   `new<T: store>(): SmartVector<T>`: Creates an empty vector.
*   `empty_with_config<T: store>(inline_capacity: u64, bucket_size: u64): SmartVector<T>`: Creates an empty vector with custom capacity and bucket size.
*   `singleton<T: store>(element: T): SmartVector<T>`: Creates a vector with a single element.

### Destroying Vectors

[](#destroying-vectors)

*   `destroy_empty<T>(v: SmartVector<T>)`: Destroys an empty vector.
*   `destroy<T: drop>(v: SmartVector<T>)`: Destroys a vector and its elements.

### Managing Elements

[](#managing-elements)

*   `push_back<T: store>(v: &mut SmartVector<T>, val: T)`: Adds an element to the end of the vector.
*   `pop_back<T>(v: &mut SmartVector<T>): T`: Removes the last element from the vector.
*   `remove<T>(v: &mut SmartVector<T>, i: u64): T`: Removes an element at a specific index.
*   `swap_remove<T>(v: &mut SmartVector<T>, i: u64): T`: Swaps an element at a specific index with the last element and removes it.
*   `borrow<T>(v: &SmartVector<T>, i: u64): &T`: Returns an immutable reference to an element at a specific index.
*   `borrow_mut<T>(v: &mut SmartVector<T>, i: u64): &mut T`: Returns a mutable reference to an element at a specific index.

### Utility Functions

[](#utility-functions)

*   `length<T>(v: &SmartVector<T>): u64`: Returns the number of elements in the vector.
*   `is_empty<T>(v: &SmartVector<T>): bool`: Checks if the vector is empty.
*   `clear<T: drop>(v: &mut SmartVector<T>)`: Clears all elements from the vector.
*   `to_vector<T: store + copy>(v: &SmartVector<T>): vector<T>`: Converts a smart vector to a native vector.

## Example Usage

[](#example-usage)

### Creating and Using a SmartVector

[](#creating-and-using-a-smartvector)

```
module 0x42::smart_vector_usage {    use aptos_std::smart_vector;
    public entry fun main() {        let v = smart_vector::new<u64>();        smart_vector::push_back(&mut v, 10);        smart_vector::push_back(&mut v, 20);        let length = smart_vector::length(&v);        assert!(length == 2, 0);        let first_elem = smart_vector::borrow(&v, 0);        assert!(*first_elem == 10, 0);        let second_elem = smart_vector::borrow(&v, 1);        assert!(*second_elem == 20, 0);        let last_elem = smart_vector::pop_back(&mut v);        assert!(last_elem == 20, 0);        smart_vector::destroy_empty(v);    }}
```

### Appending Vectors

[](#appending-vectors)

```
module 0x42::smart_vector_usage {    use aptos_std::smart_vector;
    public fun append_vectors() {        let v1 = smart_vector::new<u64>();        let v2 = smart_vector::new<u64>();
        smart_vector::push_back(&mut v1, 1);        smart_vector::push_back(&mut v1, 2);
        smart_vector::push_back(&mut v2, 3);        smart_vector::push_back(&mut v2, 4);
        smart_vector::append(&mut v1, v2);
        let length = smart_vector::length(&v1);        assert!(length == 4, 0);
        let first_elem = smart_vector::borrow(&v1, 0);        assert!(*first_elem == 1, 0);
        let second_elem = smart_vector::borrow(&v1, 1);        assert!(*second_elem == 2, 0);
        let third_elem = smart_vector::borrow(&v1, 2);        assert!(*third_elem == 3, 0);
        let fourth_elem = smart_vector::borrow(&v1, 3);        assert!(*fourth_elem == 4, 0);    }}
```

### Removing Elements

[](#removing-elements)

```
module 0x42::smart_vector_usage {    use aptos_std::smart_vector;
    public fun remove_elements() {        let v = smart_vector::new<u64>();
        smart_vector::push_back(&mut v, 1);        smart_vector::push_back(&mut v, 2);        smart_vector::push_back(&mut v, 3);
        let removed_elem = smart_vector::remove(&mut v, 1);        assert!(removed_elem == 2, 0);
        let length = smart_vector::length(&v);        assert!(length == 2, 0);
        let first_elem = smart_vector::borrow(&v, 0);        assert!(*first_elem == 1, 0);
        let second_elem = smart_vector::borrow(&v, 1);        assert!(*second_elem == 3, 0);    }}
```

### Clearing the Vector

[](#clearing-the-vector)

```
module 0x42::smart_vector_usage {    use aptos_std::smart_vector;
    public fun clear_vector() {        let v = smart_vector::new<u64>();
        smart_vector::push_back(&mut v, 1);        smart_vector::push_back(&mut v, 2);        smart_vector::push_back(&mut v, 3);
        smart_vector::clear(&mut v);        let length = smart_vector::length(&v);        assert!(length == 0, 0);    }}
```

### Swapping Elements

[](#swapping-elements)

```
module 0x42::smart_vector_usage {    use aptos_std::smart_vector;
    public fun swap_elements() {        let v = smart_vector::new<u64>();
        smart_vector::push_back(&mut v, 1);        smart_vector::push_back(&mut v, 2);        smart_vector::push_back(&mut v, 3);
        smart_vector::swap(&mut v, 0, 2);
        let first_elem = smart_vector::borrow(&v, 0);        assert!(*first_elem == 3, 0);
        let third_elem = smart_vector::borrow(&v, 2);        assert!(*third_elem == 1, 0);    }}
```

## Source Code

[](#source-code)

*   [smart\_vector.move](https://github.com/aptos-labs/aptos-core/blob/main/aptos-move/framework/aptos-stdlib/sources/data_structures/smart_vector.move)

## Other Examples

[](#other-examples)

*   [move spiders tutorial on smart vectors](https://movespiders.com/courses/modules/datastructures/lessonId/6)
*   [move spiders tutorial on querying smart vectors](https://movespiders.com/courses/modules/datastructures/lessonId/9)

# Table

> Learn about table for Move smart contract development on Aptos blockchain.

The `Table` provides a flexible and efficient way to manage large amounts of data in a table format. Each table item is represented as a separate global state item, allowing for scalable storage solutions.

## Core Features of Table

[](#core-features-of-table)

### Structure

[](#structure)

The `Table` struct is designed to handle large-scale storage with efficiency:

*   `handle`: An address that uniquely identifies the table.

### Constants

[](#constants)

The following constants define various error codes used within the module (these are implied but not explicitly stated in the provided code):

*   `ENOT_FOUND`: Key not found in the table.
*   `EALREADY_EXIST`: Key already exists in the table.
*   `EINVALID_ARGUMENT`: Invalid argument passed to a function.

### API Overview

[](#api-overview)

#### Creating Tables

[](#creating-tables)

*   `new<K: copy + drop, V: store>(): Table<K, V>`: Creates a new table.

#### Managing Entries

[](#managing-entries)

*   `add<K: copy + drop, V>(table: &mut Table<K, V>, key: K, val: V)`: Adds a key-value pair to the table. Aborts if the key already exists.
*   `remove<K: copy + drop, V>(table: &mut Table<K, V>, key: K): V`: Removes and returns the value associated with a key. Aborts if the key is not found.
*   `upsert<K: copy + drop, V: drop>(table: &mut Table<K, V>, key: K, value: V)`: Inserts or updates a key-value pair.

#### Retrieving Entries

[](#retrieving-entries)

*   `borrow<K: copy + drop, V>(table: &Table<K, V>, key: K): &V`: Returns an immutable reference to the value associated with a key. Aborts if the key is not found.
*   `borrow_with_default<K: copy + drop, V>(table: &Table<K, V>, key: K, default: &V): &V`: Returns the value associated with a key or a default value if the key is not found.
*   `borrow_mut<K: copy + drop, V>(table: &mut Table<K, V>, key: K): &mut V`: Returns a mutable reference to the value associated with a key. Aborts if the key is not found.
*   `borrow_mut_with_default<K: copy + drop, V: drop>(table: &mut Table<K, V>, key: K, default: V): &mut V`: Inserts a key-value pair if the key is not found, then returns a mutable reference to the value.

#### Utility Functions

[](#utility-functions)

*   `contains<K: copy + drop, V>(table: &Table<K, V>, key: K): bool`: Checks if the table contains a key.

## Example Usage

[](#example-usage)

### Creating and Using a Table

[](#creating-and-using-a-table)

```
module 0x42::table_usage {    use aptos_std::table;
    public entry fun main() {        let table = table::new<u64, u64>();        table::add(&mut table, 1, 100);        table::add(&mut table, 2, 200);
        let value1 = table::borrow(&table, 1);        assert!(*value1 == 100, 0);
        let value2 = table::borrow(&table, 2);        assert!(*value2 == 200, 0);
        let removed_value = table::remove(&mut table, 1);        assert!(removed_value == 100, 0);
        let contains_key = table::contains(&table, 2);        assert!(contains_key, 0);
        // Note: A table must be stored in a resource at the end of a function    }}
```

### Adding and Upserting Multiple Entries

[](#adding-and-upserting-multiple-entries)

```
module 0x42::table_usage {    use aptos_std::table;
    public fun add_and_upsert_entries() {        let table = table::new<u64, u64>();        table::add(&mut table, 1, 100);        table::upsert(&mut table, 1, 200);        table::upsert(&mut table, 2, 300);
        let value1 = table::borrow(&table, 1);        assert!(*value1 == 200, 0);
        let value2 = table::borrow(&table, 2);        assert!(*value2 == 300, 0);
        // Note: A table must be stored in a resource at the end of a function    }}
```

### Borrowing Mutable References

[](#borrowing-mutable-references)

```
module 0x42::table_usage {    use aptos_std::table;
    public fun borrow_mutable_references() {        let table = table::new<u64, u64>();        table::add(&mut table, 1, 100);
        let value_mut = table::borrow_mut(&mut table, 1);        *value_mut = 200;
        let value = table::borrow(&table, 1);        assert!(*value == 200, 0);
        // Note: A table must be stored in a resource at the end of a function    }}
```

## Source Code

[](#source-code)

*   [table.move](https://github.com/aptos-labs/aptos-core/blob/main/aptos-move/framework/aptos-stdlib/sources/table.move)

## Other Examples

[](#other-examples)

*   [Move Spiders Tables Tutorial](https://movespiders.com/courses/modules/datastructures/lessonId/4)
*   [Move Spiders Query Table via FullNode](https://movespiders.com/courses/modules/datastructures/lessonId/9)
*   [Move Spiders Query Table via View Function](https://movespiders.com/courses/modules/datastructures/lessonId/10)

# Third Party Dependencies

> Learn about third party dependencies for Move smart contract development on Aptos blockchain.

Third party dependencies are external [modules](https://aptos-labs.github.io/move-book/modules-and-packages.html) that a controlled module interacts with. Typically, these external modules exist under different accounts.

## Multi-DEX router example

[](#multi-dex-router-example)

A multi-DEX router actively utilizes third party dependencies. Instead of submitting multiple transactions to interact with different DEXs and their individual [entry](https://aptos-labs.github.io/move-book/functions.html#entry-modifier) functions within a swap route, a module (or [script](https://aptos-labs.github.io/move-book/modules-and-packages.html)) can consolidate all independent DEX invocations into a single, atomic transaction. The multi-DEX router references and calls to functions present in each of the third party DEX modules to achieve this.

## Sources

[](#sources)

Third party dependencies will have varying amounts of reliability and available information based on where they’re sourced from. Specifically, documentation for a few instances will be non-existant, as well as logic potentially being refactored.

Source code that is verified against the on-chain deployed module, like the [Git Repository](#git-repository) and [Local Source Code](#local-source-code), should always be preferred. If neither of those are available, there are other options to depend on usable code, like [decompiled code](#decompiled-code), [bytecode](#bytecode), and [ABI](#abi)\-crafted code.

### Git Repository

[](#git-repository)

The default `Move.toml` includes `AptosFramework` as a git repository dependency:

```
  [dependencies.AptosFramework]  git = "<https://github.com/aptos-labs/aptos-framework.git>"  rev = "mainnet"  subdir = "aptos-framework"
```

When Aptos CLI commands are ran, updates to the dependency are automatically retrieved and compiled against.

### Local Source Code

[](#local-source-code)

Third party source code can be included in the `sources` directory. Essentially treating it the same as custom code.

*   third\_party\_dependency\_project/
    
    *   source/
        
        *   `{ControlledCode}.move`
        *   `{ThirdPartyCode}.move`
        
    *   Move.toml

Caution

Any upgrades to the Third Party dependency will need to be retrieved, manually.

### Decompiled code

[](#decompiled-code)

Move code can be reconstructed by using the [Revela Compiler](https://aptoslabs.medium.com/move-revealed-the-revela-decompiler-b206eaf48b45#27ad) against a package’s bytecode:

```
aptos move decompile --package-path ./bytecode_modules
```

Corresponding `{ModuleName}.mv.move` files will be generated in `bytecode_modules`.

*   third\_party\_dependency\_project/
    
    *   byte\_modules/
        
        *   `{ModuleName}.mv`
        *   `{ModuleName}.mv.move`
        
    *   Move.toml

Reference it as a local source file after changing the file type to `{ModuleName}.move` and placing it in the workspace’s `sources` directory.

*   third\_party\_dependency\_project/
    
    *   sources/
        
        *   `{ModuleName}.move`
        
    *   Move.toml

Note

Decompiled code will keep behaviors of on-chain execution, but will be refactored.

### Bytecode

[](#bytecode)

The Aptos CLI allows for downloading a [package's](https://aptos-labs.github.io/move-book/modules-and-packages.html) bytecode.

```
aptos move download --account {account_addr} --bytecode --package {package_name}
```

Each bytecode dependency requires their own package, with a structure of:

*   `Move.toml` file, with the package address pre-defined.
*   `build/{ModuleName}/bytecode_modules` directory with the bytecode inside.
*   Empty sources directory.

The controlled module can then reference the dependency, upon it's inclusion in the controlled package's `Move.toml`.

Aptos Token example

A controlled `invoking_code.move` module interacts with the external `aptos_token` module:

```
module invoker::invoking_code {    use aptos_token_objects_addr::aptos_token;
    public entry fun wrapper_add_property(): u64 {        aptos_token::add_property(...);    }}
```

The below command retrieves the necessary [AptosTokenObjects package](https://explorer.aptoslabs.com/account/0x4/modules/code/aptos_token/mint?network=mainnet) bytecode from the Mainnet.

```
aptos move download --account 0x4 \--bytecode --package AptosTokenObjects \--output-dir ./aptos_token_bytecode_output/
```

*   invoking\_code/
    
    *   aptos\_token\_bytecode\_output/
        
        *   byte\_modules/
            
            *   aptos\_token.mv
            
        
    *   sources/
        
        *   invoking\_code.move
        
    *   Move.toml

The created dependency package structure and contents for `aptos_token` is:

*   aptos\_token\_objects\_addr/
    
    *   build/
        
        *   aptos\_token/
            
            *   bytecode\_modules/
                
                *   aptos\_token.mv
                
            
        
    *   sources/
        
        *   ...
        
    *   Move.toml
    
*   invoking\_code/
    
    *   aptos\_token\_bytecode\_output/
        
        *   byte\_modules/
            
            *   aptos\_token.mv
            *   aptos\_token.mv.move
            *   ...
            
        
    *   sources/
        
        *   invoking\_code.move
        
    *   Move.toml

```
[package]name = "aptos_token"version = "0.0.0"[addresses]aptos_token_module_addr = "0x4"
```

The dependency list from the controlled `invoking_code.move` module will include a local reference to the bytecode package, allowing for compilation.

```
[package]name = "invoking_code"[addresses]invoker = "_"[dependencies]aptos_token = { local = "../aptos_token_objects_addr" }
```

### ABI

[](#abi)

Move interface code can be manually crafted by reading a package's ABI. Notably, while the function header is required to be exact, the logic within is not.

Note

All available public and entry methods are defined with their name, arguments, return values, and more, within the ABI. Structs and resources will also be included.

Afterwards, the interface code is treated equivalent to local source code.

Aptos Token example

Below is a portion of the `AptosTokenObjects` ABI, gathered from the [Aptos Explorer](https://explorer.aptoslabs.com/account/0x0000000000000000000000000000000000000000000000000000000000000004/modules/code/aptos_token?network=mainnet#:~:text=1114-,ABI,-%7B):

```
{"address": "0x4","name": "aptos_token","friends": [],"exposed_functions": [    {    "name": "add_property",    "visibility": "public",    "is_entry": true,    "is_view": false,    "generic_type_params": [        {        "constraints": [            "key"        ]        }    ],    "params": [        "&signer",        "0x1::object::Object<T0>",        "0x1::string::String",        "0x1::string::String",        "vector<u8>"    ],    "return": []    },    ...]}
```

An interface Move file can be handwritten and treated as a source file. Looking similar to:

```
module 0x4::aptos_token {    // ...    public entry fun add_property<T: key>(        creator: &signer,        token: Object<T>,        key: String,        type: String,        value: vector<u8>,    ) acquires AptosCollection, AptosToken {        abort 0    }}
```

*   third\_party\_dependency\_project/
    
    *   source/
        
        *   `{ControlledCode}.move`
        *   aptos\_token.move
        
    *   Move.toml

# Aptos Token Standard Overview

> Learn about tokens for Move smart contract development on Aptos blockchain.

The [Aptos Digital Asset Standard](/build/smart-contracts/digital-asset) defines the canonical Non-fungible Token on Aptos. Aptos leverages composability to extend the digital asset standard with features like fungibility via the [Fungible Asset standard](/build/smart-contracts/fungible-asset). The concept of composability comes from the underlying data model for these constructs: the [Move object](/build/smart-contracts/objects) data model.

The rest of this document discusses how the Aptos token standards compare to the standards on Ethereum and Solana.

## Data models

[](#data-models)

To understand tokens, we begin by comparing the data models across different blockchains.

### Ethereum

[](#ethereum)

Ethereum has two types of accounts:

*   Externally-owned accounts which store a balance of Ether.
*   Contract accounts which manage their underlying smart contracts and have an associated storage for persistent state, which can only be mutated by the associated contract.

In order to create a new NFT collection, a creator must deploy their own contract to the blockchain, which in turn will create a collection and set of NFTs within its storage.

### Solana

[](#solana)

Unlike Ethereum or Aptos where data and code co-exist, Solana stores data and programs in separate accounts. There are two types of accounts on the Solana blockchain:

*   Executable accounts only store contract code
*   Non-executable accounts store data associated with and owned by executable accounts.

In order to create a new NFT collection, a creator calls an existing deployed program to populate a new collection and set of NFTs.

### Aptos

[](#aptos)

The [accounts](/network/blockchain/accounts) in Aptos store both smart contracts and data. Unlike Ethereum, the associated data of a smart contract is distributed across the space of all accounts in [resources](/network/blockchain/resources) within [accounts](/network/blockchain/accounts) or [objects](/build/smart-contracts/objects). For example, a collection and an NFT within that collection are stored in distinct objects at different addresses with the smart contract defining them at another address. A smart contract developer could also store data associated with the NFT and collection at the same address as the smart contract or in other objects.

There are two means to create NFTs on Aptos:

*   The [no-code standard](https://github.com/aptos-foundation/AIPs/blob/main/aips/aip-22.md) allows creators to call into the contract to create new collections and tokens without deploying a new contract.
*   Custom NFT contracts allow creators to customize their NFTs by extending the object model that can manage all aspects of their collection.

Aptos strikes a balance between the customizability offered by Ethereum with the simplicity of creating new collections like Solana.

Like Ethereum, Aptos requires indexing to determine the set of all NFTs owned by an account, while Solana has no need.

## Token standard comparison

[](#token-standard-comparison)

The Fungible Token (FT) was initially introduced by [EIP-20](https://eips.ethereum.org/EIPS/eip-20), and Non-Fungible Token (NFT) was defined in [EIP-721](https://eips.ethereum.org/EIPS/eip-721). Later, [EIP-1155](https://eips.ethereum.org/EIPS/eip-1155) combined FT and NFT or even Semi-Fungible Token (SFT) into one standard.

The Ethereum token standards requires each token to deploy their own individual contract code to distinguish collection of tokens. Solana account model enables another pattern where code can be reused so that one generic program operates on various data. To create a new token, you could create an account that can mint tokens and more accounts that can receive them. The mint account itself uniquely determines the token type instead of contract account, and these are all passed as arguments to the one contract deployed to some executable account.

The collection of Aptos token standards shares some similarities with Solana, especially how it covers FT, NFT and SFT into a common on-chain code. Instead of deploying a new smart contract for each new token, a creator calls a function in the contract with the necessary arguments. Depending on which function you call, the token contract will mint/transfer/burn/... tokens.

### Token identification

[](#token-identification)

Aptos identifies a token by its `Address` or `ObjectId`, a location within global storage. Collections are stored at a location determined by the address of the creator and the name of the collection.

In Ethereum, contracts are deployed on accounts determined by the account that is deploying the contract. NFTs are then stored as indexes into data tables within the contract.

In Solana, NFT data is stored under a mint account, independent of the program account.

### Token metadata

[](#token-metadata)

Aptos token has metadata in its `Token` resource with the data most commonly required by dapps to interact with tokens. Some examples include:

*   `name`: The name of the token. It must be unique within a collection.
*   `description`: The description of the token.
*   `uri`: A URL pointer to off-chain for more information about the token. The asset could be media such as an image or video or more metadata in a JSON file.
*   `collection`: A pointer to the ObjectId of the collection.

Additional fields can be stored in creator-defined resources or the `PropertyMap` resource that defines a generalizable key-value map.

In Ethereum, only a small portion of such properties are defined as methods, such as `name()`, `symbol()`, `decimals()`, `totalSupply()` of ERC-20; or `name()` and `symbol()` and `tokenURI()` of the optional metadata extension for ERC-721; ERC-1155 also has a similar method `uri()` in its own optional metadata extension. Token metadata is not standardized so that dapps have to take special treatment case by case.

In Solana, the Token Metadata program offers a Metadata Account defining numerous metadata fields associated with a token as well, including `collection` which is defined in `TokenDataId` in Aptos. Solana, however, does not offer mutability for assets, unlike Aptos. Like Aptos, Token Metadata v1.1.0 offers an `attribute` container for customized properties.

# Vector

> Master vector operations in Move for dynamic arrays, collections, and list manipulation in smart contracts.

The Vector in Move provides a flexible and dynamic array-like data structure that supports various operations such as indexing, adding, and removing elements. Vectors in Move are growable and support 0-based indexing.

## Core Features of Vector

[](#core-features-of-vector)

### Structure

[](#structure)

The `vector` module provides various native and Move functions to manage dynamic arrays:

*   `empty`: Creates an empty vector.
*   `length`: Returns the length of the vector.
*   `borrow`: Returns an immutable reference to an element at a given index.
*   `push_back`: Adds an element to the end of the vector.
*   `borrow_mut`: Returns a mutable reference to an element at a given index.
*   `pop_back`: Removes and returns the last element of the vector.
*   `destroy_empty`: Destroys an empty vector.
*   `swap`: Swaps elements at two given indices.

### Constants

[](#constants)

The following constants define various error codes used within the module:

*   `EINDEX_OUT_OF_BOUNDS`: 0x20000

### API Overview

[](#api-overview)

#### Creating Vectors

[](#creating-vectors)

*   `empty<Element>(): vector<Element>`: Creates an empty vector.
*   `singleton<Element>(e: Element): vector<Element>`: Creates a vector with a single element.

#### Managing Elements

[](#managing-elements)

*   `push_back<Element>(v: &mut vector<Element>, e: Element)`: Adds an element to the end of the vector.
*   `pop_back<Element>(v: &mut vector<Element>): Element`: Removes and returns the last element from the vector.
*   `remove<Element>(v: &mut vector<Element>, i: u64): Element`: Removes an element at a specific index and shifts subsequent elements.
*   `swap_remove<Element>(v: &mut vector<Element>, i: u64): Element`: Swaps the element at the given index with the last element and removes it.

#### Retrieving Elements

[](#retrieving-elements)

*   `borrow<Element>(v: &vector<Element>, i: u64): &Element`: Returns an immutable reference to an element at a given index.
*   `borrow_with_default<Element>(v: &vector<Element>, i: u64, default: &Element): &Element`: Returns a reference to an element or a default value if the index is out of bounds.
*   `borrow_mut<Element>(v: &mut vector<Element>, i: u64): &mut Element`: Returns a mutable reference to an element at a given index.

#### Utility Functions

[](#utility-functions)

*   `length<Element>(v: &vector<Element>): u64`: Returns the number of elements in the vector.
*   `is_empty<Element>(v: &vector<Element>): bool`: Checks if the vector is empty.
*   `contains<Element>(v: &vector<Element>, e: &Element): bool`: Checks if the vector contains a given element.
*   `index_of<Element>(v: &vector<Element>, e: &Element): (bool, u64)`: Returns the index of a given element if found.
*   `reverse<Element>(v: &mut vector<Element>)`: Reverses the order of elements in the vector.
*   `append<Element>(lhs: &mut vector<Element>, other: vector<Element>)`: Appends all elements of one vector to another.
*   `for_each<Element>(v: vector<Element>, f: |Element|)`: Applies a function to each element in the vector.
*   `for_each_ref<Element>(v: &vector<Element>, f: |&Element|)`: Applies a function to a reference of each element in the vector.
*   `for_each_mut<Element>(v: &mut vector<Element>, f: |&mut Element|)`: Applies a function to a mutable reference of each element in the vector.
*   `fold<Accumulator, Element>(v: vector<Element>, init: Accumulator, f: |Accumulator, Element|Accumulator): Accumulator`: Applies a function to accumulate a value over the elements of the vector.
*   `map<Element, NewElement>(v: vector<Element>, f: |Element|NewElement): vector<NewElement>`: Maps a function over the elements of the vector, producing a new vector.
*   `filter<Element: drop>(v: vector<Element>, p: |&Element|bool): vector<Element>`: Filters the vector using a predicate function.

## Example Usage

[](#example-usage)

### Creating and Using a Vector

[](#creating-and-using-a-vector)

```
module 0x42::vector_usage {    use std::vector;
    public entry fun main() {        let v = vector::empty<u64>();        vector::push_back(&mut v, 10);        vector::push_back(&mut v, 20);
        let length = vector::length(&v);        assert!(length == 2, 0);
        let first_elem = vector::borrow(&v, 0);        assert!(*first_elem == 10, 0);
        let second_elem = vector::borrow(&v, 1);        assert!(*second_elem == 20, 0);
        let last_elem = vector::pop_back(&mut v);        assert!(last_elem == 20, 0);
        vector::destroy_empty(v);    }}
```

### Appending Vectors

[](#appending-vectors)

```
module 0x42::vector_usage {    use std::vector;
    public fun append_vectors() {        let v1 = vector::empty<u64>();        let v2 = vector::empty<u64>();
        vector::push_back(&mut v1, 1);        vector::push_back(&mut v1, 2);
        vector::push_back(&mut v2, 3);        vector::push_back(&mut v2, 4);
        vector::append(&mut v1, v2);
        let length = vector::length(&v1);        assert!(length == 4, 0);
        let first_elem = vector::borrow(&v1, 0);        assert!(*first_elem == 1, 0);
        let second_elem = vector::borrow(&v1, 1);        assert!(*second_elem == 2, 0);
        let third_elem = vector::borrow(&v1, 2);        assert!(*third_elem == 3, 0);
        let fourth_elem = vector::borrow(&v1, 3);        assert!(*fourth_elem == 4, 0);    }}
```

### Removing Elements

[](#removing-elements)

```
module 0x42::vector_usage {    use std::vector;
    public fun remove_elements() {        let v = vector::empty<u64>();
        vector::push_back(&mut v, 1);        vector::push_back(&mut v, 2);        vector::push_back(&mut v, 3);
        let removed_elem = vector::remove(&mut v, 1);        assert!(removed_elem == 2, 0);
        let length = vector::length(&v);        assert!(length == 2, 0);
        let first_elem = vector::borrow(&v, 0);        assert!(*first_elem == 1, 0);
        let second_elem = vector::borrow(&v, 1);        assert!(*second_elem == 3, 0);    }}
```

### Swapping Elements

[](#swapping-elements)

```
module 0x42::vector_usage {    use std::vector;
    public fun swap_elements() {        let v = vector::empty<u64>();
        vector::push_back(&mut v, 1);        vector::push_back(&mut v, 2);        vector::push_back(&mut v, 3);
        vector::swap(&mut v, 0, 2);
        let first_elem = vector::borrow(&v, 0);        assert!(*first_elem == 3, 0);
        let third_elem = vector::borrow(&v, 2);        assert!(*third_elem == 1, 0);    }}
```

## Source Code

[](#source-code)

*   [vector.move](https://github.com/aptos-labs/aptos-core/blob/main/third_party/move/move-stdlib/sources/vector.move)

## Other Examples

[](#other-examples)

*   [Move Spiders Vector Tutorial](https://movespiders.com/courses/modules/datastructures/lessonId/1)
*   [Move Spiders Vector Tutorial 2](https://movespiders.com/courses/modules/basics/lessonId/7)

# Why Move?

> Learn about why move for Move smart contract development on Aptos blockchain.

The Move programming language was originally created by a team of engineers at Facebook for the Diem Payment Network. Move is designed to be a platform-agnostic language to enable common libraries, tooling, and developer communities across diverse blockchains with vastly different data and execution models. At Aptos, we believe in building a strong developer community in Move and invite them to build upon the Move on Aptos stack and contribute to the open source software.

Move is built upon the following principles:

| **Principle** | **Explanation** | | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Secure by default** | Financial systems are built to ensure users don't lose funds. Move was designed to prevent entire classes of attacks and bugs such as reentrancy attacks, double spends, and arithmetic overflow. Type safety and compile time checks are at the forefront of the security. | | **Runtime Verification** | The bytecode can be verified at runtime to verify that nothing has gone wrong, providing extra safety and preventing malicious actors. | | **Formal Verification** | Move on Aptos provides a specification language to provide formal verification of contracts. This allows for proving invariants and assists with code auditing. | | **Simplicity** | The commands and bytecode are purposely simple. This allows for easy decompilation, runtime verification, and code inspection. Using regular programming languages for blockchains often requires to ignore large part of the language to make them suitable for smart contracts (e.g. Rust). |

## Why Move on Aptos?

[](#why-move-on-aptos)

Move on Aptos supports the full language built by the team at Facebook, with additional extensions built to improve the security and the developer experience.

### Security

[](#security)

| **Advantages** | **Explanation** | | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Formal Verification** | Aptos framework is fully specified and formally verified with the Move Prover. This includes the core contracts involving governance, NFTs, and Tokens. | | **Gas Coverage** | Move VM has 100% gas coverage. Gas is charged based upon actual usage in the system (CPU, memory, storage, I/O). In other words, no gas exploits. | | **Security Redundancy** | Security redundancy provided by runtime safety checks. | | **Permission Controls** | Permission controls can flexibly be built at various levels. For example, token level permission controls exist by default to enable RWA tokenization. |

### Developer Experience

[](#developer-experience)

| **Advantages** | **Explanation** | | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Move Development Tools** | - **Unit testing**: Move has built-in unit testing for all contracts. Aptos additionally provides test functionality in the framework to test different scenarios.  
\- **Coverage**: Coverage tooling allows for both source and bytecode level coverage reporting.  
\- **Decompiler**: For better security, on-chain bytecode can be disassembled or decompiled to provide visibility into the actual contracts.  
\- **IDE Plugins**: Aptos has support for all major IDEs: [VSCode](https://marketplace.visualstudio.com/items?itemName=AptosLabs.move-on-aptos), [Cursor etc.](https://open-vsx.org/extension/aptoslabs/move-on-aptos) and [IntelliJ](https://plugins.jetbrains.com/plugin/14721-move-on-aptos). | | **Data Model** | Aptos has an accessible data model with the data definition stored on-chain. Objects and accounts can have multiple distinct structures in an easy-to-parse format. | | **Upgradability** | Upgradability ensures that application interfaces cannot be broken and doesn't require explicit adoption from downstream applications. Contracts can simply be upgraded in-place to fix bugs. | | **Cross-Interaction** | Move allows for interaction between contracts by using type-safe structs. | | **Code Storage** | Aptos stores source code on-chain improving the ability to audit and ensure contract to bytecode correctness. | | **Sponsored Transactions** | Native sponsored transaction support allows for having transactions be paid by other users with no special services or contract-specific code required. | | **Robust Token Standards** | The Digital Asset and Fungible Asset standards provide flexibility and a unified standard for diverse types of tokens and digital assets on-chain. These were influenced by existing standards such as ERC-20, ERC-721, ERC-1155 and Token-2022. | | **On-chain Randomness** | Native on-chain unbiasable randomness provides a safe and consistent way of getting random numbers, with extra safety checks at compile time. |

# Aptos Blockchain

> Core concepts of the Aptos blockchain including architecture, consensus, and fundamental mechanisms

Start here to get into the core concepts of the Aptos blockchain. Then review our [research papers](https://aptoslabs.com/research) and the Aptos source code found in the [Aptos-core](https://github.com/aptos-labs/aptos-core) repository of GitHub while continuing your journey through this site. The source contains READMEs and code comments invaluable to developing on Aptos.

[Aptos White Paper](/network/blockchain/aptos-white-paper) Explore the foundational white paper of Aptos.

[Aptos Blockchain Deep Dive](/network/blockchain/blockchain-deep-dive) Dive deep into the mechanics and architecture of the Aptos blockchain.

[Move - A Web3 Language and Runtime](/network/blockchain/move) Learn about Move, the smart-contract language designed for security and formal verification.

[Accounts](/network/blockchain/accounts) Learn how accounts work on the Aptos blockchain.

[Resources](/network/blockchain/resources) Discover how resources store data for smart contracts on chain.

[Events](/network/blockchain/events) Learn how events are generated and used within Aptos.

[Transactions and States](/network/blockchain/txns-states) Explore the relationship between transactions and state changes.

[Gas and Transaction Fees](/network/blockchain/gas-txn-fee) Understand the gas model and how transaction fees are calculated.

[Computing Transaction Gas](/network/blockchain/base-gas) Learn how gas costs are computed for transactions.

[Blocks](/network/blockchain/blocks) Discover how Aptos groups transactions into blocks.

[Staking](/network/blockchain/staking) Learn about the staking mechanism and its benefits.

[Governance](/network/blockchain/governance) Understand how governance is handled on the Aptos blockchain.

# Aptos White Paper

> Read the official Aptos blockchain white paper outlining the technical design, scalability principles, Move language integration, and architectural innovations.

## Full PDF Versions

[](#full-pdf-versions)

[🇺🇸 English (en-US) ↗](https://aptosnetwork.com/whitepaper/aptos-whitepaper_en.pdf) Original Aptos White Paper PDF in English

[🇰🇷 한국어 Korean (ko-KR) ↗](https://aptosnetwork.com/whitepaper/aptos-whitepaper_ko.pdf) Aptos White Paper PDF translated to Korean

[🇯🇵 日本語 Japanese (ja-JP) ↗](https://aptosnetwork.com/whitepaper/aptos-whitepaper_ja.pdf) Aptos White Paper PDF translated to Japanese

[🇪🇸 Español Spanish (es-ES) ↗](https://aptosnetwork.com/whitepaper/aptos-whitepaper_es.pdf) Aptos White Paper PDF translated to Spanish

## Abstract

[](#abstract)

The rise of blockchains as a new Internet infrastructure has led to developers deploying tens of thousands of decentralized applications at rapidly growing rates. Unfortunately, blockchain usage is not yet ubiquitous due to frequent outages, high costs, low throughput limits, and numerous security concerns. To enable mass adoption in the web3 era, blockchain infrastructure needs to follow the path of cloud infrastructure as a trusted, scalable, cost-efficient, and continually improving platform for building widely-used applications.

We present the Aptos blockchain, designed with scalability, safety, reliability, and upgradeability as key principles, to address these challenges. The Aptos blockchain has been developed over the past three years by over 350+ developers across the globe. It offers new and novel innovations in consensus, smart contract design, system security, performance, and decentralization. The combination of these technologies will provide a fundamental building block to bring web3 to the masses:

*   First, the Aptos blockchain natively integrates and internally uses the Move language for fast and secure transaction execution. The Move prover, a formal verifier for smart contracts written in the Move language, provides additional safeguards for contract invariants and behavior. This focus on security allows developers to better protect their software from malicious entities.
    
*   Second, the Aptos data model enables flexible key management and hybrid custodial options. This, alongside transaction transparency prior to signing and practical light client protocols, provides a safer and more trustworthy user experience.
    
*   Third, to achieve high throughput and low latency, the Aptos blockchain leverages a pipelined and modular approach for the key stages of transaction processing. Specifically, transaction dissemination, block metadata ordering, parallel transaction execution, batch storage, and ledger certification all operate concurrently. This approach fully leverages all available physical resources, improves hardware efficiency, and enables highly parallel execution.
    
*   Fourth, unlike other parallel execution engines that break transaction atomicity by requiring upfront knowledge of the data to be read and written, the Aptos blockchain does not put such limitations on developers. It can efficiently support atomicity with arbitrarily complex transactions, enabling higher throughput and lower latency for real-world applications and simplifying development.
    
*   Fifth, the Aptos modular architecture design supports client flexibility and optimizes for frequent and instant upgrades. Moreover, to rapidly deploy new technology innovations and support new web3 use cases, the Aptos blockchain provides embedded on-chain change management protocols.
    
*   Finally, the Aptos blockchain is experimenting with future initiatives to scale beyond individual validator performance: its modular design and parallel execution engine support internal sharding of a validator and homogeneous state sharding provides the potential for horizontal throughput scalability without adding additional complexity for node operators.

# Computing Transaction Gas

> Deep dive into Aptos gas computation including instruction gas, storage fees, payload costs, and optimization strategies for cost-effective transactions.

Aptos transactions by default charge a base gas fee, regardless of market conditions. For each transaction, this "base gas" amount is based on three conditions:

1.  Instructions.
2.  Storage.
3.  Payload.

The more function calls, branching conditional statements, etc. that a transaction requires, the more instruction gas it will cost. Likewise, the more reads from and writes into global storage that a transaction requires, the more storage gas it will cost. Finally, the more bytes in a transaction payload, the more it will cost.

As explained in the [optimization principles](#optimization-principles) section, storage gas has by far the largest effect on base gas. For background on the Aptos gas model, see [The Making of the Aptos Gas Schedule](https://aptoslabs.medium.com/the-making-of-the-aptos-gas-schedule-508d5686a350).

## Instruction gas

[](#instruction-gas)

Basic instruction gas parameters are defined at [`instr.rs`](https://github.com/aptos-labs/aptos-core/blob/main/aptos-move/aptos-gas-schedule/src/gas_schedule/instr.rs) and include the following instruction types:

### No-operation

[](#no-operation)

| Parameter | Meaning | | --------- | -------------- | | `nop` | A no-operation |

### Control flow

[](#control-flow)

| Parameter | Meaning | | ---------- | -------------------------------- | | `ret` | Return | | `abort` | Abort | | `br_true` | Execute conditional true branch | | `br_false` | Execute conditional false branch | | `branch` | Branch |

### Stack

[](#stack)

| Parameter | Meaning | | ------------------- | -------------------------------- | | `pop` | Pop from stack | | `ld_u8` | Load a `u8` | | `ld_u16` | Load a `u16` | | `ld_u32` | Load a `u32` | | `ld_u64` | Load a `u64` | | `ld_u128` | Load a `u128` | | `ld_256` | Load a `u256` | | `ld_true` | Load a `true` | | `ld_false` | Load a `false` | | `ld_const_base` | Base cost to load a constant | | `ld_const_per_byte` | Per-byte cost to load a constant |

### Local scope

[](#local-scope)

| Parameter | Meaning | | --------------------------- | ------------------------ | | `imm_borrow_loc` | Immutably borrow | | `mut_borrow_loc` | Mutably borrow | | `imm_borrow_field` | Immutably borrow a field | | `mut_borrow_field` | Mutably borrow a field | | `imm_borrow_field_generic` | | | `mut_borrow_field_generic` | | | `copy_loc_base` | Base cost to copy | | `copy_loc_per_abs_val_unit` | | | `move_loc_base` | Move | | `st_loc_base` | |

### Calling

[](#calling)

| Parameter | Meaning | | ------------------------- | ------------------------------- | | `call_base` | Base cost for a function call | | `call_per_arg` | Cost per function argument | | `call_per_local` | Cost per local argument | | `call_generic_base` | | | `call_generic_per_ty_arg` | Cost per type argument | | `call_generic_per_arg` | | | `call_generic_per_local` | Cost generic per local argument |

### Structs

[](#structs)

| Parameter | Meaning | | -------------------------- | ------------------------------------ | | `pack_base` | Base cost to pack a `struct` | | `pack_per_field` | Cost to pack a `struct`, per field | | `pack_generic_base` | | | `pack_generic_per_field` | | | `unpack_base` | Base cost to unpack a `struct` | | `unpack_per_field` | Cost to unpack a `struct`, per field | | `unpack_generic_base` | | | `unpack_generic_per_field` | |

### References

[](#references)

| Parameter | Meaning | | --------------------------- | ---------------------------------- | | `read_ref_base` | Base cost to read from a reference | | `read_ref_per_abs_val_unit` | | | `write_ref_base` | Base cost to write to a reference | | `freeze_ref` | Freeze a reference |

### Casting

[](#casting)

| Parameter | Meaning | | ----------- | ---------------- | | `cast_u8` | Cast to a `u8` | | `cast_u16` | Cast to a `u16` | | `cast_u32` | Cast to a `u32` | | `cast_u64` | Cast to a `u64` | | `cast_u128` | Cast to a `u128` | | `cast_u256` | Cast to a `u256` |

### Arithmetic

[](#arithmetic)

| Parameter | Meaning | | --------- | -------- | | `add` | Add | | `sub` | Subtract | | `mul` | Multiply | | `mod_` | Modulo | | `div` | Divide |

### Bitwise

[](#bitwise)

| Parameter | Meaning | | --------- | ----------------- | | `bit_or` | `OR`: `\|` | | `bit_and` | `AND`: `&` | | `xor` | `XOR`: `^` | | `shl` | Shift left: `<<` | | `shr` | Shift right: `>>` |

### Boolean

[](#boolean)

| Parameter | Meaning | | --------- | ------------ | | `or` | `OR`: `\|\|` | | `and` | `AND`: `&&` | | `not` | `NOT`: `!` |

### Comparison

[](#comparison)

| Parameter | Meaning | | ---------------------- | ------------------------------ | | `lt` | Less than: `<` | | `gt` | Greater than: `>` | | `le` | Less than or equal to: `<=` | | `ge` | Greater than or equal to: `>=` | | `eq_base` | Base equality cost: `==` | | `eq_per_abs_val_unit` | | | `neq_base` | Base not equal cost: `!=` | | `neq_per_abs_val_unit` | |

### Global storage

[](#global-storage)

| Parameter | Meaning | | -------------------------------- | ----------------------------------------------------- | | `imm_borrow_global_base` | Base cost to immutably borrow: `borrow_global<T>()` | | `imm_borrow_global_generic_base` | | | `mut_borrow_global_base` | Base cost to mutably borrow: `borrow_global_mut<T>()` | | `mut_borrow_global_generic_base` | | | `exists_base` | Base cost to check existence: `exists<T>()` | | `exists_generic_base` | | | `move_from_base` | Base cost to move from: `move_from<T>()` | | `move_from_generic_base` | | | `move_to_base` | Base cost to move to: `move_to<T>()` | | `move_to_generic_base` | |

### Vectors

[](#vectors)

| Parameter | Meaning | | ------------------------------ | ---------------------------------------- | | `vec_len_base` | Length of a vector | | `vec_imm_borrow_base` | Immutably borrow an element | | `vec_mut_borrow_base` | Mutably borrow an element | | `vec_push_back_base` | Push back | | `vec_pop_back_base` | Pop from the back | | `vec_swap_base` | Swap elements | | `vec_pack_base` | Base cost to pack a vector | | `vec_pack_per_elem` | Cost to pack a vector per element | | `vec_unpack_base` | Base cost to unpack a vector | | `vec_unpack_per_expected_elem` | Base cost to unpack a vector per element |

Additional storage gas parameters are defined in [`table.rs`](https://github.com/aptos-labs/aptos-core/blob/main/aptos-move/aptos-gas-schedule/src/gas_schedule/table.rs), [`move_stdlib.rs`](https://github.com/aptos-labs/aptos-core/blob/main/aptos-move/aptos-gas-schedule/src/gas_schedule/move_stdlib.rs), and other assorted source files in [`aptos-gas-schedule/src/`](https://github.com/aptos-labs/aptos-core/blob/main/aptos-move/aptos-gas-schedule/src).

## IO and Storage charges

[](#io-and-storage-charges)

The following gas parameters are applied (i.e., charged) to represent the costs associated with transient storage device resources, including disk IOPS and bandwidth:

In Move, one can read from the global state:

| Parameter | Meaning | | ----------------------------------- | ----------------------------------------- | | storage\_io\_per\_state\_slot\_read | charged per item loaded from global state | | storage\_io\_per\_state\_byte\_read | charged per byte loaded from global state |

For a committed transaction, various things will be written to the ledger history. Notice that the ledger history is subject to pruning and doesn't occupy permanent space on the disk, hence no storage fee charged for it.

| Parameter | Meaning | | ------------------------------------------ | ----------------------------------------------------------------------------------- | | storage\_io\_per\_state\_slot\_write | charged per state write operation in the transaction output | | storage\_io\_per\_state\_byte\_write | charged per byte in all state write ops in the transaction output | | storage\_io\_per\_event\_byte\_write | charged per byte in all events in the transaction output | | storage\_io\_per\_transaction\_byte\_write | charged per byte in the transaction itself which is also part of the ledger history |

The following storage fee parameters are applied (i.e., charged in absolute APT values) to represent the disk space and structural costs associated with using the [Aptos authenticated data structure](/network/glossary#merkle-trees) for storing items on the blockchain.

| Parameter | Meaning | | -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | storage\_fee\_per\_state\_slot\_create | allocating a state slot, by `move_to()`, `table::add()`, etc | | storage\_fee\_per\_state\_byte | Notice this is charged every time the slot grows in size, not only at allocation time. (However, for simplicity, refunding is only at deletion time. See [AIP-65](https://github.com/aptos-foundation/AIPs/blob/main/aips/aip-65.md#specification)) |

### Vectors

[](#vectors-1)

Byte-wise fees are similarly assessed on vectors, which consume ∑\_i\=0n−1e\_i+b(n)\\sum\\\_{i = 0}^{n - 1} e\\\_i + b(n)∑\_i\=0n−1e\_i+b(n) bytes, where:

*   nnn is the number of elements in the vector
*   e\_ie\\\_ie\_i is the size of element iii
*   b(n)b(n)b(n) is a "base size" which is a function of nnn

See the [BCS sequence specification](https://github.com/diem/bcs#fixed-and-variable-length-sequences) for more information on vector base size (technically a `ULEB128`), which typically occupies just one byte in practice, such that a vector of 100 `u8` elements accounts for 100+1\=101100 + 1 = 101100+1\=101 bytes. Hence, per the item-wise read methodology described above, reading the last element of such a vector is treated as a 101-byte read.

## Payload gas

[](#payload-gas)

Payload gas is defined in [`transaction.rs`](https://github.com/aptos-labs/aptos-core/blob/main/aptos-move/aptos-gas-schedule/src/gas_schedule/transaction.rs), which incorporates storage gas with several payload- and pricing-associated parameters:

| Parameter | Meaning | | ------------------------------- | -------------------------------------------------------------------------------------- | | `min_transaction_gas_units` | Minimum internal gas units for a transaction, charged at the start of execution | | `large_transaction_cutoff` | Size, in bytes, above which transactions will be charged an additional amount per byte | | `intrinsic_gas_per_byte` | Internal gas units charged per byte for payloads above `large_transaction_cutoff` | | `maximum_number_of_gas_units` | Upper limit on external gas units for a transaction | | `min_price_per_gas_unit` | Minimum gas price allowed for a transaction | | `max_price_per_gas_unit` | Maximum gas price allowed for a transaction | | `max_transaction_size_in_bytes` | Maximum transaction payload size in bytes | | `gas_unit_scaling_factor` | Conversion factor between internal gas units and external gas units |

Here, "internal gas units" are defined as constants in source files like [`instr.rs`](https://github.com/aptos-labs/aptos-core/blob/main/aptos-move/aptos-gas-schedule/src/gas_schedule/instr.rs) and [`storage_gas.move`](https://github.com/aptos-labs/aptos-core/blob/main/aptos-move/framework/aptos-framework/sources/storage_gas.move), which are more granular than "external gas units" by a factor of `gas_unit_scaling_factor`: to convert from internal gas units to external gas units, divide by `gas_unit_scaling_factor`. Then, to convert from external gas units to [octas](/network/glossary#octa), multiply by the "gas price", which denotes the number of octas per unit of external gas.

## Optimization principles

[](#optimization-principles)

### Unit and pricing constants

[](#unit-and-pricing-constants)

As of the time of this writing, `min_price_per_gas_unit` in [`transaction.rs`](https://github.com/aptos-labs/aptos-core/blob/main/aptos-move/aptos-gas-schedule/src/gas_schedule/transaction.rs) is defined as [`aptos_global_constants`](https://github.com/aptos-labs/aptos-core/blob/main/config/global-constants/src/lib.rs)`::GAS_UNIT_PRICE` (which is itself defined as 100), with other noteworthy [`transaction.rs`](https://github.com/aptos-labs/aptos-core/blob/main/aptos-move/aptos-gas-schedule/src/gas_schedule/transaction.rs) constants as follows:

| Constant | Value | | ------------------------- | -------------- | | `min_price_per_gas_unit` | 100 | | `max_price_per_gas_unit` | 10,000,000,000 | | `gas_unit_scaling_factor` | 1,000,000 |

See [Payload gas](#payload-gas) for the meaning of these constants.

### Storage Fee

[](#storage-fee)

When the network load is low, the gas unit price is expected to be low, making most aspects of the transaction cost more affordable. However, the storage fee is an exception, as it's priced in terms of absolute APT value. In most instances, the transaction fee is the predominant component of the overall transaction cost. This is especially true when a transaction allocates state slots, writes to sizable state items, emits numerous or large events, or when the transaction itself is a large one. All of these factors consume disk space on Aptos nodes and are charged accordingly.

On the other hand, the storage refund incentivizes releasing state slots by deleting state items. The state slot fee is fully refunded upon slot deallocation, while the excess state byte fee is non-refundable. This will soon change by differentiating between permanent bytes (those in the global state) and relative ephemeral bytes (those that traverse the ledger history).

Some cost optimization strategies concerning the storage fee:

1.  Minimize state item creation.
2.  Minimize event emissions.
3.  Avoid large state items, events, and transactions.
4.  Clean up state items that are no longer in use.
5.  If two fields are consistently updated together, group them into the same resource or resource group.
6.  If a struct is large and only a few fields are updated frequently, move those fields to a separate resource or resource group.

### Instruction gas

[](#instruction-gas-1)

As of the time of this writing, all instruction gas operations are multiplied by the `EXECUTION_GAS_MULTIPLIER` defined in [`meter.rs`](https://github.com/aptos-labs/aptos-core/blob/main/aptos-move/aptos-gas-meter/src/meter.rs), which is set to 20. Hence, the following representative operations assume gas costs as follows (divide internal gas by scaling factor, then multiply by minimum gas price):

| Operation | Minimum [Octas](/network/glossary#octa) | | ---------------------------- | --------------------------------------- | | Table add/borrow/remove box | 240 | | Function call | 200 | | Load constant | 130 | | Globally borrow | 100 | | Read/write reference | 40 | | Load `u128` on stack | 16 | | Table box operation per byte | 2 |

(Note that per-byte table box operation instruction gas does not account for storage gas, which is assessed separately).

For comparison, reading a 100-byte item costs r\_i+100\\\*r\_b\=3000+100\\\*3\=3300r\\\_i + 100 \\\* r\\\_b = 3000 + 100 \\\* 3 = 3300r\_i+100\\\*r\_b\=3000+100\\\*3\=3300 [octas](/network/glossary#octa) at minimum, some 16.5 times as much as a function call, and in general, instruction gas costs are largely dominated by storage gas costs.

Notably, however, there is still technically an incentive to reduce the number of function calls in a program, but engineering efforts are more effectively dedicated to writing modular, decomposed code that is geared toward reducing storage gas costs, rather than attempting to write repetitive code blocks with fewer nested functions (in nearly all cases).

In extreme cases it is possible for instruction gas to far outweigh storage gas, for example if a looping mathematical function takes 10,000 iterations to converge; but again this is an extreme case and for most applications storage gas has a larger impact on base gas than does instruction gas.

### Payload gas

[](#payload-gas-1)

As of the time of this writing, [`transaction/mod.rs`](https://github.com/aptos-labs/aptos-core/blob/main/aptos-move/aptos-gas-schedule/src/gas_schedule/transaction.rs) defines the minimum amount of internal gas per transaction as 1,500,000 internal units (15,000 [octas](/network/glossary#octa) at minimum), an amount that increases by 2,000 internal gas units (20 octas minimum) per byte for payloads larger than 600 bytes, with the maximum number of bytes permitted in a transaction set at 65536. Hence, in practice, payload gas is unlikely to be a concern.

# Aptos Blockchain Deep Dive

> Take a comprehensive deep dive into Aptos blockchain architecture, transaction lifecycle, node components, and inter-component interactions for developers.

For a deeper understanding of the lifecycle of an Aptos transaction (from an operational perspective), we will follow a transaction on its journey, from being submitted to an Aptos fullnode, to being committed to the Aptos blockchain. We will then focus on the logical components of Aptos nodes and take a look at how the transaction interacts with these components.

## Life of a Transaction

[](#life-of-a-transaction)

*   Alice and Bob are two users who each have an [account](/network/glossary#account) on the Aptos blockchain.
*   Alice's account has 110 Aptos Coins.
*   Alice is sending 10 Aptos Coins to Bob.
*   The current [sequence number](/network/glossary#sequence-number) of Alice's account is 5 (which indicates that 5 transactions have already been sent from Alice's account).
*   There are a total of 100 validator nodes — V1 to V100 on the network.
*   An Aptos client submits Alice's transaction to a REST service on an Aptos Fullnode. The fullnode forwards this transaction to a validator fullnode which in turn forwards it to validator V1.
*   Validator V1 is a proposer/leader for the current round.

### The Journey

[](#the-journey)

In this section, we will describe the lifecycle of transaction T5, from when the client submits it to when it is committed to the Aptos blockchain.

For the relevant steps, we've included a link to the corresponding inter-component interactions of the validator node. After you are familiar with all the steps in the lifecycle of the transaction, you may want to refer to the information on the corresponding inter-component interactions for each step.

graph LR
    subgraph Fullnodes
        direction TB
        REST\_Service\[REST Service\]
    end

Client(Client) -->|1| REST\_Service

subgraph Other\_Validators\[Other Validators\]
        direction TB
    end

subgraph Validators
        direction TB
        Mempool\[Mempool\]
        Consensus\[Consensus\]
        Consensus -->|7, 9| Execution
        Execution -->|11| Storage
        Execution -->|8| Virtual\_Machine(Virtual Machine)
        Mempool --> Virtual\_Machine
        Virtual\_Machine --> Storage
    end

Other\_Validators <-->|6, 10| Consensus
    REST\_Service -->|2, 3| Mempool
    Mempool <-->|4| Other\_Validators(Other Validators)
    Consensus -->|5| Mempool

Note

The arrows in all the visuals in this article originate on the component initiating an interaction/action and terminate on the component on which the action is being performed. The arrows do not represent data read, written, or returned.

The lifecycle of a transaction has five stages:

*   **Accepting**: [Accepting the transaction](#accepting-the-transaction)
*   **Sharing**: [Sharing the transaction with other validator nodes](#sharing-the-transaction-with-other-validator-nodes)
*   **Proposing**: [Proposing the block](#proposing-the-block)
*   **Executing and Consensus**: [Executing the block and reaching consensus](#executing-the-block-and-reaching-consensus)
*   **Committing**: [Committing the block](#committing-the-block)

We've described what happens in each stage below, along with links to the corresponding Aptos node component interactions.

Caution

Transactions are validated upon entering a mempool and prior to execution by consensus. The client only learns of validation results returned during the initial submission via the REST service. Transactions may silently fail to execute, especially in the case where the account has run out of utility token or changed its authentication key in the midst of many transactions. While this happens infrequently, there are ongoing efforts to improve the visibility in this space.

### Client submits a transaction

[](#client-submits-a-transaction)

An Aptos **client constructs a raw transaction** (let's call it Traw5) to transfer 10 Aptos Coins from Alice’s account to Bob’s account. The Aptos client signs the transaction with Alice's private key. The signed transaction T5 includes the following:

*   The raw transaction.
*   Alice's public key.
*   Alice's signature.

The raw transaction includes the following fields:

| Fields | Description | | ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | [Account address](/network/glossary#account-address) | Alice's account address | | Payload | Indicates an action or set of actions Alice's behalf. In the case this is a Move function, it directly calls into Move bytecode on the chain. Alternatively, it may be Move bytecode peer-to-peer [transaction script](/network/glossary#transaction-script). It also contains a list of inputs to the function or script. For this example, it is a function call to transfer an amount of Aptos Coins from Alice account to Bob's account, where Alice's account is implied by sending the transaction and Bob's account and the amount are specified as transaction inputs. | | [Gas unit price](/network/glossary#gas-unit-price) | The amount the sender is willing to pay per unit of gas, to execute the transaction. This is represented in [Octas](/network/glossary#octa). | | [Maximum gas amount](/network/glossary#maximum-gas-amount) | The maximum gas amount in APT Alice is willing to pay for this transaction. Gas charges are equal to the base gas cost covered by computation and IO multiplied by the gas price. Gas costs also include storage with an Apt-fixed priced storage model. This is represented in [Octas](/network/glossary#octa). | | [Expiration time](/network/glossary#expiration-time) | Expiration time of the transaction. | | [Sequence number](/network/glossary#sequence-number) | The sequence number (5, in this example) for an account indicates the number of transactions that have been submitted and committed on-chain from that account. In this case, 5 transactions have been submitted from Alice’s account, including Traw5. Note: a transaction with sequence number 5 can only be committed on-chain if the account sequence number is 5. | | [Chain ID](https://github.com/aptos-labs/aptos-core/blob/main/types/src/chain_id.rs) | An identifier that distinguishes the Aptos networks (to prevent cross-network attacks). |

### Accepting the transaction

[](#accepting-the-transaction)

### Sharing the transaction with other validator nodes

[](#sharing-the-transaction-with-other-validator-nodes)

### Proposing the block

[](#proposing-the-block)

### Executing the block and reaching consensus

[](#executing-the-block-and-reaching-consensus)

| Description | Aptos Node Component Interactions | | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | | 8. **Consensus → Execution**: As part of reaching agreement, the block of transactions (containing T5) is shared with the execution component. | [3\. Consensus](#3-consensus--execution-consensus--other-validators), [1\. Execution](#1-consensus--execution) | | 9. **Execution → Virtual Machine**: The execution component manages the execution of transactions in the VM. Note that this execution happens speculatively before the transactions in the block have been agreed upon. | [2\. Execution](#2-execution--vm), [3\. Virtual Machine](#3-mempool--virtual-machine) | | 10. **Consensus → Execution**: After executing the transactions in the block, the execution component appends the transactions in the block (including T5) to the [Merkle accumulator](/network/glossary#merkle-accumulator) (of the ledger history). This is an in-memory/temporary version of the Merkle accumulator. The necessary part of the proposed/speculative result of executing these transactions is returned to the consensus component to agree on. The arrow from "consensus" to "execution" indicates that the request to execute transactions was made by the consensus component. | [3\. Consensus](#3-consensus--execution-consensus--other-validators), [1\. Execution](#1-consensus--execution) | | 11. **Consensus → Other Validators**: V1 (the consensus leader) attempts to reach consensus on the proposed block's execution result with the other validator nodes participating in consensus. | [3\. Consensus](#3-consensus--execution-consensus--other-validators) |

### Committing the block

[](#committing-the-block)

Alice's account will now have 100 Aptos Coins, and its sequence number will be 6. If T5 is replayed by Bob, it will be rejected as the sequence number of Alice's account (6) is greater than the sequence number of the replayed transaction (5).

## Aptos node component interactions

[](#aptos-node-component-interactions)

In the [Life of a Transaction](#life-of-a-transaction) section, we described the typical lifecycle of a transaction (from transaction submission to transaction commit). Now let's look at the inter-component interactions of Aptos nodes as the blockchain processes transactions and responds to queries. This information will be most useful to those who:

*   Would like to get an idea of how the system works under the covers.
*   Are interested in eventually contributing to the Aptos blockchain.

You can learn more about the different types of Aptos nodes here:

*   [Validator nodes](/network/blockchain/validator-nodes)
*   [Fullnodes](/network/blockchain/fullnodes)

For our narrative, we will assume that a client submits a transaction TN to a validator VX. For each validator component, we will describe each of its inter-component interactions in subsections under the respective component's section. Note that subsections describing the inter-component interactions are not listed strictly in the order in which they are performed. Most of the interactions are relevant to the processing of a transaction, and some are relevant to clients querying the blockchain (queries for existing information on the blockchain).

The following are the core components of an Aptos node used in the lifecycle of a transaction:

**Fullnode**

*   [REST API Service](#rest-service)

**Validator node**

*   [Mempool](#mempool)
*   [Consensus](#consensus)
*   [Execution](#execution)
*   [Virtual Machine](#virtual-machine-vm)
*   [Storage](#storage)

## REST Service

[](#rest-service)

graph LR
    Client -->|1| REST\_Service\[REST Service\]
    REST\_Service -->|2| Mempool
    REST\_Service -->|3| Storage

Any request made by a client goes to the REST Service of a fullnode first. Then, the submitted transaction is forwarded to the validator fullnode, which then sends it to the validator node VX.

### 1\. Client → REST Service

[](#1-client--rest-service)

A client submits a transaction to the REST service of an Aptos fullnode.

### 2\. REST Service → Mempool

[](#2-rest-service--mempool)

The REST service of the fullnode transfers the transaction to its mempool. After mempool does some initial checks, the REST Service will return a status to the client indicating whether the transaction was accepted or rejected. For example, out-of-date transactions will be rejected: mempool will accept the transaction TN only if the sequence number of TN is greater than or equal to the current sequence number of the sender's account.

### 3\. Mempool -> Mempool

[](#3-mempool---mempool)

The mempool on the fullnode sends the transaction to the mempool of a validator fullnode, which then sends the transaction to validator node VX's mempool. Note that the transaction will not be sent to the next mempool (or passed to consensus) until the sequence number matches the sequence number of the sender’s account. Furthermore, each mempool performs the same initial checks upon receiving a transaction, this may result in a transaction being discarded on its way to consensus. The current implementation of mempool does not provide any feedback if a transaction is discarded during this process.

### 4\. REST Service → Storage

[](#4-rest-service--storage)

When a client performs a read query on the Aptos blockchain (for example, to get the balance of Alice's account), the REST service interacts with the storage component directly to obtain the requested information.

## Virtual Machine (VM)

[](#virtual-machine-vm)

graph LR
    Mempool -->|3| Virtual\_Machine\[Virtual Machine\]
    Virtual\_Machine -->|2| Execution
    Virtual\_Machine -->|1| Storage

The Move VM verifies and executes transaction scripts written in Move bytecode.

### 1\. Virtual Machine → Storage

[](#1-virtual-machine--storage)

When mempool requests the VM to validate a transaction via `VMValidator::validate_transaction()`, the VM loads the transaction sender's account from storage and performs verifications, some of which have been described in the list below.

*   Checks that the input signature on the signed transaction is correct (to reject incorrectly signed transactions).
*   Checks that the sender's account authentication key is the same as the hash of the public key (corresponding to the private key used to sign the transaction).
*   Verifies that the sequence number for the transaction is greater than or equal to the current sequence number for the sender's account. Completing this check prevents the replay of the same transaction against the sender's account.
*   Verifies that the program in the signed transaction is not malformed, as a malformed program cannot be executed by the VM.
*   Verifies that the sender's account balance contains at least the maximum gas amount multiplied by the gas price specified in the transaction, which ensures that the transaction can pay for the resources it uses.

### 2\. Execution → Virtual Machine

[](#2-execution--virtual-machine)

The execution component utilizes the VM to execute a transaction via `ExecutorTask::execute_transaction()`.

It is important to understand that executing a transaction is different from updating the state of the ledger and persisting the results in storage. A transaction TN is first executed as part of an attempt to reach agreement on blocks during consensus. If agreement is reached with the other validators on the ordering of transactions and their execution results, the results are persisted in storage and the state of the ledger is updated.

### 3\. Mempool → Virtual Machine

[](#3-mempool--virtual-machine)

When mempool receives a transaction from other validators via shared mempool or from the REST service, mempool invokes `VMValidator::validate_transaction()` on the VM to validate the transaction.

For implementation details refer to the [Move Virtual Machine README](https://github.com/move-language/move/tree/main/language/move-vm).

## Mempool

[](#mempool)

graph LR
    Mempool -->|2| Other\_Validators\[Other Validators\]

subgraph Fullnodes
        REST\_Service\[REST Service\]
        Mempool\[Mempool\]
        Consensus\[Consensus\]
        Virtual\_Machine\[Virtual Machine\]
    end

REST\_Service -->|1| Mempool
    Mempool -->|3| Consensus
    Mempool -->|4| Virtual\_Machine

Mempool is a shared buffer that holds the transactions that are "waiting" to be executed. When a new transaction is added to the mempool, the mempool shares this transaction with other validator nodes in the system. To reduce network consumption in the "shared mempool," each validator is responsible for delivering its own transactions to other validators. When a validator receives a transaction from the mempool of another validator, the transaction is added to the mempool of the recipient validator.

### 1\. REST Service → Mempool

[](#1-rest-service--mempool)

*   After receiving a transaction from the client, the REST service sends the transaction to its own mempool, which then shares the transaction with the mempool of a validator fullnode. The mempool on the validator fullnode then shares the transaction with the mempool of a validator.
*   The mempool for validator node VX accepts transaction TN for the sender's account only if the sequence number of TN is greater than or equal to the current sequence number of the sender's account.

### 2\. Mempool → Other validator nodes

[](#2-mempool--other-validator-nodes)

*   The mempool of validator node VX shares transaction TN with the other validators on the same network.
*   Other validators share the transactions in their respective mempools with VX’s mempool.

### 3\. Consensus → Mempool

[](#3-consensus--mempool)

*   When the transaction is forwarded to a validator node and once the validator node becomes the leader, its consensus component will pull a block of transactions from its mempool and replicate the proposed block to other validators. It does this to arrive at a consensus on the ordering of transactions and the execution results of the transactions in the proposed block.
*   Note that just because a transaction TN was included in a proposed consensus block, it does not guarantee that TN will eventually be persisted in the distributed database of the Aptos blockchain.

### 4\. Mempool → VM

[](#4-mempool--vm)

When mempool receives a transaction from other validators, mempool invokes `VMValidator::validate_transaction()` on the VM to validate the transaction.

## Consensus

[](#consensus)

graph TD
    subgraph Validators
        direction LR
            Consensus\[Consensus\] -->|1| Mempool\[Mempool\]
            Consensus -->|3, 4| Execution\[Execution\]
    end

Other\_Validators(Other Validators) <-->|2, 4| Consensus

The consensus component is responsible for ordering blocks of transactions and agreeing on the results of execution by participating in the [consensus protocol](/network/glossary#consensus-protocol) with other validators in the network.

### 1\. Consensus → Mempool

[](#1-consensus--mempool)

When validator VX is a leader/proposer, the consensus component of VX pulls a block of transactions from its mempool via: `Mempool::get_batch()`, and forms a proposed block of transactions.

### 2\. Consensus → Other Validators

[](#2-consensus--other-validators)

If VX is a proposer/leader, its consensus component replicates the proposed block of transactions to other validators.

### 3\. Consensus → Execution, Consensus → Other Validators

[](#3-consensus--execution-consensus--other-validators)

*   To execute a block of transactions, consensus interacts with the execution component. Consensus executes a block of transactions via `BlockExecutorTrait::execute_block()` (Refer to [Consensus → execution](#1-consensus--execution))
*   After executing the transactions in the proposed block, the execution component responds to the consensus component with the result of executing these transactions.
*   The consensus component signs the execution result and attempts to reach agreement on this result with other validators.

### 4\. Consensus → Execution

[](#4-consensus--execution)

If enough validators vote for the same execution result, the consensus component of VX informs execution via `BlockExecutorTrait::commit_blocks()` that this block is ready to be committed.

## Execution

[](#execution)

graph TD
    Consensus\[Consensus\] -->|1 and 3| Execution\[Execution\]
    Execution -->|2| Virtual\_Machine\[Virtual Machine\]
    Execution -->|4| Storage\[Storage\]

The execution component coordinates the execution of a block of transactions and maintains a transient state that can be voted upon by consensus. If these transactions are successful, they are committed to storage.

### 1\. Consensus → Execution

[](#1-consensus--execution)

*   Consensus requests execution to execute a block of transactions via: `BlockExecutorTrait::execute_block()`.
*   Execution maintains a "scratchpad," which holds in-memory copies of the relevant portions of the [Merkle accumulator](/network/glossary#merkle-accumulator). This information is used to calculate the root hash of the current state of the Aptos blockchain.
*   The root hash of the current state is combined with the information about the transactions in the proposed block to determine the new root hash of the accumulator. This is done prior to persisting any data, and to ensure that no state or transaction is stored until agreement is reached by a quorum of validators.
*   Execution computes the speculative root hash and then the consensus component of VX signs this root hash and attempts to reach agreement on this root hash with other validators.

### 2\. Execution → VM

[](#2-execution--vm)

When consensus requests execution to execute a block of transactions via `BlockExecutorTrait::execute_block()`, execution uses the VM to determine the results of executing the block of transactions.

### 3\. Consensus → Execution

[](#3-consensus--execution)

If a quorum of validators agrees on the block execution results, the consensus component of each validator informs its execution component via `BlockExecutorTrait::commit_blocks()` that this block is ready to be committed. This call to the execution component will include the signatures of the validators to provide proof of their agreement.

### 4\. Execution → Storage

[](#4-execution--storage)

Execution takes the values from its "scratchpad" and sends them to storage for persistence via `DbWriter::save_transactions()`. Execution then prunes the old values from the "scratchpad" that are no longer needed (for example, parallel blocks that cannot be committed).

For implementation details refer to the [Execution README](https://github.com/aptos-labs/aptos-core/tree/main/execution).

## Storage

[](#storage)

graph TD
    Virtual\_Machine\[Virtual Machine\] -->|1| Storage\[Storage\]
    Execution\[Execution\] -->|2, 3| Storage
    REST\_Service\[REST Service\] -->|4| Storage

The storage component persists agreed upon blocks of transactions and their execution results to the Aptos blockchain. A block of transactions (which includes transaction TN) will be saved via storage when there is agreement between more than a quorum (2f+1) of the validators participating in consensus. Agreement must include all the following:

*   The transactions to include in the block
*   The order of the transactions
*   The execution results of the transactions in the block

Refer to [Merkle accumulator](/network/glossary#merkle-accumulator) for information on how a transaction is appended to the data structure representing the Aptos blockchain.

### 1\. VM → Storage

[](#1-vm--storage)

When mempool invokes `VMValidator::validate_transaction()` to validate a transaction, `VMValidator::validate_transaction()` loads the sender's account from storage and performs read-only validity checks on the transaction.

### 2\. Execution → Storage

[](#2-execution--storage)

When the consensus component calls `BlockExecutorTrait::execute_block()`, execution reads the current state from storage combined with the in-memory "scratchpad" data to determine the execution results.

### 3\. Execution → Storage

[](#3-execution--storage)

Once consensus is reached on a block of transactions, execution calls storage via `DbWriter::save_transactions()` to save the block of transactions and permanently record them. This will also store the signatures from the validator nodes that agreed on this block of transactions. The in-memory data in "scratchpad" for this block is passed to update storage and persist the transactions. When the storage is updated, every account that was modified by these transactions will have its sequence number incremented by one.

Note: The sequence number of an account on the Aptos blockchain increments by one for each committed transaction originating from that account.

### 4\. REST Service → Storage

[](#4-rest-service--storage-1)

For client queries that read information from the blockchain, the REST service directly interacts with storage to read the requested information.

For implementation details refer to the [Storage README](https://github.com/aptos-labs/aptos-core/tree/main/storage).

# Blocks

> Understand blocks on Aptos, including their role in the versioned database, system transactions, epochs, and how they structure blockchain data.

Aptos is a per-transaction versioned database. When transactions are executed, the resulting state of each transaction is stored separately and thus allows for more granular data access. This is different from other blockchains where only the resulting state of a block (a group of transactions) is stored.

Blocks are still a fundamental unit within Aptos. Transactions are batched and executed together in a block. In addition, the [proofs](/network/blockchain/txns-states#proofs) within storage are at the block-level granularity. The number of transactions within a block varies depending on network activity and a configurable maximum block size limit. As the blockchain becomes busier, blocks will likely contain more transactions.

## System transactions

[](#system-transactions)

Each Aptos block contains both user transactions and special system transactions to _mark_ the beginning and end of the transaction batch. Specifically, there are two system transactions:

1.  `BlockMetadataTransaction` - is inserted at the beginning of the block. A `BlockMetadata` transaction can also mark the end of an [epoch](#epochs) and trigger reward distribution to validators.
2.  `StateCheckpointTransaction` - is appended at the end of the block and is used as a checkpoint milestone.

## Epochs

[](#epochs)

In Aptos, epochs represent a longer period of time in order to safely synchronize major changes such as validator set additions/removals. An epoch is a fixed duration of time, currently defined as two hours on mainnet. The number of blocks in an epoch depends on how many blocks can execute within this period of time. It is only at the start of a new epoch that major changes such as a validator joining the validator set take effect among the validators.

# Delegated Staking

> Learn about delegated staking on Aptos, delegation pools, the owner-operator-voter-delegator model, and how to participate in staking without running a validator.

Note

We strongly recommend that you read about [Staking](/network/blockchain/staking) first.

Delegated staking is an extension of the staking protocol. A delegation pool abstracts the stake owner to an entity capable of collecting stake from delegators and adding it on their behalf to the native stake pool attached to the validator. This allows multiple entities to form a stake pool that achieves the minimum requirements for the validator to join the validator set. While delegators can add stake to an inactive pool, the delegation pool will not earn rewards until it is active.

Caution

Delegation pools are permissionless and anyone can add stake. Delegation pools cannot be changed to stake pools once it's created or vice versa, though it can be removed from the validator set and assets withdrawn. For full details of the stake pool, see [Staking](/network/blockchain/staking)

For the full delegation pool smart contract, see [delegation\_pool.move](https://github.com/aptos-labs/aptos-core/blob/main/aptos-move/framework/aptos-framework/sources/delegation_pool.move)

Unlike a stake pool, a delegation pool can be initialized with zero stake. When initialized, the delegated stake pool is owned indirectly via a resource account. This account will manage the stake of the underlying stake pool on behalf of the delegators by forwarding their stake-management operations to it (add, unlock, reactivate, withdraw) while the resource account cannot be directly accessed nor externally owned.

See full list of [Delegation Pool Operations](/network/nodes/validator-node/connect-nodes/delegation-pool-operations)

![Delegated Staking](/_vercel/image?url=_astro%2Fdelegated-staking.Bj_XMVmf.png&w=640&q=100&dpl=dpl_BVzupKm7aQfXg1N3qg98Mi3YEbWs)

There are five entity types:

*   Owner
*   Operator
*   Voter
*   Delegator
*   Beneficiary

Using this model, the owner does not have to stake on the Aptos blockchain in order to run a validator.

[How Validation on the Aptos blockchain works](/network/blockchain/staking#validation-on-the-aptos-blockchain)

### Owner

[](#owner)

The delegation pool owner has the following capabilities:

1.  Creates delegation pool
2.  Assigns operator for the delegation pool
3.  Sets operator commission percentage for the delegation pool
4.  Assigns voter for the delegation pool

### Operator

[](#operator)

A node operator is assigned by the pool owner to run the validator node. The operator has the following capabilities:

1.  Join or leave the validator set once the delegation pool reaches 1M APT
2.  Perform validating functions
3.  Change the consensus key and network addresses. The consensus key is used to participate in the validator consensus process, i.e., to vote and propose a block. The operator is allowed to change ("rotate") this key in case this key is compromised.

The operator receives commission that is distributed automatically at the end of each epoch as rewards.

### Voter

[](#voter)

An owner can designate a voter. This enables the voter to participate in governance. The voter will use the voter key to sign the governance votes in the transactions.

Note

This document describes staking. See [Governance](/network/blockchain/governance) for how to participate in the Aptos on-chain governance using the owner-voter model.

### Delegator

[](#delegator)

A delegator is anyone who has stake in the delegation pool. Delegators earn rewards on their stake minus any commissions for the operator. Delegators can perform the following delegator operations:

1.  Add stake
2.  Unlock stake
3.  Reactivate stake
4.  Withdraw stake

### Beneficiary

[](#beneficiary)

A beneficiary is an address designated by the operator to receive operator commission rewards. Key aspects of the beneficiary role:

1.  Each operator can set only one beneficiary address across all their delegation pools
2.  The beneficiary can perform operations like unlock and withdraw for earned commission
3.  When changing beneficiaries, any unpaid commission rewards will go to the new beneficiary
4.  The operator can set or change the beneficiary using the `set_beneficiary_for_operator` function

## Validator flow

[](#validator-flow)

Note

See [Delegation pool operations](/network/nodes/validator-node/connect-nodes/delegation-pool-operations) for the correct sequence of commands to run for the below flow.

1.  [Operator deploys validator node](/network/nodes/validator-node)
2.  [Run command to get delegation pool address](/network/nodes/validator-node/connect-nodes/delegation-pool-operations#prerequisites)
3.  [Operator connects to the network using pool address derived in step 2](/network/nodes/validator-node/connect-nodes/connect-to-aptos-network)
4.  [Owner initializes the delegation pool and sets operator](/network/nodes/validator-node/connect-nodes/delegation-pool-operations#initialize-a-delegation-pool)
5.  Delegators can add stake at any time
6.  When the delegation pool reaches 1M APT, the operator can call aptos node join-validator-set to join the active validator set. Changes will be effective in the next epoch.
7.  Validator validates (proposes blocks as a leader-validator) and gains rewards. Rewards are distributed to delegators proportionally to stake amount. The stake will automatically be locked up for a fixed duration (set by governance) and automatically renewed at expiration.
8.  At any point, if the operator wants to update the consensus key or validator network addresses, they can call aptos node update-consensus-key or aptos node update-validator-network-addresses. Similar to changes to stake, the changes to consensus key or validator network addresses are only effective in the next epoch.
9.  Delegators can request to unlock their stake at any time. However, their stake will only become withdrawable when the delegation pool lockup expires.
10.  Validator can either explicitly leave the validator set by calling aptos node leave-validator-set or if their stake drops below the min required, they would get removed at the end of the epoch.

## Joining the validator set

[](#joining-the-validator-set)

Participating as a delegation validator node on the Aptos network works like this:

1.  Operator runs a validator node and configures the on-chain validator network addresses and rotates the consensus key.
2.  Owner initializes the delegation pool.
3.  The validator node cannot sync until the delegation pool becomes active. The delegation pool becomes active when it reaches 1M APT.
4.  Operator validates and gains rewards.
5.  The stake pool is automatically locked up for a fixed duration (set by the Aptos governance) and will be automatically renewed at expiration. Commissions are automatically distributed to the operator as rewards. The operator can unlock stake at any time, but cannot withdraw until the delegation pool’s lockup period expires.
6.  Operator must wait until the new epoch starts before their validator becomes active.

Note

For step-by-step instructions on how to join the validator set, see: [Joining Validator Set](/network/nodes/validator-node/connect-nodes/connect-to-aptos-network#join-the-validator-set).

### Automatic lockup duration

[](#automatic-lockup-duration)

When the operator joins the validator set, the delegation pool's stake will automatically be locked up for a fixed duration that is set by the Aptos governance. Delegators will follow the delegation pool's lockup cycle.

### Automatic lockup renewal

[](#automatic-lockup-renewal)

When the lockup period expires, it will be automatically renewed, so that the validator can continue to validate and receive the rewards.

### Unlocking your stake

[](#unlocking-your-stake)

Delegators can unlock stake at any time. However, the stake will only become withdrawable after the delegation pool's lockup period expires. Unlocked stake will continue earning rewards until the stake becomes withdrawable.

### Resetting the lockup

[](#resetting-the-lockup)

Lockup cannot be reset.

## Rewards

[](#rewards)

Rewards for delegated staking are calculated by using:

1.  The rewards\_rate, an annual percentage yield (APY), i.e., rewards accrue as a compound interest on your current staked amount.
2.  Delegator stake
3.  [Validator rewards performance](/network/blockchain/staking#rewards-formula)

See [Computing delegation pool rewards](/network/nodes/validator-node/connect-nodes/delegation-pool-operations#compute-delegation-pool-rewards-earned)

# Events

> Understand events on Aptos blockchain, including module events, EventHandle events (deprecated), and how to emit and query events in Move smart contracts.

Events are emitted during the execution of a transaction. Each Move module can define its own events and choose when to emit the events upon execution of the module. Aptos Move supports two form of events: module events and EventHandle events. Module events are the modern event mechanism and shipped in the framework release 1.7. EventHandle events are deprecated and shipped with the original framework. Because of how blockchains work, EventHandle events will likely never be fully removed from Aptos.

## Module Events

[](#module-events)

Module events are global event streams identified by a struct type. To define an event struct, add the attribute `#[event]` to a normal Move struct that has `drop` and `store` abilities. For example,

```
/// 0xcafe::my_module_name/// An example module event struct denotes a coin transfer.#[event]struct TransferEvent has drop, store {    sender: address,    receiver: address,    amount: u64}
```

And then create and emit the event:

```
// Define an event.let event = TransferEvent {    sender: 0xcafe,    receiver: 0xface,    amount: 100};// Emit the event just defined.0x1::event::emit(event);
```

Example module events are available [here](https://explorer.aptoslabs.com/txn/682252266/events?network=testnet). Indices 0, 1, 2 are three module events of type `0x66c34778730acbb120cefa57a3d98fd21e0c8b3a51e9baee530088b2e444e94c::event::MyEvent`. For API compatibility, module events contain the fields `Account Address`, `Creation Number` and `Sequence Number` with all set to 0.

![Module event example](/_vercel/image?url=_astro%2Fmodule-event.C52wtbwl.png&w=1280&q=100&dpl=dpl_BVzupKm7aQfXg1N3qg98Mi3YEbWs "Module event example")

## Access in Tests

[](#access-in-tests)

Events are stored in a separate merkle tree called event accumulator for each transaction. As it is ephemeral and hence independent of the state tree, MoveVM does not have read access to events when executing transaction in production. But in tests, Aptos Move supports two native functions that read emitted events for testing and debugging purposes:

```
/// Return all emitted module events with type T as a vector.# [test_only]public native fun emitted_events<T: drop + store>(): vector<T>;
/// Return true iff `msg` was emitted.# [test_only]public fun was_event_emitted<T: drop + store>(msg: & T): bool
```

## API Access

[](#api-access)

There is support for querying both module events and EventHandle events using the [GraphQL API](/network/nodes/networks).

# Event-Handle Events (Deprecated)

[](#event-handle-events-deprecated)

As part of our legacy, Aptos inherited the Libra/Diem event streams derived from EventHandles. Where each EventHandle is identified by a globally unique value, GUID, and a per-event sequence number and stored within a resource. Each event within a stream has a unique sequence number derived from the EventHandle sequence number.

For example, during a [coin transfer](/build/guides/first-transaction), both the sender and receiver's accounts will emit `SentEvent` and `ReceivedEvent`, respectively. This data is stored within the ledger and can be queried via the REST interface's [Get events by event handle](https://api.devnet.aptoslabs.com/v1/spec#/operations/get_events_by_event_handle).

Assuming that an account `0xc40f1c9b9fdc204cf77f68c9bb7029b0abbe8ad9e5561f7794964076a4fbdcfd` had sent coins to another account, the following query could be made to the REST interface: `https://api.devnet.aptoslabs.com/v1/accounts/c40f1c9b9fdc204cf77f68c9bb7029b0abbe8ad9e5561f7794964076a4fbdcfd/events/0x1::coin::CoinStore<0x1::aptos_coin::AptosCoin>/withdraw_events`. The output would be all `WithdrawEvent`s stored on that account, it would look like

```
[  {    "key": "0x0000000000000000caa60eb4a01756955ab9b2d1caca52ed",    "sequence_number": "0",    "type": "0x1::coin::WithdrawEvent",    "data": {      "amount": "1000"    }  }]
```

Each registered event has a unique `key`. The key `0x0000000000000000caa60eb4a01756955ab9b2d1caca52ed` maps to the event `0x1::coin::CoinStore<0x1::aptos_coin::AptosCoin>/sent_events` registered on account `0xc40f1c9b9fdc204cf77f68c9bb7029b0abbe8ad9e5561f7794964076a4fbdcfd`. This key can then be used to directly make event queries, e.g., `https://api.devnet.aptoslabs.com/v1/events/0x0000000000000000caa60eb4a01756955ab9b2d1caca52ed`.

These represent event streams, or a list of events with each entry containing a sequentially increasing `sequence_number` beginning at `0`, a `type`, and `data`. Each event must be defined by some `type`. There may be multiple events defined by the same or similar `type`s especially when using generics. Events have associated `data`. The general principle is to include all data necessary to understand the changes to the underlying resources before and after the execution of the transaction that changed the data and emitted the event.

## Migration to Module Events

[](#migration-to-module-events)

With the release of module events, EventHandle events are deprecated. To support migration to the module events, projects should emit a module event wherever they currently emit EventHandle events. Once external systems have sufficiently adopted module events, the legacy event may no longer need to be emitted.

Note, the EventHandle events cannot and will not be deleted and hence projects that are unable to upgrade will continue to be able to leverage them.

# Execution

> Explore transaction execution on Aptos, including deterministic processing, parallel execution with Block-STM, and performance optimizations for high throughput.

On Aptos, execution refers to the process where validators run and apply smart contract transactions from an ordered block. The execution output is then applied to the blockchain state.

It is crucial for execution to be [deterministic](https://en.wikipedia.org/wiki/Deterministic_algorithm), and all validators should ideally agree on the same final state of the ledger. A majority of validators (more than 2/3 of the validators) must agree on the final state of the ledger in order to come to a consensus. For more detailed information on consensus properties, see the section on [BFT](/network/glossary#byzantine-fault-tolerance-bft) and [consensus](/network/glossary#consensus).

Efficient execution, particularly parallel execution, is key to scaling blockchain performance and throughput. The impact of this can be felt in the block time. As of December 2024, Aptos blocks close within 250ms.

## Why Parallel Execution?

[](#why-parallel-execution)

![](https://miro.medium.com/v2/resize:fit:4800/format:webp/0*qG0KRe1KzsP8Odth)

The simplest approach for smart contract execution is to execute the transactions in a block sequentially, one at a time. However, this does not scale well. Having a large number of sequential transactions, especially with varying execution times, can cause the latency and throughput of the blockchain to drop drastically.

To solve this problem, blockchains began to adopt parallel execution, or the ability to process multiple transactions in parallel. The challenge with parallel execution, however, is that certain transactions may read or write the same resource, causing conflicts.

### Static Parallelism

[](#static-parallelism)

One approach to address the conflict issue in parallel execution is **static parallelism**, which requires developers to specify the conflicts between transactions ahead of time. This, however, brings a higher burden on the developer, and in many cases forces transactions that don't actually conflict to be sequential.

### Dynamic Parallelism

[](#dynamic-parallelism)

**Dynamic parallelism** computes the execution ordering of transactions on-the-fly, dynamically detecting dependencies and avoiding conflicts during execution. An additional property that is important for dynamic parallelism on a blockchain is that the execution output is consistent with executing transactions according to a preset order.

By not requiring developers to specify the conflicts ahead of time, dynamic parallelism allows developers to flexibly write applications without facing the design constraints of statically declaring transaction dependencies.

## Block-STM

[](#block-stm)

Aptos uses a highly efficient, multi-threaded, in-memory parallel execution engine called Block-STM. Block-STM leverages the preset order of transactions and combines Software Transactional Memory techniques with a novel collaborative schedule.

Block-STM is the state-of-the-art dynamic parallelism execution engine developed by the Aptos Labs team.

Since its release, [Polygon](https://polygon.technology/blog/innovating-the-main-chain-a-polygon-pos-study-in-parallelization), Sei, [Starknet](https://www.starknet.io/blog/parallel-execution-and-v0-13-2/), and other blockchains have adopted it to achieve parallel execution on their respective chains.

To learn more, see:

*   [Block-STM blog post](https://medium.com/aptoslabs/block-stm-how-we-execute-over-160k-transactions-per-second-on-the-aptos-blockchain-3b003657e4ba)
*   [Block-STM paper](https://arxiv.org/pdf/2203.06871)
*   [a16z crypto research talk](https://www.youtube.com/watch?v=2SE5tqPzhyw)
*   [Stark Spaces | Block-STM and Starknet](https://www.youtube.com/watch?v=y1kXOi39RX0)
*   [Block-STM: Accelerating Smart-Contract Processing](https://blog.chain.link/block-stm/)

# Fullnodes Overview

> Discover how fullnodes work on Aptos, their role in verifying blockchain history, differences from validator nodes, and how they support the network ecosystem.

An Aptos node is an entity of the Aptos ecosystem that tracks the [state](/network/glossary#state) of the Aptos blockchain. Clients interact with the blockchain via Aptos nodes. There are two types of nodes:

*   [Validator nodes](/network/blockchain/validator-nodes)
*   Fullnodes

Each Aptos node comprises several logical components:

*   [REST API service](/network/glossary#rest-api-service)
*   [Mempool](/network/blockchain/validator-nodes#mempool)
*   [Execution](/network/blockchain/validator-nodes#execution)
*   [Virtual Machine](/network/blockchain/validator-nodes#virtual-machine)
*   [Storage](/network/blockchain/validator-nodes#storage)
*   [State synchronizer](/network/blockchain/validator-nodes#state-synchronizer)

The [Aptos-core](/network/glossary#aptos-core) software can be configured to run as a validator node or as a fullnode.

## Overview

[](#overview)

Fullnodes can be run by anyone. Fullnodes verify blockchain history by either re-executing all transactions in the history of the Aptos blockchain or replaying each transaction's output. Fullnodes replicate the entire state of the blockchain by synchronizing with upstream participants, e.g., other fullnodes or validator nodes. To verify blockchain state, fullnodes receive the set of transactions and the [accumulator root hash](/network/glossary#accumulator-root-hash) of the ledger signed by the validators. In addition, fullnodes accept transactions submitted by Aptos clients and forward them directly (or indirectly) to validator nodes. While fullnodes and validators share the same code, fullnodes do not participate in consensus.

Depending on the fullnode upstream, a fullnode can be called as a validator fullnode, or a public fullnode:

*   **Validator fullnode** state sync from a validator node directly.
*   **Public fullnode** state sync from other fullnodes.

There's no difference in their functionality, only whether their upstream node is a validator or another fullnode. Read more details about network topology [here](/network/blockchain/node-networks-sync)

Third-party blockchain explorers, wallets, exchanges, and dapps may run a local fullnode to:

*   Leverage the REST interface for blockchain interactions.
*   Get a consistent view of the Aptos ledger.
*   Avoid rate limitations on read traffic.
*   Run custom analytics on historical data.
*   Get notifications about particular on-chain events.

# Gas and Storage Fees

> Learn about gas fees and storage costs on Aptos, including execution costs, storage fees, gas pricing, and optimization strategies for efficient transactions.

Any transaction execution on the Aptos blockchain requires a processing fee. As of today, this fee comprises two components:

1.  Execution & IO costs

*   This covers your usage of transient computation resources, such as processing your transactions and propagating the validated record throughout the distributed network of the mainnet.
*   It is measured in Gas Units whose price may fluctuate according to the load of the network. This allows execution and IO costs to be low when the network is less busy.
*   This portion of gas is burned permanently upon the execution of a transaction.

2.  Storage fees

*   This covers the cost to persistently store validated record in the distributed blockchain storage.
*   It is measured in fixed APT prices, so the permanent storage cost stays stable even as the gas unit price fluctuates with the network's transient load.
*   *   The storage fee can be refunded when the allocated storage slot is deleted. Currently, the network is configured to refund the entirety of the storage fee paid over the lifetime of a state storage slot.
*   To keep system implementation simple, this portion of gas is burned and minted again upon refund.

Note

Conceptually, this fee can be thought of as quite similar to how we pay for our home electric or water utilities.

## Unit of gas

[](#unit-of-gas)

Transactions can range from simple and inexpensive to complicated based upon what they do. In the Aptos blockchain, a **unit of gas** represents a basic unit of consumption for transient resources, such as doing computation or accessing the storage. The latter should not be conflated with the long-term storage aspect of such operations, as that is covered by the storage fees separately.

See [How Base Gas Works](/network/blockchain/base-gas) for a detailed description of gas fee types and available optimizations.

Note

👉 A **unit of gas** is a dimensionless number or a unit that is not associated with any one item such as a coin, expressed as an integer. The total gas units consumed by your transaction depend on the complexity of your transaction. The **gas price**, on the other hand, is expressed in terms of Aptos blockchain’s native coin [APT](/network/glossary#apt) and its subunit [Octas](/network/glossary#octa). Also see [Transactions and States](/network/blockchain/txns-states) for how a transaction submitted to the Aptos blockchain looks like.

## The Fee Statement

[](#the-fee-statement)

As of Aptos Framework release 1.7, the breakdown of fee charges and refunds is emitted as a module event represented by struct `0x1::transaction_fee::FeeStatement`.

```
#[event]/// Breakdown of fee charge and refund for a transaction./// The structure is:////// - Net charge or refund (not in the statement)///    - total charge: total_charge_gas_units, matches `gas_used` in the on-chain `TransactionInfo`.///      This is the sum of the sub-items below. Notice that there's potential precision loss when///      the conversion between internal and external gas units and between native token and gas///      units, so it's possible that the numbers don't add up exactly. -- This number is the final///      charge, while the break down is merely informational.///        - gas charge for execution (CPU time): `execution_gas_units`///        - gas charge for IO (storage random access): `io_gas_units`///        - storage fee charge (storage space): `storage_fee_octas`, to be included in///          `total_charge_gas_unit`, this number is converted to gas units according to the user///          specified `gas_unit_price` on the transaction.///    - storage deletion refund: `storage_fee_refund_octas`, this is not included in `gas_used` or///      `total_charge_gas_units`, the net charge / refund is calculated by///      `total_charge_gas_units` * `gas_unit_price` - `storage_fee_refund_octas`.////// This is meant to be emitted as a module event.struct FeeStatement has drop, store {    /// Total gas charge.    total_charge_gas_units: u64,    /// Execution gas charge.    execution_gas_units: u64,    /// IO gas charge.    io_gas_units: u64,    /// Storage fee charge.    storage_fee_octas: u64,    /// Storage fee refund.    storage_fee_refund_octas: u64,}
```

## Gas price and prioritizing transactions

[](#gas-price-and-prioritizing-transactions)

In the Aptos network, the Aptos governance sets the absolute minimum gas unit price. However, the market determines how quickly a transaction with a particular gas unit price is processed. See [Ethereum Gas Tracker](https://etherscan.io/gastracker), for example, which shows the market price movements of Ethereum gas price.

By specifying a higher gas unit price than the current market price, you can **increase** the priority level for your transaction on the blockchain by paying a larger processing fee. As part of consensus, when the leader selects transactions from its mempool to propose as part of the next block, it will prioritize selecting transactions with a higher gas unit price. Please note that higher gas fees only prioritize transaction selection for the next block.

However, within a block, the order of transaction execution is determined by the system. This order is based on [transaction shuffling](https://github.com/aptos-foundation/AIPs/blob/main/aips/aip-27.md), which makes parallel execution more efficient by considering conflict patterns. While in most cases this is unnecessary, if the network is under load this measure can ensure your transaction is processed more quickly. See the `gas_unit_price` entry under [Estimating the gas units via simulation](#estimating-gas-consumption-via-simulation) for details.

Caution

👉 If you are increasing gas unit price, but have in-flight (uncommitted) transactions for the same account, you should resubmit all of those transactions with the higher gas unit price. This is because transactions within the same account always have to respect sequence number, so effectively the higher gas unit price transaction will increase priority only after the in-flight transactions are included in a block.

## Specifying gas fees within a transaction

[](#specifying-gas-fees-within-a-transaction)

When a transaction is submitted to the Aptos blockchain, the transaction must contain the following mandatory gas fields:

*   `max_gas_amount`: The maximum number of gas units that the transaction sender is willing to spend to execute the transaction. This determines the maximum computational and storage resources that can be consumed by the transaction.
    
*   `gas_price`: The price per gas unit the transaction sender is willing to pay. It is expressed in [Octas](/network/glossary#octa).
    
    During the transaction execution, the total gas amount, expressed as:
    
    ```
    (total execution gas units consumed) + (total storage gas units consumed)
    ```
    
    must not exceed `max_gas_amount`, or else the transaction will abort the execution.

The transaction fee charged to the client will be at the most `gas_price * max_gas_amount`.

## Gas parameters set by governance

[](#gas-parameters-set-by-governance)

The following gas parameters are set by Aptos governance.

Note

These on-chain gas parameters are published on the Aptos blockchain at `0x1::gas_schedule::GasScheduleV2`.

*   `txn.maximum_number_of_gas_units`: Maximum number of gas units that can be spent (this is the maximum allowed value for the `max_gas_amount` gas parameter in the transaction). This is to ensure that the dynamic pricing adjustments do not exceed how much you are willing to pay in total.
*   `txn.min_transaction_gas_units`: Minimum number of gas units that can be spent. The `max_gas_amount` value in the transaction must be set to greater than this parameter’s value.

There also exists some global per-category limits:

*   `txn.max_execution_gas`: The maximum number of gas units a transaction can spend on execution.
*   `txn.max_io_gas`: The maximum number of gas units a transaction can spend on IO.
*   `txn.max_storage_fee`: The maximum amount of APT a transaction can spend on persistent storage. These limits help decouple one category from another, allowing us to set `txn.maximum_number_of_gas_units` generously without having to worry about abuses.

## Calculating Storage Fees

[](#calculating-storage-fees)

The storage fee for a transaction is charged according to the number of new slots allocated in the global state and the size increase in the existing slots.

There are some nuances with regard to price changing and legacy slots which didn't pay for the size of the slot below a historical "free quota". Refer to [AIP-65](https://github.com/aptos-foundation/AIPs/blob/main/aips/aip-65.md#specification) for more details.

It should also be noted that due to some backward compatibility reasons, the total storage fee of a transaction is currently presented to the client as part of the total `gas_used`. This means, this amount could vary based on the gas unit price even for the same transaction.

Here is an example. Suppose we have a transaction that costs `100` gas units in execution & IO, and `5000` [Octas](/network/glossary#octa) in storage fees. The network will show that you have used

*   `100 + 5000 / 100 = 150` gas units if the gas unit price is `100`, or
*   `100 + 5000 / 200 = 125` gas units if the unit price is `200`.

We are aware of the confusion this might create, and plan to present these as separate items in the future. However, this will require some changes to the transaction output format and downstream clients, so please be patient while we work hard to make this happen.

## Calculating Storage Deletion Refund

[](#calculating-storage-deletion-refund)

If a transaction deletes state items, a refund is issued to the transaction payer for the released storage slots. Currently, a full refund is issued -- that is, all storage fee paid for the slot and bytes of the item over the lifetime of it.

The refund amount is denominated in APT and is not converted to gas units or included in the total `gas_used`. Instead, this refund amount is specifically detailed in the `storage_fee_refund_octas` field of the [`FeeStatement`](#the-fee-statement). As a result, the transaction's net effect on the payer's APT balance is determined by `gas_used * gas_unit_price - storage_refund`. If the result is positive, there is a deduction from the account balance; if negative, there is a deposit.

## Examples

[](#examples)

### Example 1: Account balance vs transaction fee

[](#example-1-account-balance-vs-transaction-fee)

**The sender’s account must have sufficient funds to pay for the transaction fee.**

If, let's say, you transfer all the money out of your account so that you have no remaining balance to pay for the transaction fee. In such case the Aptos blockchain would let you know that the transaction will fail, and your transfer wouldn't succeed either.

### Example 2: Transaction amounts vs transaction fee

[](#example-2-transaction-amounts-vs-transaction-fee)

**Transaction fee is independent of transfer amounts in the transaction.**

In a transaction, for example, transaction A, you are transferring 1000 coins from one account to another account. In a second transaction B, with the same gas field values of transaction A, you now transfer 100,000 coins from one account to another one account. Assuming that both the transactions A and B are sent roughly at the same time, then the gas costs for transactions A and B would be near-identical.

## Estimating gas consumption via simulation

[](#estimating-gas-consumption-via-simulation)

The gas used for a transaction can be estimated by simulating the transaction on chain as described here or locally via the gas profiling feature of the Aptos CLI. The results of the simulated transaction represent the **exact** amount that is needed at the **exact** state of the blockchain at the time of the simulation. These gas units used may change based on the state of the chain. For this reason, any amount coming out of the simulation is only an estimate, and when setting the max gas amount, it should include an appropriate amount of headroom based upon your comfort-level and historical behaviors. Setting the max gas amount too low will result in the transaction aborting and the account being charged for whatever gas was consumed.

To simulate transactions on chain, used the [`SimulateTransaction`](https://api.devnet.aptoslabs.com/v1/spec#/operations/simulate_transaction) API. This API will run the exact transaction that you plan to run.

To simulate the transaction locally, use the gas profiler, which is integrated into the Aptos CLI. This will generate a web-based report to help you understand the precise gas usage of your transaction. See [Gas Profiling](/build/cli/working-with-move-contracts/local-simulation-benchmarking-and-gas-profiling#gas-profiling) for more details.

Note

Note that the `Signature` provided on the transaction must be all zeros. This is to prevent someone from using the valid signature.

To simulate the transaction, there are two flags:

1.  `estimate_gas_unit_price`: This flag will estimate the gas unit price in the transaction using the same algorithm as the [`estimate_gas_price`](https://api.devnet.aptoslabs.com/v1/spec#/operations/estimate_gas_price) API.
2.  `estimate_max_gas_amount`: This flag will find the maximum possible gas you can use, and it will simulate the transaction to tell you the actual `gas_used`.

### Simulation steps

[](#simulation-steps)

The simulation steps for finding the correct amount of gas for a transaction are as follows:

1.  Estimate the gas via simulation with both `estimate_gas_unit_price` and `estimate_max_gas_amount` set to `true`.
2.  Use the `gas_unit_price` in the returned transaction as your new transaction’s `gas_unit_price`.
3.  View the `gas_used * gas_unit_price` values in the returned transaction as the **lower bound** for the cost of the transaction.
4.  To calculate the upper bound of the cost, take the **minimum** of the `max_gas_amount` in the returned transaction, and the `gas_used * safety factor`. In the CLI a value of `1.5` is used for `safety factor`. Use this value as `max_gas_amount` for the transaction you want to submit. Note that the **upper bound** for the cost of the transaction is `max_gas_amount * gas_unit_price`, i.e., this is the most the sender of the transaction is charged.
5.  At this point you now have your `gas_unit_price` and `max_gas_amount` to submit your transaction as follows:
    1.  `gas_unit_price` from the returned simulated transaction.
    2.  `max_gas_amount` as the minimum of the `gas_used` \* `a safety factor` or the `max_gas_amount` from the transaction.
6.  If you feel the need to prioritize or deprioritize your transaction, adjust the `gas_unit_price` of the transaction. Increase the value for higher priority, and decrease the value for lower priority.

Note

Prioritization is based upon buckets of `gas_unit_price`. The buckets are defined in [`mempool_config.rs`](https://github.com/aptos-labs/aptos-core/blob/30b385bf38d3dc8c4e8ee0ff045bc5d0d2f67a85/config/src/config/mempool_config.rs#L8). The current buckets are `[0, 150, 300, 500, 1000, 3000, 5000, 10000, 100000, 1000000]`. Therefore, a `gas_unit_price` of 150 and 299 would be prioritized nearly the same.

Note

Note that the `safety factor` only takes into consideration changes related to execution and IO. Unexpected creation of storage slots may not be sufficiently covered.

# On-Chain Governance

> Learn about Aptos on-chain governance, how to create and vote on proposals, and participate in blockchain upgrade decisions through the democratic process.

The Aptos on-chain governance is a process by which the Aptos community members can create and vote on proposals that minimize the cost of blockchain upgrades. The following describes the scope of these proposals for the Aptos on-chain governance:

*   Changes to the blockchain parameters, for example, the epoch duration, and the minimum required and maximum allowed validator stake.
*   Changes to the core blockchain code.
*   Upgrades to the Aptos Framework modules for fixing bugs or for adding or enhancing the Aptos blockchain functionality.
*   Deploying new framework modules (at the address `0x1` - `0xa`).

## How a proposal becomes ready to be resolved

[](#how-a-proposal-becomes-ready-to-be-resolved)

See below for a summary description of how a proposal comes to exist and when it becomes ready to be resolved:

![Proposal voting flow](/_astro/voting-resolution-flow.4bPjQ-SV.svg) ![Proposal voting flow](/_astro/voting-resolution-flow-dark.XJxBWhNV.svg)

*   The Aptos community can suggest an Aptos Improvement Proposal (AIP) in the [Aptos Foundation AIP GitHub](https://github.com/aptos-foundation/AIPs).
*   When appropriate, an on-chain proposal can be created for the AIP via the `aptos_governance` module.
*   Voters can then vote on this proposal on-chain via the `aptos_governance` module. If there is sufficient support for a proposal, then it can be resolved.
*   Governance requires a minimal number of votes to be cast by an expiration threshold. However, if sufficient votes, more than 50% of the total supply, are accumulated prior to that threshold, the proposal can be executed **without waiting for the full voting period**.

## Who can propose

[](#who-can-propose)

*   To either propose or vote, you must stake, but you are not required to run a validator node. However, we recommend that you run validator with a stake as part of the validator set to gain rewards from your stake.
*   To create a proposal, the proposer's backing stake pool must have the minimum required proposer stake. The proposer's stake must be locked up for at least as long as the proposal's voting period. This is to avoid potential spam proposals.
*   Proposers can create a proposal by calling [`aptos_governance::create_proposal`](https://github.com/aptos-labs/aptos-core/blob/27a255ebc662817944435349afc4ec33ea317e64/aptos-move/framework/aptos-framework/sources/aptos_governance.move#L183).

## Who can vote

[](#who-can-vote)

*   To vote, you must stake, though you are not required to run a validator node. Your voting power is derived from the backing stake pool.
*   Voting power is calculated based on the current epoch's active stake of the proposer or voter's backing stake pool. In addition, the stake pool's lockup must be at least as long as the proposal's duration.
*   Verify proposals before voting. Ensure each proposal is linked to its source code, and if there is a corresponding AIP, the AIP is in the title and description.

If you are a [staking pool](/network/blockchain/staking) voter, follow the instructions for voting [here](/network/nodes/validator-node/connect-nodes/staking-pool-voter).

If you are a [delegated staker](/network/blockchain/delegated-staking), follow the instructions for voting [here](/network/nodes/validator-node/connect-nodes/staking-pool-voter#delegation-pool-voter).

## Who can resolve

[](#who-can-resolve)

*   Anyone can resolve an on-chain proposal that has passed voting requirements by using the `aptos governance execute-proposal` command from Aptos CLI.

## Aptos Improvement Proposals (AIPs)

[](#aptos-improvement-proposals-aips)

AIPs are proposals created by the Aptos community or the Aptos Labs team to improve the operations and development of the Aptos chain. To submit an AIP, create an issue in [`Aptos Foundation's GitHub repository`](https://github.com/aptos-foundation/AIPs/issues) using the [template](https://github.com/aptos-foundation/AIPs/blob/main/TEMPLATE.md) To keep up with new AIPs, check the `#aip-announcements` channel on [Aptos' discord channel](https://discord.gg/aptosnetwork). To view and vote on on-chain proposals, go to [`Aptos' Governance website`](https://governance.aptosfoundation.org/).

## Technical Implementation of Aptos Governance

[](#technical-implementation-of-aptos-governance)

The majority of the governance logic is in [`aptos_governance.move and voting.move`](https://github.com/aptos-labs/aptos-core/blob/main/aptos-move/framework/aptos-framework/sources). The `aptos_governance` module outlines how users can interact with Aptos Governance. It's the external-facing module of the Aptos on-chain governance process and contains logic and checks that are specific to Aptos Governance. The `voting` module is the Aptos governance standard that can be used by DAOs on the Aptos chain to create their own on-chain governance process.

If you are thinking about creating a DAO on Aptos, you can refer to `aptos_governance`'s usage of the `voting` module as an example. In `aptos_governance`, we rely on the `voting` module to create, vote on, and resolve a proposal.

*   `aptos_governance::create_proposal` calls `voting::create_proposal` to create a proposal on-chain, when an off-chain AIP acquires sufficient importance.
*   `aptos_governance::vote` calls `voting::vote` to record the vote on a proposal on-chain;
*   `aptos_governance::resolve` can be called by anyone. It calls `voting::resolve` to resolve the proposal on-chain.

# Move - A Web3 Language and Runtime

> Explore Move programming language on Aptos, its safety features, comparison with other VMs, and unique capabilities for building secure Web3 applications.

The Aptos blockchain consists of validator nodes that run a consensus protocol. The consensus protocol agrees upon the ordering of transactions and their output when executed on the Move Virtual Machine (MoveVM). Each validator node translates transactions along with the current blockchain ledger state as input into the VM. The MoveVM processes this input to produce a changeset or storage delta as output. Once consensus agrees and commits to the output, it becomes publicly visible. In this guide, we will introduce you to core Move concepts and how they apply to developing on Aptos.

## What is Move?

[](#what-is-move)

Move is a safe and secure programming language for Web3 that emphasizes **scarcity** and **access control**. Any assets in Move can be represented by or stored within _resource_. **Scarcity** is enforced by default as structs cannot be accidentally duplicated or dropped. Only structs that have explicitly been defined at the bytecode layer as _copy_ can be duplicated and _drop_ can be dropped, respectively.

**Access control** comes from both the notion of accounts and module access privileges. A module in Move may either be a library or a program that can create, store, or transfer assets. Move ensures that only public module functions may be accessed by other modules. Unless a struct has a public constructor, it can only be constructed within the module that defines it. Similarly, fields within a struct can only be accessed and mutated within its module that or via public accessors and setters. Furthermore, structs defined with _key_ can be stored and read from global storage only within the module defines it. Structs with _store_ can be stored within another _store_ or _key_ struct inside or outside the module that defines that struct.

In Move, a transaction's sender is represented by a _signer_, a verified owner of a specific account. The signer has the highest level of permission in Move and is the only entity capable of adding resources into an account. In addition, a module developer can require that a signer be present to access resources or modify assets stored within an account.

## Comparison to other VMs

[](#comparison-to-other-vms)

| | Aptos / Move | Solana / SeaLevel | EVM | Sui / Move | | --------------------------- | ------------------------------------------------------------ | ----------------------------------------------------------- | ---------------------------------------------------------- | ------------------------------------- | | Data storage | Stored at a global address or within the owner's account | Stored within the owner's account associated with a program | Stored within the account associated with a smart contract | Stored at a global address | | Parallelization | Capable of inferring parallelization at runtime within Aptos | Requires specifying all data accessed | Currently serial nothing in production | Requires specifying all data accessed | | Transaction safety | Sequence number | Transaction uniqueness | nonces, similar to sequence numbers | Transaction uniqueness | | Type safety | Module structs and generics | Program structs | Contract types | Module structs and generics | | Function calling | Static dispatch | Static dispatch | Dynamic dispatch | Static dispatch | | Authenticated Storage | [Yes](/network/glossary#merkle-trees) | No | Yes | No | | Object global accessibility | Yes | Not applicable | Not applicable | No, can be placed in other objects |

## Aptos Move features

[](#aptos-move-features)

Each deployment of the MoveVM has the ability to extend the core MoveVM with additional features via an adapter layer. Furthermore, MoveVM has a framework to support standard operations much like a computer has an operating system.

The Aptos Move adapter features include:

*   [Move Objects](https://github.com/aptos-foundation/AIPs/blob/main/aips/aip-10.md) that offer an extensible programming model for globally access to heterogeneous set of resources stored at a single address on-chain.
*   [Cryptography primitives](/build/smart-contracts/cryptography) for building scalable, privacy-preserving dapps.
*   [Resource accounts](/build/smart-contracts/resource-accounts) that offer programmable accounts on-chain, which can be useful for DAOs (decentralized autonomous organizations), shared accounts, or building complex applications on-chain.
*   [Tables](https://github.com/aptos-labs/aptos-core/blob/main/aptos-move/framework/aptos-stdlib/sources/table.move) for storing key, value data within an account at scale.
*   Parallelism via [Block-STM](https://medium.com/aptoslabs/block-stm-how-we-execute-over-160k-transactions-per-second-on-the-aptos-blockchain-3b003657e4ba) that enables concurrent execution of transactions without any input from the user.
*   Multi-agent framework that enables a single transaction to be submitted with multiple distinct `signer` entities.

The Aptos framework ships with many useful libraries:

*   An [Aptos Token Objects](https://github.com/aptos-labs/aptos-core/tree/main/aptos-move/framework/aptos-token-objects/sources) standard as defined in [AIP-11](https://github.com/aptos-foundation/AIPs/blob/main/aips/aip-11.md) and [AIP-22](https://github.com/aptos-foundation/AIPs/blob/main/aips/aip-22.md) that makes it possible to create interoperable NFTs with either lightweight smart contract development or none at all.
*   A [Coin standard](https://github.com/aptos-labs/aptos-core/blob/main/aptos-move/framework/aptos-framework/sources/coin.move) that makes it possible to create type-safe Coins by publishing a trivial module.
*   A [Fungible asset standard](https://github.com/aptos-labs/aptos-core/blob/main/aptos-move/framework/aptos-framework/sources/fungible_asset.move) as defined in [AIP-21](https://github.com/aptos-foundation/AIPs/blob/main/aips/aip-21.md) to modernize the coin concept with better programmability and controls.
*   A [staking](https://github.com/aptos-labs/aptos-core/blob/main/aptos-move/framework/aptos-framework/sources/staking_contract.move) and [delegation](https://github.com/aptos-labs/aptos-core/blob/main/aptos-move/framework/aptos-framework/sources/delegation_pool.move) framework.
*   A [`type_of`](https://github.com/aptos-labs/aptos-core/blob/main/aptos-move/framework/aptos-stdlib/sources/type_info.move) service to identify at run-time the address, module, and struct name of a given type.
*   A [timestamp service](https://github.com/aptos-labs/aptos-core/blob/main/aptos-move/framework/aptos-framework/sources/timestamp.move) that provides a monotonically increasing clock that maps to the actual current Unix time.

With updates frequently.

## More Resources

[](#more-resources)

Developers can begin their journey in Move by heading over to our [Move developer page](/network/blockchain/move).

# Node Networking and State Synchronization

> Learn about the different Aptos node types, their network topology, and how nodes synchronize with each other to maintain blockchain state consistency.

Validator nodes and fullnodes form a hierarchical structure with validator nodes at the root and fullnodes everywhere else. The Aptos blockchain distinguishes two types of fullnodes: validator fullnodes and public fullnodes. Validator fullnodes connect directly to validator nodes and offer scalability alongside DDoS mitigation. Public fullnodes connect to validator fullnodes (or other public fullnodes) to gain low-latency access to the Aptos network.

![v-fn-network.svg](/_astro/v-fn-network.CP9d9r0J.svg?dpl=dpl_BVzupKm7aQfXg1N3qg98Mi3YEbWs)

## Node types

[](#node-types)

Aptos operates with these node types:

*   [Validator nodes (VNs)](/network/blockchain/validator-nodes) - participates in consensus and drives [transaction processing](/network/blockchain/txns-states).
*   Validator fullnodes (VFNs) - captures and keeps up-to-date on the state of the blockchain; run by the validator operator, so it can connect directly to the validator node and therefore serve requests from public fullnodes. Otherwise, it works like a public fullnode.
*   [Public fullnodes (PFNs)](/network/blockchain/fullnodes) - run by someone who is not a validator operator, PFNs cannot connect directly to a validator node and therefore rely upon VFNs for synchronization.
*   [Archival nodes (ANs)](/network/nodes/configure/state-sync#archival-pfns) - is a fullnode that contains all blockchain data since the start of the blockchain's history.

## Separate network stacks

[](#separate-network-stacks)

The Aptos blockchain supports distinct networking stacks for various network topologies. For example, the validator network is independent of the fullnode network. The advantages of having separate network stacks include:

*   Clean separation between the different networks.
*   Better support for security preferences (e.g., bidirectional vs server authentication).
*   Allowance for isolated discovery protocols (i.e., on-chain discovery for validator node's public endpoints vs. manual configuration for private organizations).

# Node synchronization

[](#node-synchronization)

Aptos nodes synchronize to the latest state of the Aptos blockchain through two mechanisms: consensus or state synchronization. Validator nodes will use both consensus and state synchronization to stay up-to-date, while fullnodes use only state synchronization.

For example, a validator node will invoke state synchronization when it comes online for the first time or reboots (e.g., after being offline for a while). Once the validator is up-to-date with the latest state of the blockchain it will begin participating in consensus and rely exclusively on consensus to stay up-to-date. Fullnodes, however, continuously rely on state synchronization to get and stay up-to-date as the blockchain grows.

As of December 2024, the Aptos network's block time was under 250ms.

## State synchronizer

[](#state-synchronizer)

Each Aptos node contains a [State Synchronizer](/network/nodes/configure/state-sync) component which is used to synchronize the state of the node with its peers. This component has the same functionality for all types of Aptos nodes: it utilizes the dedicated peer-to-peer network to continuously request and disseminate blockchain data. Validator nodes distribute blockchain data within the validator node network, while fullnodes rely on other fullnodes (i.e., validator nodes or public fullnodes).

# Move Resources

> Learn about Resources in Move on Aptos, how they differ from instances, their permission models, and storage mechanisms for managing on-chain state.

On Aptos, on-chain state is organized into resources and modules. These are then stored within the individual accounts. This is different from other blockchains, such as Ethereum, where each smart contract maintains its own storage space. See [Accounts](/network/blockchain/accounts) for more details on accounts.

## Resources vs Instances

[](#resources-vs-instances)

Move modules define struct definitions. Struct definitions may include the abilities such as `key` or `store`. Resources are struct instance with The `key` ability that are stored in global storage or directly in an account. The `store` ability allows struct instances to be stored within resources. An example here is how the APT coin is stored: CoinStore is the resource that contains the APT coin, while the Coin itself is an instance:

```
/// A holder of a specific coin type and associated event handles./// These are kept in a single resource to ensure locality of data.struct CoinStore<phantom CoinType> has key {    coin: Coin<CoinType>,}
/// Main structure representing a coin/token in an account's custody.struct Coin<phantom CoinType> has store {    /// Amount of coin this address has.    value: u64,}
```

The Coin instance can be taken out of CoinStore with the owning account's permission and easily transferred to another CoinStore resource. It can also be kept in any other custom resource, if the definition allows, for example:

```
struct CustomCoinBox<phantom CoinType> has key {    coin: Coin<CoinType>,}
```

## Define resources and objects

[](#define-resources-and-objects)

All instances and resources are defined within a module that is stored at an address. For example `0x1234::coin::CoinStore<0x1234::coin::SomeCoin>` would be represented as:

```
module 0x1234::coin {    struct CoinStore<phantom CoinType> has key {        coin: Coin<CoinType>,    }
    struct SomeCoin { }}
```

In this example, `0x1234` is the address, `coin` is the module, `CoinStore` is a struct that can be stored as a resource, and `SomeCoin` is a struct that is unlikely to ever be represented as an instance. The use of the phantom type allows for there to exist many distinct types of `CoinStore` resources with different `CoinType` parameters.

## Permissions of Instances including Resources

[](#permissions-of-instances-including-resources)

Permissions of resources and other instances are dictated by the module where the struct is defined. For example, an instance within a resource may be accessed and even removed from the resource, but the internal state cannot be changed without permission from the module where the instance's struct is defined.

Ownership, on the other hand, is signified by either storing a resource under an account or by logic within the module that defines the struct.

## Viewing a resource

[](#viewing-a-resource)

Resources are stored within accounts. Resources can be located by searching within the owner's account for the resource at its full query path inclusive of the account where it is stored as well as its address and module. Resources can be viewed on the [Aptos Explorer](https://explorer.aptoslabs.com/) by searching for the owning account or directly fetched from a fullnode's API.

## How resources are stored

[](#how-resources-are-stored)

The module that defines a struct specifies how instances may be stored. For example, events for depositing a token can be stored in the receiver account where the deposit happens or in the account where the token module is deployed. In general, storing data in individual user accounts enables a higher level of execution efficiency as there would be no state read/write conflicts among transactions from different accounts, allowing for seamless parallel execution.

# Staking

> Understand staking on Aptos blockchain, including validator operations, rewards, lockup periods, and the owner-operator-voter model for network participation.

Note

We strongly recommend that you read the consensus section of [Aptos Blockchain Deep Dive](/network/blockchain/blockchain-deep-dive#consensus) before proceeding further.

In a distributed system like blockchain, executing a transaction is distinct from updating the state of the ledger and persisting the results in storage. An agreement, i.e., consensus, must be reached by a quorum of validators on the ordering of transactions and their execution results before these results are persisted in storage and the state of the ledger is updated.

Anyone can participate in the Aptos consensus process, if they stake sufficient utility coin, i.e., place their utility coin into escrow. To encourage validators to participate in the consensus process, each validator's vote weight is proportional to the amount of validator's stake. In exchange, the validator is rewarded proportionally to the amount staked. Hence, the performance of the blockchain is aligned with the validator's interest, i.e., rewards.

Note

Currently, slashing is not implemented.

The current on-chain data can be found in [`staking_config::StakingConfig`](https://api.mainnet.aptoslabs.com/v1/accounts/0x1/resource/0x1::staking_config::StakingConfig). The configuration set is defined in [`staking_config.move`](https://github.com/aptos-labs/aptos-core/blob/main/aptos-move/framework/aptos-framework/sources/configs/staking_config.move).

The rest of this document presents how staking works on the Aptos blockchain. See [Supporting documentation](#supporting-documentation) at the bottom for related resources.

## Staking on the Aptos blockchain

[](#staking-on-the-aptos-blockchain)

Below is a summary flow diagram of how staking on the Aptos blockchain works. The sections following the summary describe it in detail.

![Staking Flow](/_astro/staking-light.tXXsfFR-.svg) ![Staking Flow](/_astro/staking-dark.DVUrnYgo.svg)

The Aptos staking module defines a capability that represents ownership.

Note

See the `OwnerCapability` defined in [stake.move](https://github.com/aptos-labs/aptos-core/blob/main/aptos-move/framework/aptos-framework/sources/stake.move).

The `OwnerCapability` resource can be used to control the stake pool. Three personas are supported:

*   Owner
*   Operator
*   Voter

Using this owner-operator-voter model, a custodian can assume the owner persona and stake on the Aptos blockchain and participate in the Aptos governance. This model allows delegations and staking services to be built as it separates the account that is in control of the funds from the other accounts (operator, voter), hence allows secure delegations of responsibilities.

This section describes how this works, using Bob and Alice in the example.

### Owner

[](#owner)

The owner is the owner of the funds. For example, Bob creates an account on the Aptos blockchain. Now Bob has the `OwnerCapability` resource. Bob can assign his account’s operator address to the account of Alice, a trusted node operator, to appoint Alice as a validator.

As an owner:

*   Bob owns the funds that will be used for staking.
*   Only Bob can add, unlock or withdraw funds.
*   Only Bob can extend the lockup period.
*   Bob can change the node operator Alice to some other node operator anytime Bob wishes to do so.
*   Bob can set the operator commission percentage.
*   The reward will be deposited into Bob's (owner's) account.

### Operator

[](#operator)

A node operator is assigned by the fund owner to run the validator node and receives commission as set by the owner. The two personas, the owner and the operator, can be two separate entities or the same. For example, Alice (operator) runs the validator node, operating at the behest of Bob, the fund owner.

As an operator:

*   Alice has permissions only to join or leave the validator set.
*   As a validator, Alice will perform the validating function.
*   Alice has the permissions to change the consensus key and network addresses. The consensus key is used by Alice to participate in the validator consensus process, i.e., to vote and propose a block. Alice is allowed to change ("rotate") this key in case this key is compromised.
*   However, Alice cannot move funds (unless Alice is the owner, i.e., Alice has the `OwnerCapability` resource).
*   The operator commission is deducted from the staker (owner) rewards and deposited into the operator account.

### Voter

[](#voter)

An owner can designate a voter. This enables the voter to participate in governance. The voter will use the voter key to sign the governance votes in the transactions.

Note

This document describes staking. See [Governance](/network/blockchain/governance) for how to participate in the Aptos on-chain governance using the owner-voter model.

## Validation on the Aptos blockchain

[](#validation-on-the-aptos-blockchain)

Throughout the duration of an epoch, the following flow of events occurs several times (thousands of times):

*   A validator leader is selected by a deterministic formula based on the validator reputation determined by validator's performance (including whether the validator has voted in the past or not) and stake. **This leader selection is not done by voting.**
*   The selected leader sends a proposal containing the collected quorum votes of the previous proposal and the leader's proposed order of transactions for the new block.
*   All the validators from the validator set will vote on the leader's proposal for the new block. Once consensus is reached, the block can be finalized. Hence, the actual list of votes to achieve consensus is a subset of all the validators in the validator set. This leader validator is rewarded. **Rewards are given only to the leader validator, not to the voter validators.**
*   The above flow repeats with the selection of another validator leader and repeating the steps for the next new block. Rewards are given at the end of the epoch.

## Validator state and stake state

[](#validator-state-and-stake-state)

States are defined for a validator and the stake.

*   **Validator state:** A validator can be in any one of these four states. Moreover, the validator can go from inactive (not tracked in the validator set anywhere) state to any one of the other three states:
    
    *   inactive
    *   pending\_active.
    *   active.
    *   pending\_inactive.
*   **Stake state:** A validator in pending\_inactive or active state, can have their stake in either of these four states:
    
    *   inactive.
    *   pending\_active.
    *   active.
    *   pending\_inactive.
    
    These stake states are applicable for the existing validators in the validator set adding or removing their stake.

### Validator states

[](#validator-states)

![Signed Transaction Flow](/_astro/validator-state.D6ztszN1.svg) ![Signed Transaction Flow](/_astro/validator-state-dark.CScBuPOd.svg)

There are two edge cases to call out:

1.  If a validator's stake drops below the required [minimum](#minimum-and-maximum-stake), that validator will be moved from active state directly to the inactive state during an epoch change. This happens only during an epoch change.
2.  Aptos governance can also directly remove validators from the active set. **Note that governance proposals will always trigger an epoch change.**

### Stake state

[](#stake-state)

The state of stake has more granularity than that of the validator; additional stake can be added and a portion of stake removed from an active validator.

![Signed Transaction Flow](/_astro/stake-state.D4F03QIl.svg) ![Signed Transaction Flow](/_astro/stake-state-dark.Bnq4nSt9.svg)

### Validator rules

[](#validator-rules)

The below rules is applicable during the changes of state:

*   Voting power can change (increase or decrease) only on epoch boundary.
*   A validator’s consensus key and the validator and validator fullnode network addresses can change only on epoch boundary.
*   Pending inactive stake cannot be moved into inactive (and thus withdrawable) until before lockup expires.
*   No validators in the active validator set can have their stake below the minimum required stake.

## Validator flow

[](#validator-flow)

Note

See [Staking pool operations](/network/nodes/validator-node/connect-nodes/staking-pool-operations) for the correct sequence of commands to run for the below flow.

1.  Owner initializes the stake pool with `aptos stake create-staking-contract`.
2.  When the owner is ready to deposit the stake (or have funds assigned by a staking service in exchange for ownership capability), owner calls `aptos stake add-stake`.
3.  When the validator node is ready, the operator can call `aptos node join-validator-set` to join the active validator set. Changes will be effective in the next epoch.
4.  Validator validates (proposes blocks as a leader-validator) and gains rewards. The stake will automatically be locked up for a fixed duration (set by governance) and automatically renewed at expiration.
5.  At any point, if the operator wants to update the consensus key or validator network addresses, they can call `aptos node update-consensus-key` or `aptos node update-validator-network-addresses`. Similar to changes to stake, the changes to consensus key or validator network addresses are only effective in the next epoch.
6.  Validator can request to unlock their stake at any time. However, their stake will only become withdrawable when their current lockup expires. This can be at most as long as the fixed lockup duration.
7.  After exiting, the validator can either explicitly leave the validator set by calling `aptos node leave-validator-set` or if their stake drops below the min required, they would get removed at the end of the epoch.
8.  Validator can always rejoin the validator set by going through steps 2-3 again.
9.  An owner can always switch operators by calling `aptos stake set-operator`.
10.  An owner can always switch designated voter by calling `aptos stake set-delegated-voter`.

## Joining the validator set

[](#joining-the-validator-set)

Participating as a validator node on the Aptos network works like this:

1.  Operator runs a validator node and configures the on-chain validator network addresses and rotates the consensus key.
2.  Owner deposits her Aptos coins funds as stake, or have funds assigned by a staking service. The stake must be at least the minimum amount required.
3.  **The validator node cannot sync until the stake pool becomes active.**
4.  Operator validates and gains rewards.
5.  The staked pool is automatically be locked up for a fixed duration (set by the Aptos governance) and will be automatically renewed at expiration. You cannot withdraw any of your staked amount until your lockup period expires. See [stake.move#L728](https://github.com/aptos-labs/aptos-core/blob/00a234cc233b01f1a7e1680f81b72214a7af91a9/aptos-move/framework/aptos-framework/sources/stake.move#L728).
6.  Operator must wait until the new epoch starts before their validator becomes active.

Note

For step-by-step instructions on how to join the validator set, see: [Joining Validator Set](/network/nodes/validator-node/connect-nodes/connect-to-aptos-network#join-the-validator-set).

### Minimum and maximum stake

[](#minimum-and-maximum-stake)

You must stake the required minimum amount to join the validator set. Moreover, you can only stake up to the maximum stake amount. The current required minimum for staking is 1M APT tokens and the maximum is 50M APT tokens.

If at any time after joining the validator set, your current staked amount exceeds the maximum allowed stake (for example as the rewards are added to your staked amount), then your voting power and the rewards will be calculated only using the maximum allowed stake amount, and not your current staked amount.

The owner can withdraw part of the stake and leave their balance below the required minimum. In such case, their stake pool will be removed from the validator set when the next epoch starts.

### Automatic lockup duration

[](#automatic-lockup-duration)

When you join the validator set, your stake will automatically be locked up for a fixed duration that is set by the Aptos governance.

### Automatic lockup renewal

[](#automatic-lockup-renewal)

When your lockup period expires, it will be automatically renewed, so that you can continue to validate and receive the rewards.

### Unlocking your stake

[](#unlocking-your-stake)

You can request to unlock your stake at any time. However, your stake will only become withdrawable when your current lockup expires. This can be at most as long as the fixed lockup duration. You will continue earning rewards on your stake until it becomes withdrawable.

The principal amount is updated when any of the following actions occur:

1.  Operator [requests commission unlock](/network/nodes/validator-node/connect-nodes/staking-pool-operations#requesting-commission)
2.  Staker (owner) withdraws funds
3.  Staker (owner) switches operators

When the staker unlocks stake, this also triggers a commission unlock. The full commission amount for any staking rewards earned is unlocked. This is not proportional to the unlock stake amount. Commission is distributed to the operator after the lockup ends when `request commission` is called a second time or when staker withdraws (distributes) the unlocked stake.

### Resetting the lockup

[](#resetting-the-lockup)

When the lockup period expires, it is automatically renewed by the network. However, the owner can explicitly reset the lockup.

Note

The lockup duration is decided by the Aptos governance, i.e., by the covenants that the Aptos community members vote on, and not by any special entity like the Aptos Labs.

## Epoch

[](#epoch)

An epoch in the Aptos blockchain is defined as a duration of time, in seconds, during which a number of blocks are voted on by the validators, the validator set is updated, and the rewards are distributed to the validators.

Note

The Aptos mainnet epoch is set as 7200 seconds (two hours).

### Triggers at the epoch start

[](#triggers-at-the-epoch-start)

Note

See the [Triggers at epoch boundary section of `stake.move`](https://github.com/aptos-labs/aptos-core/blob/256618470f2ad7d89757263fbdbae38ac7085317/aptos-move/framework/aptos-framework/sources/stake.move#L1036) for the full code.

At the start of each epoch, the following key events are triggered:

*   Update the validator set by adding the pending active validators to the active validators set and by removing the pending inactive validators from the active validators set.
*   Move any pending active stake to active stake, and any pending inactive stake to inactive stake.
*   The staking pool's voting power in this new epoch is updated to the total active stake.
*   Automatically renew a validator's lockup for the validators who will still be in the validator set in the next epoch.
*   The voting power of each validator in the validator set is updated to be the corresponding staking pool's voting power.
*   Rewards are distributed to the validators that participated in the previous epoch.

## Rewards

[](#rewards)

Rewards for staking are calculated by using:

1.  The `rewards_rate`, an annual percentage yield (APY), i.e., rewards accrue as a compound interest on your current staked amount.
2.  Your staked amount.
3.  Your proposer performance in the Aptos governance.

Note

The `rewards_rate` is set by the Aptos governance. Also see [Validation on the Aptos blockchain](#validation-on-the-aptos-blockchain).

### Rewards formula

[](#rewards-formula)

See below the formula used to calculate rewards to the validator:

```
Reward = staked_amount * rewards_rate per epoch * (Number of successful proposals by the validator / Total number of proposals made by the validator)
```

### Rewards paid every epoch

[](#rewards-paid-every-epoch)

Rewards are paid every epoch. Any reward you (i.e., validator) earned at the end of current epoch is added to your staked amount. The reward at the end of the next epoch is calculated based on your increased staked amount (i.e., original staked amount plus the added reward), and so on.

### Rewards based on the proposer performance

[](#rewards-based-on-the-proposer-performance)

The validator rewards calculation uses the validator's proposer performance. Once you are in the validator set, you can propose in every epoch. The more successfully you propose, i.e., your proposals pass, the more rewards you will receive.

Note that rewards are given only to the **leader-validators**, i.e., validators who propose the new block, and not to the **voter-validators** who vote on the leader's proposal for the new block. See [Validation on the Aptos blockchain](#validation-on-the-aptos-blockchain).

Note

All the validator rewards are also subject to lockup period as they are added to the original staked amount.

## Leaving the validator set

[](#leaving-the-validator-set)

Note

See the Aptos Stake module in the Move language at [stake.move](https://github.com/aptos-labs/aptos-core/blob/main/aptos-move/framework/aptos-framework/sources/stake.move).

*   At any time you can call the following sequence of functions to leave the validator set:
    *   Call `Stake::unlock` to unlock your stake amount, and
    *   Either call `Stake::withdraw` to withdraw your staked amount at the next epoch, or call `Stake::leave_validator_set`.

## Rejoining the validator set

[](#rejoining-the-validator-set)

When you leave a validator set, you can rejoin by depositing the minimum required stake amount.

## Supporting documentation

[](#supporting-documentation)

*   [Current on-chain data](https://api.mainnet.aptoslabs.com/v1/accounts/0x1/resource/0x1::staking_config::StakingConfig)
*   [Staking Pool Operations](/network/nodes/validator-node/connect-nodes/staking-pool-operations)
*   [Delegation Pool Operations](/network/nodes/validator-node/connect-nodes/delegation-pool-operations)
*   [Configuration file `staking_config.move`](https://github.com/aptos-labs/aptos-core/blob/main/aptos-move/framework/aptos-framework/sources/configs/staking_config.move)
*   [Contract file `staking_contract.move`](https://github.com/aptos-labs/aptos-core/blob/main/aptos-move/framework/aptos-framework/sources/staking_contract.move) covering requesting commissions
*   [All staking-related \`.move files](https://github.com/aptos-labs/aptos-core/tree/main/aptos-move/framework/aptos-framework/sources)

# Transaction Payloads and BCS

> Learn the Aptos transaction payload types, how REST JSON maps to BCS, and how to build and decode payloads with TypeScript.

A transaction payload defines the operation that a transaction executes. The sender, sequence number, gas settings, expiration time, and signature are not part of the payload.

The Aptos REST API represents payloads as JSON. Transaction signing and network transport use [BCS](https://github.com/aptos-labs/bcs) (Binary Canonical Serialization) to represent payloads and transactions.

## Payload types

[](#payload-types)

`TransactionPayload` is a BCS enum. Each variant begins with a ULEB128-encoded enum index.

| BCS index | Payload | REST JSON `type` | Description | | --------: | ---------------------- | ------------------------------- | ------------------------------------------------------ | | `0` | Script payload | `script_payload` | Executes a Move script included in the transaction. | | `1` | Module bundle payload | `module_bundle_payload` | Deprecated. | | `2` | Entry function payload | `entry_function_payload` | Calls an entry function in a published module. | | `3` | Multisig payload | `multisig_payload` | Executes an operation as an on-chain multisig account. | | `4` | Versioned payload | Not exposed directly | Versioned payload used by orderless transactions. | | `5` | Encrypted payload | `encrypted_transaction_payload` | Contains an encrypted transaction payload. |

`write_set_payload` is used only by genesis and system transactions. It is not a `TransactionPayload` that a regular user transaction can submit.

## BCS encoding rules

[](#bcs-encoding-rules)

The following rules apply to the BCS layouts in this document:

| Type | Encoding | | --------------------- | ------------------------------------------------------------------ | | Enum | ULEB128 enum index followed by the fields of the selected variant. | | `vector<T>` | ULEB128 element count followed by each element. | | `vector<u8>` | ULEB128 byte length followed by the bytes. | | `Option<T>` | `0x00` for `None`; `0x01` followed by `T` for `Some(T)`. | | `u64`, `u128`, `u256` | Fixed-width, little-endian. | | Address | 32 bytes. |

## Script payload

[](#script-payload)

`Script` contains Move script bytecode, type arguments, and script arguments.

REST JSON:

```
{  "type": "script_payload",  "code": { "bytecode": "0xa11ceb0b..." },  "type_arguments": [],  "arguments": ["0x123", "100000000"]}
```

BCS layout:

```
uleb128(0)                    // TransactionPayload::Scriptvector<u8>                    // Move script bytecodevector<TypeTag>               // Type argumentsvector<TransactionArgument>   // Script arguments
```

`TransactionArgument` is an enum that includes a type index. New applications generally use entry function payloads. Script payloads are intended for operations that must include Move bytecode in the transaction.

## Module bundle payload

[](#module-bundle-payload)

`ModuleBundle` is deprecated. Nodes retain its enum position for BCS compatibility but reject new transactions that use it. Use the SDK package publishing API to publish a Move package.

REST JSON:

```
{  "type": "module_bundle_payload"}
```

Retained BCS layout:

```
uleb128(1)  // TransactionPayload::ModuleBundleu64         // Compatibility field with no current behavior
```

## Entry function payload

[](#entry-function-payload)

`EntryFunction` calls a `public entry fun` in a published module.

REST JSON:

```
{  "type": "entry_function_payload",  "function": "0x1::aptos_account::transfer",  "type_arguments": [],  "arguments": ["0x123", "100000000"]}
```

BCS layout:

```
uleb128(2)          // TransactionPayload::EntryFunctionModuleId            // Module address and nameIdentifier          // Function namevector<TypeTag>     // Type argumentsvector<vector<u8>>  // Function arguments
```

Each function argument is BCS-encoded according to its Move type in the ABI and stored in a separate `vector<u8>`. The argument bytes do not include type information, so decoding requires the function ABI.

Build an entry function payload with the TypeScript SDK:

```
import { AccountAddress, Aptos, AptosConfig, Network, U64 } from "@aptos-labs/ts-sdk";
const aptos = new Aptos(new AptosConfig({ network: Network.TESTNET }));
const transaction = await aptos.transaction.build.simple({  sender: AccountAddress.fromString("0xabc"),  data: {    function: "0x1::aptos_account::transfer",    functionArguments: [AccountAddress.fromString("0x123"), new U64(100_000_000)],  },});
const payloadHex = transaction.rawTransaction.payload.bcsToHex().toString();
```

## Multisig payload

[](#multisig-payload)

`Multisig` specifies an on-chain multisig account and can include an entry function or script payload.

REST JSON:

```
{  "type": "multisig_payload",  "multisig_address": "0x123",  "transaction_payload": {    "type": "entry_function_payload",    "function": "0x1::aptos_account::transfer",    "type_arguments": [],    "arguments": ["0x456", "100000000"]  }}
```

BCS layout:

```
uleb128(3)                         // TransactionPayload::MultisigAccountAddress                     // Multisig account addressOption<MultisigTransactionPayload> // Payload to execute
```

`MultisigTransactionPayload` is a nested enum: index `0` is an entry function and index `1` is a script. `None` uses a payload already stored in the on-chain multisig account.

An on-chain multisig account is different from a multi-agent transaction. A multi-agent transaction has multiple signers but uses a regular transaction payload.

## Versioned payload

[](#versioned-payload)

`Payload` is an extensible, versioned structure. Its current inner version is `TransactionPayloadInner::V1`.

BCS layout:

```
uleb128(4)              // TransactionPayload::Payloaduleb128(0)              // TransactionPayloadInner::V1TransactionExecutable   // Entry function, script, empty, or encrypted operationTransactionExtraConfig  // Multisig address, replay-protection nonce, and other settings
```

The REST API converts this structure into entry function, script, or multisig JSON based on `TransactionExecutable` and `TransactionExtraConfig`. It does not return `Payload::V1` as a separate REST payload type.

### Orderless transactions

[](#orderless-transactions)

An orderless transaction is not a separate payload variant. It uses `TransactionPayload::Payload` and sets `replay_protection_nonce: Some(u64)` in `TransactionExtraConfig`. Its `RawTransaction.sequence_number` is set to `u64::MAX`.

```
const transaction = await aptos.transaction.build.simple({  sender: sender.accountAddress,  data: {    function: "0x1::aptos_account::transfer",    functionArguments: [recipient.accountAddress, 100],  },  options: {    replayProtectionNonce: 12345n,  },});
```

`replayProtectionNonce` must be unique during the transaction's validity period. An orderless transaction has a maximum expiration period of 60 seconds.

## Encrypted payload

[](#encrypted-payload)

`EncryptedPayload` is available on networks that support AIP-144. On submission, it contains the ciphertext, payload hash, encryption epoch, extra configuration, and an optional claimed entry function.

REST JSON:

```
{  "type": "encrypted_transaction_payload",  "encrypted_state": "encrypted",  "payload_hash": "0x...",  "ciphertext": "0x...",  "encryption_epoch": "123",  "claimed_entry_fun": null}
```

BCS layout:

```
uleb128(5)                     // TransactionPayload::EncryptedPayloaduleb128(0)                     // EncryptedPayload::EncryptedCiphertext                      // CiphertextTransactionExtraConfig         // Extra configuration[u8; 32]                       // Payload hashu64                            // Encryption epochOption<ClaimedEntryFunction>   // Optional claimed entry function
```

The REST API uses `encrypted_state` to distinguish `encrypted`, `decrypted`, and `failed_decryption`. Only the `encrypted` state can be submitted. See [Encrypted Pending Transactions](/build/guides/encrypted-pending-transactions).

## Decode a BCS payload

[](#decode-a-bcs-payload)

`TransactionPayload.deserialize()` decodes the payload enum and its fields. Entry function arguments remain raw bytes and must be decoded separately using the ABI.

```
import {  Deserializer,  TransactionPayload,  TransactionPayloadEntryFunction,  U64,} from "@aptos-labs/ts-sdk";
function decodeEntryFunctionPayload(payloadHex: string) {  const decoded = TransactionPayload.deserialize(Deserializer.fromHex(payloadHex));
  if (!(decoded instanceof TransactionPayloadEntryFunction)) {    throw new Error("Expected an entry function payload");  }
  // The second argument is u64 according to the function ABI.  const amountBytes = decoded.entryFunction.args[1].bcsToBytes();  return U64.deserialize(new Deserializer(amountBytes)).value;}
```

`TransactionPayload`, `RawTransaction`, and `SignedTransaction` are different BCS objects. A transaction signature covers the complete raw transaction, not only its payload.

Note

The on-chain `TransactionPayload` definition is in `types/src/transaction/mod.rs` in aptos-core. The REST JSON types and conversion logic are in `api/types/src/transaction.rs` and `api/types/src/convert.rs`.

# Validator Nodes Overview

> Learn about validator nodes on the Aptos blockchain, their components, and how they participate in consensus to process transactions and maintain network security.

An Aptos node is an entity of the Aptos ecosystem that tracks the state of the Aptos blockchain. Clients interact with the blockchain via Aptos nodes. There are two types of nodes:

*   Validator nodes
*   [Fullnodes](/network/blockchain/fullnodes)

Each Aptos node comprises several logical components:

*   [REST API service](/network/glossary#rest-api-service)
*   [Mempool](#mempool)
*   [Consensus (disabled in fullnodes)](#consensus)
*   [Execution](#execution)
*   [Virtual Machine](#virtual-machine-vm)
*   [Storage](#storage)
*   [State synchronizer](#state-synchronizer)

The [Aptos-core](/network/glossary#aptos-core) software can be configured to run as a validator node or as a fullnode.

![Aptos Explorer Validators page showing global node distribution](/_vercel/image?url=_astro%2Fexplorer-validators.CqCsHx6Z.png&w=1280&q=100&dpl=dpl_BVzupKm7aQfXg1N3qg98Mi3YEbWs)

Aptos validator network as of 3/30/2026: 115 nodes across 16 countries. [View live on Explorer](https://explorer.aptoslabs.com/validators?network=mainnet)

## Overview

[](#overview)

When a transaction is submitted to the Aptos blockchain, validator nodes run a distributed [consensus protocol](/network/glossary#consensus-protocol), execute the transaction, and store the transaction and the execution results on the blockchain. Validator nodes decide which transactions will be added to the blockchain and in which order.

The Aptos blockchain uses a Byzantine Fault Tolerance (BFT) consensus protocol for validator nodes to agree on the ledger of finalized transactions and their execution results. Validator nodes process these transactions and include them in their local copy of the blockchain database. This means that up-to-date validator nodes always maintain a copy of the current [state](/network/glossary#state) of the blockchain, locally.

Validator nodes communicate directly with other validator nodes over a private network. [Fullnodes](/network/blockchain/fullnodes) are an external validation and/or dissemination resource for the finalized transaction history. They receive transactions from peers and may re-execute them locally (the same way a validator executes transactions). Fullnodes store the results of re-executed transactions to local storage. In doing so, they can challenge any foul-play by validators and provide evidence if there is any attempt to re-write or modify the blockchain history. This helps to mitigate against validator corruption and/or collusion.

Note

The AptosBFT consensus protocol provides fault tolerance of up to one-third of malicious validator nodes.

## Validator node components

[](#validator-node-components)

![](/_astro/validator.Cw82vyRD.svg?dpl=dpl_BVzupKm7aQfXg1N3qg98Mi3YEbWs)

### Mempool

[](#mempool)

Mempool is a component within each node that holds an in-memory buffer of transactions that have been submitted to the blockchain, but not yet agreed upon or executed. This buffer is replicated between validator nodes and fullnodes.

The JSON-RPC service of a fullnode sends transactions to a validator node's mempool. Mempool performs various checks on the transactions to ensure transaction validity and protect against DOS attacks. When a new transaction passes initial verification and is added to mempool, it is then distributed to the mempools of other validator nodes in the network.

When a validator node temporarily becomes a leader in the consensus protocol, consensus pulls the transactions from mempool and proposes a new transaction block. This block is broadcast to other validators and contains a total ordering over all transactions in the block. Each validator then executes the block and submits votes on whether to accept the new block proposal.

### Consensus

[](#consensus)

Consensus is the component that is responsible for ordering blocks of transactions and agreeing on the results of execution by participating in the consensus protocol with other validator nodes in the network.

### Execution

[](#execution)

Execution is the component that coordinates the execution of a block of transactions and maintains a transient state. Consensus votes on this transient state. Execution maintains an in-memory representation of the execution results until consensus commits the block to the distributed database. Execution uses the virtual machine to execute transactions. Execution acts as the glue layer between the inputs of the system (represented by transactions), storage (providing a persistency layer), and the virtual machine (for execution).

### Virtual machine (VM)

[](#virtual-machine-vm)

The virtual machine (VM) is used to run the Move program within each transaction and determine execution results. A node's mempool uses the VM to perform verification checks on transactions, while execution uses the VM to execute transactions.

### Storage

[](#storage)

The storage component is used to persist agreed upon blocks of transactions and their execution results to the local database.

### State synchronizer

[](#state-synchronizer)

Nodes use their state synchronizer component to "catch up" to the latest state of the blockchain and stay up-to-date.

# Aptos Testnet Faucet – Get Free APT for Development

> Generate free APT testnet tokens instantly with the Aptos Faucet. Ideal for testing smart contracts and building on the Aptos blockchain.

The Aptos Testnet Faucet lets developers instantly request free APT tokens on the **Aptos testnet**.  
These tokens are for **testing purposes only** — they hold no real-world value and cannot be exchanged for mainnet APT.

Use the faucet to:

*   Deploy and test **Move smart contracts**
*   Experiment with Aptos SDKs (TypeScript, Python, Rust, and more)
*   Build and refine dApps before launching to mainnet

## How to Use the Faucet

[](#how-to-use-the-faucet)

1.  **Sign in** with your Google account.
2.  **Enter your Aptos testnet wallet address**.
3.  Click **Request APT** to instantly receive tokens.
4.  Check your wallet balance — tokens should appear within a few seconds.

> **Tip:** If you don’t have a testnet account, you can either [Create an Account with the Aptos TypeScript SDK](/build/sdks/ts-sdk/quickstart) (developer method) or [Install an Aptos Wallet and Switch to Testnet](https://aptosnetwork.com/ecosystem/directory/category/wallets) (UI method) to get started.

## Related Resources

[](#related-resources)

*   [Create an Account with the Aptos TypeScript SDK](/build/sdks/ts-sdk/quickstart)
*   [Install an Aptos Wallet](https://aptosnetwork.com/ecosystem/directory/category/wallets)
*   [Deploy a Smart Contract on Testnet](/build/guides/build-e2e-dapp/1-create-smart-contract)
*   [Aptos CLI – Create Test Accounts and Send Transactions](/build/cli/trying-things-on-chain/create-test-accounts)
*   [Faucet API Reference](/build/apis/faucet-api)

# Bootstrap a Node

> Options for bootstrapping new Aptos nodes including state sync fast mode, snapshot restoration, and backup recovery for accessing ledger history.

Bootstrapping a new node usually only depends on [state sync](/network/nodes/configure/state-sync) in its fast sync mode, which synchronizes to a recent state with help from its peers and start syncing recent ledger history from there. However, if longer ledger history is needed for any reason, we have these choices:

*   ### [Bootstrap from a Snapshot](/network/nodes/bootstrap-fullnode/bootstrap-fullnode)
    
    [](#bootstrap-from-a-snapshot)
    
*   ### [Bootstrap from a Backup](/network/nodes/bootstrap-fullnode/aptos-db-restore)
    
    [](#bootstrap-from-a-backup)

# Bootstrap from a Backup

> Bootstrap Aptos nodes using cryptographically-proven backup files to quickly restore databases or recover historical blockchain data.

This document describes how to bootstrap an Aptos node using a backup. This can be done on all node types, including validators, VFNs and PFNs. Bootstrapping using a backup helps node operators achieve two goals:

1.  Quickly bootstrap a database to start a new or failed node.
2.  Efficiently recover data from any specific period in the blockchain's history (e.g., from genesis to a target version).

To achieve these goals, the Aptos database restore tool lets you use existing [public backup files](#public-backup-files) to restore the database of a node. This includes the transaction history containing events, write sets, and key-value pairs. Using the tool, you can restore transactions from any historical range, or restore the database to the latest version in the backup. The public backup files are backed by cryptographic proofs and stored on both AWS and Google Cloud for easy access.

## Public backup files

[](#public-backup-files)

Aptos Labs maintains a few publicly accessible database backups by continuously querying a PFN and storing the backup data in remote storage, such as Amazon S3 or Google Cloud Storage. The links to this backup data can be seen below:

| | AWS Backup Data | Google Cloud Backup Data | | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Testnet | Discontinued | [https://github.com/aptos-labs/aptos-networks/blob/main/testnet/backups/gcs.yaml](https://github.com/aptos-labs/aptos-networks/blob/main/testnet/backups/gcs.yaml) | | Mainnet | [https://github.com/aptos-labs/aptos-networks/blob/main/mainnet/backups/s3-public.yaml](https://github.com/aptos-labs/aptos-networks/blob/main/mainnet/backups/s3-public.yaml) | [https://github.com/aptos-labs/aptos-networks/blob/main/mainnet/backups/gcs.yaml](https://github.com/aptos-labs/aptos-networks/blob/main/mainnet/backups/gcs.yaml) |

Note

Backups are only created for `testnet` and `mainnet`. Given that `devnet` is wiped frequently, it is not useful to maintain backups for it.

The backup files consist of three types of data that can be used to reconstruct the blockchain DB:

*   `epoch_ending` – This contains the ledger\_info at the ending block of each epoch since the genesis. This data can be used to prove the epoch's provenance from the genesis and validator set of each epoch.
*   `state_snapshot` – This contains a snapshot of the blockchain's state Merkle tree (SMT) and key values at a certain version.
*   `transaction` – This contains the raw transaction metadata, payload, the executed outputs of the transaction after VM, and the cryptographic proofs of the transaction in the ledger history.

Each type of data in the backup storage is organized as follows:

*   The metadata file in the metadata folder contains the range of each backup and the relative path to the backup folder.
*   The backup contains a manifest file and all the actual chunked data files.

See the diagram below for a visual representation of the backup data structure:

![aptos-db-restore.png](/_vercel/image?url=_astro%2Faptos-db-restore.Cz0GZdu7.png&w=1280&q=100&dpl=dpl_BVzupKm7aQfXg1N3qg98Mi3YEbWs)

## Restore an Aptos DB

[](#restore-an-aptos-db)

The [Aptos CLI](/build/cli) supports two kinds of restore operations for Aptos nodes:

1.  Recreating a database with a minimal transaction history at a user-specified transaction version (or the latest version offered by the backup).
2.  Restoring the database over a specific period. In addition to the above, this option ensures that the recreated database carries the ledger history of the user-designated version range.

Note

Aptos CLI 1.0.14 or newer is needed to perform these operations. Additionally, depending on whether you use AWS or Google Cloud, install [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) or [gsutil](https://cloud.google.com/storage/docs/gsutil_install).

The sections below provide examples of how to use the Aptos CLI to restore a database from a backup.

### Bootstrap to the latest version

[](#bootstrap-to-the-latest-version)

The `aptos node bootstrap-db` command can quickly restore a database from the latest snapshot back to a target version, but it does not restore the transaction history prior to the target version.

Use the following options to run the command:

*   `target-version` – The sync will begin from this period onwards in the transaction history (towards the latest version).
*   `command-adapter-config` – The path to one of the [YAML configuration files](#public-backup-files) that specifies the location of the public backup files and commands used by our backup and restore tool to interact with the remote storage.
*   `target-db-dir` – The target DB path to write the restored database.

Example command:

```
aptos node bootstrap-db \    --target-version 500000000 \    --command-adapter-config /path/to/s3-public.yaml \    --target-db-dir /path/to/local/db
```

### Restore over a specific time period

[](#restore-over-a-specific-time-period)

The `aptos node bootstrap-db` command can restore the transaction history within a specified period, along with the state Merkle tree at the target version.

Use the following options to run the command:

*   `ledger-history-start-version` – The sync will begin from this period onwards in the transaction history (towards the target version).
*   `target-version` – The sync will end at this period in the transaction history.
*   `command-adapter-config` – The path to one of the [YAML configuration files](#public-backup-files) that specifies the location of the public backup files and commands used by our backup and restore tool to interact with the remote storage.
*   `target-db-dir` – The target DB path to write the restored database.

Example command:

```
aptos node bootstrap-db \    --ledger-history-start-version 150000000 \    --target-version 155000000    --command-adapter-config /path/to/s3-public.yaml \    --target-db-dir /path/to/local/db
```

### Restore a full history from genesis

[](#restore-a-full-history-from-genesis)

To restore an Aptos node with the full history from genesis, set `ledger-history-start-version` to 0 and disable the pruner by following the instructions in the [disabling the ledger pruner](/network/nodes/configure/data-pruning) section before starting the node. Note: performing a full history restore requires a significant amount of resources and time. See the resource requirements below.

*   **Open File Limit**: Set the open file limit >= 999999, e.g., using `ulimit -n 1048576`.

If you are restoring a node, you will need the following resources:

| | Disk | RAM | | ------- | ------ | ----- | | Testnet | 1.5 TB | 32 GB | | Mainnet | 1 TB | 32 GB |

Example command:

```
aptos node bootstrap-db \  --ledger-history-start-version 0 \  --target-version use_the_largest_version_in_backup \  --command-adapter-config /path/to/s3-public.yaml \  --target-db-dir /path/to/local/db
```

Note

If you don't specify the target\_version (via `--target-version`), the tool will use the latest version in the backup as the target version.

# Bootstrap from a Snapshot

> Quickly bootstrap Aptos validator, VFN, or PFN nodes using community-provided snapshots to avoid slow state sync processes.

This document describes how to bootstrap an Aptos node quickly using a snapshot. This can be done on all node types, including validators, VFNs and PFNs.

Caution

**Indexer snapshots**  
The snapshots provided by the community do not provide indexer support. If you are bootstrapping an indexer node, you will need to do so by using a [backup](/network/nodes/bootstrap-fullnode/aptos-db-restore).

Although you can bootstrap a new node using [state sync](/network/nodes/configure/state-sync), this might not be the fastest approach after the network has been running for a while; it can either take too much time, or it won't be able to fetch all the required data since other nodes may have already pruned their ledger history. To avoid this, you can bootstrap your node using an existing snapshot, which is simply a copy of the storage data of an existing node.

Caution

**Mainnet snapshots**  
It is not recommended to use snapshots for bootstrapping nodes in **mainnet**. This is because snapshots are not verified by the Aptos software. As a result, the snapshot may be invalid or contain incorrect data. To prevent security concerns, we recommend using snapshots only in test environments, e.g., **devnet** and **testnet**.

If you must bootstrap a node using a **mainnet** snapshot, you should either generate the snapshot yourself or obtain it from a trusted source. You should also verify the snapshot's integrity and authenticity before using it (e.g., via cryptographic signatures and checksums).

## Find an existing snapshot

[](#find-an-existing-snapshot)

There are a number of snapshots that can be downloaded from different Aptos community members. These include:

*   BWareLabs (Testnet and Mainnet): [BWareLabs Aptos Node Snapshots](https://bwarelabs.com/snapshots/aptos)

Note

**Questions about snapshot data**  
Depending on how the snapshot is constructed and compressed, the snapshot files may be different sizes. If you have any questions about the snapshot data, or run into any issues, please reach out to the Aptos community members directly via the [#node-support](https://discord.com/channels/945856774056083548/953421979136962560) channel in [Aptos Discord](https://discord.gg/aptosnetwork).

## Use a snapshot

[](#use-a-snapshot)

To use a snapshot, simply download and copy the files to the location of the storage database for your node. This location can be found and updated in the fullnode `yaml` configuration file under `data_dir`. See the example tutorial ([Run a PFN](/network/nodes/full-node/deployments)) for how to configure the data directory.

# Building Aptos From Source

> Complete guide to building Aptos Core from source code including environment setup, dependencies installation, and build instructions for Linux, macOS, and Windows.

[CLI Binary releases are available](/build/cli), but if you want to build from source for an Aptos node or CLI, this is how.

## Supported operating systems

[](#supported-operating-systems)

Aptos can be built on various operating systems, including Linux, macOS. and Windows. Aptos is tested extensively on Linux and macOS, and less so on Windows. Here are the versions we use:

*   Linux - Ubuntu version 20.04 and 22.04
*   macOS - macOS Monterey and later
*   Microsoft Windows - Windows 10, 11 and Windows Server 2022+

## Clone the Aptos-core repo

[](#clone-the-aptos-core-repo)

1.  Install [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git). Git is required to clone the aptos-core repo, and will need to be installed prior to continuing. You can install it with the instructions on the official [Git website](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git).
    
2.  Clone the Aptos repository. To clone the Aptos repository (repo), you first need to open a command line prompt (Terminal on macOS / Linux, PowerShell on Windows). Then run the following command to clone the Git repository from GitHub.
    
    ```
    git clone https://github.com/aptos-labs/aptos-core.git
    ```
    
3.  Now let's go into the newly created directory `aptos-core` by _changing directory_ or `cd`ing into it:
    
    ```
    cd aptos-core
    ```

### (Optional) Check out release branch

[](#optional-check-out-release-branch)

Optionally, check out a release branch to install an Aptos node. We suggest you check out `devnet` for your first development. See [Choose a network](/network/nodes/networks) for an explanation of their differences.

Release Branches

*   [Devnet](#tab-panel-126)
*   [Testnet](#tab-panel-127)
*   [Mainnet](#tab-panel-128)

```
git checkout --track origin/devnet
```

```
git checkout --track origin/testnet
```

```
git checkout --track origin/mainnet
```

## Set up build dependencies

[](#set-up-build-dependencies)

Prepare your developer environment by installing the dependencies needed to build, test and inspect Aptos Core. No matter your selected mechanism for installing these dependencies, **it is imperative you keep your entire toolchain up-to-date**. If you encounter issues later, update all packages and try again.

macOS

**\> Using the automated script**

1.  Ensure you have `brew` package manager installed: [https://brew.sh/](https://brew.sh/)
2.  Run the dev setup script to prepare your environment:

```
./scripts/dev_setup.sh
```

3.  Update your current shell environment:

```
source ~/.cargo/env
```

Note

You can see the available options for the script by running

```
./scripts/dev_setup.sh --help
```

**\> Manual installation of dependencies**

If the script above doesn't work for you, you can install these manually, but it's **not recommended**.

1.  [Rust](https://www.rust-lang.org/tools/install)
2.  [CMake](https://cmake.org/download/)
3.  [LLVM](https://releases.llvm.org/)
4.  [LLD](https://lld.llvm.org/)

Linux

**\> Using the automated script**

1.  Run the dev setup script to prepare your environment:

```
./scripts/dev_setup.sh
```

2.  Update your current shell environment:

```
source ~/.cargo/env
```

Note

You can see the available options for the script by running

```
./scripts/dev_setup.sh --help
```

**\> Manual installation of dependencies**

If the script above does not work for you, you can install these manually, but it is **not recommended**:

1.  [Rust](https://www.rust-lang.org/tools/install).
2.  [CMake](https://cmake.org/download/).
3.  [LLVM](https://releases.llvm.org/).
4.  [libssl-dev](https://packages.ubuntu.com/jammy/libssl-dev) and [libclang-dev](https://packages.ubuntu.com/jammy/libclang-dev)

Windows

**\> Using the automated script**

1.  Open a PowerShell terminal as an administrator.
2.  Run the dev setup script to prepare your environment:

```
PowerShell -ExecutionPolicy Bypass -File ./scripts/windows_dev_setup.ps1
```

3.  Open a new PowerShell terminal after installing all dependencies

**\> Manual installation of dependencies**

1.  Install [Rust](https://www.rust-lang.org/tools/install).
2.  Install [LLVM](https://releases.llvm.org/). Visit their GitHub repository for the [latest prebuilt release](https://github.com/llvm/llvm-project/releases/tag/llvmorg-15.0.7).
3.  Install [Microsoft Visual Studio Build Tools for Windows](https://visualstudio.microsoft.com/downloads/#build-tools-for-visual-studio-2022). During setup, select "Desktop development with C++" and three additional options: MSVC C++ build tools, Windows 10/11 SDK, and C++ CMake tools for Windows.
4.  If on Windows ARM, install [Visual Studio](https://visualstudio.microsoft.com/vs).
5.  If not already installed during Visual Studio/Build Tools installation, install [CMake](https://cmake.org/download/).
6.  Open a new PowerShell terminal after installing all dependencies

### Additional Tools

[](#additional-tools)

If you used `scripts/dev_setup.sh` for macOS or Linux setup, additional tools are optionally available.

## Building Aptos

[](#building-aptos)

The simplest check that you have a working environment is to build everything and run the tests.

```
cargo buildcargo test -- --skip prover
```

If you have already installed the Move Prover Tools above then you don't need to skip the prover tests. To install the prover (optional), follow the [Prover guide](/build/smart-contracts/prover)

Other documentation of specific tools has recommended patterns for `cargo build` and `cargo run`

### Other resources

[](#other-resources)

*   [Run a Local Development Network](/network/nodes/localnet/local-development-network)
*   [Indexer](/build/indexer)
*   [Node Health Checker](/network/nodes/measure/node-health-checker)

# Configure a Node

> Understanding and configuring Aptos node internals including consensus observer, state sync, data pruning, telemetry, and node files.

This section contains tutorials for understanding and configuring Aptos node internals. These include:

*   ### [Consensus Observer](/network/nodes/configure/consensus-observer)
    
    [](#consensus-observer)
    
*   ### [State Synchronization](/network/nodes/configure/state-sync)
    
    [](#state-synchronization)
    
*   ### [Data Pruning](/network/nodes/configure/data-pruning)
    
    [](#data-pruning)
    
*   ### [Telemetry](/network/nodes/configure/telemetry)
    
    [](#telemetry)
    
*   ### [Locating Node Files](/network/nodes/configure/node-files-all-networks)
    
    [](#locating-node-files)

# Consensus Observer

> Configure consensus observer to reduce block synchronization time and transaction latencies for public fullnodes (PFNs) by 10-50%.

Consensus observer is a new data dissemination technique that reduces block synchronization time, and transaction latencies for Aptos fullnodes (i.e., VFNs and PFNs). It has been shown to reduce end-to-end transaction latencies in Mainnet by 10% to 50%, depending on the load (i.e., transactions per second).

More information on consensus observer can be found in the AIP: [AIP-93: Consensus Observer](https://github.com/aptos-foundation/AIPs/blob/main/aips/aip-93.md).

Tip

**Public Fullnodes (PFNs)**  
The configuration settings described in this document are for public fullnodes (PFNs) only. Consensus observer has already been enabled (by default) for validators and validator fullnodes (VFNs). It is not recommended to change the consensus observer configurations for validators and VFNs.

## Configure consensus observer

[](#configure-consensus-observer)

Caution

**Minimum Hardware Requirements**  
Consensus observer is not enabled on PFNs (by default) because it requires nodes to meet the [minimum hardware requirements](/network/nodes/full-node/pfn-requirements#hardware-requirements). If your node is under-provisioned and does not meet these requirements, enabling consensus observer will result in degraded performance because it requires more CPU than traditional state sync. Only enable consensus observer if your node meets the minimum hardware requirements.

### Enable consensus observer

[](#enable-consensus-observer)

To enable consensus observer on your PFN, add the following to your node configuration file:

```
consensus:  enable_pre_commit: false
consensus_observer:  observer_enabled: true  publisher_enabled: true
```

### Disable consensus observer

[](#disable-consensus-observer)

To disable consensus observer on your PFN, add the following to your node configuration file:

```
consensus:  enable_pre_commit: true
consensus_observer:  observer_enabled: false  publisher_enabled: false
```

# Data Pruning

> Configure blockchain data pruning on Aptos nodes to manage storage space by controlling ledger history retention with customizable pruning windows.

All Aptos nodes (e.g., validators, VFNs and PFNs) process transactions and commit new data to the blockchain. As the blockchain grows (indefinitely), nodes can manage the amount of storage disk space required by pruning old blockchain data. To achieve this, Aptos nodes prune the blockchain **ledger history** in their database, which contains the history of all transactions. The ledger history may be **complete** (e.g., if you're operating an archival node), or **pruned** to a certain window of transactions (to reduce storage requirements).

By default, ledger pruning is enabled on all nodes, and the pruning window can be configured. This document describes how you can configure the behavior of the ledger pruner.

Tip

**Default pruning window**  
The default configuration of the ledger pruner is to keep only the most recent 150 million transactions. Almost all Aptos nodes in Mainnet and Testnet use the default configuration. If you wish to run an archival node, follow the instructions [here](/network/nodes/configure/state-sync#archival-pfns).

## Disable the ledger pruner

[](#disable-the-ledger-pruner)

If you wish to disable the ledger pruner entirely, you can do so by adding the following to your node configuration file.

```
storage:  storage_pruner_config:    ledger_pruner_config:      enable: false
```

Danger

**Unbounded storage growth**  
Be warned that disabling the ledger pruner will result in unbounded storage growth. This can lead to the storage disk filling up very quickly. Disabling the ledger pruner is not recommended.

## Configure the ledger pruner

[](#configure-the-ledger-pruner)

You can configure the size of the ledger pruning window (i.e., the number of most recent transactions to retain in storage). To do this, add the following to your node configuration file.

```
storage:  storage_pruner_config:    ledger_pruner_config:      prune_window: 100000000 # 100 million transactions
```

Caution

**Minimum pruning window**  
Setting the pruning window smaller than 100 million transactions can lead to runtime errors and damage the health of the node.

# Locating Node Files

> Find and download required configuration files, genesis blobs, and waypoints for deploying Aptos nodes on mainnet, testnet, and devnet networks.

This section contains pages for locating and downloading the files required to deploy an Aptos node on different networks. These include:

*   ### [Files For Mainnet](/network/nodes/configure/node-files-all-networks/node-files-mainnet)
    
    [](#files-for-mainnet)
    
*   ### [Files For Testnet](/network/nodes/configure/node-files-all-networks/node-files-testnet)
    
    [](#files-for-testnet)
    
*   ### [Files For Devnet](/network/nodes/configure/node-files-all-networks/node-files-devnet)
    
    [](#files-for-devnet)

# Files For Devnet

> Download required configuration files, genesis blob, waypoint, and Docker compose files for deploying Aptos nodes on devnet.

When deploying an Aptos node in **devnet**, you may need to download the files listed on this page. The files are organized by node type.

Note

**File access**  
Depending on the type of node you are deploying, and the deployment method, you may need to download some or all of the files listed below.

## Validator Files

[](#validator-files)

All the files listed below are for validator nodes.

### docker-compose.yaml

[](#docker-composeyaml)

*   **Git repo:** `aptos-core`
*   **Git branch:** `devnet` on [https://github.com/aptos-labs/aptos-core](https://github.com/aptos-labs/aptos-core)
*   **Command to download:**
    
    ```
    wget -O docker-compose.yaml https://raw.githubusercontent.com/aptos-labs/aptos-core/devnet/docker/compose/aptos-node/docker-compose.yaml
    ```

### validator.yaml

[](#validatoryaml)

*   **Git repo:** `aptos-core`
*   **Git branch:** `devnet` on [https://github.com/aptos-labs/aptos-core](https://github.com/aptos-labs/aptos-core)
*   **Command to download:**
    
    ```
    wget -O validator.yaml https://raw.githubusercontent.com/aptos-labs/aptos-core/devnet/docker/compose/aptos-node/validator.yaml
    ```

### genesis.blob

[](#genesisblob)

*   **Git repo:** `aptos-networks`
*   **Git branch:** `main` on [https://github.com/aptos-labs/aptos-networks](https://github.com/aptos-labs/aptos-networks)
*   **Command to download:**
    
    ```
    wget -O genesis.blob https://raw.githubusercontent.com/aptos-labs/aptos-networks/main/devnet/genesis.blob
    ```

### waypoint.txt

[](#waypointtxt)

*   **Git repo:** `aptos-networks`
*   **Git branch:** `main` on [https://github.com/aptos-labs/aptos-networks](https://github.com/aptos-labs/aptos-networks)
*   **Command to download:**
    
    ```
    wget -O waypoint.txt https://raw.githubusercontent.com/aptos-labs/aptos-networks/main/devnet/waypoint.txt
    ```

### docker-compose-src.yaml

[](#docker-compose-srcyaml)

*   **Git repo:** `aptos-core`
*   **Git branch:** `devnet` on [https://github.com/aptos-labs/aptos-core](https://github.com/aptos-labs/aptos-core)
*   **Command to download:**
    
    ```
    wget -O docker-compose-src.yaml https://raw.githubusercontent.com/aptos-labs/aptos-core/devnet/docker/compose/aptos-node/docker-compose-src.yaml
    ```

### haproxy.cfg

[](#haproxycfg)

*   **Git repo:** `aptos-core`
*   **Git branch:** `devnet` on [https://github.com/aptos-labs/aptos-core](https://github.com/aptos-labs/aptos-core)
*   **Command to download:**
    
    ```
    wget -O haproxy.cfg https://raw.githubusercontent.com/aptos-labs/aptos-core/devnet/docker/compose/aptos-node/haproxy.cfg
    ```

### blocked.ips

[](#blockedips)

*   **Git repo:** `aptos-core`
*   **Git branch:** `devnet` on [https://github.com/aptos-labs/aptos-core](https://github.com/aptos-labs/aptos-core)
*   **Command to download:**
    
    ```
    wget -O blocked.ips https://raw.githubusercontent.com/aptos-labs/aptos-core/devnet/docker/compose/aptos-node/blocked.ips
    ```

## VFN or PFN files

[](#vfn-or-pfn-files)

The files listed below are for VFNs or PFNs.

### docker-compose-fullnode.yaml

[](#docker-compose-fullnodeyaml)

*   **Git repo:** `aptos-core`
*   **Git branch:** `devnet` on [https://github.com/aptos-labs/aptos-core](https://github.com/aptos-labs/aptos-core)
*   **Command to download:**
    
    ```
    wget -O docker-compose-fullnode.yaml https://raw.githubusercontent.com/aptos-labs/aptos-core/devnet/docker/compose/aptos-node/docker-compose-fullnode.yaml
    ```

### fullnode.yaml

[](#fullnodeyaml)

*   **Git repo:** `aptos-core`
*   **Git branch:** `devnet` on [https://github.com/aptos-labs/aptos-core](https://github.com/aptos-labs/aptos-core)
*   **Command to download:**
    
    ```
    wget -O fullnode.yaml https://raw.githubusercontent.com/aptos-labs/aptos-core/devnet/docker/compose/aptos-node/fullnode.yaml
    ```

### haproxy-fullnode.cfg

[](#haproxy-fullnodecfg)

*   **Git repo:** `aptos-core`
*   **Git branch:** `devnet` on [https://github.com/aptos-labs/aptos-core](https://github.com/aptos-labs/aptos-core)
*   **Command to download:**
    
    ```
    wget -O haproxy-fullnode.cfg https://raw.githubusercontent.com/aptos-labs/aptos-core/devnet/docker/compose/aptos-node/haproxy-fullnode.cfg
    ```

# Files For Mainnet

> Download required configuration files, genesis blob, waypoint, and Docker compose files for deploying Aptos nodes on mainnet.

When deploying an Aptos node in **mainnet**, you may need to download the files listed on this page. The files are organized by node type.

Note

**File access**  
Depending on the type of node you are deploying, and the deployment method, you may need to download some or all of the files listed below.

## Validator Files

[](#validator-files)

All the files listed below are for validator nodes.

### docker-compose.yaml

[](#docker-composeyaml)

*   **Git repo:** `aptos-core`
*   **Git branch:** `mainnet` on [https://github.com/aptos-labs/aptos-core](https://github.com/aptos-labs/aptos-core)
*   **Command to download:**
    
    ```
    wget -O docker-compose.yaml https://raw.githubusercontent.com/aptos-labs/aptos-core/mainnet/docker/compose/aptos-node/docker-compose.yaml
    ```

### validator.yaml

[](#validatoryaml)

*   **Git repo:** `aptos-core`
*   **Git branch:** `mainnet` on [https://github.com/aptos-labs/aptos-core](https://github.com/aptos-labs/aptos-core)
*   **Command to download:**
    
    ```
    wget -O validator.yaml https://raw.githubusercontent.com/aptos-labs/aptos-core/mainnet/docker/compose/aptos-node/validator.yaml
    ```

### genesis.blob

[](#genesisblob)

### waypoint.txt

[](#waypointtxt)

*   **Git repo:** `aptos-networks`
*   **Git branch:** `main` on [https://github.com/aptos-labs/aptos-networks](https://github.com/aptos-labs/aptos-networks)
*   **Command to download:**
    
    ```
    wget -O waypoint.txt https://raw.githubusercontent.com/aptos-labs/aptos-networks/main/mainnet/waypoint.txt
    ```

### docker-compose-src.yaml

[](#docker-compose-srcyaml)

*   **Git repo:** `aptos-core`
*   **Git branch:** `mainnet` on [https://github.com/aptos-labs/aptos-core](https://github.com/aptos-labs/aptos-core)
*   **Command to download:**
    
    ```
    wget -O docker-compose-src.yaml https://raw.githubusercontent.com/aptos-labs/aptos-core/mainnet/docker/compose/aptos-node/docker-compose-src.yaml
    ```

### haproxy.cfg

[](#haproxycfg)

*   **Git repo:** `aptos-core`
*   **Git branch:** `mainnet` on [https://github.com/aptos-labs/aptos-core](https://github.com/aptos-labs/aptos-core)
*   **Command to download:**
    
    ```
    wget -O haproxy.cfg https://raw.githubusercontent.com/aptos-labs/aptos-core/mainnet/docker/compose/aptos-node/haproxy.cfg
    ```

### blocked.ips

[](#blockedips)

*   **Git repo:** `aptos-core`
*   **Git branch:** `mainnet` on [https://github.com/aptos-labs/aptos-core](https://github.com/aptos-labs/aptos-core)
*   **Command to download:**
    
    ```
    wget -O blocked.ips https://raw.githubusercontent.com/aptos-labs/aptos-core/mainnet/docker/compose/aptos-node/blocked.ips
    ```

* * *

## VFN or PFN files

[](#vfn-or-pfn-files)

The files listed below are for VFNs or PFNs.

### docker-compose-fullnode.yaml

[](#docker-compose-fullnodeyaml)

*   **Git repo:** `aptos-core`
*   **Git branch:** `mainnet` on [https://github.com/aptos-labs/aptos-core](https://github.com/aptos-labs/aptos-core)
*   **Command to download:**
    
    ```
    wget -O docker-compose-fullnode.yaml https://raw.githubusercontent.com/aptos-labs/aptos-core/mainnet/docker/compose/aptos-node/docker-compose-fullnode.yaml
    ```

### fullnode.yaml

[](#fullnodeyaml)

*   **Git repo:** `aptos-core`
*   **Git branch:** `mainnet` on [https://github.com/aptos-labs/aptos-core](https://github.com/aptos-labs/aptos-core)
*   **Command to download:**
    
    ```
    wget -O fullnode.yaml https://raw.githubusercontent.com/aptos-labs/aptos-core/mainnet/docker/compose/aptos-node/fullnode.yaml
    ```

### haproxy-fullnode.cfg

[](#haproxy-fullnodecfg)

*   **Git repo:** `aptos-core`
*   **Git branch:** `mainnet` on [https://github.com/aptos-labs/aptos-core](https://github.com/aptos-labs/aptos-core)
*   **Command to download:**
    
    ```
    wget -O haproxy-fullnode.cfg https://raw.githubusercontent.com/aptos-labs/aptos-core/mainnet/docker/compose/aptos-node/haproxy-fullnode.cfg
    ```

# Files For Testnet

> Download required configuration files, genesis blob, waypoint, and Docker compose files for deploying Aptos nodes on testnet.

When deploying an Aptos node in **testnet**, you may need to download the files listed on this page. The files are organized by node type.

Note

**File access** Depending on the type of node you are deploying, and the deployment method, you may need to download some or all of the files listed below.

## Validator Files

[](#validator-files)

All the files listed below are for validator nodes.

### docker-compose.yaml

[](#docker-composeyaml)

*   **Git repo:** `aptos-core`
*   **Git branch:** `testnet` on [https://github.com/aptos-labs/aptos-core](https://github.com/aptos-labs/aptos-core)
*   **Command to download:**
    
    ```
    wget -O docker-compose.yaml https://raw.githubusercontent.com/aptos-labs/aptos-core/testnet/docker/compose/aptos-node/docker-compose.yaml
    ```

### validator.yaml

[](#validatoryaml)

*   **Git repo:** `aptos-core`
*   **Git branch:** `testnet` on [https://github.com/aptos-labs/aptos-core](https://github.com/aptos-labs/aptos-core)
*   **Command to download:**
    
    ```
    wget -O validator.yaml https://raw.githubusercontent.com/aptos-labs/aptos-core/testnet/docker/compose/aptos-node/validator.yaml
    ```

### genesis.blob

[](#genesisblob)

### waypoint.txt

[](#waypointtxt)

*   **Git repo:** `aptos-networks`
*   **Git branch:** `main` on [https://github.com/aptos-labs/aptos-networks](https://github.com/aptos-labs/aptos-networks)
*   **Command to download:**
    
    ```
    wget -O waypoint.txt https://raw.githubusercontent.com/aptos-labs/aptos-networks/main/testnet/waypoint.txt
    ```

### digest\_key.bin

[](#digest_keybin)

Validator-only trusted-setup material consumed by consensus. VFNs and PFNs do not need this file.

*   **Git repo:** `aptos-networks`
*   **Git branch:** `main` on [https://github.com/aptos-labs/aptos-networks](https://github.com/aptos-labs/aptos-networks)
*   **Command to download:**
    
    ```
    wget -O digest_key.bin https://github.com/aptos-labs/aptos-networks/raw/main/testnet/digest_key.bin
    ```

Note

This file is stored via Git LFS, so the download URL uses `github.com/.../raw/main/...` (which follows the LFS redirect) rather than `raw.githubusercontent.com`. The `wget` above is for **self-managed** deployments (source code or Docker); point `consensus.digest_key_blob_path` in `validator.yaml` at the on-disk location (for example `/opt/aptos/genesis/digest_key.bin`). **Helm/k8s** deployments do not download manually — the `aptos-node` chart fetches the blob via its init container. See [Update Trusted Setup](/network/nodes/validator-node/modify-nodes/update-trusted-setup) for the full per-deployment flow and verification steps.

### pp.bin

[](#ppbin)

Validator-only public-parameters blob consumed by consensus. VFNs and PFNs do not need this file.

*   **Git repo:** `aptos-networks`
*   **Git branch:** `main` on [https://github.com/aptos-labs/aptos-networks](https://github.com/aptos-labs/aptos-networks)
*   **Command to download:**
    
    ```
    wget -O pp.bin https://github.com/aptos-labs/aptos-networks/raw/main/testnet/pp.bin
    ```

Note

This file is stored via Git LFS, so the download URL uses `github.com/.../raw/main/...` (which follows the LFS redirect) rather than `raw.githubusercontent.com`. The `wget` above is for **self-managed** deployments (source code or Docker); point `consensus.public_parameters_blob_path` in `validator.yaml` at the on-disk location (for example `/opt/aptos/genesis/pp.bin`). **Helm/k8s** deployments do not download manually — the `aptos-node` chart fetches the blob via its init container. See [Update Trusted Setup](/network/nodes/validator-node/modify-nodes/update-trusted-setup) for the full per-deployment flow and verification steps.

### docker-compose-src.yaml

[](#docker-compose-srcyaml)

*   **Git repo:** `aptos-core`
*   **Git branch:** `testnet` on [https://github.com/aptos-labs/aptos-core](https://github.com/aptos-labs/aptos-core)
*   **Command to download:**
    
    ```
    wget -O docker-compose-src.yaml https://raw.githubusercontent.com/aptos-labs/aptos-core/testnet/docker/compose/aptos-node/docker-compose-src.yaml
    ```

### haproxy.cfg

[](#haproxycfg)

*   **Git repo:** `aptos-core`
*   **Git branch:** `testnet` on [https://github.com/aptos-labs/aptos-core](https://github.com/aptos-labs/aptos-core)
*   **Command to download:**
    
    ```
    wget -O haproxy.cfg https://raw.githubusercontent.com/aptos-labs/aptos-core/testnet/docker/compose/aptos-node/haproxy.cfg
    ```

### blocked.ips

[](#blockedips)

*   **Git repo:** `aptos-core`
*   **Git branch:** `testnet` on [https://github.com/aptos-labs/aptos-core](https://github.com/aptos-labs/aptos-core)
*   **Command to download:**
    
    ```
    wget -O blocked.ips https://raw.githubusercontent.com/aptos-labs/aptos-core/testnet/docker/compose/aptos-node/blocked.ips
    ```

## VFN or PFN files

[](#vfn-or-pfn-files)

The files listed below are for VFNs or PFNs.

## docker-compose-fullnode.yaml

[](#docker-compose-fullnodeyaml)

*   **Git repo:** `aptos-core`
*   **Git branch:** `testnet` on [https://github.com/aptos-labs/aptos-core](https://github.com/aptos-labs/aptos-core)
*   **Command to download:**
    
    ```
    wget -O docker-compose-fullnode.yaml https://raw.githubusercontent.com/aptos-labs/aptos-core/testnet/docker/compose/aptos-node/docker-compose-fullnode.yaml
    ```

## fullnode.yaml

[](#fullnodeyaml)

*   **Git repo:** `aptos-core`
*   **Git branch:** `testnet` on [https://github.com/aptos-labs/aptos-core](https://github.com/aptos-labs/aptos-core)
*   **Command to download:**
    
    ```
    wget -O fullnode.yaml https://raw.githubusercontent.com/aptos-labs/aptos-core/testnet/docker/compose/aptos-node/fullnode.yaml
    ```

## haproxy-fullnode.cfg

[](#haproxy-fullnodecfg)

*   **Git repo:** `aptos-core`
*   **Git branch:** `testnet` on [https://github.com/aptos-labs/aptos-core](https://github.com/aptos-labs/aptos-core)
*   **Command to download:**
    
    ```
    wget -O haproxy-fullnode.cfg https://raw.githubusercontent.com/aptos-labs/aptos-core/testnet/docker/compose/aptos-node/haproxy-fullnode.cfg
    ```

# State Synchronization

> Learn how state synchronization keeps Aptos nodes updated with the latest blockchain state including configuration options and syncing modes.

Nodes in an Aptos network (e.g., validators, VFNs and PFNs) must always be synchronized to the latest blockchain state. The [state synchronization](https://medium.com/aptoslabs/the-evolution-of-state-sync-the-path-to-100k-transactions-per-second-with-sub-second-latency-at-52e25a2c6f10) (state sync) component that runs on each node is responsible for this. State sync identifies and fetches new blockchain data from peers, validates the data and persists it to local storage. This document explains how to configure state sync on your node.

## State sync

[](#state-sync)

At a high-level, state sync operates in two phases. First, nodes bootstrap on startup (in the **bootstrapping phase**). This allows the node to catch up to the latest state in the Aptos blockchain. Then, the node will stay up-to-date with the blockchain by continuously syncing (in the **continuous syncing phase**).

Tip

**Need to start a node quickly? Here's what we recommend:**

*   **Mainnet**: To sync the entire blockchain history, restore from a [backup](/network/nodes/bootstrap-fullnode/aptos-db-restore). Otherwise, use [fast sync](/network/nodes/configure/state-sync#fast-syncing).
*   **Testnet**: To sync the entire blockchain history, restore from a [backup](/network/nodes/bootstrap-fullnode/aptos-db-restore). Otherwise, use [fast sync](/network/nodes/configure/state-sync#fast-syncing).
*   **Devnet**: To sync the entire blockchain history, use [intelligent syncing](/network/nodes/configure/state-sync#intelligent-syncing). Otherwise, use [fast sync](/network/nodes/configure/state-sync#fast-syncing).

### Bootstrapping modes

[](#bootstrapping-modes)

When the node starts, state sync will perform bootstrapping using the configured bootstrapping mode.

Tip

**Default bootstrapping modes?**

*   **Mainnet and Testnet**: The default bootstrapping mode is **fast syncing**, because these networks are long-lived and have a large amount of historical data.
*   **Devnet**: The default bootstrapping mode is **intelligent syncing from genesis**, because this network is short-lived and typically has a small amount of historical data.

There are several bootstrapping modes:

*   **Execute transactions from genesis**. This mode will fetch all transactions since genesis (i.e., the start of the blockchain's history), and re-execute each transaction. This mode is the slowest bootstrapping mode.
*   **Apply transaction outputs from genesis**. This mode will fetch all transactions since genesis (i.e., the start of the blockchain's history), but it will skip transaction re-execution and instead apply the outputs of the transactions as originally produced by validator execution.
*   **Intelligent syncing from genesis**. This mode is a hybrid of the previous two modes. It will fetch all transactions since genesis (i.e., the start of the blockchain's history), and will either execute the transactions, or apply the transaction outputs, depending on whichever is faster, per data chunk. This allows the node to adapt to CPU and network resource constraints more efficiently.
*   **Fast syncing**. This mode will fetch the latest blockchain state directly, skipping all historical transactions. As a result, the node will not have historical transaction data, but it will be able to catch up much more quickly.

Caution

**Syncing from genesis?**  
Most nodes in Mainnet and Testnet do not keep all transaction data since genesis. If you wish to sync all data since genesis, you need to manually add seed peers to node's configuration file, so that your node can connect to peers with the data. See [Connecting to Seed Peers](/network/nodes/full-node/modify/fullnode-network-connections#connecting-to-seed-peers).

### Continuous syncing modes

[](#continuous-syncing-modes)

After the node has bootstrapped, state sync will move into the continuous syncing phase to stay up-to-date with the blockchain.

Tip

**Default continuous syncing modes?**  
The default continuous syncing mode is always intelligent syncing, because this mode is the most performant.

There are several continuous syncing modes:

*   **Executing transactions**. This mode will keep the node up-to-date by executing transactions as they are committed to the blockchain.
*   **Applying transaction outputs**. This mode will keep the node up-to-date by skipping the transaction execution and only applying the outputs of the transactions as previously produced by validator execution.
*   **Intelligent syncing**. This mode will keep the node up-to-date by either executing the transactions, or applying the transaction outputs, depending on whichever is faster, per data chunk. This allows the node to adapt to CPU and network resource constraints more efficiently.

## Configuring state sync

[](#configuring-state-sync)

The snippets below provide instructions for configuring state sync on your nodes for different use cases. These configurations can be added to your node's configuration file, e.g., `fullnode.yaml` or `validator.yaml`.

Danger

**Do you need to configure state sync?**  
Most users should not need to configure state sync manually. State sync will automatically select the best configuration for your node and network. You should only configure state sync if you have a use case that requires it. Selecting the wrong configuration will lead to slower syncing times and degraded performance.

### Executing transactions from genesis

[](#executing-transactions-from-genesis)

To execute all transactions from genesis and continue to execute new transactions as they are committed, add the following to your node configuration file:

```
state_sync:  state_sync_driver:    bootstrapping_mode: ExecuteTransactionsFromGenesis    continuous_syncing_mode: ExecuteTransactions
```

### Applying transaction outputs from genesis

[](#applying-transaction-outputs-from-genesis)

To apply all transaction outputs from genesis and continue to apply new transaction outputs as transactions are committed, add the following to your node configuration file:

```
state_sync:  state_sync_driver:    bootstrapping_mode: ApplyTransactionOutputsFromGenesis    continuous_syncing_mode: ApplyTransactionOutputs
```

### Intelligent syncing from genesis

[](#intelligent-syncing-from-genesis)

To execute or apply all transactions and outputs since genesis (and continue to do the same as new transactions are committed), add the following to your node configuration file:

```
state_sync:  state_sync_driver:    bootstrapping_mode: ExecuteOrApplyFromGenesis    continuous_syncing_mode: ExecuteTransactionsOrApplyOutputs
```

### Fast syncing

[](#fast-syncing)

To download the latest blockchain state and continue to process new transactions as they are committed, add the following to your node configuration file:

```
state_sync:  state_sync_driver:    bootstrapping_mode: DownloadLatestStates    continuous_syncing_mode: ExecuteTransactionsOrApplyOutputs
```

## Verifying Syncing Progress

[](#verifying-syncing-progress)

To verify that your node is syncing correctly, you can monitor the relevant state sync metrics exposed by the [Node Inspection Service](/network/nodes/measure/node-inspection-service).

If your node is bootstrapping in **fast syncing** mode, you should monitor the following metric:

*   `aptos_state_sync_version{type="synced_states"}`: This metric indicates the highest blockchain state that has been processed. This metric will increase as your node fast syncs. Once all states have been downloaded, this metric will stop increasing and your node will begin processing transactions as usual.

During normal node operation, you should monitor the following metric:

*   `aptos_state_sync_version{type="synced"}`: This metric indicates the highest transaction version that has been fully processed by your node. This metric will increase as long as your node is syncing correctly.

Tip

**Fast syncing times**  
The speed of fast syncing depends on several factors, including your network bandwidth and disk performance. On most well-provisioned nodes, fast syncing usually completes within a few hours.

## Archival PFNs

[](#archival-pfns)

Danger

**Archival nodes are deprecated**  
Running archival nodes is expensive and slow, as the amount of data being stored on the node will grow indefinitely. As a result, archival nodes have officially been deprecated. If you wish to store and maintain the entire blockchain history, we recommend using an [Indexer](/build/indexer).

To operate an archival PFN (which is a PFN that contains all blockchain data since the start of the network, i.e., genesis), you can:

1.  Make sure that your PFN is **not** using fast syncing as the bootstrapping mode. Fast syncing will skip the transaction history. Instead, using a mode that syncs from genesis, e.g., intelligent syncing from genesis.
2.  Disable the ledger pruner, as described in the [Data Pruning document](/network/nodes/configure/data-pruning#disable-the-ledger-pruner). This will ensure that no data is deleted and the PFN contains all blockchain data.

Following these two steps together will ensure that your PFN fetches all data since genesis, and continues to synchronize without pruning any data.

Caution

**Syncing from genesis?**  
As mentioned above, if you wish to sync all data since genesis, you need to manually add seed peers to your node's configuration file. See [Connecting to Seed Peers](/network/nodes/full-node/modify/fullnode-network-connections#connecting-to-seed-peers).

## Security implications and data integrity

[](#security-implications-and-data-integrity)

All state syncing modes perform data integrity verifications to ensure that data is correct and appropriately signed by the validators. However, there are some differences in the security guarantees provided by each mode:

1.  **Executing transactions from genesis**: Executing transactions from genesis is the most secure syncing mode. It will verify that all transactions since the beginning of time were correctly agreed upon by consensus and that all transactions were appropriately executed by the validators.
2.  **Applying transaction outputs from genesis**: Applying transaction outputs from genesis requires that the syncing node trust the validators to have executed the transactions correctly. However, all other blockchain state is still manually re-verified, e.g., consensus messages, the transaction history and state hashes.
3.  **Intelligent syncing**: Intelligent syncing will either execute transactions or apply transaction outputs depending on whichever is faster, per data chunk. The security implications of using this mode are identical to above, depending on which method is used for each data chunk.
4.  **Fast syncing**: Fast syncing skips the transaction history and downloads the latest blockchain state before continuously syncing. To do this, it requires that the syncing node trust the validators to have correctly agreed upon all transactions in the transaction history as well as the results of executing those transactions. However, all other blockchain data is still manually re-verified, e.g., epoch changes and the resulting blockchain states.

All the syncing modes get their root of trust from the validator set and cryptographic signatures from those validators over the blockchain data. For more information about how this works, see the [state synchronization blog post](https://medium.com/aptoslabs/the-evolution-of-state-sync-the-path-to-100k-transactions-per-second-with-sub-second-latency-at-52e25a2c6f10).

# Telemetry

> Understanding and configuring telemetry data collection from Aptos nodes including what information is sent and how to disable it if needed.

When you run a node on an Aptos network, your node will send telemetry data to Aptos Labs. All node types (e.g., validators, VFNs and PFNs) send telemetry data. This also occurs for other binaries (e.g., the Aptos CLI). If you would prefer not to send telemetry, you can disable telemetry using the instructions below.

Tip

**No personal information is collected**  
Aptos telemetry does **not** collect personal information, such as usernames or email addresses. It only collects relevant software telemetry, such as software version, node metrics, operating system information and the IP address of your node. This data is used to enhance network decentralization and performance.

## Node telemetry

[](#node-telemetry)

The categories of information collected by Aptos node telemetry, for the `aptos-node` binary, are listed below:

*   **Core metrics:** Core metrics are those emitted by the core components of the `aptos-node` binary. These include, state sync, consensus, mempool and storage. You can see the full list of core metrics, [here](https://github.com/aptos-labs/aptos-core/blob/main/crates/aptos-telemetry/src/core_metrics.rs#L14-L29).
    
*   **Build information**: Rust build information, including the versions of Rust, cargo, the target architecture and the build tag are also collected. You can see the full list of build information, [here](https://github.com/aptos-labs/aptos-core/blob/main/crates/aptos-build-info/src/lib.rs#L8-L20).
    
*   **System information**: System information is also collected by node telemetry. This includes resource information (e.g., CPU, RAM, disk and network specifications) as well as operating system information. You can see the full list of system information, [here](https://github.com/aptos-labs/aptos-core/blob/main/crates/aptos-telemetry/src/system_information.rs#L14-L32).
    
*   **Network metrics:**: Network metrics are also collected by node telemetry. These include network information such as the number of connected peers, the number of inbound and outbound messages, and the size of messages sent and received. You can see the full list of network metrics, [here](https://github.com/aptos-labs/aptos-core/blob/main/crates/aptos-telemetry/src/network_metrics.rs#L12-L17).
    
*   **Prometheus metrics**: Prometheus metrics are also collected by node telemetry. These include runtime metrics for all the components of the `aptos-node` binary. You can see the full list of Prometheus metrics by visiting the metrics endpoint on your node using the [node inspection service](/network/nodes/measure/node-inspection-service).
    
*   **Node logs**: Logs of warn-level and higher are also collected by node telemetry. These are used to monitor the health of the network. You can identify these logs by filtering the logs for the `aptos-node` binary, locally.

## CLI telemetry

[](#cli-telemetry)

The categories of information collected by Aptos CLI telemetry, for the `aptos` CLI, are listed below:

*   **Command metrics**: Command metrics are those emitted by the CLI when a command is executed. These include the command itself, the latency of the command, and the success or failure of the command. You can see the full list of CLI metrics, [here](https://github.com/aptos-labs/aptos-core/blob/main/crates/aptos-telemetry/src/cli_metrics.rs#L12-L15).
    
*   **Build information**: Rust build information, including the versions of Rust, cargo, the target architecture and the build tag are also collected for the CLI. You can see the full list of build information, [here](https://github.com/aptos-labs/aptos-core/blob/main/crates/aptos-build-info/src/lib.rs#L8-L20).

## Disabling telemetry

[](#disabling-telemetry)

Danger

**Disabling telemetry?**  
Disabling telemetry is not recommended, as it helps the Aptos Labs team improve the performance and reliability of Aptos software. If you choose to disable telemetry, it will be much more difficult for the team to identify and debug any issues that you may be facing.

If there are specific privacy or compliance requirements that prevent you from sending telemetry, or if you have concerns with certain types of information being sent, please reach out to the Aptos Labs team to see how they can help.

On macOS and Linux, you can set the `APTOS_DISABLE_TELEMETRY` environment variable to disable the metrics sent by both the Aptos node and the Aptos CLI tool. To disable all telemetry, set `APTOS_DISABLE_TELEMETRY` environment to `true`:

```
export APTOS_DISABLE_TELEMETRY=true
```

The above command only disables telemetry for a single session in the current terminal where you run the command. To disable it permanently across all terminals and Aptos binary invocations, include it in your startup profile. For example:

```
echo "export APTOS_DISABLE_TELEMETRY=true" >> ~/.profilesource ~/.profile
```

## Configuring telemetry

[](#configuring-telemetry)

Tip

**Configuring telemetry?**  
If you find that you need to disable specific telemetry metrics or collections, consider reaching out to the Aptos Labs team first, to let them know. Aptos Labs actively considers making changes to telemetry based on user feedback.

You can also configure telemetry to disable specific telemetry metrics and collections. The environment variable list below shows the variables you can set to configure telemetry for Aptos nodes and the CLI:

*   `APTOS_DISABLE_TELEMETRY`: This disables all telemetry emission, including sending telemetry to the Google Analytics service (GA4).
*   `APTOS_FORCE_ENABLE_TELEMETRY`: This overrides the chain ID check and forces the Aptos node to send telemetry regardless of whether the remote service accepts it or not.
*   `APTOS_DISABLE_TELEMETRY_PUSH_METRICS`: This disables sending [Prometheus](https://prometheus.io/) metrics.
*   `APTOS_DISABLE_TELEMETRY_PUSH_LOGS`: This disables sending logs.
*   `APTOS_DISABLE_TELEMETRY_PUSH_EVENTS`: This disables sending custom events.
*   `APTOS_DISABLE_LOG_ENV_POLLING`: This disables the dynamic ability to send verbose logs.
*   `APTOS_DISABLE_PROMETHEUS_NODE_METRICS`: This disables sending the Aptos node resource metrics such as system CPU, memory, etc.

# Run a Public Fullnode

> Deploy and operate your own public fullnode (PFN) to synchronize with the Aptos blockchain and stay up-to-date with the latest state.

You can run your own public fullnode (PFN) to synchronize the state of the Aptos blockchain and stay up-to-date. PFNs replicate the entire state of the blockchain by syncing from other Aptos VFNs and PFNs. PFNs can be run by anyone. This section explains how to deploy a PFN and connect to an Aptos network. You can learn more about the different types of nodes in the [Blockchain Deep Dive](/network/blockchain) section.

Note

**Default connection to mainnet**  
If you follow the default setup in this document, then your PFN will be connected to the Aptos mainnet. To connect to a different Aptos network, such as devnet or testnet, make sure you have the correct docker image tag, or source code branch if you build the binary directly.

You can find the genesis and waypoint files for all the networks, here ➜ [https://github.com/aptos-labs/aptos-networks](https://github.com/aptos-labs/aptos-networks).

# Deploy a PFN

> Step-by-step guides for deploying a public fullnode (PFN) on Aptos networks using various deployment methods including source code, Docker, and cloud platforms.

The following guides provide step-by-step instructions for deploying a PFN on the Aptos networks.

Note

**Do I have to run a PFN?**  
If you do not wish to run a PFN, but still want to interact with the Aptos blockchain, you can use the REST API provided by the Aptos Labs' PFNs (see [Aptos APIs](/build/apis)). Note, however, that Aptos Labs-provided PFNs have rate limits, which can impede your development. You can get higher rate limits by creating an [Geomi](https://geomi.dev/) account and attaching a payment method. You can also deploy your own PFN and synchronize with the Aptos blockchain directly, or use a different node infrastructure provider.

Select the guide for the deployment method you prefer:

Caution

**Choose a network**  
These guides default to deploying a PFN in the Aptos mainnet network, but they can easily be used to do the same in other networks (e.g., devnet or testnet network). To do so, check out the desired network branch and use the `genesis.blob` and `waypoint.txt` node files for the respective branches: [mainnet](/network/nodes/configure/node-files-all-networks/node-files-mainnet), [devnet](/network/nodes/configure/node-files-all-networks/node-files-devnet), and [testnet](/network/nodes/configure/node-files-all-networks/node-files-testnet).

*   ### [Using Source Code](/network/nodes/full-node/deployments/using-source-code)
    
    [](#using-source-code)
    
*   ### [Using Docker](/network/nodes/full-node/deployments/using-docker)
    
    [](#using-docker)
    
*   ### [Using GCP](/network/nodes/full-node/deployments/using-gcp)
    
    [](#using-gcp)

# Using Docker

> Deploy a public fullnode (PFN) using Docker containers with automated configuration download and container setup for x86-64 systems.

This section describes how to configure and run your PFN using Docker.

Caution

**Supported only on x86-64 CPUs**  
Running aptos-core via Docker is currently only supported on x86-64 CPUs. If you have an Apple M1/M2 (ARM64) Mac, use the aptos-core source code approach (above). If M1/M2 support is important to you, comment on this issue: [https://github.com/aptos-labs/aptos-core/issues/1412](https://github.com/aptos-labs/aptos-core/issues/1412)

1.  First, install [Docker](https://docs.docker.com/get-docker/).
2.  Next, run the following script to prepare your local configuration and data directory for mainnet. This will download the `fullnode.yaml` configuration file, the `genesis.blob` and `waypoint.txt` files for your PFN, and create a `data` directory to store the blockchain database:

```
mkdir mainnet && cd mainnetmkdir data && \curl -O https://raw.githubusercontent.com/aptos-labs/aptos-core/mainnet/docker/compose/aptos-node/fullnode.yaml && \curl -O https://raw.githubusercontent.com/aptos-labs/aptos-networks/main/mainnet/waypoint.txt && \curl -O https://raw.githubusercontent.com/aptos-labs/aptos-networks/main/mainnet/genesis.blob
```

Caution

**Don't want to connect to mainnet?**  
To connect to other networks (e.g., `devnet` and `testnet`), you can find the genesis and waypoint here ➜ [https://github.com/aptos-labs/aptos-networks](https://github.com/aptos-labs/aptos-networks). Be sure to download the `genesis.blob` and `waypoint.txt` for those networks, instead of using the genesis and waypoint pointed to by the `curl` commands above.

3.  Next, make sure that the `fullnode.yaml` configuration file that you downloaded above contains only the following content. This will ensure that this configuration is for a PFN and not for another node type (e.g., validator or VFN):

```
base:  role: "full_node"  data_dir: "/opt/aptos/data"  waypoint:    from_file: "/opt/aptos/etc/waypoint.txt"
execution:  genesis_file_location: "/opt/aptos/etc/genesis.blob"
full_node_networks:  - network_id: "public"    discovery_method: "onchain"    listen_address: "/ip4/0.0.0.0/tcp/6182"
api:  enabled: true  address: "0.0.0.0:8080"
```

Caution

**Don't want to allow inbound connections?**  
Override the following if you do not want other PFNs connecting to yours: `listen_address: "/ip4/127.0.0.1/tcp/6182"`.

4.  Next, run the following `docker` command:

```
docker run --pull=always \  --rm -p 8080:8080 \  -p 9101:9101 -p 6180:6180 \  -v $(pwd):/opt/aptos/etc -v $(pwd)/data:/opt/aptos/data \  --workdir /opt/aptos/etc \  --name=aptos-fullnode aptoslabs/validator:mainnet aptos-node \  -f /opt/aptos/etc/fullnode.yaml
```

Caution

**Sudo access**  
Note: you may need to prefix the docker command with `sudo` depending on your configuration.

Note

**Docker tags**  
The `mainnet` tag always refers to the latest official Docker image tag. You can find the latest hash for comparison at: [https://github.com/aptos-labs/aptos-networks/tree/main/mainnet](https://github.com/aptos-labs/aptos-networks/tree/main/mainnet)

You have now successfully configured and started running a PFN in the Aptos mainnet.

Note

**Verify your PFN** If you want to verify that your PFN is running correctly, you can follow the instructions in the [Verify a PFN](/network/nodes/full-node/verify-pfn) guide.

# Using GCP

> Deploy a public fullnode (PFN) on Google Cloud Platform using Terraform and Kubernetes with comprehensive setup, validation, and monitoring instructions.

This tutorial explains how to configure and deploy a PFN using Google Cloud (GCP). Running a PFN in the cloud usually provides better stability and availability compared to running it on your laptop.

Caution

**Don't want to connect to devnet?**  
This tutorial defaults to deploying a PFN in the Aptos `devnet` network. To connect to other networks (e.g., `mainnet` and `testnet`), replace all instances of `devnet` with the appropriate network name.

## Prerequisites

[](#prerequisites)

You can run the commands in this guide to deploy your PFN on Google Kubernetes Engine from any machine you want, e.g. a [VM on GCP](https://cloud.google.com/compute), [Google Cloud Shell](https://cloud.google.com/shell), or your personal computer.

The following packages are pre-installed with Cloud Shell. **Make sure to review** the [documentation around ephemeral mode](https://cloud.google.com/shell/docs/using-cloud-shell/#choose_ephemeral_mode) if you choose to use Cloud Shell. However, if you are running the installation from your laptop or another machine, you need to install:

*   Terraform 1.3.6: [https://www.terraform.io/downloads.html](https://www.terraform.io/downloads.html)
*   Kubernetes CLI: [https://kubernetes.io/docs/tasks/tools/](https://kubernetes.io/docs/tasks/tools/)
*   Google Cloud CLI: [https://cloud.google.com/sdk/docs/install-sdk](https://cloud.google.com/sdk/docs/install-sdk)

After you have installed the gcloud CLI, [log into GCP using gcloud](https://cloud.google.com/sdk/gcloud/reference/auth/login):

```
gcloud auth login --update-adc
```

Note

**Already have a GCP account set up?**  
If you already have a GCP account setup, skip to [Getting Started](#getting-started). If you do not have a GCP account, then follow the below sections to create and configure your GCP account.

### GCP setup

[](#gcp-setup)

#### Sign up for the 90-day free trial

[](#sign-up-for-the-90-day-free-trial)

Google Cloud offers a \[90 day, 300 free trial for every new user\](https://cloud.google.com/free/docs/gcp-free-tier/#free-trial). The 300 are given as credits to your account and you can use them to get a sense of Google Cloud products. Some GCP feature such as GPUs and Windows servers are not available in the free trial. Sign up for the credits, [here](https://cloud.google.com/free).

#### Create a new GCP project

[](#create-a-new-gcp-project)

*   Create a new project on the GCP Console or using the gcloud command from the Google Cloud CLI. Be sure to familiarize yourself with the [resource hierarchy on GCP](https://cloud.google.com/resource-manager/docs/cloud-platform-resource-hierarchy).
*   [Follow these instructions to setup a new project](https://cloud.google.com/resource-manager/docs/creating-managing-projects#creating_a_project).

#### Enable billing, upgrade your account

[](#enable-billing-upgrade-your-account)

You will still be able to use the free trial credits, but enabling billing allows you to have full access to all the features of GCP and not experience any interruption to your nodes. [Upgrade your account by following the steps outlined here.](https://cloud.google.com/free/docs/gcp-free-tier#how-to-upgrade)

#### Additional GCP resources

[](#additional-gcp-resources)

This should be enough to get your GCP setup ready to start deploying your PFN. But if you are new to GCP, you may want to check out some of their [guides](https://cloud.google.com/docs/get-started/quickstarts) and [Google Cloud Skills Boost](https://www.cloudskillsboost.google/catalog).

## Getting started

[](#getting-started)

Note

**Before you proceed**  
From here on, this guide assumes that you have already set up your GCP account, and have created a new project for deploying an Aptos PFN.

You can deploy a PFN on GCP by using the Aptos Terraform module.

1.  Create a working directory for your configuration.
    
    *   Choose a workspace name e.g. `devnet`. **Note**: This defines the Terraform workspace name, which in turn is used to form resource names. Feel free to choose a different name if you are connecting to a different network.
    
    ```
    export WORKSPACE=devnet
    ```
    
    *   Create a directory for the workspace
    
    ```
    mkdir -p ~/$WORKSPACE
    ```
    
2.  Create a storage bucket for storing the Terraform state on Google Cloud Storage. Use the console or this gcs command to create the bucket. The name of the bucket must be unique. See the Google Cloud Storage documentation, [here](https://cloud.google.com/storage/docs/creating-buckets#prereq-cli).

```
gsutil mb gs://BUCKET_NAME# for examplegsutil mb gs://<project-name>-aptos-terraform-dev
```

3.  Create Terraform file called `main.tf` in your working directory:

```
cd ~/$WORKSPACEtouch main.tf
```

4.  Modify the `main.tf` file to configure Terraform and create a PFN from the Terraform module.

**Note:** If you are using a different version of Terraform, you will need to use the `tfenv` command to change the required version.

You can find the Docker image tag for `devnet` on the [Aptos Docker Hub](https://hub.docker.com/r/aptoslabs/validator/tags?page=1&ordering=last_updated&name=devnet).

Caution

**Want to connect to a different network?**  
If you wish to connect to a different network than `devnet`, you will need to find the appropriate Docker image tag for that network and replace all references to it.

Example content for `main.tf`:

```
terraform {  required_version = "~> 1.3.6"  backend "gcs" {    bucket = "BUCKET_NAME" # bucket name created in step 2    prefix = "state/fullnode"  }}
module "fullnode" {  # download Terraform module from aptos-labs/aptos-core repo  source        = "github.com/aptos-labs/aptos-core.git//terraform/fullnode/gcp?ref=main"  region        = "us-central1"  # Specify the region  zone          = "c"            # Specify the zone suffix  project       = "gcp-fullnode" # Specify your GCP project ID  fullnode_name = "BUCKET_NAME" #bucket name created in step 2  era           = 1              # bump era number to wipe the chain  image_tag     = "devnet" # Specify the docker image tag}
```

5.  Initialize Terraform in the same directory of your `main.tf` file:

```
terraform init
```

This will download all the Terraform dependencies into the `.terraform` folder.

6.  Create a new Terraform workspace to isolate your environments:

```
terraform workspace new $WORKSPACE# This command will list all workspacesterraform workspace list
```

7.  Apply the configuration:

```
terraform apply
```

This might take a while to finish (10 - 20 minutes), Terraform will create all the resources on your cloud account.

## Validation

[](#validation)

Once Terraform apply finishes, you can follow this section to validate your deployment.

1.  Configure your Kubernetes client to access the cluster you just deployed:

```
gcloud container clusters get-credentials aptos-$WORKSPACE --zone <region_zone_name> --project <project_name># for example:gcloud container clusters get-credentials aptos-devnet --zone us-central1-a --project aptos-fullnode
```

2.  Check that your PFN pods are now running (this may take a few minutes):

```
kubectl get pods -n aptos
```

You should see this:

```
NAME                       READY   STATUS    RESTARTS   AGEdevnet0-aptos-fullnode-0   1/1     Running   0          56s
```

3.  Get your PFN IP:

```
kubectl get svc -o custom-columns=IP:status.loadBalancer.ingress -n aptos
```

You should see something like this:

```
[map[ip:104.198.36.142]]
```

4.  Check the REST API, make sure that the ledger version is increasing:

```
curl http://<IP>/v1# Example command syntax: curl http://104.198.36.142/v1
```

You should see this something like this:

```
{  "chain_id": 25,  "epoch": "22",  "ledger_version": "9019844",  "oldest_ledger_version": "0",  "ledger_timestamp": "1661620200131348",  "node_role": "full_node",  "oldest_block_height": "0",  "block_height": "1825467"}
```

5.  To verify the correctness of your PFN, you will need to:
    
    *   Set up a port-forwarding mechanism directly to the Aptos pod in one ssh terminal, and
    *   Test it in another ssh terminal.
    
    Follow the below steps:
    
    *   Set up the port-forwarding to the aptos-fullnode pod. Use `kubectl get pods -n aptos` to get the name of the pod:
        
        ```
        kubectl port-forward -n aptos <pod-name> 9101:9101# for example:kubectl port-forward -n aptos devnet0-aptos-fullnode-0 9101:9101
        ```
        
    *   Open a new ssh terminal. Execute the following curl calls to verify the correctness:
        
        ```
        curl -v http://0:9101/metrics 2> /dev/null | grep "aptos_state_sync_version{type=\"synced\"}"
        curl -v http://0:9101/metrics 2> /dev/null | grep "aptos_connections{direction=\"outbound\""
        ```
        
    *   Exit port-forwarding when you are done by entering control-c in the terminal.

## PFN identity and seed peers

[](#pfn-identity-and-seed-peers)

### Static identity

[](#static-identity)

If you want to configure your node with a static identity, first see the [Generate a PFN Identity](/network/nodes/full-node/modify/network-identity-fullnode) tutorial to generate a static identity, and then follow the below instructions to configure your Terraform file.

1.  Generate a static identity for your PFN by following the guide: [Creating a static identity for a PFN](/network/nodes/full-node/modify/network-identity-fullnode#generate-a-static-identity).
    
2.  Modify the `main.tf` to add `fullnode_identity` entries in `fullnode_helm_values`. This will configure the identity for the PFN. Insert the correct values for your PFN's identity attributes. For example:

3.  Apply Terraform changes:

```
terraform apply
```

### Seed peers

[](#seed-peers)

You can add seed peers to allow your PFN to connect to specific nodes. See the guide [Customize PFN Networks](/network/nodes/full-node/modify/fullnode-network-connections) for more information.

1.  Obtain the seed peer information.
    
2.  Modify the `main.tf` to add the seed peers in `fullnode_helm_values`. This will configure the seeds for the PFN. For example:

```
module "fullnode" {  # download Terraform module from aptos-labs/aptos-core repo  source        = "github.com/aptos-labs/aptos-core.git//terraform/fullnode/gcp?ref=main"  region        = "us-central1"  # Specify the region  zone          = "c"            # Specify the zone suffix  project       = "gcp-fullnode" # Specify your GCP project name  era           = 1              # bump era number to wipe the chain  image_tag     = "dev_5b525691" # Specify the docker image tag to use
  fullnode_helm_values = {    # add a list of peers as upstream    aptos_chains = {      devnet = {        seeds = {          "bb14af025d226288a3488b4433cf5cb54d6a710365a2d95ac6ffbd9b9198a86a" = {          addresses = ["/dns4/pfn0.node.devnet.aptoslabs.com/tcp/6182/noise-ik/bb14af025d226288a3488b4433cf5cb54d6a710365a2d95ac6ffbd9b9198a86a/handshake/0"]          role = "Upstream"          },          "7fe8523388084607cdf78ff40e3e717652173b436ae1809df4a5fcfc67f8fc61" = {          addresses = ["/dns4/pfn1.node.devnet.aptoslabs.com/tcp/6182/noise-ik/7fe8523388084607cdf78ff40e3e717652173b436ae1809df4a5fcfc67f8fc61/handshake/0"]          role = "Upstream"          },          "f6b135a59591677afc98168791551a0a476222516fdc55869d2b649c614d965b" = {          addresses = ["/dns4/pfn2.node.devnet.aptoslabs.com/tcp/6182/noise-ik/f6b135a59591677afc98168791551a0a476222516fdc55869d2b649c614d965b/handshake/0"]          role = "Upstream"          }        }      }    }  }}
```

3.  Apply Terraform changes:

```
terraform apply
```

## Check logging

[](#check-logging)

To check the logs of the pod, use the following commands:

```
# Get a list of the podskubectl get pods -n aptos
# Get logs of the podkubectl logs <pod-name> -n aptos# for example:kubectl logs devnet0-aptos-fullnode-0 -n aptos
```

When using GKE, the logs of the cluster and pod will automatically show up in the Google Cloud console. From the console menu, choose `Kubernetes Engine`. From the side menu, choose `Workloads`. You will see all the pods from the cluster listed.

![GKE Workloads screenshot](/_vercel/image?url=_astro%2Ftutorial-gcp-logging1.D_qwPwxW.png&w=1280&q=100&dpl=dpl_BVzupKm7aQfXg1N3qg98Mi3YEbWs "GKE Workloads screenshot")

The `devnet0-aptos-fullnode` is the pod that is running the aptos fullnode container. Click on the pod to view details. You will see some metrics and other details about the pod.

![GKE Workloads Pod screenshot](/_vercel/image?url=_astro%2Ftutorial-gcp-logging2.CNkBiQCe.png&w=1280&q=100&dpl=dpl_BVzupKm7aQfXg1N3qg98Mi3YEbWs "GKE Workloads Pod screenshot")

Click the `LOGS` tab to view the logs directly from the pod. If there are errors in the pod, you will see them here.

![GKE Workloads Pod Logs screenshot](/_vercel/image?url=_astro%2Ftutorial-gcp-logging3.zCOzOb1M.png&w=1280&q=100&dpl=dpl_BVzupKm7aQfXg1N3qg98Mi3YEbWs "GKE Workloads Pod Logs screenshot")

Click the `open in new window` icon to view the logs in the Log Explorer. This screen allows advanced searching in the logs.

![GKE Workloads Pod Logs Explorer screenshot](/_vercel/image?url=_astro%2Ftutorial-gcp-logging4.ChvZ5CLB.png&w=1280&q=100&dpl=dpl_BVzupKm7aQfXg1N3qg98Mi3YEbWs "GKE Workloads Pod Logs Explorer screenshot")

Other logging insights are available in the Logs Dashboard

![GKE Workloads Pod Logs Dashboard screenshot](/_vercel/image?url=_astro%2Ftutorial-gcp-logging5.C2IQY7yE.png&w=1280&q=100&dpl=dpl_BVzupKm7aQfXg1N3qg98Mi3YEbWs "GKE Workloads Pod Logs Dashboard screenshot")

Additional [features](https://cloud.google.com/logging/docs) are available through [Cloud Logging](https://cloud.google.com/logging), including creating log-based metrics, logging sinks and log buckets.

## Check monitoring

[](#check-monitoring)

Google cloud captures many metrics from the cluster and makes them easily viewable in the console. From the console menu, choose `Kubernetes Engine`. Click on the cluster that aptos is deployed to. Click on the `Operations` link at the top right. Click on the `Metrics` sub-tab to view specific cluster metrics.

![GKE Monitoring metrics screenshot](/_vercel/image?url=_astro%2Ftutorial-gcp-mon1.BBHDDFJG.png&w=1280&q=100&dpl=dpl_BVzupKm7aQfXg1N3qg98Mi3YEbWs "GKE Monitoring metrics screenshot")

Click the `View in Cloud Monitoring` link at the top to view the built-in GKE [dashboard](https://cloud.google.com/stackdriver/docs/solutions/gke/observing) for the cluster.

![GKE Monitoring dashboard screenshot](/_vercel/image?url=_astro%2Ftutorial-gcp-mon2.0RE-w4Zj.png&w=1280&q=100&dpl=dpl_BVzupKm7aQfXg1N3qg98Mi3YEbWs "GKE Monitoring dashboard screenshot")

Google Cloud [Monitoring](https://cloud.google.com/monitoring) has many other features to easily monitor the cluster and pods. You can configure [uptime checks](https://cloud.google.com/monitoring/uptime-checks/introduction) for the services and configure [alerts](https://cloud.google.com/monitoring/alerts/using-alerting-ui) for when the metrics reach a certain [threshold](https://cloud.google.com/stackdriver/docs/solutions/slo-monitoring/sli-metrics/overview).

Note

**Verify your PFN**  
If you want to verify that your PFN is running correctly, you can follow the instructions in the [Verify a PFN](/network/nodes/full-node/verify-pfn) guide.

# Using Source Code

> Deploy a public fullnode (PFN) by building from aptos-core source code with complete configuration and setup instructions.

To deploy a PFN using the `aptos-core` source code, first, see [Building Aptos From Source](/network/nodes/building-from-source) for instructions on how to download the `aptos-core` repository and build the binary. Then, follow the steps below:

1.  Make sure your current working directory is `aptos-core`.
    
2.  Check out the `mainnet` branch using `git checkout --track origin/mainnet`; remember, you may instead use `devnet` or `testnet` if you wish to run your PFN in a different network.
    
3.  Next, download the `genesis.blob` and `waypoint.txt` files for the network your PFN will connect to:
    
    *   Run this command to download the genesis blob (for mainnet):
        
        ```
        curl -O https://raw.githubusercontent.com/aptos-labs/aptos-networks/main/mainnet/genesis.blob
        ```
        
    *   Run this command to download the waypoint file (for mainnet):
        
        ```
        curl -O https://raw.githubusercontent.com/aptos-labs/aptos-networks/main/mainnet/waypoint.txt
        ```
        
    
    Caution
    
    **Don't want to connect to mainnet?**  
    To connect to other networks (e.g., `devnet` and `testnet`), you can find the genesis and waypoint here ➜ [https://github.com/aptos-labs/aptos-networks](https://github.com/aptos-labs/aptos-networks). Be sure to download the `genesis.blob` and `waypoint.txt` for those networks, instead of using the genesis and waypoint pointed to by the `curl` commands above.
    
4.  Next, run the command below to create a copy of the PFN configuration YAML template:
    
    ```
    cp config/src/config/test_data/public_full_node.yaml fullnode.yaml
    ```
    
5.  Finally, edit the `fullnode.yaml` configuration file to ensure that your PFN: (i) contains the genesis blob and waypoint file you just downloaded; and (ii) saves the synchronized blockchain data to the location of your choice (on your local machine). To do this:
    
    1.  Specify the correct path to the `genesis.blob` file you just downloaded by editing `execution.genesis_file_location` in the `fullnode.yaml` configuration. By default, it points to `genesis.blob` in the current working directory.
        
        ```
        execution:  genesis_file_location: "./genesis.blob"
        ```
        
    2.  Specify the correct path to the `waypoint.txt` file you just downloaded by editing `base.waypoint.from_file` in the `fullnode.yaml` configuration. By default, it points to `waypoint.txt` in the current working directory. For example:
        
        ```
        base:  waypoint:    from_file: "./waypoint.txt"
        ```
        
    3.  Specify the directory on your local machine that you want to store the blockchain database by editing the `base.data_dir` in the `fullnode.yaml` configuration. For example, you can create a directory `my-full-node/data` in your home directory and specify it as:
        
        ```
        base:  data_dir: "</path/to/my/homedir/my-full-node/data>"
        ```
        
6.  Start your local public fullnode by running the below command:

```
cargo run -p aptos-node --release -- -f ./fullnode.yaml
```

Note

**Debugging?**  
The command above will build a release binary for `aptos-node` at: `aptos-core/target/release/aptos-node`. The release binaries tend to be substantially faster than debug binaries but lack debugging information useful for development. To build a debug binary, omit the `--release` flag from the command above.

You have now successfully configured and started running a PFN in the Aptos mainnet.

Note

**Verify your PFN**  
If you want to verify that your PFN is running correctly, you can follow the instructions in the [Verify a PFN](/network/nodes/full-node/verify-pfn) guide.

# Modify a PFN

> Common operations and modifications for public fullnodes (PFN) including upgrades, identity generation, and network customization.

This section contains tutorials for performing common operations and modifications to a PFN. These include:

*   ### [Upgrade your PFN](/network/nodes/full-node/modify/update-fullnode-with-new-releases)
    
    [](#upgrade-your-pfn)
    
*   ### [Generate a PFN Identity](/network/nodes/full-node/modify/network-identity-fullnode)
    
    [](#generate-a-pfn-identity)
    
*   ### [Customize PFN Networks](/network/nodes/full-node/modify/fullnode-network-connections)
    
    [](#customize-pfn-networks)

# Customize PFN Networks

> Advanced network configuration options for public fullnodes (PFN) including seed peers, static identities, and private network setups.

Caution

**Advanced customization**  
Most PFN operators will not need to customize their PFN's network connections. This is only required for advanced use cases, such as connecting to specific peers, or configuring a private PFN. If you do not have a relevant use case, you should avoid making changes to your PFN's network connections.

When running a PFN, you can configure your node's network connections for a few different purposes. For example, you can add a seed peer to your node's configuration to connect your node to a specific peer of your choosing. Or you can leverage a static network identity for your PFN to allow other nodes to connect to you, as described in [Generate a PFN Identity](/network/nodes/full-node/modify/network-identity-fullnode).

This document outlines how to configure the network of your PFN for different use cases, including:

*   Allowing nodes to connect to your PFN.
*   Connecting your PFN to seed peers.
*   Configuring priority access for other PFNs.
*   Configuring your PFN as a private PFN.

## Allowing PFN connections

[](#allowing-pfn-connections)

Note

**Generate a static identity**  
Before allowing other nodes to connect to your PFN, you will need to create a static identity. See [Generate a PFN Identity](/network/nodes/full-node/modify/network-identity-fullnode).

Once you start your PFN with a static identity you can allow others to connect to your PFN:

Note

**Default port settings**  
In the steps below, the port numbers used are for illustration only. You can use your choice of port numbers. See [PFN Requirements](/network/nodes/full-node/pfn-requirements) for more information on port settings.

*   Make sure you open the TCP port of the network you wish to allow external connections on (e.g., `6180` or `6182`). This is required to allow other nodes to connect to your PFN.
*   If you are using Docker, simply add `- "6180:6180"` or `- "6182:6182"` under ports in your `docker-compose.yaml` file.
*   Share your PFN static network identity with others. They can then use it in the `seeds` key of their node's configuration file to connect to your PFN. See the section below.
*   Make sure the port number you put in the `addresses` matches the one you have in the PFN configuration file (for example, `6180` or `6182`).

Note

You can share your PFN's network identity in our Discord to advertise your node for others to connect to. Note: this is optional (and not required!).

The snippets below show the configuration file entries and format for allowing other nodes to connect to your PFN. The format of each seed peer entry should have a unique `peer_id`, list of `addresses`, and a `role`:

```
<Peer_ID>:  addresses:  # with DNS  - "/dns4/<DNS_Name>/tcp/<Port_Number>/noise-ik/<Public_Key>/handshake/0"  role: Upstream<Peer_ID>:  addresses:  # with IP  - "/ip4/<IP_Address>/tcp/<Port_Number>/noise-ik/<Public_Key>/handshake/0"  role: Upstream
```

For example:

```
B881EA2C174D8211C123E5A91D86227DB116A44BB345A6E66874F83D8993F813:  addresses:  - "/dns4/pfn0.node.devnet.aptoslabs.com/tcp/6182/noise-ik/B881EA2C174D8211C123E5A91D86227DB116A44BB345A6E66874F83D8993F813/handshake/0"  role: "Upstream"B881EA2C174D8211C123E5A91D86227DB116A44BB345A6E66874F83D8993F813:  addresses:  - "/ip4/100.20.221.187/tcp/6182/noise-ik/B881EA2C174D8211C123E5A91D86227DB116A44BB345A6E66874F83D8993F813/handshake/0"  role: "Upstream"
```

## Connecting to seed peers

[](#connecting-to-seed-peers)

Caution

**Seeds are not required**  
Seed peers are not usually required for your PFN to connect to any Aptos network. All Aptos networks are automatically discoverable. Adding seed peers should only be done if you wish to connect to a specific peer or set of peers (e.g., if you wish to sync historical data that is not available through regular peers).

To add seed peers to your PFN, the seed peers' addresses should be added to your PFN configuration file, under the `seeds` key in the public network configuration. Each seed peer entry should have a unique `peer_id`, list of `addresses`, and a `role` (e.g., `Upstream`). The snippet below shows an example of a configuration file with seed peers manually added:

```
full_node_networks:  - discovery_method: "onchain"    listen_address: ...    seeds: # All seeds are declared below      bb14af025d226288a3488b4433cf5cb54d6a710365a2d95ac6ffbd9b9198a86a:        addresses:          - "/dns4/pfn0.node.devnet.aptoslabs.com/tcp/6182/noise-ik/bb14af025d226288a3488b4433cf5cb54d6a710365a2d95ac6ffbd9b9198a86a/handshake/0"        role: "Upstream"      7fe8523388084607cdf78ff40e3e717652173b436ae1809df4a5fcfc67f8fc61:        addresses:          - "/dns4/pfn1.node.devnet.aptoslabs.com/tcp/6182/noise-ik/7fe8523388084607cdf78ff40e3e717652173b436ae1809df4a5fcfc67f8fc61/handshake/0"        role: "Upstream"      f6b135a59591677afc98168791551a0a476222516fdc55869d2b649c614d965b:        addresses:          - "/dns4/pfn2.node.devnet.aptoslabs.com/tcp/6182/noise-ik/f6b135a59591677afc98168791551a0a476222516fdc55869d2b649c614d965b/handshake/0"        role: "Upstream"
```

## Configuring priority access

[](#configuring-priority-access)

To configure your PFN to allow other nodes to connect to it even when your PFN has hit the maximum number of available network connections, follow this method:

In the configuration file for your PFN add the other node as a seed peer with the `Downstream` role. This will allow the other node to connect directly to you with priority access. For example:

```
seeds:  <other node's peer id>    addresses:    - <address of the other node>    role: Downstream # Allows the node to connect to us
```

Similarly, to make the other node dial out to your PFN, add the following to the other node's configuration file:

```
seeds:  <your node's peer id>    addresses:    - <address of your npde>    role: PreferredUpstream # Allows the node to connect to the seed peer
```

## Configuring private PFNs

[](#configuring-private-pfns)

You can also configure your PFN as a private PFN should you wish. What this means is that your PFN will not allow unauthenticated connections, specifically, any node that is not a validator, VFN or seed peer will be unable to connect to your PFN.

To configure your PFN as a private PFN, add the following to your PFN configuration file. Note, you should add this to the public network entry in the `full_node_networks` configuration:

```
...full_node_networks:  - discovery_method: "onchain"    listen_address: ...    max_inbound_connections: 0  # Prevents any unauthenticated inbound connections    mutual_authentication: true  # Requires authenticated connections    ......
```

# Generate a PFN Identity

> Learn about ephemeral vs. static identities for public fullnodes (PFN) and how to generate unique network identities for monitoring and persistence.

Danger

Validators and VFNs have their identities initialized when first created and their identities are long-lived (immutable). PFN identities are more ephemeral and can be regenerated. As such, generating an identity using this guide **should only be done for PFNs**, and not for validators or VFNs.

## Ephemeral vs. Static Identities

[](#ephemeral-vs-static-identities)

Public fullnodes (PFNs) will automatically start up with a randomly generated (ephemeral) network identity unless a static identity is provided. This works well for regular PFNs. However, there are cases where you may want to generate and assign a static network identity to your PFN (e.g., for monitoring purposes).

Caution

PFN identities should be unique across the network. If you are running multiple PFNs, make sure to generate a unique identity for each PFN. Attempting to share the same identity across multiple PFNs will result in degraded node performance.

### Ephemeral Identity

[](#ephemeral-identity)

*   Automatically generated on node startup. The same ephemeral identity is used across restarts if the identity key file already exists.
*   By default, the identity file is stored at `/opt/aptos/data/db/ephemeral_identity_key`.

### Static Identity

[](#static-identity)

This is useful when:

*   You wish to advertise your PFN as a seed (i.e., for other Aptos PFNs to connect to).
*   You wish to add your PFN to an allowlist of known identities on an upstream PFN or VFN.
*   You wish to fix the identity of your PFN across restarts and releases so that telemetry and other monitoring tools can track your PFN over time.

## Generate a static identity

[](#generate-a-static-identity)

To create a static identity for your PFN, you will first need to generate a private and public key pair. You will then need to derive the `peer_id` from the public key, and use the `peer_id` in your configuration file (e.g., `fullnode.yaml`) to configure the static network identity for your PFN.

The steps below will guide you through the process of generating a static identity for your PFN. The exact steps depend on whether you are using the `aptos-core` source code to run your PFN, or Docker.

### Using the aptos-core source code

[](#using-the-aptos-core-source-code)

If you use the `aptos-core` source code to run your PFN, follow these steps:

1.  **Generate the private key**

First, use the [Aptos CLI](/build/cli) (`aptos`) to produce a hex encoded static x25519 private key. This will be the private key for your network identity. Run the following `aptos` CLI command:

```
aptos key generate --key-type x25519 --output-file /path/to/private-key.txt
```

This command will create a file `private-key.txt` with the private key in it, and a corresponding `private-key.txt.pub` file with the public key in it. An example `private-key.txt` file and `private-key.txt.pub` file are shown below:

```
cat ~/private-key.txtC83110913CBE4583F820FABEB7514293624E46862FAE1FD339B923F0CACC647D%
cat ~/private-key.txt.pubB881EA2C174D8211C123E5A91D86227DB116A44BB345A6E66874F83D8993F813%
```

2.  **Retrieve the peer identity**

Next, retrieve the peer identity from the public key using the `aptos` CLI. The `--host` flag in the command will provide the host information to output a network address for your PFN. Run the following command (be sure to update the `--host` flag with your actual host information):

```
aptos key extract-peer --host example.com:6180 \    --public-network-key-file private-key.txt.pub \    --output-file peer-info.yaml
```

This command will output the public identity information for your PFN to a file `peer-info.yaml`. For example:

```
{  "Result": {    "B881EA2C174D8211C123E5A91D86227DB116A44BB345A6E66874F83D8993F813": {      "addresses": [        "/dns/example.com/tcp/6180/noise-ik/0xB881EA2C174D8211C123E5A91D86227DB116A44BB345A6E66874F83D8993F813/handshake/0"      ],      "keys": [        "0xB881EA2C174D8211C123E5A91D86227DB116A44BB345A6E66874F83D8993F813"      ],      "role": "Upstream"    }  }}
```

In this example, `B881EA2C174D8211C123E5A91D86227DB116A44BB345A6E66874F83D8993F813` is the `peer_id`.

3.  **Start a PFN with the identity**

After extracting the peer identity from the public key, you can start your PFN with the identity using the public key in the `peer_id` field of the configuration file (e.g., `fullnode.yaml`). For example:

```
full_node_networks:  - network_id: "public"discovery_method: "onchain"identity:  type: "from_config"  key: "<PRIVATE_KEY>"  peer_id: "<PEER_ID>"
```

In our example (from above), the configuration file (`fullnode.yaml`) should now have the following information:

```
full_node_networks:  - network_id: "public"    discovery_method: "onchain"    identity:      type: "from_config"      key: "C83110913CBE4583F820FABEB7514293624E46862FAE1FD339B923F0CACC647D"      peer_id: "B881EA2C174D8211C123E5A91D86227DB116A44BB345A6E66874F83D8993F813"
```

Starting your PFN with this configuration will assign your PFN with the static network identity you generated.

### Using Docker

[](#using-docker)

If you use Docker to run your PFN, follow these steps:

1.  **Prepare your tools**

First, `cd` into the directory for your local PFN and start a Docker container with the latest tools, for example:

```
cd ~/my-full-nodedocker run -it aptoslabs/tools:devnet /bin/bash
```

2.  **Generate the private key**

Next, follow the remaining steps from inside the `aptoslabs/tools` Docker container.

Open a new terminal and `cd` into the directory where you started the Docker container for your PFN. Making sure to provide the **full path** to where you want the private key file to be stored, run the command:

```
aptos key generate \    --key-type x25519 \    --output-file /path/to/private-key.txt
```

3.  **Retrieve the peer identity**

```
aptos key extract-peer --host example.com:6180 \    --public-network-key-file private-key.txt.pub \    --output-file peer-info.yaml
```

This command will output the public identity information for your PFN to a file `peer-info.yaml`. For example:

In this example, `B881EA2C174D8211C123E5A91D86227DB116A44BB345A6E66874F83D8993F813` is the `peer_id`.

4.  **Start a PFN with the identity**

```
full_node_networks:  - network_id: "public"discovery_method: "onchain"identity:  type: "from_config"  key: "<PRIVATE_KEY>"  peer_id: "<PEER_ID>"
```

In our example (from above), the configuration file (`fullnode.yaml`) should now have the following information:

Starting your PFN with this configuration will assign your PFN with the static network identity you generated.

## Check your node identity

[](#check-your-node-identity)

If you want to check the identity of your node at runtime, there are several ways to do so. Two of the simplest methods are:

*   **Using the REST API**: You can query the `/v1/info` endpoint of your node's [REST API](/build/apis/fullnode-rest-api) to retrieve the identity information.
*   **Using the Node Inspection Service**: You can query the `/identity_information` endpoint on your node's inspection service to retrieve the identity information of your node. You can read more [here](/network/nodes/measure/node-inspection-service#examine-identity-information).

Note

Nodes with multiple network connection types (e.g., `VFN` and `public` networks) will have identities for each connection type. For public fullnodes (PFNs), there is only one network connection type (`public`), so there will be only one identity.

# Upgrade your PFN

> Step-by-step guide to update your public fullnode (PFN) with new Aptos releases including source code, Docker, and Terraform deployment methods.

This document outlines the process for updating your PFN with new Aptos releases. All PFNs will need to be updated when new releases are available. For PFNs running in `devnet`, an additional data wipe step is required as `devnet` is wiped on every new release.

## Source code deployment

[](#source-code-deployment)

If you run your PFN from the [aptos-core](https://github.com/aptos-labs/aptos-core.git) source code, you can update your PFN by following these steps:

1.  Stop your PFN by running the command below (or killing the `aptos-node` process manually):
    
    ```
    cargo stop aptos-node
    ```
    
2.  Fetch the latest release appropriate for your network, e.g., `devnet`, `testnet`, or `mainnet`. Be sure to replace `[network_branch]` with the appropriate branch name below:
    
    ```
    git checkout [network_branch] && git pull
    ```
    
3.  Rebuild the binary as you did during the initial setup.
    
4.  If your PFN is running in `devnet`, follow the additional steps in the [Data Wipe and Reset](#upgrade-with-data-wipe-devnet-only) section below.
    
5.  Restart your PFN by running the same deployment command as before. For example:
    
    ```
    cargo run -p aptos-node --release -- -f ./fullnode.yaml
    ```

### (Devnet) Data Wipe and Reset

[](#devnet-data-wipe-and-reset)

Caution

**Devnet only wipe**  
Only follow these additional steps if your PFN is running in `devnet`. Other networks (e.g., `testnet` and `mainnet`) don't require this step (as data is never wiped)!

If your PFN is running in `devnet`, follow these additional steps after stopping your PFN (and before restarting it!):

1.  Delete the data folder (the directory path is what you specified in the configuration file, e.g., `fullnode.yaml`).
    
    *   The default data folder is `/opt/aptos/data`.
2.  Delete the `genesis.blob` file and `waypoint.txt` file (depending on how you configured it, you might not have this file and may instead have a `waypoint` directly in your configuration file).
    
3.  Download the new [genesis.blob](/network/nodes/configure/node-files-all-networks/node-files-devnet#genesisblob) file and the new [waypoint](/network/nodes/configure/node-files-all-networks/node-files-devnet#waypointtxt).
    
4.  Update the configuration file (e.g., `fullnode.yaml`) with the new genesis.blob and waypoint files.
    
5.  Restart your PFN by running the same deployment command as before.

## Docker deployment

[](#docker-deployment)

If you run your PFN from a Docker image, you can update your PFN by:

1.  Stop your PFN by running the command below:
    
    ```
    docker compose down --volumes
    ```
    
2.  (Devnet only!) If your PFN is running in `devnet`, delete the entire directory which holds your PFN config and data directory.
3.  Re-install and configure those files as during the original setup.
4.  Restart your PFN by running the same deployment command as before. For example:
    
    ```
    docker compose up -d
    ```

## GCP deployment

[](#gcp-deployment)

If you run your PFN in GCP, follow the steps below to update your PFN. Note: if your PFN is running in `devnet`, an additional data wipe step is required.

### Upgrade with data wipe (devnet only)

[](#upgrade-with-data-wipe-devnet-only)

Caution

**Devnet only wipe**  
Only follow these steps if your PFN is running in `devnet`. Other networks don't require this step (as data is never wiped) and we recommend not wiping your data in these networks.

If you are running a `devnet` PFN, follow these steps to update:

1.  Increase the `era` number in `main.tf` to trigger a new data volume creation, which will start the PFN on a new DB.
    
2.  Update the `image_tag` in `main.tf` to contain the new release version.
    
3.  Update the Terraform module for the PFN (run this in the same directory of your `main.tf` file):

```
terraform get -update
```

4.  Apply the Terraform changes:

```
terraform apply
```

### Upgrade without data wipe

[](#upgrade-without-data-wipe)

If you are not running a `devnet` PFN, follow these steps to update:

1.  Update the `image_tag` in `main.tf`.
    
2.  Update the Terraform module for the PFN (run this in the same directory of your `main.tf` file):

```
terraform get -update
```

3.  Apply the Terraform changes:

```
terraform apply
# If you didn't update the image tag, terraform will show nothing to change, in this case, force a helm updateterraform apply -var force_helm_update=true
```

# PFN Requirements

> Hardware, network, storage, and port requirements for running a production-grade public fullnode (PFN) on the Aptos blockchain.

To ensure that your public fullnode (PFN) operates smoothly, it should meet the requirements specified in this document.

## Hardware requirements

[](#hardware-requirements)

Caution

**Minimum hardware requirements**  
Failing to meet the minimum hardware requirements mean that your PFN will experience degradation under load and general instability in production environments. It is not recommended to run a PFN without meeting the minimum hardware requirements.

For running a production-grade PFN, we recommend that your hardware meet the same requirements as a validator or VFN. You can see the hardware requirements for these, here: [validator and VFN hardware requirements](/network/nodes/validator-node/node-requirements#hardware-requirements).

Note

**Testing PFNs**  
If you wish to run a PFN for development or testing only, lower hardware specs can be used. But, it should not be used in production.

## Network requirements and ports

[](#network-requirements-and-ports)

When you are running a PFN, you are required to open network ports on your nodes to allow other nodes (i.e., peers) to connect to you. There are different Aptos network types, and each network type uses a different port. However, the only network type that a PFN uses is the public network, where PFNs to connect to other PFNs and VFNs.

Your PFN can be configured so that the public network operates using a specific port on your node. You can configure the port settings using the node configuration YAML file. Here is an [example configuration file](https://github.com/aptos-labs/aptos-core/blob/main/config/src/config/test_data/public_full_node.yaml#L16) for a PFN that configures the public network to use port `6180`.

### Port settings

[](#port-settings)

The recommendations described below assume the default port settings used by PFNs. If you have changed the default port settings in your configuration file, then you should adjust the recommendations accordingly.

Caution

**Exposing ports**  
Unless explicitly required, we recommend that you do not expose any other ports while operating a PFN. This is because exposing additional ports can increase the attack surface of your node and make it more vulnerable to adversaries.

#### Running a PFN:

[](#running-a-pfn)

Assuming default ports are used, the following should be configured for PFNs:

*   Open the following TCP ports:
    *   `6182` – **Public network**: Open this port publicly to enable other PFNs to connect to your PFN.
*   Close the following TCP ports:
    *   `9101` – **Inspection service**: Close this port to prevent unauthorized metric inspection.
    *   `9102` – **Admin service**: Close this port to prevent unauthorized admin service interaction.
    *   `80/8080` - **REST API**: Close this port to prevent unauthorized REST API access.

Caution

**Exposing services**  
The inspection service port (`9101`), admin service port (`9102`) and the REST API port (`80` or `8080`) are likely useful for your internal network, e.g., application development and debugging. However, the inspection service port and the admin service port should never be exposed publicly as they can be easily abused. Similarly, if you choose to expose the REST API endpoint publicly, you should deploy an additional authentication or rate-limiting mechanism to prevent abuse.

## Storage requirements

[](#storage-requirements)

The amount of data stored by Aptos PFNs depends on the ledger history (length) of the blockchain and the number of on-chain states (e.g., accounts and resources). Both the ledger history and the number of on-chain states depend on several additional factors, including the age of the blockchain, the average transaction rate over time, and the configuration of the ledger database pruner. At the time of writing, we estimate that testnet and mainnet PFNs require several 100's of GB of storage.

Note that because archival nodes store the entire history of the blockchain, the database size on archival nodes will continue to grow unbounded. As a result, we cannot provide a recommendation for archival node storage sizes.

Note

**Devnet blockchain storage**  
The Aptos devnet is currently reset on a weekly basis. If you are deploying a devnet PFN, this means that the storage will be reset (i.e., wiped) every week. See the `#devnet-release` channel on the [Aptos Discord](https://discord.gg/aptosnetwork).

# Verify a PFN

> Monitor and verify your public fullnode (PFN) operation by checking synchronization status, network connections, and storage metrics.

After deploying your PFN, you can verify that it is operating correctly by checking several of the PFN's metrics. This document describes the common types of checks that you might wish to perform.

Note

You can learn more about Aptos metrics in the [Node Inspection Service](/network/nodes/measure/node-inspection-service) documents.

### Verify synchronization

[](#verify-synchronization)

During the initial synchronization of your PFN, there may be a lot of data to transfer (read more about how state sync works in the [state sync](/network/nodes/configure/state-sync) guide). You can monitor state sync progress by querying the metrics port to see what version your node is currently synced to. Run the following example command to see the currently synced version of your node:

```
curl 127.0.0.1:9101/metrics 2> /dev/null | grep "aptos_state_sync_version{.*\"synced\"}" | awk '{print $2}'
```

The command will output the current synced version of your node. For example:

```
71000
```

Compare the synced version returned by this command (e.g., `71000`) with the highest version shown on the [Aptos explorer page](https://explorer.aptoslabs.com/?network=mainnet). If your node is catching up to the highest version, it is synchronizing correctly. It is fine if the explorer page differs by a few versions, as the explorer nodes may sync with some variance.

Caution

**Using fast sync?**  
If your node is fast syncing, the command may show `0` until it has finally caught up. To verify that the node is fast syncing, run the following command:

```
curl 127.0.0.1:9101/metrics 2> /dev/null | grep "aptos_state_sync_version{.*\"synced_states\"}" | awk '{print $2}'
```

This should show an increasing number of synced states. It may take several hours for your node to fast sync to the latest version. Eventually, once fast syncing is complete, the `aptos_state_sync_version{.*"synced"}` command will return the current synced version of your node.

You can read more about fast syncing here: [State sync bootstrapping](/network/nodes/configure/state-sync#bootstrapping-phase).

### (Optional) Verify outbound network connections

[](#optional-verify-outbound-network-connections)

If you wish, you can also check the outbound network connections for your PFN. The number of outbound network connections should be more than `0` for healthy PFNs. Run the following command:

```
curl 127.0.0.1:9101/metrics 2> /dev/null | grep "aptos_connections{direction=\"outbound\""
```

The above command will output the number of outbound network connections for your node. For example:

```
curl 127.0.0.1:9101/metrics 2> /dev/null | grep "aptos_connections{direction=\"outbound\""aptos_connections{direction="outbound",network_id="Public",peer_id="aabd651f",role_type="full_node"} 3
```

If the number of outbound connections returned is `0`, then it means your node cannot connect to the Aptos blockchain. If this happens to you, follow these steps to resolve the issue:

1.  Update your node to the latest release by following the [Update your Node](/network/nodes/full-node/modify/update-fullnode-with-new-releases).
2.  Remove any `seed` peers you may have added to your configuration file. The seeds may be preventing you from connecting to the network. Seed peers are discussed in the [Connecting your PFN to seed peers](/network/nodes/full-node/modify/fullnode-network-connections#connecting-to-seed-peers) section.
3.  Ensure that you have used the correct `genesis.blob` and `waypoint.txt` files for your network. This is a common error.

### (Optional) Examine Docker ledger size

[](#optional-examine-docker-ledger-size)

If you are running your PFN using Docker, you can monitor the size of the blockchain ledger by entering the Docker container and checking the size. This will allow you to see how much storage the blockchain ledger is currently consuming.

*   First, run `docker container ls` on your terminal and copy the NAME field output. This will be a string similar to `public_full_node_fullnode_1`.
*   Next, run these commands to check the storage size consumed by the ledger, using the NAME field you copied over in place of `public_full_node_fullnode_1`:

```
# Obtain the container ID:id=$(docker container ls | grep public_full_node_fullnode_1 | grep -oE "^[0-9a-zA-Z]+")
# Enter the container:docker exec -it $id /bin/bash
# Observe the volume (ledger) size:du -cs -BM /opt/aptos/data
```

# Develop with Localnet

> Run a local Aptos blockchain network for development and testing applications, including CLI-based and source code deployment options.

If you want to develop and test your applications on the Aptos blockchain, you can run a local network (**localnet**). This network will run on your local machine, and will not be connected to any other Aptos network. Running a localnet is the easiest way to test and develop Aptos applications, and make changes to the Aptos node software.

## Recommended Steps

[](#recommended-steps)

Most developers should use the Aptos CLI to run a local development network. This is the simplest and easiest way to get started. It provides a local deployment that works just like a production network, including the [Node API](/build/apis), [Transaction Stream](/build/indexer/txn-stream), [Indexer API](/build/indexer) and [Faucet](/build/apis/faucet-api).

To get started, follow this guide: [Localnet using the Aptos CLI](/network/nodes/localnet/local-development-network)

## Specialized Steps

[](#specialized-steps)

If you're developing the core Aptos node software, or have more complex testing needs, consider the guides below. The first guide provides a way to run a localnet with a single validator node, and the second guide provides a way to run a localnet with multiple validator nodes, and validator fullnodes (VFNs).

To run a localnet with a single validator node, directly from the `aptos-core` source code, follow this guide:

*   [Localnet from source code](/network/nodes/localnet/run-a-localnet)

To run a localnet with multiple validator nodes and validator fullnodes (VFNs), follow this guide:

*   [Multi-node Localnet](/network/nodes/localnet/run-a-multinode-localnet)

# Localnet using the Aptos CLI

> Complete guide to running a local Aptos development network using the CLI with Node API, Indexer API, transaction stream, and faucet services.

Local networks can be helpful when testing your code. They are not connected to any production Aptos networks like mainnet, but they are useful for three main reasons:

1.  **No rate limits:** You can interact with hosted services like the Node API, Indexer API, and faucet with no rate-limits to speed up testing.
2.  **Reproducibility:** You can set up specific on-chain scenarios and restart the network from scratch at any point to return to a clean slate.
3.  **High availability**: The Aptos devnet and testnet networks are periodically upgraded, during which time they can be unavailable. Local development networks are also always available even if you have no internet access.

# Starting A Local Network

[](#starting-a-local-network)

1.  Ensure you have the [Aptos CLI](/build/cli) installed.
    
    You can verify if the Aptos CLI is installed by running `aptos --version`.
    
2.  Ensure you have Docker installed.
    
    You can check whether Docker is installed by running `docker --version`.
    
    1.  This is exclusively needed for making a production-like environment by running the Indexer API. Many downstream tools such as the Aptos SDK depend on the Indexer API.
    2.  Docker recommends that you install via [Docker Desktop](https://www.docker.com/products/docker-desktop/) to get automatic updates.
3.  Start Docker.
    
4.  Run the following command in a new terminal to start the private network:
    
    ```
    aptos node run-local-testnet --with-indexer-api
    ```
    
    Caution
    
    Note: Despite using the name `local-testnet` above, this has nothing to do with the official Aptos testnet. This command will run a network entirely local to your machine.
    
    You should expect to see an output similar to this:
    
    ```
    Readiness endpoint: http://0.0.0.0:8070/
    Indexer API is starting, please wait...Node API is starting, please wait...Transaction stream is starting, please wait...Postgres is starting, please wait...Faucet is starting, please wait...
    Completed generating configuration:        Log file: "/Users/dport/.aptos/testnet/validator.log"        Test dir: "/Users/dport/.aptos/testnet"        Aptos root key path: "/Users/dport/.aptos/testnet/mint.key"        Waypoint: 0:397412c0f96b10fa3daa24bfda962671c3c3ae484e2d67ed60534750e2311f3d        ChainId: 4        REST API endpoint: http://0.0.0.0:8080        Metrics endpoint: http://0.0.0.0:9101/metrics        Aptosnet fullnode network endpoint: /ip4/0.0.0.0/tcp/6181        Indexer gRPC node stream endpoint: 0.0.0.0:50051
    Aptos is running, press ctrl-c to exit
    Node API is ready. Endpoint: http://0.0.0.0:8080/Postgres is ready. Endpoint: postgres://postgres@127.0.0.1:5433/local_testnetTransaction stream is ready. Endpoint: http://0.0.0.0:50051/Indexer API is ready. Endpoint: http://127.0.0.1:8090Faucet is ready. Endpoint: http://127.0.0.1:8081/
    Applying post startup steps...
    Setup is complete, you can now use the local testnet!
    ```
    
5.  Wait for the network to start
    
    Once the terminal says `Setup is complete, you can now use the local testnet!` the local network will be running.
    
    Caution
    
    If you ran into an error, look at the common errors below to debug.
    
    Common Errors On Network Startup
    
    ### Address Already In Use
    
    [](#address-already-in-use)
    
    ```
    panicked at 'error binding to 0.0.0.0:8080: error creating server listener: Address already in use (os error 48)'
    ```
    
    This means one of the ports needed by the local network is already in use by another process.
    
    To fix this on Unix systems, you can:
    
    1.  Identify the name and PID of the process by running `lsof -i :8080`.
    2.  Run `kill <pid>` once you know the PID to free up that port.
    
    ### Too many open files error
    
    [](#too-many-open-files-error)
    
    ```
    panicked at crates/aptos/src/node/local_testnet/logging.rs:64:10:called \`Result::unwrap()\` on an \`Err\` value: Os { code: 24, kind: Uncategorized, message: \"Too many open files\" }
    ```
    
    This means there were too many open files on your system. On many Unix systems you can increase the maximum number of open files by adding something like this to your `.zshrc`:
    
    ```
    ulimit -n 1048576
    ```
    
    ### Docker is not available
    
    [](#docker-is-not-available)
    
    ```
    Unexpected error: Failed to apply pre-run steps for Postgres: Docker is not available, confirm it is installed and running. On Linux you may need to use sudo
    ```
    
    To debug this, try the below fixes:
    
    1.  Make sure you have docker installed by running `docker --version`.
    2.  Ensure the Docker daemon is running by running `docker info` (if this errors saying `Cannot connect to the Docker daemon` Docker is NOT running)
    3.  Make sure the socket for connecting to Docker is present on your machine in the default location. For example, on Unix systems `/var/run/docker.sock` should exist.
        1.  If that file does not exist, open Docker Desktop and enable `Settings -> Advanced -> Allow the default Docker socket to be used.`
        2.  Or, you can find where the Docker socket is by running `docker context inspect | grep Host`, then symlink that location to the default location by running `sudo ln -s /Users/dport/.docker/run/docker.sock /var/run/docker.sock`
    
    As you can see from the example output in step 4, once the local network is running, you have access to the following services:
    
    *   [Node API](/build/apis/fullnode-rest-api): This is a REST API that runs directly on the node. It enables core write functionality such as transaction submission and a limited set of read functionality, such as reading account resources or Move module information.
    *   [Indexer API](/build/indexer/indexer-api): This is a [GraphQL](https://graphql.org/) API that provides rich read access to indexed blockchain data. If you click on the URL for the Indexer API above, by default [http://127.0.0.1:8090](http://127.0.0.1:8090), it will open the Hasura Console, a web UI that will help you query the Indexer GraphQL API.
    *   [Transaction Stream Service](/build/indexer/txn-stream): This is a gRPC stream of transactions used by the Indexer API. This is only relevant to you if you are developing an [Indexer SDK](/build/indexer/indexer-sdk) custom processor.
    *   [Postgres](https://www.postgresql.org/): This is the database that the Indexer processors write to. The Indexer API reads from this database.
    *   [Faucet](/build/apis/faucet-api): You can use this to fund accounts on your local network.
    
    If you do not want to run any of these sub-components of a network, there are flags to disable them.
    
    If you are writing a script and would like to wait for the local network to come up with all services, you can make a GET request to `http://127.0.0.1:8070`. At first this will return http code [503](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/503). When it returns [200](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200) it means all the services are ready.
    
    For more information on different flags you can pass when starting your local network, or configuration settings such as changing which port certain services run on, run the help command:
    
    ```
    aptos node run-local-testnet --help
    ```

## Using The Local Network

[](#using-the-local-network)

Now that the network is running, you can use it like you would any other network.

So, you can create a local profile like this:

```
aptos init --profile <your-profile-name> --network local
```

You can then use that profile for any commands you want to use going forward. For example, if you wanted to publish a Move module like the [`hello_blockchain`](https://github.com/aptos-labs/aptos-core/tree/main/aptos-move/move-examples/hello_blockchain) package to your local network you could run:

```
aptos move publish --profile <your-profile-name> --package-dir /opt/git/aptos-core/aptos-move/move-examples/hello_blockchain --named-addresses HelloBlockchain=local
```

### Configuring the TypeScript SDK

[](#configuring-the-typescript-sdk)

If you want to use the local network with the TypeScript SDK, you can use local network URLs when initializing the client object (`Aptos`):

```
import { Aptos, AptosConfig, Network } from "@aptos-labs/ts-sdk";
const network = Network.LOCAL;const config = new AptosConfig({ network });const client = new Aptos(config);
```

### Resetting the local network

[](#resetting-the-local-network)

Sometimes while developing it is helpful to reset the local network back to its initial state, for example:

*   You made backwards incompatible changes to a Move module, and you'd like to redeploy it without renaming it or using a new account.
*   You are building a [custom indexer processor](/build/indexer) and would like to index using a fresh network.
*   You want to clear all on chain state, e.g. accounts, objects, etc.

To start with a brand new local network, use the `--force-restart` flag:

```
aptos node run-local-testnet --force-restart
```

It will then prompt you if you really want to restart the chain, to ensure that you do not delete your work by accident.

```
Are you sure you want to delete the existing chain? [yes/no]> yes
```

If you do not want to be prompted, include `--assume-yes` as well:

```
aptos node run-local-testnet --force-restart --assume-yes
```

## Running in a container

[](#running-in-a-container)

If you want to run the localnet using a Docker container, you can do it like this:

```
docker run \   --platform linux/amd64 \   -v /var/run/docker.sock:/var/run/docker.sock \   --network host \   -v /tmp/testnet:/testnet \   aptoslabs/tools:nightly \   aptos node run-local-testnet \   --test-dir /testnet \   --with-indexer-api
```

Instead of `nightly` you can use any tag from [here](https://hub.docker.com/r/aptoslabs/tools/tags).

Note: `-v /var/run/docker.sock:/var/run/docker.sock` allows the CLI to run other containers using the host Docker daemon, for example Postgres and Hasura for the indexer API. You don't have to do this if you are not setting `--with-indexer-api`.

Note: If this fails because `/var/run/docker.sock` doesn't exist, see the [Docker is not available](#docker-is-not-available) section above.

# Localnet from source code

> Run a local Aptos network from aptos-core source code for testing modifications to the codebase or Aptos Framework with single validator setup.

You can run a localnet using the [aptos-core](https://github.com/aptos-labs/aptos-core) source code. This approach is useful for testing modifications to the aptos-core codebase or to the Aptos Framework.

Note

It is easier to run a localnet using the [Aptos CLI](/network/nodes/localnet/local-development-network) than it is to run it from source code. The CLI also provides a more user-friendly experience and additional features. Learn how by following this guide: [Localnet using the Aptos CLI](/network/nodes/localnet/local-development-network).

The rest of this document describes:

*   How to start your localnet with a single validator node.
*   How to start a Faucet service and attach it to your localnet.

## Using the Aptos-core source code

[](#using-the-aptos-core-source-code)

1.  Follow steps in [Building Aptos From Source](/network/nodes/building-from-source)
    
2.  With your development environment ready, you can start your localnet.
    
    Note
    
    *   When you run the below command to start the localnet, your terminal will enter into an interactive mode, with a message `Aptos is running, press ctrl-c to exit`. Hence, you will need to open another shell terminal for the subsequent steps described in this section.
    *   After the below command runs, copy the `Test dir` information from the terminal output for the next step.
    
    To start your localnet, run the following command:
    
    ```
    CARGO_NET_GIT_FETCH_WITH_CLI=true cargo run -p aptos-node -- --test
    ```
    
    See below for an example of the partial output. Make a note of the `Test dir` from the output.
    
    ```
    .........
    Completed generating configuration:    Log file: "/private/var/folders/gn/m74t8ylx55z935q8wx035qn80000gn/T/b3adc18c144bfcc78a1541953893bc1c/validator.log"    Test dir: "/private/var/folders/gn/m74t8ylx55z935q8wx035qn80000gn/T/b3adc18c144bfcc78a1541953893bc1c/0/node.yaml"    Aptos root key path: "/private/var/folders/gn/m74t8ylx55z935q8wx035qn80000gn/T/b3adc18c144bfcc78a1541953893bc1c/mint.key"    Waypoint: 0:47e676b5fe38ebe2aec6053db7b3daa0b805693d6422e3475e46e89499464ecf    ChainId: TESTING    REST API endpoint: 0.0.0.0:8080    Fullnode network: /ip4/0.0.0.0/tcp/7180Aptos is running, press ctrl-c to exit
    ```

Tip

The above command starts a localnet with a single validator node. The command runs `aptos-node` from a genesis-only ledger state. If you want to reuse the ledger state produced by a previous run of `aptos-node`, then use:

```
cargo run -p aptos-node -- --test --config <config-path>
```

### Attaching a Faucet to your localnet

[](#attaching-a-faucet-to-your-localnet)

Faucets are stateless services that can be run in parallel with the localnet. A Faucet is a way to create Aptos test coins with no real-world value. You can use the Faucet by sending a request to create coins and transfer them into a given account on your behalf.

1.  Make sure that you started your localnet as described in Step 5 above.
2.  Open a new shell terminal.
3.  Copy the _Aptos root key path_ from your terminal where you started the localnet, and use it to replace the `mint-key-file-path` in the below command.
4.  Run the following command to start a Faucet:

```
cargo run --package aptos-faucet-service -- run-simple --key-file-path "/tmp/694173aa3bbe019499bbd5cf3fe0e2fc/mint.key" --node-url http://127.0.0.1:8080 --chain-id TESTING
```

This will start a Faucet running locally without any restrictions to tokens that can be claimed and minted. This Faucet service will be as accessible as the localnet you started above.

## Interacting with the localnet

[](#interacting-with-the-localnet)

After starting your localnet, you will see the following:

```
Entering test mode, this should never be used in production!Completed generating configuration:        Log file: "/tmp/694173aa3bbe019499bbd5cf3fe0e2fc/validator.log"        Test dir: "/tmp/694173aa3bbe019499bbd5cf3fe0e2fc/0/node.yaml"        Aptos root key path: "/tmp/694173aa3bbe019499bbd5cf3fe0e2fc/mint.key"        Waypoint: 0:197bc8b76761622c2d2054d8bf93c1802fa0eb4bc55f0f3d4442878fdecc297f        ChainId: TESTING        REST API endpoint: 0.0.0.0:8080        Fullnode network: /ip4/0.0.0.0/tcp/7180
Aptos is running, press ctrl-c to exit
```

Use the [Aptos CLI tool](/build/cli) to interact with your localnet. The above output contains information you will use for starting the [Aptos CLI tool](/build/cli):

*   `Aptos root key path`: The root key (also known as the mint or faucet key) controls the account that can mint tokens. Available in the docker compose folder under `aptos_root_key`.
*   `Waypoint`: A verifiable checkpoint of the blockchain (available in the docker compose folder under waypoint.txt)
*   `REST endpoint`: The endpoint for the REST service, e.g., `http://127.0.0.1:8080`.
*   `ChainId`: The chain ID uniquely distinguishes this network from other blockchain networks.

## Next steps

[](#next-steps)

At this point, you will have a special root account at `0x1` that can perform the mint operation. Follow up with some tutorials such as on [Aptos Learn workshops](https://learn.aptoslabs.com/en/workshops)

# Multi-node Localnet

> Deploy a local network with multiple validator nodes and validator fullnodes using Aptos Forge for advanced testing and development scenarios.

This guide describes how to run a local network with multiple validator nodes and validator fullnodes. You will use [Aptos Forge](https://github.com/aptos-labs/aptos-core/tree/main/testsuite/forge-cli/src) in the [aptos-core](https://github.com/aptos-labs/aptos-core) source code for this.

Note

The steps described in this guide should only be used for test networks of multi-node local networks. Do not use this guide for deploying networks in production environments. This guide also assumes that you have completed the steps in [Building Aptos From Source](/network/nodes/building-from-source).

## Localnet with multiple validators

[](#localnet-with-multiple-validators)

To deploy a localnet with multiple local validators, run this command from the root directory of the [aptos-core](https://github.com/aptos-labs/aptos-core) source code:

```
cargo run -p aptos-forge-cli \        -- \        --suite "run_forever" \        --num-validators 4 test local-swarm
```

This will start a local network of 4 validators, each running in their own process. The network will run forever unless you manually terminate it.

The terminal output will display the locations of the validator files (for example, the genesis files, logs, node configurations, etc.) and the commands that were run to start each node. The process id (PID) of each node and server addresses (e.g., REST APIs) are also displayed when it starts. For example, if you run the above command you should see:

```
...2022-09-01T15:41:27.228289Z [main] INFO crates/aptos-genesis/src/builder.rs:462 Building genesis with 4 validators. Directory of output: "/private/var/folders/dx/c0l2rrkn0656gfx6v5_dy_p80000gn/T/.tmpq9uPMJ"...2022-09-01T15:41:28.090606Z [main] INFO testsuite/forge/src/backend/local/swarm.rs:207 The root (or mint) key for the swarm is: 0xf9f......2022-09-01T15:41:28.094800Z [main] INFO testsuite/forge/src/backend/local/node.rs:129 Started node 0 (PID: 78939) with command: ".../aptos-core/target/debug/aptos-node" "-f" "/private/var/folders/dx/c0l2rrkn0656gfx6v5_dy_p80000gn/T/.tmpq9uPMJ/0/node.yaml"2022-09-01T15:41:28.094825Z [main] INFO testsuite/forge/src/backend/local/node.rs:137 Node 0: REST API is listening at: http://127.0.0.1:645662022-09-01T15:41:28.094838Z [main] INFO testsuite/forge/src/backend/local/node.rs:142 Node 0: Inspection service is listening at http://127.0.0.1:64568...
```

Using the information from this output, you can stop a single node and restart it. For example, to stop and restart the node `0`, execute the below commands:

```
kill -9 <Node 0 PID>cargo run -p aptos-node \        -- \        -f <Location to the node 0 configuration file displayed above>
```

## Faucet and minting

[](#faucet-and-minting)

In order to mint coins in this test network you need to run a faucet. You can do that with this command:

```
cargo run -p aptos-faucet-service -- run-simple --key <key> --node-url <node_url>
```

You can get the values above like this:

*   `key`: When you started the swarm, there was output like this: `The root (or mint) key for the swarm is: 0xf9f...`. This is the `key`.
*   `node_url`: When you started the swarm, there was output like this: `REST API is listening at: http://127.0.0.1:64566`. This is the `node_url`.

The above command will run a faucet locally, listening on port `8081`. Using this faucet, you can then mint tokens to your test accounts, for example:

```
curl -X POST http://127.0.0.1:8081/mint?amount=<amount to mint>&pub_key=<public key to mint tokens to>
```

As an alternative to using the faucet service, you may use the faucet CLI directly:

```
cargo run -p aptos-faucet-cli -- --amount 10 --accounts <account_address> --key <private_key>
```

Tip

See more on how the faucet works in the [README](https://github.com/aptos-labs/aptos-core/tree/main/crates/aptos-faucet). Also see how to use the [Aptos CLI](/build/cli) with an existing faucet.

## Validator fullnodes

[](#validator-fullnodes)

To also run validator fullnodes inside the network, use the `--num-validator-fullnodes` flag. For example:

```
cargo run -p aptos-forge-cli \        -- \        --suite "run_forever" \        --num-validators 3 \        --num-validator-fullnodes 1 test local-swarm
```

## Additional usage

[](#additional-usage)

To see all tool usage options, run:

```
cargo run -p aptos-forge-cli --help
```

# Monitor your Nodes

> Comprehensive node monitoring and inspection tools including metrics collection, health checking, and performance analysis for Aptos nodes.

You have several options for monitoring and inspecting the health and performance of your nodes:

*   ### [Node Inspection Service](/network/nodes/measure/node-inspection-service)
    
    [](#node-inspection-service)
    
*   ### [Important Node Metrics](/network/nodes/measure/important-metrics)
    
    [](#important-node-metrics)
    
*   ### [Node Health Checker](/network/nodes/measure/node-health-checker)
    
    [](#node-health-checker)

# Important Node Metrics

> Key metrics and counters for monitoring Aptos node health including consensus, state sync, networking, and storage performance indicators.

When you visit the metrics endpoint (see [Node Inspection Service](/network/nodes/measure/node-inspection-service)), you will notice that there are a large number of metrics and counters being produced by your node. Most of these metrics and counters are useful only for blockchain development and diagnosing hard-to-find issues. As a result, we recommend that node operators ignore most metrics and pay attention to only the key metrics presented below:

Note

**Metric instability**  
As Aptos continues to grow and develop the blockchain software, many metrics will come and go. As a result, we recommend relying on the presence of only the metrics explicitly mentioned below. All other metrics should be considered unstable and may be changed/removed without warning.

### Consensus

[](#consensus)

If you are running a validator node, the following [consensus](/network/blockchain/blockchain-deep-dive#consensus) metrics are important:

1.  `aptos_consensus_proposals_count`: Counts the number of times the node sent a block proposal to the network. The count will increase only when the validator is chosen to be a proposer, which depends on the node's stake and leader election reputation. You should expect this metric to increase at least once per hour.
2.  `aptos_consensus_last_committed_round`: Counts the last committed round of the node. During consensus, we expect this value to increase once per consensus round, which should be multiple times per second. If this does not happen, it is likely the node is not participating in consensus.
3.  `aptos_consensus_timeout_count`: Counts the number of times the node locally timed out while trying to participate in consensus. If this counter increases, it is likely the node is not participating in consensus and may be having issues, e.g., network difficulties.
4.  `aptos_state_sync_executing_component_counters{label="consensus"`: This counter increases a few times per second as long as the node is participating in consensus. When this counter stops increasing, it means the node is not participating in consensus, and has likely fallen back to state synchronization (e.g., because it fell behind the rest of the validators and needs to catch up).

### State sync

[](#state-sync)

If you are running a fullnode (or a validator that still needs to synchronize to the latest blockchain state), the following [state sync](/network/nodes/configure/state-sync) metrics are important:

1.  `aptos_state_sync_version{type="synced"}`: This metric displays the current synced version of the node, i.e., the number of transactions the node has processed. If this metric stops increasing, it means the node is not syncing. Likewise, if this metric doesn't increase faster than the rate at which new transactions are committed to the blockchain, it means the node is unlikely to get and stay up-to-date with the rest of the network. Note: if you've selected to use [fast sync](/network/nodes/configure/state-sync#fast-syncing), this metric won't increase until all states have been downloaded, which may take some time. See (3) below.
2.  `aptos_data_client_highest_advertised_data{data_type="transactions"}`: This metric displays the highest version synced and advertised by the peers that your node is connected to. As a result, when this metric is higher than `aptos_state_sync_version{type="synced"}` (above) it means your node can see new blockchain data and will sync the data from its peers.
3.  `aptos_state_sync_version{type="synced_states"}`: This metric counts the number of states that have been downloaded while a node is [fast syncing](/network/nodes/configure/state-sync#fast-syncing). If this metric doesn't increase, and `aptos_state_sync_version{type="synced"}` doesn't increase (from above), it means the node is not syncing at all and an issue has likely occurred.
4.  `aptos_state_sync_bootstrapper_errors` and `aptos_state_sync_continuous_syncer_errors`: If your node is facing issues syncing (or is seeing transient failures), these metrics will increase each time an error occurs. The `error_label` inside these metrics will display the error type.

Note

Compare the synced version shown by `aptos_state_sync_version{type="synced"}` with the highest version shown on the [Aptos Explorer](https://explorer.aptoslabs.com/?network=mainnet) to see how far behind the latest blockchain version your node is. Remember to select the correct network that your node is syncing to (e.g., `mainnet`).

### Networking

[](#networking)

The following network metrics are important, for both validators and fullnodes:

1.  `aptos_connections{direction="inbound"` and `aptos_connections{direction="outbound"`: These metrics count the number of peers your node is connected to, as well as the direction of the network connection. An `inbound` connection means that a peer (e.g., another fullnode) has connected to you. An `outbound` connection means that your node has connected to another node (e.g., connected to a validator fullnode).
    1.  If your node is a validator, the sum of both `inbound` and `outbound` connections should be equal to the number of other validators in the network. Note that only the sum of these connections matter. If all connections are `inbound`, or all are `outbound`, this doesn't matter.
    2.  If your node is a fullnode, the number of `outbound` connections should be `> 0`. This will ensure your node is able to synchronize. Note that the number of `inbound` connections matters only if you want to act as a seed in the network and allow other nodes to connect to you as discussed [Fullnode Network Connections](/network/nodes/full-node/modify/fullnode-network-connections#allowing-pfn-connections).

### Mempool

[](#mempool)

The following [mempool](/network/blockchain/blockchain-deep-dive#mempool) metrics are important:

1.  `core_mempool_index_size{index="system_ttl"`: This metric displays the number of transactions currently sitting in the mempool of the node and waiting to be committed to the blockchain:
    1.  If your node is a fullnode, it's highly unlikely that this metric will be `> 0`, unless transactions are actively being sent to your node via the REST API and/or other fullnodes that have connected to you. Most fullnode operators should ignore this metric.
    2.  If your node is a validator, you can use this metric to see if transactions from your node's mempool are being included in the blockchain (e.g., if the count decreases). Likewise, if this metric only increases, it means that either: (i) your node is unable to forward transactions to other validators to be included in the blockchain; or (ii) that the entire blockchain is under heavy load and may soon become congested.

### REST API

[](#rest-api)

The following [REST API](/build/apis/fullnode-rest-api) metrics are important:

1.  `aptos_api_requests_count{method="GET"` and `aptos_api_requests_count{method="POST"`: These metrics count the number of REST API `GET` and `POST` requests that have been received via the node's REST API. This allows you to monitor and track the amount of REST API traffic on your node. You can also further use the `operation_id` in the metric to monitor the types of operations the requests are performing.
    
2.  `aptos_api_response_status_count`: This metric counts the number of response types that were sent for the REST API. For example, `aptos_api_response_status_count{status="200"}` counts the number of requests that were successfully handled with a `200` response code. You can use this metric to track the success and failure rate of the REST API traffic.

# Node Health Checker

> Use the Aptos Node Health Checker (NHC) service to evaluate and monitor the health of your fullnodes by comparing against baseline configurations.

The Aptos Node Health Checker (NHC) service can be used to check the health of any Aptos fullnodes (VFNs or PFNs). If you are a node operator, use the NHC service to check if your node is running correctly. The NHC service evaluates your node's health by comparing against a baseline node configuration, and outputs the evaluation results.

This document describes how to run NHC locally when you are operating a node.

Note

If you don't want to run the NHC service yourself, you can use the [publicly available NHC service](https://nodetools.aptosfoundation.org/#/node_checker) run by the Aptos Foundation.

## Quickstart

[](#quickstart)

Before you get into the details of how NHC works, you can run the below steps to start the NHC service and send it a request. This tutorial uses a baseline configuration for a devnet fullnode, i.e., it will evaluate your node against a devnet fullnode that is configured with the baseline configuration YAML.

**Important**: If your local node is not a devnet fullnode, you must use a different baseline config. See [the configuration examples in aptos-core](https://github.com/aptos-labs/aptos-core/tree/main/ecosystem/node-checker/configuration_examples) for other such example configs.

1.  Download the baseline configuration YAML
    
    Download a baseline configuration YAML file for a devnet fullnode. The below command will download the `devnet_fullnode.yaml` configuration file:
    
    ```
    mkdir /tmp/nhccd /tmp/nhcwget https://raw.githubusercontent.com/aptos-labs/aptos-core/main/ecosystem/node-checker/configuration_examples/devnet_fullnode.yaml
    ```
    
2.  Start the NHC service
    
    Start the NHC service by providing the above-downloaded `devnet_fullnode.yaml` baseline configuration YAML file:
    
    ```
    docker run -v /tmp/nhc:/nhc -p 20121:20121 -t aptoslabs/node-checker:nightly /usr/local/bin/aptos-node-checker server run --baseline-config-paths /nhc/devnet_fullnode.yaml
    ```
    
3.  Send a request to NHC service
    
    Finally, send a request to the NHC service you started above. The following command runs health checks of your node that is at `node_url=http://mynode.mysite.com` and compares these results with the node configured in the baseline configuration `devnet_fullnode`:
    
    ```
    curl 'http://localhost:20121/check?node_url=http://mynode.mysite.com&api_port=80&baseline_configuration_id=devnet_fullnode'
    ```
    
    You will see output similar to this:
    
    ```
    {  "check_results": [    {      "headline": "Chain ID reported by baseline and target match",      "score": 100,      "explanation": "The node under investigation reported the same Chain ID 18 as is reported by the baseline node",      "checker_name": "node_identity",      "links": []    },    {      "headline": "Role Type reported by baseline and target match",      "score": 100,      "explanation": "The node under investigation reported the same Role Type full_node as is reported by the baseline node",      "checker_name": "node_identity",      "links": []    },    {      "headline": "Target node produced valid recent transaction",      "score": 100,      "explanation": "We were able to pull the same transaction (version: 3238616) from both your node and the baseline node. Great! This implies that your node is keeping up with other nodes in the network.",      "checker_name": "transaction_availability",      "links": []    }  ],  "summary_score": 100,  "summary_explanation": "100: Awesome!"}
    ```

## How NHC works

[](#how-nhc-works)

The NHC runs as a service. When you want to run a health check of your node, you send the HTTP requests to this service.

A single NHC instance can be configured to check the health of multiple node configurations, each of different type, for example:

*   A public fullnode connected to the Aptos mainnet.
*   A validator node connected to the Aptos testnet.
*   A node running in a single node testnet.

### Baseline configuration

[](#baseline-configuration)

In all the above cases, a baseline node is used to compare your node's health. For example, for a public fullnode connected to the Aptos devnet, the baseline node might be a node run by the Aptos team and this node demonstrates optimal performance and participation characteristics.

You will download the baseline configuration YAML before running the NHC service for your node. The baseline node's configuration YAML describes where to find this baseline node (URL + port), what evaluators (e.g., metrics checks, TPS tests, API validations, etc.) the NHC service should run, what parameters the NHC should use for those evaluators, what name the configuration has, and so on. See these [example baseline configuration YAML files](https://github.com/aptos-labs/aptos-core/tree/main/ecosystem/node-checker/configuration_examples).

When you send requests to the NHC service, you must include a baseline configuration. For example, a request to NHC to use `devnet_fullnode` as the baseline configuration will look like this:

```
curl 'http://nhc.aptoslabs.com/check?node_url=http://myfullnode.mysite.com&baseline_configuration_id=devnet_fullnode'
```

### Getting baseline configurations ready

[](#getting-baseline-configurations-ready)

In order to run the NHC service, you must have a baseline configuration that the service can use. You have two options here:

#### Configure a pre-existing YAML

[](#configure-a-pre-existing-yaml)

You can find a few [example baseline configuration YAML files](https://github.com/aptos-labs/aptos-core/tree/main/ecosystem/node-checker/configuration_examples) that work for each of the above use cases and more.

Next, download these configuration YAML files into the `/etc/nhc` folder in your host system. For example:

```
mkdir /tmp/nhccd /tmp/nhcconfigs=(devnet_fullnode testnet_fullnode mainnet_fullnode); for c in ${configs[@]}; do wget https://raw.githubusercontent.com/aptos-labs/aptos-core/main/ecosystem/node-checker/configuration_examples/$c.yaml; done
```

These configurations are not quite ready to be used as they are. You will need to modify certain fields, such as the baseline node address or evaluator set (`evaluators` and `evaluator_args` in the YAML) used. The best way to iterate on this is to run the NHC with a downloaded baseline configuration and see what it says on startup.

### Required files

[](#required-files)

For some NHC configurations, you will need accompanying files, e.g., `mint.key` to use for running a TPS test against a validator. You should make sure these files are also available to NHC, either on disk or mounted into your container. NHC expects them on startup at a path specified in the baseline configuration YAML.

## Running NHC: Docker

[](#running-nhc-docker)

Note

While the Aptos team hosts our own instances of this service, we encourage node operators to run their own instances.

When you are ready with baseline configuration YAML and the required files, you can run the NHC server with a command like this, for example, with Docker:

```
docker run -v /etc/nhc:/etc/nhc -p 20121:20121 -t aptoslabs/node-checker:nightly /usr/local/bin/aptos-node-checker server run --baseline-config-paths /tmp/nhc/devnet_fullnode.yaml /tmp/nhc/testnet_fullnode.yaml /tmp/nhc/mainnet/fullnode.yaml
```

Note

You may want to include other environment variables such as `RUST_LOG=info`. As you can see, by default NHC runs on port 20121. Make sure to publish it from the container, as shown in the above command, and ensure the port is open on your host. You may change the port NHC runs on with `--listen-port`.

## Running NHC: Source

[](#running-nhc-source)

First, check out the source:

```
git clone git@github.com:aptos-labs/aptos-core.gitcd aptos-core
```

Depending on your setup, you may want to check out a particular branch, to ensure NHC is compatible with your node, e.g., `git checkout --track devnet`.

Run NHC:

```
cargo run -p aptos-node-checker --release -- server run --baseline-config-paths /tmp/nhc/devnet_fullnode.yaml
```

## Generating the OpenAPI specs

[](#generating-the-openapi-specs)

To generate the OpenAPI specs, run the following commands from `ecosystem/node-checker`:

```
cargo run -- server generate-openapi -f yaml > doc/spec.yamlcargo run -- server generate-openapi -f json > doc/spec.json
```

You can also hit the `/spec.yaml` and `/spec.json` endpoints of the running service.

# Node Health Checker FAQ

> Frequently asked questions about the Aptos Node Health Checker including troubleshooting evaluation failures and understanding latency tests.

The Aptos Node Health Checker (NHC) service can be used to check the health of your node(s). See [Node Health Checker](/network/nodes/measure/node-health-checker) for full documentation on the NHC.

The purpose of this FAQ is to help you understand why your node did not pass a particular health check when you ran NHC for it. If you didn't find the information you wanted in this FAQ, [open an issue](https://github.com/aptos-labs/aptos-core/issues/new/choose), or [open a PR](https://github.com/aptos-labs/aptos-core/pulls) and add the information yourself.

## How does the latency evaluator work?

[](#how-does-the-latency-evaluator-work)

You are likely here because you were given an NHC evaluation result like this:

```
Average latency too high: The average latency was 1216ms, which is higher than the maximum allowed latency of 1000ms.
```

While the NHC reports 1216ms above, when you `ping` you might see a latency like 600ms. This difference is because when you `ping` an IP, the result you see is a single round trip (where the latency is the round trip time (RTT)). On the other hand, the NHC latency test will a request to the API running on your node. In effect, this means that the NHC will time 2 round trips, because it does the following:

1.  SYN
2.  SYNACK
3.  ACK + Send HTTP request
4.  Receive HTTP response

i.e., the NHC must do a TCP handshake (one round trip) and then make an HTTP request (second round trip).

The reason the NHC uses the latency evaluator is to ensure that we can maintain good network performance. In particular, if the latency to your node is too high, it will result in a low TPS and high time to finality, both of which are very important to running a highly performant L1 blockchain. **If you receive this error, you will need to try and improve the latency to your node. We have set high thresholds on this value with the understanding that nodes will be running all over the world**.

# Node Inspection Service

> Access runtime metrics and system information from Aptos nodes through the inspection service for monitoring health and performance.

Aptos nodes collect metrics and system information while running. These metrics provide a way to track, monitor and inspect the health and performance of the node dynamically, at runtime. Node metrics and system information can be queried or exported via an inspection service that runs on each node. To see the list of important metrics and counters, see the [Important Node Metrics](/network/nodes/measure/important-metrics) document.

Caution

We do not recommend making the inspection service publicly accessible, as it may expose potentially sensitive information about your node, such as file paths and directories.

## Inspection service features

[](#inspection-service-features)

If you'd like to examine all the endpoints provided by the inspection service, visit the following URL once you have started your node:

```
http://localhost:9101/
```

This will display a directory of all the endpoints and features offered by the service, for example:

```
Welcome to the Aptos Inspection Service!The following endpoints are available:  - /configuration  - /consensus_health_check  - /forge_metrics  - /identity_information  - /json_metrics  - /metrics  - /peer_information  - /system_information
```

## Examine node metrics

[](#examine-node-metrics)

If you'd like to examine the metrics of your node at runtime, visit the following URL:

```
http://localhost:9101/metrics
```

This will display the values of all the metrics and counters of your node at the time you queried it. To see updates to these values, simply refresh the page.

Likewise, if you wish to view the metrics in `json` format, visit the following URL:

```
http://localhost:9101/json_metrics
```

## Configure the inspection service

[](#configure-the-inspection-service)

You can configure various aspects of the node inspection service, for example, you can change the port it listens on, enable or disable certain endpoints, and more. The inspection service is enabled by default, so you do not need to do anything special once you start your node.

The inspection service should run by default at port `9101`. To change the port the inspection service listens on (e.g., to `1000`), add the following to your node configuration file:

```
inspection_service:  port: 1000
```

## Examine node configuration

[](#examine-node-configuration)

The inspection service also provides a way to examine the configuration file of your node at runtime (i.e., the node configuration file that your node started with).

Caution

By default, the configuration endpoint is disabled as it may expose potentially sensitive information about your node, e.g., file paths and directories. We recommend enabling this endpoint only if the inspection service is not publicly accessible.

To enable this feature, add the following to your node configuration file:

```
inspection_service:  expose_configuration: true
```

And visit the configuration URL:

```
http://localhost:9101/configuration
```

## Examine system information

[](#examine-system-information)

Likewise, the inspection service also provides a way to examine the system information of your node at runtime (i.e., build and hardware information). Simply visit the following URL:

```
http://localhost:9101/system_information
```

If you'd like to disable this endpoint, add the following to your node configuration file:

```
inspection_service:  expose_system_information: false
```

Note

The system information displayed here is not guaranteed to be 100% accurate due to limitations in the way this information is collected.

## Examine identity information

[](#examine-identity-information)

The inspection service also provides an easy way to examine the identity of your node (i.e., the peer ID for each network) at runtime. Simply visit the following URL:

```
http://localhost:9101/identity_information
```

If you'd like to disable this endpoint, add the following to your node configuration file:

```
inspection_service:  expose_identity_information: false
```

# Aptos Networks

> Overview of Aptos blockchain networks including Localnet, Devnet, Testnet, and Mainnet with their properties, URLs, and configuration details.

## Network Overview

[](#network-overview)

1.  [Localnet](http://127.0.0.1:8080) -- our standalone tool for local development against a known version of the codebase with no external network.
2.  [Devnet](https://api.devnet.aptoslabs.com/v1/spec#/) -- a shared resource for the community, data resets weekly, weekly update from aptos-core main branch.
3.  [Testnet](https://api.testnet.aptoslabs.com/v1/spec#/) -- a shared resource for the community, data will be preserved, network configuration will mimic Mainnet.
4.  [Mainnet](https://api.mainnet.aptoslabs.com/v1/spec#/) -- a production network with real assets.

### Network properties

[](#network-properties)

| Network Name | Chain ID | Genesis & Waypoint | Faucet | Epoch Duration | Network Provider | Release Cadence | Wipe Cadence | | ------------ | ----------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | --------------------------------------------------------------------- | -------------- | --------------------------------------------------- | --------------- | ------------ | | Mainnet | 1 | [Files Here](https://github.com/aptos-labs/aptos-networks/tree/main/mainnet) | N/A | 2 hours | Fully Decentralized | Monthly, varies | Never | | Testnet | 2 | [Files Here](https://github.com/aptos-labs/aptos-networks/tree/main/testnet) | No programmatic access, you must use the [mint page](/network/faucet) | 2 hours | Managed by Aptos Labs on behalf of Aptos Foundation | Monthly, varies | Never | | Devnet | [On Aptos Explorer **select Devnet from top right**](https://explorer.aptoslabs.com/?network=Devnet). | [Files Here](https://github.com/aptos-labs/aptos-networks/tree/main/devnet) | Accessible programmatically via the API | 2 hours | Managed by Aptos Labs on behalf of Aptos Foundation | Weekly | On update |

### Network URLs

[](#network-urls)

The below URLs are provided by Aptos Labs.

| Network Name | REST API | REST API Spec | Indexer GraphQL API | Indexer GraphQL API Spec | Indexer GRPC | Faucet | Current Token Supply API | | ------------ | ------------------------------------------------ | ------------------------------------------------------------ | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | ------------------------------------------ | ---------------------------------------------- | ------------------------------------------------------- | | Mainnet | [REST API](https://api.mainnet.aptoslabs.com/v1) | [REST API Spec](https://api.mainnet.aptoslabs.com/v1/spec#/) | [Indexer API](https://api.mainnet.aptoslabs.com/v1/graphql) | [Indexer API Spec](https://cloud.hasura.io/public/graphiql?endpoint=https://api.mainnet.aptoslabs.com/v1/graphql) | [GRPC](https://grpc.mainnet.aptoslabs.com) | N/A | [API](https://aptos-supply.dev.gcp.aptosdev.com/supply) | | Testnet | [REST API](https://api.testnet.aptoslabs.com/v1) | [REST API Spec](https://api.testnet.aptoslabs.com/v1/spec#/) | [Indexer API](https://api.testnet.aptoslabs.com/v1/graphql) | [Indexer API Spec](https://cloud.hasura.io/public/graphiql?endpoint=https://api.testnet.aptoslabs.com/v1/graphql) | [GRPC](https://grpc.testnet.aptoslabs.com) | [Mint](/network/faucet) | N/A | | Devnet | [REST API](https://api.devnet.aptoslabs.com/v1) | [REST API Spec](https://api.devnet.aptoslabs.com/v1/spec#/) | [Indexer API](https://api.devnet.aptoslabs.com/v1/graphql) | [Indexer API Spec](https://cloud.hasura.io/public/graphiql?endpoint=https://api.devnet.aptoslabs.com/v1/graphql) | [GRPC](https://grpc.devnet.aptoslabs.com) | [Faucet](https://faucet.devnet.aptoslabs.com/) | N/A |

Token Supply API Update On December 12, 2024, the Aptos Foundation updated its current token supply API. This updated version of the API more accurately reflects the current circulating supply of mainnet by updating the circulating supply number as of the beginning of the current monthly period. The previous version of the API reported the circulating supply as of the prior monthly period. There have been no changes to the network’s circulating supply schedule and the network’s circulating supply remains consistent with the original tokenomics as published [here](https://aptosnetwork.com/currents/aptos-tokenomics-overview).

# Run a Validator and VFN

> Learn how to participate in the Aptos consensus protocol by deploying and running a validator node and validator fullnode (VFN) with step-by-step guidance.

To participate in the Aptos consensus protocol, you must deploy and run a validator node and (optionally) a validator fullnode (VFN). This document provides a high-level overview of the important steps required for deploying both node types.

Note

While VFNs are not required to participate in consensus, it is highly recommended for every validator operator to run a VFN. This is because VFNs are the sole ingress and egress points of blockchain data for the ecosystem. Having many VFNs in the network helps to improve reliability, increase data availability, and provide high-quality blockchain access to the public.

Before initializing a staking pool or delegation pool, read about [Staking](/network/blockchain/staking) and [Delegated Staking](/network/blockchain/delegated-staking) to learn the differences between the stake pool types. Note that once a stake pool has been created, it cannot be changed to a delegation pool or vice versa.

Use the documents within this section to run an Aptos validator and a VFN. At a high-level, the process is as follows:

1.  Understand the requirements and deployment types.
    
    Read the node requirements and select a deployment method (e.g., on-premises or cloud services). Start by reading the node requirements to get to know the compute, memory, networking and storage resources you need. Also, select a method to deploy your nodes, i.e., use cloud managed Kubernetes, Docker, or source code.
    
2.  Generate identities for your nodes.
    
    Create your public/private keypairs and account addresses for the validator and VFN. Remember to keep your private keys confidential!
    
3.  Configure your validator and VFN.
    
    Configure your nodes to use the generated keys and identities. Using YAML files, configure your nodes with the keys and identities generated in the previous step. This is required to allow your nodes to connect to other nodes (i.e., peers) securely.
    
4.  Download genesis and a waypoint for your nodes.
    
    Bootstrap the nodes with a genesis and waypoint, and prepare them for startup. With the nodes configured correctly, install the binaries and download the genesis blob and waypoint files. These will give your nodes the information they need to start syncing with other peers.
    
5.  Join the validator set and start participating.
    
    Initialize the staking pool, join the validator set and start validating to earn rewards. Before other peers will accept connections from your nodes, you will need to join the validator set. To do this, you must initialize a staking pool and delegate to operators and voters. Once your staking pool has been set up, you can join the validator set. At this point your nodes will begin to sync with the network and your validator will be able to start participating in consensus. This is when you can start earning rewards.

# Connect to the Network

> Connect your deployed validator and validator fullnode (VFN) to the Aptos network by initializing staking pools and joining the validator set.

Caution

**Node deployment**  
Before you can connect your nodes to the Aptos network, you will need to deploy them. Make sure to have deployed your nodes using one of the [deployment methods](/network/nodes/validator-node/deploy-nodes) before proceeding.

Once you have deployed your validator and validator fullnode (VFN), you will need to connect them to the Aptos network. This requires initializing your staking pool, joining the validator set, updating your identity files, and bootstrapping your nodes. If you do not complete these steps, your nodes will not be able to connect to other nodes in the network.

Follow the [Connect to a Network](/network/nodes/validator-node/connect-nodes/connect-to-aptos-network) guide to get started.

# Connect to a Network

> Step-by-step guide to connect your validator and VFN to an Aptos network including stake pool initialization, identity updates, and validator set joining.

This document describes how to connect your validator and validator fullnode (VFN) to an Aptos network.

Caution

**MINIMUM STAKING REQUIREMENTS**  
You should only follow these instructions if your validator is able to meet the minimum [staking requirements](/network/blockchain/staking#minimum-and-maximum-stake) for the network. The current required minimum staking requirement is 1 Million APT tokens.

At a high-level, there are four steps required to connect your nodes to an Aptos network:

1.  Initialize stake pool
    
    First, you will need to initialize the stake pool.
    
2.  Update identities
    
    Second, you will need to update your node identity configurations to match the pool address.
    
3.  Join validator set
    
    Third, you will need to join the validator set.
    
4.  Bootstrap your nodes
    
    Finally, you will need to bootstrap your nodes, so they can connect to the network and start syncing.

We will go through each of these steps in detail below.

## Initialize the stake pool

[](#initialize-the-stake-pool)

To begin, you will need to initialize the staking pool for your nodes. There are two types of pools you can initialize, a staking pool or a delegation pool. You can read more about the differences between these pools in the [Staking](/network/blockchain/staking) and [Delegated Staking](/network/blockchain/delegated-staking) sections.

To initialize a staking pool, follow the instructions in [staking pool operations](/network/nodes/validator-node/connect-nodes/staking-pool-operations#initialize-a-staking-pool). Otherwise, to initialize a delegation pool, follow the instructions in [delegation pool operations](/network/nodes/validator-node/connect-nodes/delegation-pool-operations#initialize-a-delegation-pool).

## Update identities

[](#update-identities)

Before joining the validator set, you will need to update your node identity configuration files to match the pool address. This is required to ensure that your nodes are able to connect to other peers in the network.

Caution

**UPDATING THE POOL ADDRESS**  
It is a common error to forget to update the pool address in the node identity configurations. If you do not update the pool address for **both your validator and VFN identity files**, your nodes will not be able to connect to other peers in the network.

Follow the steps below to update your node identity configurations, depending on the deployment method you used.

### Using Source Code

[](#using-source-code)

If you used the source code to deploy your nodes, follow these steps:

1.  Stop your validator and VFN and remove the data directory from both nodes. Make sure to remove the `secure-data.json` file on the validator, too. You can see the location of the `secure-data.json` file in your validator's configuration file.
2.  Update your `account_address` in the `validator-identity.yaml` and `validator-fullnode-identity.yaml` files to your **pool address**. Do not change anything else.
3.  Restart the validator and VFN.

### Using Docker

[](#using-docker)

If you used Docker to deploy your nodes, follow these steps:

1.  Stop your node and remove the data volumes: `docker compose down --volumes`. Make sure to remove the `secure-data.json` file on the validator, too. You can see the location of the `secure-data.json` file in your validator's configuration file.
2.  Update your `account_address` in the `validator-identity.yaml` and `validator-fullnode-identity.yaml` files to your **pool address**. Do not change anything else.
3.  Restart the nodes with: `docker compose up`

### Using Terraform

[](#using-terraform)

If you used Terraform to deploy your nodes (e.g., for AWS, Azure or GCP), follow these steps:

1.  Increase the `era` number in your Terraform configuration. When this configuration is applied, it will wipe the data.
    
2.  Set the `enable_monitoring` variable in your terraform module. For example:
    
    ```
    module "aptos-node" {  ...  enable_monitoring           = true  utility_instance_num        = 3  # this will add one more utility instance to run monitoring component}
    ```
    
3.  Apply the changes with: `terraform apply` You will see a new pod getting created. Run `kubectl get pods` to check.
    
4.  Find the IP/DNS for the monitoring load balancer, using:
    
    ```
    kubectl get svc ${WORKSPACE}-mon-aptos-monitoring --output jsonpath='{.status.loadBalancer.ingress[0]}'
    ```
    
    You will be able to access the Terraform dashboard on `http://<ip/DNS>`.
    
5.  Pull the latest of the terraform module `terraform get -update`, and then apply the Terraform: `terraform apply`.
    
6.  Download the `genesis.blob` and `waypoint.txt` files for your network. See [Node Files](/network/nodes/configure/node-files-all-networks) for locations and commands to download these files.
    
7.  Update your `account_address` in the `validator-identity.yaml` and `validator-fullnode-identity.yaml` files to your **pool address**. Do not change anything else.
    
8.  Recreate the secrets. Make sure the secret name matches your `era` number, e.g. if you have `era = 3`, then you should replace the secret name to be:

```
${WORKSPACE}-aptos-node-0-genesis-e3
```

```
export WORKSPACE=<your workspace name>
kubectl create secret generic ${WORKSPACE}-aptos-node-0-genesis-e2 \    --from-file=genesis.blob=genesis.blob \    --from-file=waypoint.txt=waypoint.txt \    --from-file=validator-identity.yaml=keys/validator-identity.yaml \    --from-file=validator-full-node-identity.yaml=keys/validator-full-node-identity.yaml
```

## Join the validator set

[](#join-the-validator-set)

Next, you will need to join the validator set. Follow the steps below:

Caution

**MAINNET VS TESTNET**  
The commands shown below are for the Aptos mainnet. If you are connecting to a different network, you will need to change the `--network` value in the commands accordingly. You can view the values in [Aptos Blockchain Networks](/network/nodes/networks) to see how profiles can be configured based on the network.

### 1\. Initialize the Aptos CLI

[](#1-initialize-the-aptos-cli)

First, initialize the Aptos CLI with your operator account private key. This can be found in your `private-keys.yaml` file under the entry `account_private_key`.

Replace `<operator_account_private_key>` with the value from the file in the command below:

```
aptos init --profile mainnet-operator \   --network mainnet \   --private-key <operator_account_private_key> \   --skip-faucet
```

### 2\. Check your account balance

[](#2-check-your-account-balance)

Next, make sure you have enough funds to pay for transaction gas on the network. You can check this using the CLI, by running the command below:

```
aptos account list --profile mainnet-operator
```

This will show you the coin balance you have in the validator account. You will see an output like below:

```
"coin": {   "value": "5000"}
```

### 3\. Update on-chain network addresses

[](#3-update-on-chain-network-addresses)

Next, you will need to update the network addresses for your validator and VFN. This is required to ensure that your nodes are able to connect to other peers in the network. First, fetch the pool address for your nodes, by running the command below. Note: the owner address is the address of the account that owns the stake pool, and was used to initialize the stake pool.

```
aptos node get-stake-pool --owner-address <owner_address>
```

Using the pool address from the command above, you will need to update the network addresses for your nodes. You can do this by running the command below. Note that it requires the `operator.yaml` file, which was created when you first deployed your nodes.

```
aptos node update-validator-network-addresses  \   --pool-address <pool-address> \   --operator-config-file ~/$WORKSPACE/$USERNAME/operator.yaml \   --profile mainnet-operator
```

Note

**UPDATING THE NETWORK ADDRESSES**  
Updating your network addresses on-chain requires waiting for the next epoch to begin. This is because the network addresses are updated at the end of the current epoch. Before the next epoch, your nodes will not be able to connect to other peers in the network.

### 4\. Update on-chain consensus key

[](#4-update-on-chain-consensus-key)

Next, you will need to update the consensus key for your nodes. This is required to ensure that your nodes are able to participate in consensus. You can do this by running the command below. Note that it requires the pool address and the `operator.yaml` file (similar to above).

```
aptos node update-consensus-key  \   --pool-address <pool-address> \   --operator-config-file ~/$WORKSPACE/$USERNAME/operator.yaml \   --profile mainnet-operator
```

Note

**UPDATING THE CONSENSUS KEY**  
Updating your consensus key on-chain requires waiting for the next epoch to begin. This is because the consensus key is updated at the end of the current epoch. Before the next epoch, your nodes will not be able to participate in consensus.

### 5\. Join the validator set

[](#5-join-the-validator-set)

Finally, you will need to join the validator set. You can do this by running the command below:

```
aptos node join-validator-set \   --pool-address <pool-address> \   --profile mainnet-operator
```

The validator set is updated at the end of every epoch. You will need to wait for the next epoch to begin before your validator node is able to join the validator set.

Note

**IDENTIFYING THE NEXT EPOCH**  
You can identify the next epoch by checking the [Aptos Explorer](https://explorer.aptoslabs.com/validators/all?network=mainnet) or by running the command `aptos node get-stake-pool`.

### 6\. Check the validator set

[](#6-check-the-validator-set)

When you execute the command to join the validator set, your validator will be in a "Pending Active" state until the next epoch occurs. You can run the command below to look for your validator in the `pending_active` list.

```
aptos node show-validator-set --profile mainnet-operator | jq -r '.Result.pending_active' | grep <pool_address>
```

When the next epoch occurs, the node will be moved into `active_validators` list. Run the command below to see your validator in the "active\_validators" list:

```
aptos node show-validator-set --profile mainnet-operator | jq -r '.Result.active_validators' | grep <pool_address>
```

## Bootstrap your nodes

[](#bootstrap-your-nodes)

After joining the validator set and updating your node identity configurations to match the pool address, you will need to bootstrap your nodes to connect to the network. To do this, follow the steps below:

1.  Start the VFN. The VFN will connect to the network and start syncing. See [State Synchronization](/network/nodes/configure/state-sync) for more information.
2.  Once the VFN is synced, restart the validator. It will sync from the VFN and then connect to other validators in the network and start participating in consensus.

Once both of these steps are complete, your nodes will be connected to the network and participating in consensus.

## Next steps

[](#next-steps)

Congratulations! You have successfully connected your nodes to the Aptos network. To verify that your nodes are running correctly, visit the [Node Health](/network/nodes/validator-node/verify-nodes/node-liveness-criteria) document. This document describes how you can verify and monitor the health of your validator and VFN, including an initial node verification section.

# Delegation Pool Operations

> Comprehensive guide to delegation pool operations for delegated staking including initialization, delegation, commission management, and allowlisting features.

> Beta: This documentation is in experimental, beta mode. Supply feedback by opening a [GitHub issue](https://github.com/aptos-labs/developer-docs/issues/new/choose). See also the related [Staking Pool Operations](/network/nodes/validator-node/connect-nodes/staking-pool-operations) instructions.

Validator operators should follow these instructions to carry out delegation pool operations for [delegated staking](/network/blockchain/delegated-staking). You may delegate as little as 10 APT plus a small add stake fee that will be mostly refunded as rewards at the end of the current epoch. You might notice that some UIs might use 11 APT as the minimum for a round number. Note that your validator will become part of the _Active Validator Set_ only when the delegation pool satisfies the minimum cumulative [staking requirement of 1 million APT](/network/nodes/validator-node/connect-nodes/staking-pool-operations).

The delegation pool owner should set an operator for the pool via the `set_operator` function described in the [Perform pool owner operations](#perform-pool-owner-operations) section. The operator should then start their own Aptos node, as it is a best practice to have a different account for owner and operator. Once the delegation pool attains 1 million APT, the operator can join the validator set.

The operator address will receive the pool commission that was set at the initialization of the delegation pool, which is automatically distributed as stake in the delegation pool at the end of each epoch. The operator will act as a normal Delegation Pool account that is able to do all the operations described in [Perform delegation pool operations](#perform-delegation-pool-operations).

## Prerequisites

[](#prerequisites)

1.  [Install and configure](/build/cli) the Aptos CLI. If you are looking to develop on the Aptos blockchain, debug apps, or perform node operations, the Aptos tool offers a command line interface for these purposes.
2.  [Initialize local configuration and create an account](/build/cli/setup-cli) on the Aptos blockchain.

## Initialize a delegation pool

[](#initialize-a-delegation-pool)

Before initializing a delegation pool, you need to know the delegation pool address. You can use the following CLI commands to obtain the delegation pool address depending on where you are in the process:

*   Before you create the delegation pool:
    
    ```
    aptos account derive-resource-account-address --address <owner_address> --seed "aptos_framework::delegation_pool<SEED>" --seed-encoding utf8
    ```
    
    *   The `<SEED>` is a number chosen by you to create the resource account address to host the delegation pool resource. Once you choose a seed, you should use the same value for all following usages.
*   After you create the delegation pool:
    
    ```
    aptos account derive-resource-account-address
    ```

1.  Run the command below, substitute in the profile you previously configured during initialization:
    
    ```
    aptos move run --profile <your-profile> \   --function-id 0x1::delegation_pool::initialize_delegation_pool \   --args u64:1000 string:00
    ```
    
    Where `--args`:
    
    *   `u64:1000` represents `operator_commission_percentage` - 1000 is equivalent to 10% and 10000 is 100%.
    *   `string:00` represents `delegation_pool_creation_seed` - a number chosen by you to create a resource account associated with your owner address; this account is used to host the delegation pool resource. You should use the same number here as the `--seed` you used in the previous step to create the delegation pool.
2.  Once this command is executed without error an account for resources is established using the `owner` signer and a provided `delegation_pool_creation_seed` to hold the `delegation pool resource` and possess the underlying stake pool.
    
3.  The `owner` is granted authority over assigning the `operator` and `voter` roles, which are initially held by the `owner`.
    
4.  The delegation pool can now accept a minimum amount of 10 APT from any user who wishes to delegate to it.
    
5.  The delegation pool can now [connect to the Aptos Network](/network/nodes/validator-node/connect-nodes/connect-to-aptos-network).

## Perform delegation pool operations

[](#perform-delegation-pool-operations)

This section describes the available operations that can be performed on this recently created pool. Once the delegation pool has been established, use the Aptos CLI to operate the pool. The available actions that can be performed on it include:

*   Add `amount` of coins to the delegation pool `pool_address` using the public entry method `add_stake(delegator: &signer, pool_address: address, amount u64)` and substituting your values into the command below before running it:
    
    ```
    aptos move run --profile delegator \  --function-id 0x1::delegation_pool::add_stake \  --args address:<pool_address> u64:<amount>
    ```
    
*   Undelegate (unlock) the amount of funds from the delegator's active and pending active stake up to the limit of the active stake in the stake pool using public entry method `unlock(delegator: &signer, pool_address: address, amount: u64)` and substituting your values into the command below before running it:
    
    ```
    aptos move run --profile delegator \  --function-id 0x1::delegation_pool::unlock \  --args address:<pool_address> u64:<amount>
    ```
    
*   Cancel undelegate (reactivate stake) `amount` of coins from `pending_inactive` state to `active state` using public entry method `reactivate_stake(delegator: &signer, pool_address: address, amount: u64)` with the command and your values:
    
    ```
    aptos move run --profile delegator \  --function-id 0x1::delegation_pool::reactivate_stake \  --args address:<pool_address> u64:<amount>
    ```
    
*   Withdraw `amount` of owned inactive stake from the delegation pool at `pool_address` using the public entry method `withdraw(delegator: &signer, pool_address: address, amount: u64)` and the command:
    
    ```
    aptos move run --profile delegator \  --function-id 0x1::delegation_pool::withdraw \  --args address:<pool_address> u64:<amount>
    ```

## Perform pool owner operations

[](#perform-pool-owner-operations)

Delegation pool owners have access to specific methods designed for modifying the `operator` and `voter` roles of the delegation pool. Use the following Aptos CLI commands and include the relevant addresses:

*   Set the operator address for the delegation pool:
    
    ```
    aptos move run --profile delegation_pool_owner \  --function-id 0x1::delegation_pool::set_operator \  --args address:<new_operator_address>
    ```

Delegation pool owners can update the commission percentage for the delegation pool. The commission rate change can be requested at least 7.5 days before the current lockup cycle ends. The new commission percentage takes effect upon any `synchronize_delegation_pool` call after the end of the current lockup cycle. Owners are required to call `synchronize_delegation_pool` as soon as the lockup cycle ends to ensure that the new commission percentage takes effect. Otherwise, the old commission rate will continue to be used until the next `synchronize_delegation_pool` call.

*   Update the commission percentage for the delegation pool; `<new_commission_percentage>` has two decimal points precision (e.g., 13.25% is represented as 1325):
    
    ```
    aptos move run --profile delegation_pool_owner \  --function-id 0x1::delegation_pool::update_commission_percentage \  --args u64:<new_commission_percentage>
    ```

## Set beneficiary addresses for operators

[](#set-beneficiary-addresses-for-operators)

Delegation pool operators can set beneficiary addresses to receive the operator commission earned by the delegation pool.

*   The beneficiary addresses can be set by the operator using the following command:
    
    ```
    aptos move run --profile delegation_pool_operator \  --function-id 0x1::delegation_pool::set_beneficiary_for_operator \  --args address:<new_beneficiary_address>
    ```
    
*   To view the beneficiary address set for the operator, use the following command:
    
    ```
    aptos move view --url <REST API for the network> \  --function-id 0x1::delegation_pool::beneficiary_for_operator \  --args address:<operator_address>
    ```

Any existing unpaid commission rewards will be paid to the new beneficiary. To ensures payment to the current beneficiary, one should first call `synchronize_delegation_pool` before switching the beneficiary. In case an operator operates multiple delegation pools, the operator can only set one beneficiary for all the delegation pools, not a separate one for each pool.

Once the beneficiary address is set, the operator commission earned by the delegation pool will be distributed to the beneficiary address. The beneficiary account can perform the operations such as `unlock` and `withdraw` for the commission earned.

## Check delegation pool information

[](#check-delegation-pool-information)

Until the delegation pool has received 1 million APT and the validator has been added to the set of active validators, there will be no rewards to track during each cycle. In order to obtain information about a delegation pool, use the Aptos [View function](/build/apis/fullnode-rest-api#reading-state-with-the-view-function)

*   `get_owned_pool_address(owner: address): address` - Returns the address of the delegation pool belonging to the owner, or produces an error if there is no delegation pool associated with the owner.
    
*   `delegation_pool_exists(addr: address): bool` - Returns true if a delegation pool exists at the provided address `addr`.
    
*   `operator_commission_percentage(pool_address: address): u64` - Returns the operator commission percentage set on the delegation pool at initialization.
    
*   `get_stake(pool_address: address, delegator_address: address): (u64, u64, u64)` - Returns total stake owned by `delegator_address` within delegation pool `pool_address` in each of its individual states: (`active`,`inactive`,`pending_inactive`).
    
*   `get_delegation_pool_stake(pool_address: address): (u64, u64, u64, u64)` - Returns the stake amounts on `pool_address` in the different states: (`active`,`inactive`,`pending_active`,`pending_inactive`).
    
*   `shareholders_count_active_pool(pool_address: address): u64` - Returns the number of delegators owning an active stake within `pool_address`.
    
*   `get_pending_withdrawal(pool_address: address, delegator_address: address): (bool, u64)` - Returns if the specified delegator possesses any withdrawable stake. However, if the delegator has recently initiated a request to release some of their stake and the stake pool's lockup cycle has not ended yet, then their funds may not yet be available for withdrawal.
    
*   `can_withdraw_pending_inactive(pool_address: address): bool` - Returns whether `pending_inactive` stake can be directly withdrawn from the delegation pool, implicitly its stake pool, in the special case the validator had gone inactive before its lockup expired.

In the [Aptos TypeScript SDK](/build/sdks/ts-sdk), a View function request would resemble:

```
import { Aptos, AptosConfig } from "@aptos-labs/ts-sdk";
const NODE_URL = "https://aptos-testnet.public.blastapi.io";
(async () => {  const aptosConfig = new AptosConfig({ fullnode: NODE_URL });  const aptos = new Aptos(aptosConfig);  const payload: InputViewRequestData = {    function: "0x1::delagation_pool::get_stake",    functionArguments: ["pool_address", "delegator_address"],  };  console.log(await aptos.view({ payload }));})();
```

Alternatively, you can use Aptos CLI to call View functions.

```
aptos move view [OPTIONS] --function-id <FUNCTION_ID>
```

To discover the available options and the process for making an `aptos move view` call, access the help information with `aptos move view --help`. This will display the required arguments for invoking the view functions.

## Compute delegation pool rewards earned

[](#compute-delegation-pool-rewards-earned)

Use this formula to calculate _rewards earned_ for `active` and `pending_inactive` staking. This formula assumes that different stake operations such as `unlock` and `reactivate` take out the _principals_ first and then _rewards_. Therefore, _rewards earned_ may vary based upon how the formula you use is constructed:

1.  Get the amount of `active` and `pending_inactive` staking from the [`get_stake`](https://github.com/aptos-labs/aptos-core/blob/ed63ab756cda61439287304ed89bbb156fcbeaed/aptos-move/framework/aptos-framework/sources/delegation_pool.move#L321) view function.
    
2.  Calculate principal:
    
    *   "active principal" = **AddStakeEvent** - **UnlockStakeEvent** + **ReactivateStakeEvent**. If at any point during the iteration, "active principal" < 0, reset to 0. Negative principal could happen when the amount users `unlock` include rewards earned from staking.
    *   "pending inactive principal" = **UnlockStakeEvent** - **ReactivateStakeEvent**. If at any point during the iteration, "pending inactive principal" < 0, reset to 0. Negative principal could happen when the amount users `reactivate` include rewards earned from staking.
3.  Compute rewards earned:
    
    *   active rewards = `active` - active principal.
    *   pending\_inactive\_rewards = `pending_inactive` - "pending inactive principal".

## Allowlisting for delegation pools

[](#allowlisting-for-delegation-pools)

Delegation pool owners can set an allowlist for their delegation pool. They can add or remove addresses from the allowlist and evict delegators who are not on the allowlist. Here is the flow:

1.  By default, a delegation pool is permissionless and does not have an allowlist. The pool owner can set an allowlist, transitioning the pool to a permissioned state.
2.  When an allowlist is first established in a delegation pool, it starts empty. This initial empty allowlist does not impact existing stakes in the pool. However, the pool will not accept any new stakes or reactivation of pending-inactive stakes from any stakers because no one is on the allowlist initially.
3.  The pool owner may add stakers' wallet addresses to the allowlist. Once an address is added, the staker can add new stakes or reactivate existing stakes in the pool. Note that this feature does not facilitate a mechanism for stakers to request to be added to the allowlist; such requests must be managed off-chain (e.g., through private communication between the operator and staker, or UI-based solutions).
4.  If a delegator is removed from the allowlist, they are no longer able to add or reactivate stakes. However, they retain the ability to unlock and withdraw their existing stakes.
5.  The pool owner can evict a delegator who is not included on the allowlist. This action will unlock the delegator's entire stake, transitioning all of their active stakes to a pending inactive state. As the evicted delegator is not on the allowlist, they cannot reactive their stake. Note that these tokens will remain locked up until the end of the lockup period, and the existing stake will also continue to earn rewards until then. When the lockup period ends, the funds will be unstaked (inactive), but will remain in the pool until the delegator initiates a withdrawal.
6.  If a delegator's stake enters the pending inactive state due to eviction, the pool owner can subsequently add the delegator back to the allowlist. However, this action will not automatically reactivate the stake. Automatic reactivation is not provided to prevent potential misuse by a malicious pool owner who might repeatedly evict and re-allowlist a delegator to prevent them from leaving the pool. Once a delegator is back on the allowlist, the delegator must manually call the reactivate\_stake function to reactivate their stake.
7.  Delegation pools that have enabled allowlisting can disable it. When disabled, the delegation pool becomes permissionless, allowing any staker to stake to the pool.

*   The delegation pool owner can enable allow listing and create an empty allowlist using the following command:
    
    ```
    aptos move run --profile delegation_pool_owner \  --function-id 0x1::delegation_pool::enable_delegators_allowlisting
    ```
    
*   The delegation pool owner can disable allow listing and delete the existing allowlist using the following command:
    
    ```
    aptos move run --profile delegation_pool_owner \  --function-id 0x1::delegation_pool::disable_delegators_allowlisting
    ```
    
*   The delegation pool owner can add an address to the allowlist using the following command:
    
    ```
    aptos move run --profile delegation_pool_owner \  --function-id 0x1::delegation_pool::allowlist_delegator \  --args address:<delegator_address>
    ```
    
*   The delegation pool owner can remove an address from the allowlist using the following command:
    
    ```
    aptos move run --profile delegation_pool_owner \  --function-id 0x1::delegation_pool::remove_delegator_from_allowlist \  --args address:<delegator_address>
    ```
    
*   The delegation pool owner can evict a delegator from the pool by unlocking their entire stake using the following command:
    
    ```
    aptos move run --profile delegation_pool_owner \  --function-id 0x1::delegation_pool::evict_delegator \  --args address:<delegator_address>
    ```

There are also view functions available to check the allowlist status and the addresses on the allowlist:

*   The following view function returns whether `pool` has allow listing enabled:
    
    ```
    aptos move view --url <REST API for the network> \  --function-id 0x1::delegation_pool::allowlisting_enabled \  --args address:<pool>
    ```
    
*   The following view function returns whether `delegator` is on the allowlist of `pool`:
    
    ```
    aptos move view --url <REST API for the network> \  --function-id 0x1::delegation_pool::delegator_allowlisted \  --args address:<pool> address:<delegator>
    ```
    
*   The following view function returns the allowlist defined on pool:
    
    ```
    aptos move view --url <REST API for the network> \  --function-id 0x1::delegation_pool::get_delegators_allowlist \  --args address:<pool>
    ```

# Staking Pool Operations

> Complete guide to staking pool operations including initialization, owner operations, commission management, and performance monitoring with minimum 1M APT requirement.

This document describes how to perform [staking](/network/blockchain/staking) pool operations. Note that a staking pool can only accept stake from the stake pool owner. You can stake only when you meet the minimum staking requirement.

Note

**MINIMUM STAKING REQUIREMENT**  
The current minimum staking requirement is 1 million APT.

See also the related [Delegation Pool Operations](/network/nodes/validator-node/connect-nodes/delegation-pool-operations) instructions to accept stake from multiple delegators in order to reach the minimum staking requirement.

Caution

**POOL TYPES ARE STATIC**  
There is no upgrade mechanism for the staking contract to move from a staking pool to a delegation pool. A new delegation pool must be created.

## Initialize a staking pool

[](#initialize-a-staking-pool)

Note

**TESTNET VS MAINNET**  
The Aptos CLI commands below target mainnet. Change the `--network` value for testnet and devnet. View the values in [Aptos Blockchain Networks](/network/nodes/networks) to see how profiles can be configured based on the network.

Before initializing a staking pool, ensure that there is an existing owner account with 1 Million APT.

1.  Initialize the [Aptos CLI](/build/cli) with a private key from an existing account, such as a wallet, or create a new account.

```
aptos init --profile mainnet-owner \  --network mainnet
```

You can either enter the private key from an existing wallet, or create new wallet address.

2.  Run the following command to initialize the staking pool:

```
aptos stake create-staking-contract \  --operator <operator-address> \  --voter <voter-address> \  --amount 100000000000000 \  --commission-percentage 10 \  --profile mainnet-owner
```

3.  Once the staking pool has been initialized, you can proceed to [connect to the Aptos Network](/network/nodes/validator-node/connect-nodes/connect-to-aptos-network).

## Perform pool owner operations

[](#perform-pool-owner-operations)

### Transfer coin between accounts

[](#transfer-coin-between-accounts)

```
aptos account transfer \  --account <operator-address> \  --amount <amount> \  --profile mainnet-owner
```

### Switch operator

[](#switch-operator)

```
aptos stake set-operator \  --operator-address <new-operator-address> \  --profile mainnet-owner
```

### Switch voter

[](#switch-voter)

```
aptos stake set-delegated-voter \  --voter-address <new-voter-address> \  --profile mainnet-owner
```

### Add stake

[](#add-stake)

```
aptos stake add-stake \  --amount <amount> \  --profile mainnet-owner
```

### Increase stake lockup

[](#increase-stake-lockup)

```
aptos stake increase-lockup --profile mainnet-owner
```

### Unlock stake

[](#unlock-stake)

```
aptos stake unlock-stake \  --amount <amount> \  --profile mainnet-owner
```

### Withdraw stake

[](#withdraw-stake)

```
aptos stake withdraw-stake \  --amount <amount> \  --profile mainnet-owner
```

### Update commission

[](#update-commission)

```
aptos move run --function-id 0x1::staking_contract::update_commission \  --args address:<operator_address> u64:<commission_percentage> \  --profile mainnet-owner
```

## Set beneficiary addresses for operators

[](#set-beneficiary-addresses-for-operators)

Staking pool operators can set beneficiary addresses to receive the operator commission earned by the staking pool.

*   The beneficiary addresses can be set by the operator using the following command:
    
    ```
    aptos move run --profile mainnet_operator \  --function-id 0x1::staking_contract::set_beneficiary_for_operator \  --args address:<new_beneficiary_address>
    ```
    
*   To view the beneficiary address set for the operator, use the following command:
    
    ```
    aptos move view --url <REST API for the network> \  --function-id 0x1::staking_contract::beneficiary_for_operator \  --args address:<operator_address>
    ```

Any existing unpaid commission rewards will be paid to the new beneficiary. To ensures payment to the current beneficiary, one should first call `distribute` before switching the beneficiary. In case an operator operates multiple staking pools, the operator can set one beneficiary for all the staking pools, not a separate one for each pool.

Once the beneficiary address is set, either the operator or the beneficiary can request the operator commission by `request_commission`.

## Checking your stake pool information

[](#checking-your-stake-pool-information)

Note

Before you proceed, see [Validation on the Aptos blockchain](/network/blockchain/staking#validation-on-the-aptos-blockchain) for a brief overview.

To check the details of your stake pool, run the below CLI command with the `get-stake-pool` option by providing the `--owner-address` and `--url` fields.

The below command is for an example owner address `e7be097a90c18f6bdd53efe0e74bf34393cac2f0ae941523ea196a47b6859edb`.

Note

For testnet or devnet `--url` field values, see [Aptos Blockchain Networks](/network/nodes/networks).

```
aptos node get-stake-pool \  --owner-address e7be097a90c18f6bdd53efe0e74bf34393cac2f0ae941523ea196a47b6859edb \  --profile mainnet-operator
```

Example output:

```
{  "Result": [    {      "state": "Active",      "pool_address": "25c3482850a188d8aa6edc5751846e1226a27863643f5ebc52be4f7d822264e3",      "operator_address": "3bec5a529b023449dfc86e9a6b5b51bf75cec4a62bf21c15bbbef08a75f7038f",      "voter_address": "3bec5a529b023449dfc86e9a6b5b51bf75cec4a62bf21c15bbbef08a75f7038f",      "pool_type": "StakingContract",      "total_stake": 100525929489123,      "commission_percentage": 10,      "commission_not_yet_unlocked": 15949746439,      "lockup_expiration_utc_time": "2022-10-07T07:12:55Z",      "consensus_public_key": "0xb3a7ac1491b0165f08f136c2b02739846b6610084984d5298c2983c4f8e5553284bffca2e3fe2b99167da82717501732",      "validator_network_addresses": [        "/ip4/35.91.145.164/tcp/6180/noise-ik/0xeddf05470520af91b847f353dd804a04399e1213d130a4260e813527f2c49262/handshake/0"      ],      "fullnode_network_addresses": [],      "epoch_info": {        "epoch": 594,        "epoch_interval_secs": 3600,        "current_epoch_start_time": {          "unix_time": 1665087178789891,          "utc_time": "2022-10-06T20:12:58.789891Z"        },        "next_epoch_start_time": {          "unix_time": 1665090778789891,          "utc_time": "2022-10-06T21:12:58.789891Z"        }      }    }  ]}
```

### Description of output fields

[](#description-of-output-fields)

**state**

*   "Active": Validator is already in the validator set and proposing.
*   "Pending\_active": Validator will be added to the validator set in the next epoch. \*\*Do not try to join the validator set again before the arrival of next epoch, or else you will receive an error. \*\*

**pool\_address**

*   Use this "pool\_address" (not the operator address) in you `validator.yaml` file. If you mistakenly used the operator address, you will receive the message: "Validator not in validator set".

**commission\_percentage**

*   This can be set only by the stake pool owner. Operator receives the "commission\_percentage" of the generated staking rewards. If you request the commission (you can do so by running the command `aptos stake request-commission`), then at the end of the `lockup_expiration_utc_time` the commission part of the rewards will go to the operator address while the rest will stay in the stake pool and belong to the owner. Here "the commission part of the rewards" means the value of **commission\_not\_yet\_unlocked**.
    
    For example, in a scenario with a lock-up of one month, you call `aptos stake request-commission` every month. This will pay out the commission that was accrued during the previous month but only when unlocked at the end of the previous month. Regardless of how often you run `aptos stake request-commission` during the month, the commission is only paid out upon the completion of `lockup_expiration_utc_time`.
    
    Note
    
    **COMPOUNDING**  
    Note that if you do not request commission for multiple months, your commission will accrue more due to compounding of the **commission\_percentage** during these months.

**commission\_not\_yet\_unlocked**

*   The amount of commission (amount of APT) that is not yet unlocked. It will be unlocked at the `lockup_expiration_utc_time`. This is the total commission amount available to the operator, i.e., the staking rewards **only** to the operator. This does not include the staking rewards to the owner.

**lockup\_expiration\_utc\_time**

*   The date when the commission will unlock. However, this unlocked commission will not be auto-disbursed. It will only disburse when the command `aptos stake request-commission` is called again.

**epoch\_info**

*   Use [Epoch Converter](https://www.epochconverter.com/) or a similar tool to convert the `unix_time` into human-readable time.

## Requesting commission

[](#requesting-commission)

Either an owner, an operator or the beneficiary of the operator can request commission. You must request commission **twice**, once before the end of the lockup period and a second time after the lockup period ends, i.e., at the end of **lockup\_expiration\_utc\_time**, by running the `aptos stake request-commission` command. Make sure to provide the operator and the owner addresses. See an example command below:

```
aptos stake request-commission \  --operator-address 0x3bec5a529b023449dfc86e9a6b5b51bf75cec4a62bf21c15bbbef08a75f7038f \  --owner-address 0xe7be097a90c18f6bdd53efe0e74bf34393cac2f0ae941523ea196a47b6859edb \  --profile mainnet-operator
```

When you run the `aptos stake request-commission` command before the end of the lockup expiration, the command will initiate unlock for any locked commission earned up until that moment in time. The commission will remain in `pending_inactive` until the end of the lockup period, will continue to earn rewards until the lockup period expires. The commission will not be withdrawable until after the end of the lockup period, when `aptos stake request-commission` is called a second time.

See example below:

Month 1 Day 29, you call the command, it would initiate unlock for 29 days worth of commission.

Month 2, Day 29, if you call the command again, it would disburse the fully unlocked commission from previous month (29 days worth), and initiate commission unlock for Month 1 Day 30 + Month 2 Day 1-29 (30 days worth).

Month 3, Day 29, if you call the commission again, 30 days of commission would be disbursed, and a new batch of commission would initiate unlock.

You can call the command multiple times, and the amount you receive depends on the day when you requested commission unlock previously.

Commission is unlocked when `request-commission` is called, the staker unlocks stake, or the staker switches operator.

## Checking your validator performance

[](#checking-your-validator-performance)

To see your validator performance in the current and past epochs and the rewards earned, run the below command. The output will show the validator's performance in block proposals, and in governance voting and governance proposals. Default values are used in the below command. Type `aptos node get-performance --help` to see default values used.

```
aptos node get-performance \  --pool-address <pool address> \  --profile mainnet-operator
```

Example output:

```
{  "Result": {    "current_epoch_successful_proposals": 56,    "current_epoch_failed_proposals": 0,    "previous_epoch_rewards": [      "12312716242",      "12272043711",      "12312912674",      "12313011054",      "12313109435",      "12180092056",      "12313305136",      "12313403519",      "12313501903",      "12313600288"    ],    "epoch_info": {      "epoch": 68,      "epoch_interval": 3600000000,      "last_epoch_start_time": {        "unix_time": 1665074662417326,        "utc_time": "2022-10-06T16:44:22.417326Z",        "local_time": "Thu Oct  6 16:44:22 2022"      },      "next_epoch_start_time": {        "unix_time": 1665078262417326,        "utc_time": "2022-10-06T17:44:22.417326Z",        "local_time": "Thu Oct  6 17:44:22 2022"      }    }  }}
```

#### Description of fields

[](#description-of-fields)

**current\_epoch\_successful\_proposals**

*   Successful leader-validator proposals during the current epoch. Also see [Validation on the Aptos blockchain](/network/blockchain/staking#validation-on-the-aptos-blockchain) for the distinction between leader-validator and the voter-validator.

**previous\_epoch\_rewards**

*   An ordered list of rewards earned (APT amounts) for the previous 10 epochs, starting with the 10 epoch in the past. In the above example, a reward of 12312716242 APT was earned 10 epochs past and a reward of 12313600288 APT was earned in the most recent epoch. If a reward is 0 for any epoch, then:
    *   Either the validator was not part of the validator set in that epoch (could have been in either inactive or pending\_active validator state), or
    *   The validator missed all the leader proposals.

### Checking the performance for all epochs

[](#checking-the-performance-for-all-epochs)

To check the performance of all the epochs since the genesis, run the below command. You can filter the results for your pool address with `grep`, as shown below:

```
aptos node analyze-validator-performance \  --analyze-mode detailed-epoch-table \  --profile mainnet-operator \  --start-epoch 0 | grep <pool address>
```

## Tracking rewards

[](#tracking-rewards)

`DistributeEvent` is emitted when there is a transfer from staking\_contract to the operator or staker (owner). Rewards can be tracked either by listening to `DistributeEvent` or by using the [View function](/build/apis/fullnode-rest-api#reading-state-with-the-view-function) to call `staking_contract_amounts`. This will return `accumulated_rewards` and `commission_amount`.

# Voting for a Staking Pool

> Guide for staking pool voters to participate in Aptos governance using both the Governance UI and Aptos CLI for proposal voting and delegation.

If you are a [staking pool](/network/blockchain/staking) voter, then we recommend strongly that you do not store your Aptos voter keys with a custodian before the custodian supports this function. Until then, we suggest you store your voter keys in an Aptos wallet like [Petra](https://petra.app/).

This document describes how to perform staking voter operations while in the Aptos mainnet using an Aptos wallet.

### Using Governance UI

[](#using-governance-ui)

To participate as a voter in the Aptos governance, follow these steps:

1.  Go to the [Proposals section](https://governance.aptosfoundation.org/) of the Aptos Governance page.
2.  Connect your wallet by clicking on **CONNECT WALLET** (top-right).
3.  Make sure that wallet is set to connect to Mainnet.
4.  View the proposals. When you are ready to vote on a proposal, click on the proposal and vote.
5.  You will see a green bar indicating that the voting transaction is successful.

### Using the Aptos CLI

[](#using-the-aptos-cli)

1.  Get your stake pool info using: `aptos node get-stake-pool --owner-address <owner-address> --url <REST API for the network>`.
2.  To see the list of proposals, execute: `aptos governance list-proposals --url https://api.mainnet.aptoslabs.com`.
3.  To set up your voter profile, run: `aptos init`.
4.  To vote on a proposal, execute: `aptos governance vote --proposal-id <PROPOSAL_ID> --pool-address <POOL_ADDRESS> --url <URL> --profile <profile>`.

## Delegation Pool Voter

[](#delegation-pool-voter)

If you staked to a [delegation pool](/network/blockchain/delegated-staking), you can vote proportional to your stake amount in the delegation pool or delegate your votes to another voter address.

### Using Governance UI

[](#using-governance-ui-1)

To participate as a voter, follow these steps:

1.  Go to the [Proposals section](https://govscan.live/aptos-proposals) on Govscan.
2.  Connect your wallet by clicking on **CONNECT WALLET**
3.  Make sure that wallet is set to connect to Mainnet.
4.  View the proposals. When you are ready to vote on a proposal, click on the proposal and vote.
5.  You will see a green bar indicating that the voting transaction is successful.

### Using the Aptos CLI

[](#using-the-aptos-cli-1)

1.  Get your delegation pool address from the [Aptos Explorer page](https://explorer.aptoslabs.com/validators/delegation?network=mainnet).
2.  To see the list of proposals, execute: `aptos governance list-proposals --url https://api.mainnet.aptoslabs.com`.
3.  To set up your voter profile, run: `aptos init`.
4.  To vote on a proposal, execute: `aptos move run --function-id 0x1::delegation_pool::vote --args address:<pool-address> u64:<proposal-id> u64:<voting-power> bool:<true or false>`.

To delegate your voting power, follow these steps:

1.  Get your delegation pool address from the [Aptos Explorer page](https://explorer.aptoslabs.com/validators/delegation?network=mainnet).
2.  To set up your voter profile, run: `aptos init`.
3.  To delegate voting power, run: `aptos move run --function-id 0x1::delegation_pool::delegate_voting_power --args address:<pool-address> address:<delegated-voter-address>`.
4.  The new delegated voter will take effect in the next lockup cycle after the current lockup cycle ends. To view delegated voter, run `aptos move view --profile delegator --function-id 0x1::delegation_pool::calculate_and_update_delegator_voter --args address:<pool-address> address:<delegator-address>`.

# Deploy Validator and VFN Nodes

> Choose from multiple deployment methods to set up your validator and validator fullnode (VFN) across various platforms and cloud providers.

Before you can run a validator and validator fullnode (VFN) in an Aptos network, you will need to select a deployment method for your nodes. The guides below provide step-by-step instructions for deploying a validator node and VFN on various platforms, and across different Aptos networks.

Once your nodes are deployed, you can connect them to an Aptos network by initializing your staking pool and joining the validator set. See [Connect Nodes](/network/nodes/validator-node/connect-nodes) for more information.

Caution

Before selecting a deployment method, make sure to read and understand the [Node Requirements](/network/nodes/validator-node/node-requirements) first.

# Deployment methods

[](#deployment-methods)

Select a deployment method for your nodes:

*   ### [Using Source Code](/network/nodes/validator-node/deploy-nodes/using-source-code)
    
    [](#using-source-code)
    
*   ### [Using Docker](/network/nodes/validator-node/deploy-nodes/using-docker)
    
    [](#using-docker)
    
*   ### [Using AWS](/network/nodes/validator-node/deploy-nodes/using-aws)
    
    [](#using-aws)
    
*   ### [Using Azure](/network/nodes/validator-node/deploy-nodes/using-azure)
    
    [](#using-azure)
    
*   ### [Using GCP](/network/nodes/validator-node/deploy-nodes/using-gcp)
    
    [](#using-gcp)

# Using AWS

> Deploy Aptos validator and validator fullnode (VFN) on Amazon Web Services using Terraform and EKS with comprehensive setup instructions.

This is a step-by-step guide to deploy an Aptos validator and validator fullnode (VFN) using Amazon Web Services (AWS). Using this guide, the validator and VFN will be deployed on separate machines.

Caution

**Prerequisites**  
Before you begin, make sure to read and understand the [Node Requirements](/network/nodes/validator-node/node-requirements). Similarly, make sure you have installed the [Aptos CLI](/build/cli), [Terraform](https://www.terraform.io/downloads.html), [Kubernetes CLI](https://kubernetes.io/docs/tasks/tools/), and [AWS CLI](https://aws.amazon.com/cli/). This guide assumes that you already have an AWS account setup.

## Deployment steps

[](#deployment-steps)

Note

**Default connection to mainnet**  
If you follow the default setup in this document, then your validator and VFN will be connected to the Aptos mainnet. To connect to a different Aptos network, such as testnet, make sure you download the correct genesis and waypoint files for the network you want to connect to. Similarly, you will need to modify the Terraform files to use the correct configurations (e.g., `source`, `image_tag` and `chain_id`).

1.  Create a working directory for your Aptos nodes, and pick a username for your nodes, e.g.,
    
    ```
    export WORKSPACE=mainnetexport USERNAME=alicemkdir ~/$WORKSPACEcd ~/$WORKSPACE
    ```
    
2.  Create an S3 storage bucket for storing the Terraform state on AWS. You can do this on the AWS UI or using the command below:
    
    ```
    aws s3 mb s3://<bucket name> --region <region name>
    ```
    
3.  Create a Terraform file called `main.tf` in your working directory:
    
    ```
    cd ~/$WORKSPACEvi main.tf
    ```
    
4.  Modify the `main.tf` file to configure Terraform and create the Terraform module. See the example below:
    
    ```
    terraform {  required_version = "~> 1.3.6"  backend "s3" {    bucket = "terraform.aptos-node"    key    = "state/aptos-node"    region = <aws region>  }}
    provider "aws" {  region = <aws region>}
    module "aptos-node" {  # Download the Terraform module from the aptos-core repository.  source        = "github.com/aptos-labs/aptos-core.git//terraform/aptos-node/aws"  region        = <aws region>  # Specify the AWS region  # zone_id     = "<Route53 zone id>"  # Use Route53 if you want to use DNS  era           = 1  # Bump the era number to wipe the chain data  chain_id      = 1  # Use 1 for mainnet, or different values for other networks.  image_tag     = "mainnet" # Specify the image tag to use based on the network  validator_name = "<Name of your validator>" # Specify the name of your validator}
    ```
    
    For all customization options, see:
    
    *   The Terraform variables: [https://github.com/aptos-labs/aptos-core/blob/main/terraform/aptos-node/aws/variables.tf](https://github.com/aptos-labs/aptos-core/blob/main/terraform/aptos-node/aws/variables.tf)
    *   The Helm values: [https://github.com/aptos-labs/aptos-core/blob/main/terraform/helm/aptos-node/values.yaml](https://github.com/aptos-labs/aptos-core/blob/main/terraform/helm/aptos-node/values.yaml).
5.  Initialize Terraform in the `$WORKSPACE` directory where you created the `main.tf` file.
    
    ```
    terraform init
    ```
    
    This will download all the Terraform dependencies into the `.terraform` folder in your current working directory.
    
6.  Create a new Terraform workspace to isolate your environments, and see the list of workspaces.
    
    ```
    terraform workspace new $WORKSPACE
    # This command will list all workspacesterraform workspace list
    ```
    
7.  Apply the Terraform configuration.
    
    ```
    terraform apply
    ```
    
    This may take a while to finish (e.g., >20 minutes). Terraform will create all the resources on your cloud account.
    
8.  After `terraform apply` finishes, you can check if the resources have been created correctly, by running the following commands:
    
    *   `aws eks update-kubeconfig --name aptos-$WORKSPACE`: This command will configure access for your k8s cluster.
    *   `kubectl get pods`: This command will output all pods in the cluster. You should see haproxy, the validator and the VFN (with the validator and VFN pod `pending` due to further action in later steps).
    *   `kubectl get svc`: This command will output all services in the cluster. You should see the `validator-lb` and `fullnode-lb`, with an external IP for network connectivity.
9.  Next, we need to inject your node's IP information into your environment. You can do this by running the following commands:
    
    ```
    export VALIDATOR_ADDRESS="$(kubectl get svc ${WORKSPACE}-aptos-node-0-validator-lb --output jsonpath='{.status.loadBalancer.ingress[0].hostname}')"
    export FULLNODE_ADDRESS="$(kubectl get svc ${WORKSPACE}-aptos-node-0-fullnode-lb --output jsonpath='{.status.loadBalancer.ingress[0].hostname}')"
    ```
    
10.  Now, generate the key pairs for your nodes in your working directory. You can do this by running the following command with the Aptos CLI:
     
     ```
     aptos genesis generate-keys --output-dir ~/$WORKSPACE/keys
     ```
     
     This will create 4 key files under `~/$WORKSPACE/keys` directory:
     
     *   `public-keys.yaml`: This file contains all public keys for your validator and VFN, as well as your account address.
     *   `private-keys.yaml`: This file contains all private keys for your validator and VFN.
     *   `validator-identity.yaml`: This file contains the public and private keys for your validator, as well as your account address.
     *   `validator-full-node-identity.yaml`: This file contains the public and private keys for your VFN, as well as your account address.
     
     Caution
     
     **Backup your private keys**  
     Your private keys are important for you to establish ownership of your nodes. Never share your **private** keys with anyone, and make sure to **backup** `private-keys.yaml` somewhere safe.
     
11.  Next, you will need to set your validator configuration. This includes setting the validator and VFN host names, which may be IP addresses or DNS addresses. This can be done by running the following command:
     
     ```
     aptos genesis set-validator-configuration \  --local-repository-dir ~/$WORKSPACE \  --username $USERNAME \  --owner-public-identity-file ~/$WORKSPACE/keys/public-keys.yaml \  --validator-host $VALIDATOR_ADDRESS:6180 \  --full-node-host $FULLNODE_ADDRESS:6182 \  --stake-amount 100000000000000
     ```
     
     Configuring the validator will create two YAML files in the `~/$WORKSPACE/$USERNAME` directory: `owner.yaml` and `operator.yaml`. These will be useful for connecting your nodes to the Aptos network (later).
     
12.  Download the following files by following the instructions on the [Node Files](/network/nodes/configure/node-files-all-networks) pages. You will need to select the appropriate network (e.g., `mainnet`, `testnet`, `devnet`) and download the following files:
     
     *   `genesis.blob`
     *   `waypoint.txt`
     
     Note
     
     The DKG trusted-setup blobs (`digest_key.bin`, `pp.bin`) required by validators are **not** downloaded here. The `aptos-node` Helm chart fetches them into a persistent volume via its init container — configure the `trustedSetup.*` chart values per [Update Trusted Setup → Kubernetes deployment](/network/nodes/validator-node/modify-nodes/update-trusted-setup#kubernetes-deployment-helm-chart).
     
13.  To recap, in your working directory (`~/$WORKSPACE`), you should have a list of files:
     
     *   `main.tf`: The Terraform files to install the `aptos-node` module.
     *   `keys` folder containing:
         *   `public-keys.yaml`: Public keys for both nodes.
         *   `private-keys.yaml`: Private keys for both nodes.
         *   `validator-identity.yaml`: Key and account information for the validator.
         *   `validator-full-node-identity.yaml`: Key and account information for the VFN.
     *   `$username` folder containing:
         *   `owner.yaml`: The owner, operator and voter mappings.
         *   `operator.yaml`: Validator and VFN operator information.
     *   `waypoint.txt`: The waypoint for the genesis transaction on the network you are connecting to.
     *   `genesis.blob` The genesis blob for the network you are connecting to.
14.  Finally, insert the `genesis.blob`, `waypoint.txt` and the identity files as secrets into the k8s cluster, by running the following command:
     
     ```
     kubectl create secret generic ${WORKSPACE}-aptos-node-0-genesis-e1 \    --from-file=genesis.blob=genesis.blob \    --from-file=waypoint.txt=waypoint.txt \    --from-file=validator-identity.yaml=keys/validator-identity.yaml \    --from-file=validator-full-node-identity.yaml=keys/validator-full-node-identity.yaml
     ```
     
     Caution
     
     **Era numbers and dangling volumes**  
     The `-e1` suffix in the command above refers to the era number. If you changed the `era` number, make sure it matches when creating the secrets.
     
     The `era` is a concept relevant only to Kubernetes deployments of an Aptos node. Changing the `era` provides an easy way to wipe your deployment's state (e.g., blockchain data). However, this may lead to dangling persistent volumes. Confirm the existence of any dangling volumes with `kubectl get pvc` and delete any dangling volumes manually to minimize costs.
     
15.  Now, we should be able to see that all pods are running, including the validator and VFN. You can check this by executing the following command:
     
     ```
     kubectl get pods
     # Example outputNAME                                        READY   STATUS    RESTARTS   AGEnode1-aptos-node-0-fullnode-e9-0              1/1     Running   0          4h31mnode1-aptos-node-0-haproxy-7cc4c5f74c-l4l6n   1/1     Running   0          4h40mnode1-aptos-node-0-validator-0                1/1     Running   0          4h30m
     ```

Caution

**Next steps**  
You have now completed setting up your validator and VFN using AWS. However, your nodes will not be able to connect to the Aptos network just yet.

## Connecting to the Aptos Network

[](#connecting-to-the-aptos-network)

You have now completed setting up your validator and VFN using AWS. Proceed to [Connect Nodes](/network/nodes/validator-node/connect-nodes) for the next steps.

# Using Azure

> Deploy Aptos validator and validator fullnode (VFN) on Microsoft Azure using Terraform and Kubernetes with detailed setup guide.

This is a step-by-step guide to deploy an Aptos validator and validator fullnode (VFN) using Microsoft Azure. Using this guide, the validator and VFN will be deployed on separate machines.

Caution

**Prerequisites**  
Before you begin, make sure to read and understand the [Node Requirements](/network/nodes/validator-node/node-requirements). Similarly, make sure you have installed the [Aptos CLI](/build/cli), [Terraform](https://www.terraform.io/downloads.html), [Kubernetes CLI](https://kubernetes.io/docs/tasks/tools/), and [Azure CLI](https://docs.microsoft.com/en-us/cli/azure/install-azure-cli). This guide assumes that you already have an Azure account setup.

## Deployment steps

[](#deployment-steps)

Note

1.  Create a working directory for your Aptos nodes, and pick a username for your nodes, e.g.,
    
    ```
    export WORKSPACE=mainnetexport USERNAME=alicemkdir ~/$WORKSPACEcd ~/$WORKSPACE
    ```
    
2.  Create a blob storage container for storing the Terraform state on Azure, you can do this on the Azure UI or using the commands below:
    
    ```
    az group create -l <azure region> -n aptos-$WORKSPACEaz storage account create -n <storage account name> -g aptos-$WORKSPACE -l <azure region> --sku Standard_LRSaz storage container create -n <container name> --account-name <storage account name> --resource-group aptos-$WORKSPACE
    ```
    
3.  Create a Terraform file called `main.tf` in your working directory:
    
    ```
    cd ~/$WORKSPACEvi main.tf
    ```
    
4.  Modify the `main.tf` file to configure Terraform and create the Terraform module. See the example below:
    
    ```
    terraform {  required_version = "~> 1.3.6"  backend "azurerm" {    resource_group_name  = <resource group name>    storage_account_name = <storage account name>    container_name       = <container name>    key                  = "state/validator"  }}
    module "aptos-node" {  # Download the Terraform module from the aptos-core repository.  source        = "github.com/aptos-labs/aptos-core.git//terraform/aptos-node/azure"  region        = <azure region>  # Specify the Azure region  era           = 1  # Bump the era number to wipe the chain data  chain_id      = 1  # Use 1 for mainnet, or different values for other networks.  image_tag     = "mainnet" # Specify the image tag to use based on the network  validator_name = "<Name of your validator>" # Specify the name of your validator}
    ```
    
    For all customization options, see:
    
    *   The Terraform variables [https://github.com/aptos-labs/aptos-core/blob/main/terraform/aptos-node/azure/variables.tf](https://github.com/aptos-labs/aptos-core/blob/main/terraform/aptos-node/azure/variables.tf)
    *   The Helm values: [https://github.com/aptos-labs/aptos-core/blob/main/terraform/helm/aptos-node/values.yaml](https://github.com/aptos-labs/aptos-core/blob/main/terraform/helm/aptos-node/values.yaml).
5.  Initialize Terraform in the `$WORKSPACE` directory where you created the `main.tf` file.
    
    ```
    terraform init
    ```
    
    This will download all the Terraform dependencies into the `.terraform` folder in your current working directory.
    
6.  Create a new Terraform workspace to isolate your environments, and see the list of workspaces.
    
    ```
    terraform workspace new $WORKSPACE
    # This command will list all workspacesterraform workspace list
    ```
    
7.  Apply the Terraform configuration.
    
    ```
    terraform apply
    ```
    
    This may take a while to finish (e.g., >20 minutes). Terraform will create all the resources on your cloud account.
    
8.  After `terraform apply` finishes, you can check if the resources have been created correctly, by running the following commands:
    
    *   `az aks get-credentials --resource-group aptos-$WORKSPACE --name aptos-$WORKSPACE`: This command will configure access for your k8s cluster.
    *   `kubectl get pods`: This command will output all pods in the cluster. You should see haproxy, the validator and the VFN (with the validator and VFN pod `pending` due to further action in later steps).
    *   `kubectl get svc`: This command will output all services in the cluster. You should see the `validator-lb` and `fullnode-lb`, with an external IP for network connectivity.
9.  Next, we need to inject your node's IP information into your environment. You can do this by running the following commands:
    
    ```
    export VALIDATOR_ADDRESS="$(kubectl get svc ${WORKSPACE}-aptos-node-0-validator-lb --output jsonpath='{.status.loadBalancer.ingress[0].hostname}')"
    export FULLNODE_ADDRESS="$(kubectl get svc ${WORKSPACE}-aptos-node-0-fullnode-lb --output jsonpath='{.status.loadBalancer.ingress[0].hostname}')"
    ```
    
10.  Now, generate the key pairs for your nodes in your working directory. You can do this by running the following command with the Aptos CLI:
     
     ```
     aptos genesis generate-keys --output-dir ~/$WORKSPACE/keys
     ```
     
     This will create 4 key files under `~/$WORKSPACE/keys` directory:
     
     *   `public-keys.yaml`: This file contains all public keys for your validator and VFN, as well as your account address.
     *   `private-keys.yaml`: This file contains all private keys for your validator and VFN.
     *   `validator-identity.yaml`: This file contains the public and private keys for your validator, as well as your account address.
     *   `validator-full-node-identity.yaml`: This file contains the public and private keys for your VFN, as well as your account address.
     
     Caution
     
     **Backup your private keys**  
     Your private keys are important for you to establish ownership of your nodes. Never share your **private** keys with anyone, and make sure to **backup** `private-keys.yaml` somewhere safe.
     
11.  Next, you will need to set your validator configuration. This includes setting the validator and VFN host names, which may be IP addresses or DNS addresses. This can be done by running the following command:
     
     ```
     aptos genesis set-validator-configuration \  --local-repository-dir ~/$WORKSPACE \  --username $USERNAME \  --owner-public-identity-file ~/$WORKSPACE/keys/public-keys.yaml \  --validator-host $VALIDATOR_ADDRESS:6180 \  --full-node-host $FULLNODE_ADDRESS:6182 \  --stake-amount 100000000000000
     ```
     
     Configuring the validator will create two YAML files in the `~/$WORKSPACE/$USERNAME` directory: `owner.yaml` and `operator.yaml`. These will be useful for connecting your nodes to the Aptos network (later).
     
12.  Download the following files by following the instructions on the [Node Files](/network/nodes/configure/node-files-all-networks) pages. You will need to select the appropriate network (e.g., `mainnet`, `testnet`, `devnet`) and download the following files:
     
     *   `genesis.blob`
     *   `waypoint.txt`
     
     Note
     
     The DKG trusted-setup blobs (`digest_key.bin`, `pp.bin`) required by validators are **not** downloaded here. The `aptos-node` Helm chart fetches them into a persistent volume via its init container — configure the `trustedSetup.*` chart values per [Update Trusted Setup → Kubernetes deployment](/network/nodes/validator-node/modify-nodes/update-trusted-setup#kubernetes-deployment-helm-chart).
     
13.  To recap, in your working directory (`~/$WORKSPACE`), you should have a list of files:
     
     *   `main.tf`: The Terraform files to install the `aptos-node` module.
     *   `keys` folder containing:
         *   `public-keys.yaml`: Public keys for both nodes.
         *   `private-keys.yaml`: Private keys for both nodes.
         *   `validator-identity.yaml`: Key and account information for the validator.
         *   `validator-full-node-identity.yaml`: Key and account information for the VFN.
     *   `$username` folder containing:
         *   `owner.yaml`: The owner, operator and voter mappings.
         *   `operator.yaml`: Validator and VFN operator information.
     *   `waypoint.txt`: The waypoint for the genesis transaction on the network you are connecting to.
     *   `genesis.blob` The genesis blob for the network you are connecting to.
14.  Finally, insert the `genesis.blob`, `waypoint.txt` and the identity files as secrets into the k8s cluster, by running the following command:
     
     ```
     kubectl create secret generic ${WORKSPACE}-aptos-node-0-genesis-e1 \  --from-file=genesis.blob=genesis.blob \  --from-file=waypoint.txt=waypoint.txt \  --from-file=validator-identity.yaml=keys/validator-identity.yaml \  --from-file=validator-full-node-identity.yaml=keys/validator-full-node-identity.yaml
     ```
     
     Caution
     
     **Era numbers and dangling volumes**  
     The `-e1` suffix in the command above refers to the era number. If you changed the `era` number, make sure it matches when creating the secrets.
     
     The `era` is a concept relevant only to Kubernetes deployments of an Aptos node. Changing the `era` provides an easy way to wipe your deployment's state (e.g., blockchain data). However, this may lead to dangling persistent volumes. Confirm the existence of any dangling volumes with `kubectl get pvc` and delete any dangling volumes manually to minimize costs.
     
15.  Now, we should be able to see that all pods are running, including the validator and VFN. You can check this by executing the following command:
     
     ```
     kubectl get pods
     # Example outputNAME                                        READY   STATUS    RESTARTS   AGEnode1-aptos-node-0-fullnode-e9-0              1/1     Running   0          4h31mnode1-aptos-node-0-haproxy-7cc4c5f74c-l4l6n   1/1     Running   0          4h40mnode1-aptos-node-0-validator-0                1/1     Running   0          4h30m
     ```

Caution

**Next steps**  
You have now completed setting up your validator and VFN using Azure. However, your nodes will not be able to connect to the Aptos network just yet.

## Connecting to the Aptos Network

[](#connecting-to-the-aptos-network)

You have now completed setting up your validator and VFN using Azure. Proceed to [Connect Nodes](/network/nodes/validator-node/connect-nodes) for the next steps.

# Using Docker

> Step-by-step guide to deploy Aptos validator and validator fullnode (VFN) using Docker containers on separate machines.

Caution

**Apple M1+ Users**  
Docker deployment has only been tested on Linux, Windows, and Intel macOS. If you are on M1+ macOS, you will need to deploy using [source code](/network/nodes/full-node/deployments/using-source-code).

This is a step-by-step guide to deploy an Aptos validator and validator fullnode (VFN) using Docker. Using this guide, the validator and VFN will be deployed on separate machines.

Caution

## Deployment steps

[](#deployment-steps)

Note

**Default connection to mainnet**  
If you follow the default setup in this document, then your validator and VFN will be connected to the Aptos mainnet. To connect to a different Aptos network, such as testnet, make sure you download the correct genesis and waypoint files for the network you want to connect to. Similarly, you will need to modify the docker compose files to use the correct docker images by network name.

1.  Create a working directory for your Aptos nodes, and pick a username for your nodes, e.g.,
    
    ```
    export WORKSPACE=mainnetexport USERNAME=alicemkdir ~/$WORKSPACEcd ~/$WORKSPACE
    ```
    
2.  Generate the key pairs for your nodes in your working directory. You can do this by running the following command with the Aptos CLI:
    
    ```
    aptos genesis generate-keys --output-dir ~/$WORKSPACE/keys
    ```
    
    This will create 4 key files under `~/$WORKSPACE/keys` directory:
    
    *   `public-keys.yaml`: This file contains all public keys for your validator and VFN, as well as your account address.
    *   `private-keys.yaml`: This file contains all private keys for your validator and VFN.
    *   `validator-identity.yaml`: This file contains the public and private keys for your validator, as well as your account address.
    *   `validator-full-node-identity.yaml`: This file contains the public and private keys for your VFN, as well as your account address.
    
    Caution
    
    **Backup your private keys**  
    Your private keys are important for you to establish ownership of your nodes. Never share your **private** keys with anyone, and make sure to **backup** `private-keys.yaml` somewhere safe.
    
3.  Next, you will need to set your validator configuration. This includes setting the validator and VFN host names, which may be IP addresses or DNS addresses.
    
    Caution
    
    **DNS addresses**  
    Using DNS is recommended over IP addresses, as it enables more efficient node migrations and is more resilient to host changes.
    
    You can set your validator configuration by running the following command with the Aptos CLI:
    
    ```
    # Replace <validator node IP / DNS address> and <Full Node IP / DNS address> below,# with the appropriate IP or DNS address for your nodes.
    cd ~/$WORKSPACEaptos genesis set-validator-configuration \    --local-repository-dir ~/$WORKSPACE \    --username $USERNAME \    --owner-public-identity-file ~/$WORKSPACE/keys/public-keys.yaml \    --validator-host <validator node IP / DNS address>:<Port> \    --full-node-host <Full Node IP / DNS address>:<Port> \    --stake-amount 100000000000000
    # For example, if you are using IP addresses:
    aptos genesis set-validator-configuration \    --local-repository-dir ~/$WORKSPACE \    --username $USERNAME \    --owner-public-identity-file ~/$WORKSPACE/keys/public-keys.yaml \    --validator-host 35.232.235.205:6180 \    --full-node-host 34.135.169.144:6182 \    --stake-amount 100000000000000
    # Otherwise, if you are using DNS addresses:
    aptos genesis set-validator-configuration \    --local-repository-dir ~/$WORKSPACE \    --username $USERNAME \    --owner-public-identity-file ~/$WORKSPACE/keys/public-keys.yaml \    --validator-host bot.aptosdev.com:6180 \    --full-node-host fn.bot.aptosdev.com:6182 \    --stake-amount 100000000000000
    ```
    
    Configuring the validator will create two YAML files in the `~/$WORKSPACE/$USERNAME` directory: `owner.yaml` and `operator.yaml`. These will be useful for connecting your nodes to the Aptos network (later).
    
4.  Download the following files by following the instructions on the [Node Files](/network/nodes/configure/node-files-all-networks) pages. You will need to select the appropriate network (e.g., `mainnet`, `testnet`, `devnet`) and download the following files:
    
    *   `validator.yaml`
    *   `fullnode.yaml`
    *   `docker-compose.yaml`
    *   `docker-compose-fullnode.yaml`
    *   `haproxy.cfg`
    *   `haproxy-fullnode.cfg`
    *   `blocked.ips`
    *   `genesis.blob`
    *   `waypoint.txt`
5.  **Validators only:** download the trusted-setup blobs into your working directory, alongside `genesis.blob` and `waypoint.txt`. The upstream `docker-compose.yaml` bind-mounts them from there into the container:
    
    ```
    cd ~/$WORKSPACEwget -O digest_key.bin https://github.com/aptos-labs/aptos-networks/raw/main/<network>/digest_key.binwget -O pp.bin https://github.com/aptos-labs/aptos-networks/raw/main/<network>/pp.bin
    ```
    
    Replace `<network>` with the appropriate network (`testnet` or `mainnet`). See [Update Trusted Setup → Docker (compose) deployment](/network/nodes/validator-node/modify-nodes/update-trusted-setup#docker-compose-deployment) for the verification step (`aptos node validate-digest-key` / `validate-public-parameters`).
    
6.  To recap, in your working directory (`~/$WORKSPACE`), you should have a list of files:
    
    *   `docker-compose.yaml`: The docker compose file to run the validator.
    *   `docker-compose-fullnode.yaml`: The docker compose file to run the VFN.
    *   `keys` folder containing:
        *   `public-keys.yaml`: Public keys for both nodes.
        *   `private-keys.yaml`: Private keys for both nodes.
        *   `validator-identity.yaml`: Key and account information for the validator.
        *   `validator-full-node-identity.yaml`: Key and account information for the VFN.
    *   `$username` folder containing:
        *   `owner.yaml`: The owner, operator and voter mappings.
        *   `operator.yaml`: Validator and VFN operator information.
    *   `waypoint.txt`: The waypoint for the genesis transaction on the network you are connecting to.
    *   `genesis.blob`: The genesis blob for the network you are connecting to.
    *   `digest_key.bin`: Validators only. DKG digest-key blob loaded by consensus.
    *   `pp.bin`: Validators only. DKG public-parameters blob loaded by consensus.
7.  To start the validator node, run the following command in your working directory:
    
    ```
    docker-compose up (or `docker compose up` depends on your version)
    ```
    
    This will start the validator node using the docker compose file and the images specified in the `docker-compose.yaml` file. If you wish to change the network you are connecting to, you will need to modify the file to use the correct docker images by network name.
    
8.  Before you can start the VFN, you will need to modify the `fullnode.yaml` file to update the host address for the validator node. For example, if you are using IP addresses, you will need to update the `full_node_networks` `addresses` for the `vfn` network as follows:
    
    ```
    ---addresses:  - "/ip4/100.100.100.100/tcp/6181/noise-ik/..." # Set the IP Address of the validator
    ```
    
    Otherwise, if you are using DNS addresses, you will need to update the `addresses` field as follows:
    
    ```
    ---addresses:  - "/dns/example.com/tcp/6181/noise-ik/..." # Set the DNS Address of the validator
    ```
    
9.  To start your VFN, run the following commands on a separate, dedicated VFN machine. You will need to copy across the keys, configuration and docker compose files from the validator machine.
    
    Caution
    
    **VFN identity**  
    You should copy the keys and configuration files across to the VFN machine from the working location where they were generated. Do not attempt to generate another set of keys or files for the VFN, as these will not be recognized by the network.
    
    To start the VFN, run the following command in your working directory:
    
    ```
    docker-compose -f docker-compose-fullnode.yaml up
    ```
    
    This will start the VFN using the docker compose file and the images specified in the `docker-compose-fullnode.yaml` file. If you wish to change the network you are connecting to, you will need to modify the file to use the correct docker images by network name.
    
    Caution
    
    **Next steps**  
    You have now completed setting up your validator and VFN using Docker. However, your nodes will not be able to connect to the Aptos network just yet.

## Connecting to the Aptos Network

[](#connecting-to-the-aptos-network)

You have now completed setting up your validator and VFN using Docker. Proceed to [Connect Nodes](/network/nodes/validator-node/connect-nodes) for the next steps.

# Using GCP

> Deploy Aptos validator and validator fullnode (VFN) on Google Cloud Platform using Terraform and Kubernetes with step-by-step instructions.

This is a step-by-step guide to deploy an Aptos validator and validator fullnode (VFN) using Google Cloud Platform Services (GCP). Using this guide, the validator and VFN will be deployed on separate machines.

Caution

**Prerequisites**  
Before you begin, make sure to read and understand the [Node Requirements](/network/nodes/validator-node/node-requirements). Similarly, make sure you have installed the [Aptos CLI](/build/cli), [Terraform](https://www.terraform.io/downloads.html), [Kubernetes CLI](https://kubernetes.io/docs/tasks/tools/), and [Google Cloud CLI](https://cloud.google.com/sdk/docs/install-sdk). This guide assumes that you already have a GCP account setup, and have created a new project for deploying your nodes.

## Deployment steps

[](#deployment-steps)

1.  Create a working directory for your Aptos nodes, and pick a username for your nodes, e.g.,
    
    ```
    export WORKSPACE=mainnetexport USERNAME=alicemkdir ~/$WORKSPACEcd ~/$WORKSPACE
    ```
    
2.  Create a storage bucket for storing the Terraform state on Google Cloud Storage.
    
    Caution
    
    **Storage bucket name**  
    The name of the Google Cloud storage bucket must be unique. See the Google Cloud Storage documentation, [here](https://cloud.google.com/storage/docs/creating-buckets#prereq-cli).
    
    Use the GCP UI or Google Cloud Storage command to create the bucket:
    
    ```
    gsutil mb gs://BUCKET_NAME
    # Here's an example of creating a bucketgsutil mb gs://<project-name>-aptos-terraform-dev
    ```
    
3.  Create a Terraform file called `main.tf` in your working directory:
    
    ```
    cd ~/$WORKSPACEvi main.tf
    ```
    
4.  Modify the `main.tf` file to configure Terraform and create the Terraform module. See the example below:
    
    ```
    terraform {  required_version = "~> 1.3.6"  backend "gcs" {    bucket = "BUCKET_NAME" # The bucket name created above    prefix = "state/aptos-node"  }}
    module "aptos-node" {  # Download the Terraform module from the aptos-core repository.  source        = "github.com/aptos-labs/aptos-core.git//terraform/aptos-node/gcp"  region        = "us-central1"  # Specify the GCP region  zone          = "c"            # Specify the zone suffix  project       = "<GCP Project ID>" # Specify your GCP project ID  era           = 1  # Bump the era number to wipe the chain data  chain_id      = 1  # Use 1 for mainnet, or different values for other networks.  image_tag     = "mainnet" # Specify the image tag to use based on the network  validator_name = "<Name of your validator>" # Specify the name of your validator}
    ```
    
    For all customization options, see:
    
    *   The Terraform variables: [https://github.com/aptos-labs/aptos-core/blob/main/terraform/aptos-node/gcp/variables.tf](https://github.com/aptos-labs/aptos-core/blob/main/terraform/aptos-node/gcp/variables.tf)
    *   The Helm values: [https://github.com/aptos-labs/aptos-core/blob/main/terraform/helm/aptos-node/values.yaml](https://github.com/aptos-labs/aptos-core/blob/main/terraform/helm/aptos-node/values.yaml).
5.  Initialize Terraform in the `$WORKSPACE` directory where you created the `main.tf` file.
    
    ```
    terraform init
    ```
    
    This will download all the Terraform dependencies into the `.terraform` folder in your current working directory.
    
6.  Create a new Terraform workspace to isolate your environments, and see the list of workspaces.
    
    ```
    terraform workspace new $WORKSPACE
    # This command will list all workspacesterraform workspace list
    ```
    
7.  Apply the Terraform configuration.
    
    ```
    terraform apply
    ```
    
    This may take a while to finish (e.g., >20 minutes). Terraform will create all the resources on your cloud account.
    
8.  After `terraform apply` finishes, you can check if the resources have been created correctly, by running the following commands:
    
    *   `gcloud container clusters get-credentials aptos-$WORKSPACE --zone <region/zone> --project <project>`: This command will configure access for your k8s cluster.
    *   `kubectl get pods`: This command will output all pods in the cluster. You should see haproxy, the validator and the VFN (with the validator and VFN pod `pending` due to further action in later steps).
    *   `kubectl get svc`: This command will output all services in the cluster. You should see the `validator-lb` and `fullnode-lb`, with an external IP for network connectivity.
9.  Next, we need to inject your node's IP information into your environment. You can do this by running the following commands:
    
    ```
    export VALIDATOR_ADDRESS="$(kubectl get svc ${WORKSPACE}-aptos-node-0-validator-lb --output jsonpath='{.status.loadBalancer.ingress[0].hostname}')"
    export FULLNODE_ADDRESS="$(kubectl get svc ${WORKSPACE}-aptos-node-0-fullnode-lb --output jsonpath='{.status.loadBalancer.ingress[0].hostname}')"
    ```
    
10.  Now, generate the key pairs for your nodes in your working directory. You can do this by running the following command with the Aptos CLI:
     
     ```
     aptos genesis generate-keys --output-dir ~/$WORKSPACE/keys
     ```
     
     This will create 4 key files under `~/$WORKSPACE/keys` directory:
     
     *   `public-keys.yaml`: This file contains all public keys for your validator and VFN, as well as your account address.
     *   `private-keys.yaml`: This file contains all private keys for your validator and VFN.
     *   `validator-identity.yaml`: This file contains the public and private keys for your validator, as well as your account address.
     *   `validator-full-node-identity.yaml`: This file contains the public and private keys for your VFN, as well as your account address.
     
     Caution
     
     **Backup your private keys**  
     Your private keys are important for you to establish ownership of your nodes. Never share your **private** keys with anyone, and make sure to **backup** `private-keys.yaml` somewhere safe.
     
11.  Next, you will need to set your validator configuration. This includes setting the validator and VFN host names, which may be IP addresses or DNS addresses. This can be done by running the following command:
     
     ```
     aptos genesis set-validator-configuration \  --local-repository-dir ~/$WORKSPACE \  --username $USERNAME \  --owner-public-identity-file ~/$WORKSPACE/keys/public-keys.yaml \  --validator-host $VALIDATOR_ADDRESS:6180 \  --full-node-host $FULLNODE_ADDRESS:6182 \  --stake-amount 100000000000000
     ```
     
     Configuring the validator will create two YAML files in the `~/$WORKSPACE/$USERNAME` directory: `owner.yaml` and `operator.yaml`. These will be useful for connecting your nodes to the Aptos network (later).
     
12.  Download the following files by following the instructions on the [Node Files](/network/nodes/configure/node-files-all-networks) pages. You will need to select the appropriate network (e.g., `mainnet`, `testnet`, `devnet`) and download the following files:
     
     *   `genesis.blob`
     *   `waypoint.txt`
     
     Note
     
     The DKG trusted-setup blobs (`digest_key.bin`, `pp.bin`) required by validators are **not** downloaded here. The `aptos-node` Helm chart fetches them into a persistent volume via its init container — configure the `trustedSetup.*` chart values per [Update Trusted Setup → Kubernetes deployment](/network/nodes/validator-node/modify-nodes/update-trusted-setup#kubernetes-deployment-helm-chart).
     
13.  To recap, in your working directory (`~/$WORKSPACE`), you should have a list of files:
     
     *   `main.tf`: The Terraform files to install the `aptos-node` module.
     *   `keys` folder containing:
         *   `public-keys.yaml`: Public keys for both nodes.
         *   `private-keys.yaml`: Private keys for both nodes.
         *   `validator-identity.yaml`: Key and account information for the validator.
         *   `validator-full-node-identity.yaml`: Key and account information for the VFN.
     *   `$username` folder containing:
         *   `owner.yaml`: The owner, operator and voter mappings.
         *   `operator.yaml`: Validator and VFN operator information.
     *   `waypoint.txt`: The waypoint for the genesis transaction on the network you are connecting to.
     *   `genesis.blob` The genesis blob for the network you are connecting to.
14.  Finally, insert the `genesis.blob`, `waypoint.txt` and the identity files as secrets into the k8s cluster, by running the following command:
     
     ```
     kubectl create secret generic ${WORKSPACE}-aptos-node-0-genesis-e1 \    --from-file=genesis.blob=genesis.blob \    --from-file=waypoint.txt=waypoint.txt \    --from-file=validator-identity.yaml=keys/validator-identity.yaml \    --from-file=validator-full-node-identity.yaml=keys/validator-full-node-identity.yaml
     ```
     
     Caution
     
     **Era numbers and dangling volumes**  
     The `-e1` suffix in the command above refers to the era number. If you changed the `era` number, make sure it matches when creating the secrets.
     
     The `era` is a concept relevant only to Kubernetes deployments of an Aptos node. Changing the `era` provides an easy way to wipe your deployment's state (e.g., blockchain data). However, this may lead to dangling persistent volumes. Confirm the existence of any dangling volumes with `kubectl get pvc` and delete any dangling volumes manually to minimize costs.
     
15.  Now, we should be able to see that all pods are running, including the validator and VFN. You can check this by executing the following command:
     
     ```
     kubectl get pods
     # Example outputNAME                                        READY   STATUS    RESTARTS   AGEnode1-aptos-node-0-fullnode-e9-0              1/1     Running   0          4h31mnode1-aptos-node-0-haproxy-7cc4c5f74c-l4l6n   1/1     Running   0          4h40mnode1-aptos-node-0-validator-0                1/1     Running   0          4h30m
     ```

Caution

**Next steps**  
You have now completed setting up your validator and VFN using GCP. However, your nodes will not be able to connect to the Aptos network just yet.

## Connecting to the Aptos Network

[](#connecting-to-the-aptos-network)

You have now completed setting up your validator and VFN using GCP. Proceed to [Connect Nodes](/network/nodes/validator-node/connect-nodes) for the next steps.

# Using Source Code

> Build and deploy Aptos validator and validator fullnode (VFN) directly from source code with comprehensive setup instructions.

This is a step-by-step guide to deploy an Aptos validator and validator fullnode (VFN) using source code. Using this guide, the validator and VFN will be deployed on separate machines.

Caution

## Deployment Steps

[](#deployment-steps)

Note

**Default connection to mainnet**  
If you follow the default setup in this document, then your validator and VFN will be connected to the Aptos mainnet. To connect to a different Aptos network, such as testnet, make sure you select the appropriate source code branch when you build the binary, and download the correct genesis and waypoint files for the network you want to connect to.

1.  Follow the steps in [Building Aptos From Source](/network/nodes/building-from-source) to download the `aptos-core` repository and source code.
    
2.  Checkout the `mainnet` branch using `git checkout --track origin/mainnet`. Note: if you want to deploy a validator and VFN on another network, use the appropriate branch name (e.g., `testnet`).
    
3.  Create a working directory for your Aptos nodes, and pick a username for your nodes, e.g.,
    
    ```
    export WORKSPACE=mainnetexport USERNAME=alicemkdir ~/$WORKSPACE
    ```
    
4.  Generate the key pairs for your nodes in your working directory. You can do this by running the following command with the Aptos CLI:
    
    ```
    aptos genesis generate-keys --output-dir ~/$WORKSPACE/keys
    ```
    
    This will create 4 key files under `~/$WORKSPACE/keys` directory:
    
    *   `public-keys.yaml`: This file contains all public keys for your validator and VFN, as well as your account address.
    *   `private-keys.yaml`: This file contains all private keys for your validator and VFN.
    *   `validator-identity.yaml`: This file contains the public and private keys for your validator, as well as your account address.
    *   `validator-full-node-identity.yaml`: This file contains the public and private keys for your VFN, as well as your account address.
    
    Caution
    
    **Backup your private keys**  
    Your private keys are important for you to establish ownership of your nodes. Never share your **private** keys with anyone, and make sure to **backup** `private-keys.yaml` somewhere safe.
    
5.  Next, you will need to set your validator configuration. This includes setting the validator and VFN host names, which may be IP addresses or DNS addresses.
    
    Note
    
    **DNS addresses**  
    Using DNS is recommended over IP addresses, as it enables more efficient node migrations and is more resilient to host changes.
    
    You can set your validator configuration by running the following command with the Aptos CLI:
    
    ```
    # Replace <validator node IP / DNS address> and <Full Node IP / DNS address> below,# with the appropriate IP or DNS address for your nodes.
    cd ~/$WORKSPACEaptos genesis set-validator-configuration \    --local-repository-dir ~/$WORKSPACE \    --username $USERNAME \    --owner-public-identity-file ~/$WORKSPACE/keys/public-keys.yaml \    --validator-host <validator node IP / DNS address>:<Port> \    --full-node-host <Full Node IP / DNS address>:<Port> \    --stake-amount 100000000000000
    # For example, if you are using IP addresses:
    aptos genesis set-validator-configuration \    --local-repository-dir ~/$WORKSPACE \    --username $USERNAME \    --owner-public-identity-file ~/$WORKSPACE/keys/public-keys.yaml \    --validator-host 35.232.235.205:6180 \    --full-node-host 34.135.169.144:6182 \    --stake-amount 100000000000000
    # Otherwise, if you are using DNS addresses:
    aptos genesis set-validator-configuration \    --local-repository-dir ~/$WORKSPACE \    --username $USERNAME \    --owner-public-identity-file ~/$WORKSPACE/keys/public-keys.yaml \    --validator-host bot.aptosdev.com:6180 \    --full-node-host fn.bot.aptosdev.com:6182 \    --stake-amount 100000000000000
    ```
    
    Configuring the validator will create two YAML files in the `~/$WORKSPACE/$USERNAME` directory: `owner.yaml` and `operator.yaml`. These will be useful for connecting your nodes to the Aptos network (later).
    
6.  Download the following files by following the instructions on the [Node Files](/network/nodes/configure/node-files-all-networks) pages. You will need to select the appropriate network (e.g., `mainnet`, `testnet`, `devnet`) and download the following files:
    
    *   `validator.yaml`
    *   `fullnode.yaml`
    *   `genesis.blob`
    *   `waypoint.txt`
7.  **Validators only:** download the trusted-setup blobs to a path on persistent local storage. The example below uses `/opt/aptos/genesis/`, alongside `genesis.blob` and `waypoint.txt`. Use the same paths when you set `consensus.digest_key_blob_path` and `consensus.public_parameters_blob_path` in `validator.yaml` (step 9).
    
    ```
    wget -O /opt/aptos/genesis/digest_key.bin \  https://github.com/aptos-labs/aptos-networks/raw/main/<network>/digest_key.binwget -O /opt/aptos/genesis/pp.bin \  https://github.com/aptos-labs/aptos-networks/raw/main/<network>/pp.bin
    ```
    
    Replace `<network>` with the appropriate network (`testnet` or `mainnet`). See [Update Trusted Setup → Source code deployment](/network/nodes/validator-node/modify-nodes/update-trusted-setup#source-code-deployment) for the verification step (`aptos node validate-digest-key` / `validate-public-parameters`).
    
8.  Next, copy the `validator.yaml` and `fullnode.yaml` template files (that were just downloaded) into the `~/$WORKSPACE/config/` directory. This can be done by running the following commands:
    
    ```
    mkdir ~/$WORKSPACE/configcp validator.yaml ~/$WORKSPACE/config/validator.yamlcp fullnode.yaml ~/$WORKSPACE/config/fullnode.yaml
    ```
    
    These will be the primary configuration files for your validator and VFN, respectively.
    
9.  Now, modify the `validator.yaml` and `fullnode.yaml` template files to contain the appropriate information and working directories for your validator and VFN.
    
    For the `validator.yaml` file, you will need to modify the following fields:
    
    *   `base.data_dir`: The directory where the blockchain data will be stored.
    *   `base.waypoint`: The waypoint for the genesis transaction on the network you are connecting to.
    *   `consensus.initial_safety_rules_config`: The waypoint for the genesis transaction on the network you are connecting to, as well as the `validator-identity.yaml` file location.
    *   `execution.genesis_file_location`: The genesis blob for the network you are connecting to.
    *   `storage.rocksdb_configs.enable_storage_sharding`: Set to `true`.
    *   `validator_network.identity`: The `validator-identity.yaml` file location.
    
    For the `fullnode.yaml` file, you will need to modify the following fields:
    
    *   `base.data_dir`: The directory where the blockchain data will be stored.
        
    *   `base.waypoint`: The waypoint for the genesis transaction on the network you are connecting to.
        
    *   `execution.genesis_file_location`: The genesis blob for the network you are connecting to.
        
    *   `storage.rocksdb_configs.enable_storage_sharding`: Set to `true`.
        
    *   `full_node_networks`: - The `public` network will need to be updated with the `validator-full-node-identity.yaml` file location. - The `vfn` network will need to be updated with the correct IP address or DNS address of the validator. For example, if you are using IP addresses, you will need to update the `addresses` field as follows:
        
        ```
        ---addresses:  - "/ip4/100.100.100.100/tcp/6181/noise-ik/..." # Set the IP Address of the validator
        ```
        
        Otherwise, if you are using DNS addresses, you will need to update the `addresses` field as follows:
        
        ```
        ---addresses:  - "/dns/example.com/tcp/6181/noise-ik/..." # Set the DNS Address of the validator
        ```
        
10.  To recap, in your working directory (`~/$WORKSPACE`), you should have a list of files:
     
     *   `config` folder containing:
         *   `validator.yaml`: The validator config file.
         *   `fullnode.yaml`: The VFN config file.
     *   `keys` folder containing:
         *   `public-keys.yaml`: Public keys for both nodes.
         *   `private-keys.yaml`: Private keys for both nodes.
         *   `validator-identity.yaml`: Key and account information for the validator.
         *   `validator-full-node-identity.yaml`: Key and account information for the VFN.
     *   `$username` folder containing:
         *   `owner.yaml`: The owner, operator and voter mappings.
         *   `operator.yaml`: Validator and VFN operator information.
     *   `waypoint.txt`: The waypoint for the genesis transaction on the network you are connecting to.
     *   `genesis.blob`: The genesis blob for the network you are connecting to.
     *   `digest_key.bin` and `pp.bin` (validators only): DKG trusted-setup blobs at the paths chosen in step 7 (may live outside the working directory).
11.  Now that you have set up your configuration files, you can start your validator and VFN. To start your validator, run the following commands, with the paths assuming you are in the root of the `aptos-core` directory:
     
     ```
     cargo cleancargo build -p aptos-node --releasesudo mv target/release/aptos-node /usr/local/binaptos-node -f ~/$WORKSPACE/config/validator.yaml
     ```
     
     To start your VFN, run the following commands on a separate, dedicated VFN machine. You will need to download the `aptos-core` source code and build the binary on the VFN machine. Likewise, you will need to copy across the keys and configuration files from the validator machine.
     
     Caution
     
     **VFN identity**  
     You should copy the keys and configuration files across to the VFN machine from the working location where they were generated. Do not attempt to generate another set of keys or files for the VFN, as these will not be recognized by the network.
     
     Start your VFN by running the following commands, with the paths assuming you are in the root of the `aptos-core` directory:
     
     ```
     cargo cleancargo build -p aptos-node --releasesudo mv target/release/aptos-node /usr/local/binaptos-node -f ~/$WORKSPACE/config/fullnode.yaml
     ```
     
     Caution
     
     **Next steps**  
     You have now completed setting up your validator and VFN using source code. However, your nodes will not be able to connect to the Aptos network just yet.

### (Optional) Running as a Service

[](#optional-running-as-a-service)

If you want to run `aptos-node` as a service, you can set it up to run as a service controlled by `systemctl`. This is optional, and can be done using the service template below. You will need to modify the template to match your environment and configuration.

```
[Unit]Description=Aptos Node Service
[Service]User=nodeuserGroup=nodeuser
LimitNOFILE=500000
#Environment="RUST_LOG=error"WorkingDirectory=/home/nodeuser/aptos-coreExecStart=/usr/local/bin/aptos-node -f /home/nodeuser/aptos-mainnet/config/validator.yaml
Restart=on-failureRestartSec=3s
StandardOutput=journalStandardError=journalSyslogIdentifier=aptos-node
[Install]WantedBy=multi-user.target
```

## Connecting to the Aptos Network

[](#connecting-to-the-aptos-network)

You have now completed setting up your validator and VFN using source code. Proceed to [Connect Nodes](/network/nodes/validator-node/connect-nodes) for the next steps.

# How to Modify Nodes

> Learn how to perform common maintenance operations on your validator and validator fullnode (VFN) including upgrades, shutdowns, and key rotation.

This section contains tutorials for performing common operations and modifications to your validator and validator fullnode (VFN). These include:

*   ### [Upgrade Nodes](/network/nodes/validator-node/modify-nodes/update-validator-node)
    
    [](#upgrade-nodes)
    
*   ### [Shutdown Nodes](/network/nodes/validator-node/modify-nodes/shutting-down-nodes)
    
    [](#shutdown-nodes)
    
*   ### [Rotate Consensus Key](/network/nodes/validator-node/modify-nodes/rotate-consensus-key)
    
    [](#rotate-consensus-key)

# Rotate Consensus Key

> Step-by-step guide to rotate your validator's consensus key for enhanced security including key generation, on-chain updates, and cleanup procedures.

Consensus key rotation is an action taken by a node operator to change the identity of a validator they control. It happens typically when the corresponding private key is (potentially) lost/leaked, or every few months as a common security practice.

Below is the step-by-step guide of performing a consensus key rotation with detailed examples.

## New key generation

[](#new-key-generation)

Using the following [Aptos CLI](/build/cli) command to generate a new consensus identity. In this example, identity files are saved to directory `/new/key/root`.

```
aptos genesis generate-keys --output-dir /new/key/root
```

## Add new private key to node

[](#add-new-private-key-to-node)

Edit the node config yaml as described below.

```
# ...consensus:    # ...    safety_rules:        # ...        initial_safety_rules_config:            from_file:                # ...                identity_blob_path: /old/key/root/validator-identity.yaml                overriding_identity_paths:              # new!                - /new/key/root/validator-identity.yaml # new!
```

Note

*   Field `identity_blob_path` is required.
*   Field `overriding_identity_paths` is optional, and allows multiple identities to be specified for rotation purposes.
*   The node will choose the identity that matches the on-chain state.

Now restart the node. It should load the new key but continue using the old key for consensus.

## Add new public key on chain

[](#add-new-public-key-on-chain)

Aptos CLI is needed again, and your operator account is assumed to have been set up as a CLI profile `profile1`.

Find your pool address (denoted by `$POOL_ADDR`).

In `/new/key/root/public-keys.yaml`,

*   find the public key of your new consensus identity (denoted by `$NEW_PUBLIC_KEY`);
*   find the proof of possession of your new consensus identity (denoted by `$PROOF_OF_POSSESSION`).

Run a transaction with aptos CLI to update the on-chain consensus public key for the next epoch.

```
aptos move run \    --profile profile1 \    --function-id 0x1::stake::rotate_consensus_key \    --args \        address:$POOL_ADDR \        hex:$NEW_PUBLIC_KEY \        hex:$PROOF_OF_POSSESSION
```

Here is a complete example.

```
aptos move run \    --profile profile1 \    --function-id 0x1::stake::rotate_consensus_key \    --args \        address:0x1eb42885d7d5232269229e56bb80d0959584e14485097ebf9ab619cf4fda5c02 \        hex:0xacb7859468ca85cf9935e64ebb2b9b3fa8187de42d541acebaf732365a0131eaa994098f9d0d7e6b8ddea8ef11e16c55 \        hex:0x8e27fd9300433191b1123217928a6f5190a6ec344ea8623555712a850029b34f5c4bab68df7568b48bcced408cde5174064284407ee760df5dbf12d1c6090589ea1a692997018aca740e91d2182e5715c7745565fe99361e279ccfcfa10ae1f7
```

## Wait for the next epoch

[](#wait-for-the-next-epoch)

The new key should become effective after the next epoch change (which happens every 2 hours).

## (Advanced) Old key clean-up

[](#advanced-old-key-clean-up)

In the secure storage (typically a file named `secure_storage.json`), consensus identities are organized as follows.

*   Field `consensus` contains the default consensus identity.
    *   Typically created when you start the node for the first time.
    *   Must exist.
*   Field `consensus_X` contains additional consensus identities with `X` as its public key.
    *   Created because you once added it to `overriding_identity_paths` in node config yaml.

**Currently, identities won't be deleted automatically from secure storage**, even if you delete the corresponding identity from the node config yaml.

If you need to ensure the old key is completely gone, manually clean-up is needed.

Here is an example of `secure_storage.json`.

```
{    // ...    "consensus": {        "data": "GetResponse",        "last_update": 1731372563,        "value": "0x221f6fbfefa0a40b84c88fbb546a0884977dcc56719a96ed4e5d69b6a4ff58c8"    },    "consensus_acb7859468ca85cf9935e64ebb2b9b3fa8187de42d541acebaf732365a0131eaa994098f9d0d7e6b8ddea8ef11e16c55": {        "data": "GetResponse",        "last_update": 1731383387,        "value": "0x18d5098b3819d5fb0fc208b8bb0946b263f961f60716fc4d10d4b010fdb89a55"    },    // ...}
```

To delete private key `0x18d5...`, simply delete the entire field with key `consensus_acb7...`.

To delete private key `0x221f...`, update the value `0x221f...` to something else (e.g. another private key).

# Deprecate VFNs

> Shut down your Validator Full Node (VFN) and configure your validator to accept direct PFN connections as part of the AIP-139 rollout.

[AIP-139](https://github.com/aptos-foundation/AIPs/blob/main/aips/aip-139-deprecating-validator-full-nodes-vfns.md) deprecates Validator Full Nodes (VFNs) by allowing validators to accept direct connections from Public Full Nodes (PFNs). This removes the need for operators to run a separate VFN alongside their validator.

Tip

**Devnet and Testnet**  
VFN removal has already occurred on Devnet and Testnet. The instructions in this document apply only to Mainnet VFN deprecation and removal.

## Summary

[](#summary)

This guide provides step-by-step instructions for **Mainnet** validator operators to shut down their VFNs and configure their validators to accept PFN connections. To achieve this, you will need to perform the following tasks:

1.  **Prerequisite**: Ensure you are running **aptos-node v1.45.x** or later.
2.  Configure the validator to accept inbound PFN connections.
3.  Verify the PFN port is accessible from the public internet.
4.  **Important**: Wait for confirmation from Aptos Labs before shutting down your VFN. Announcements will be made across release groups.
5.  Shut down your VFN.

Follow the instructions in each step carefully, and reach out to the Aptos Labs team if you have any questions or need assistance.

## Prerequisites

[](#prerequisites)

Before proceeding, verify that you are running **aptos-node v1.45.x** or later. Older releases do not support direct validator-to-PFN connections.

You can check your node version by running:

```
aptos-node --version
```

If you are on an older release, upgrade before continuing.

## Step 1: Configure PFN connections

[](#step-1-configure-pfn-connections)

Configure your validator to accept inbound PFN connections. This requires your validator to be listening for PFN connections on an open port.

There are three options:

1.  **(Recommended)** Use the default port (6182) to accept PFN connections.
2.  Use a custom port to accept PFN connections.
3.  **(Discouraged)** Reject PFN connections.

Tip

**Accept PFN connections**  
We strongly encourage operators to accept PFN connections (option 1 or 2 above). Accepting PFN connections is necessary for network health and ecosystem connectivity. If validators reject PFN connections, this may impact the ability of PFNs to sync and serve data.

### Option 1: Use the default port

[](#option-1-use-the-default-port)

By default, the validator binary will start listening for PFN connections on port **6182** (without any config changes). If you are happy with this port, no additional steps are required. Simply ensure port 6182 is open in your firewall, and your validator will be able to accept inbound PFN connections.

### Option 2: Use a custom port

[](#option-2-use-a-custom-port)

If you want to use a different port for PFN connections, you can configure the validator to listen on that port instead. To do this, add a `full_node_networks` section to your validator config with the desired port:

validator.yaml

```
full_node_networks:  - network_id: "public"    discovery_method: "none"     # Prevents unnecessary outbound connections to other PFNs.    max_outbound_connections: 0  # Prevents unnecessary outbound connections to other PFNs.    listen_address: "/ip4/0.0.0.0/tcp/<your-port>"    identity:      type: from_file      path: /path/to/validator-identity.yaml  # Path to the validator identity file
```

Replace `<your-port>` with the port you want to use (e.g., `7777`), and ensure the port is open in your firewall. Set the `identity` field to the validator's network identity by pointing to the `validator-identity.yaml` file.

After updating the config and restarting the validator, you must also update the on-chain `fullnode_network_addresses` to point to your validator's host and the new port. To do this, update your operator config file (e.g., `operator.yaml`) with these three fields:

operator.yaml

```
full_node_network_public_key: "<validator-network-public-key>"full_node_host:  host: <validator-host>  port: <your-port>
```

Replace `<validator-network-public-key>` with the public key from your `validator-identity.yaml` file, `<validator-host>` with your validator's public IP or hostname, and `<your-port>` with the port configured above. Then run:

```
aptos node update-validator-network-addresses \  --pool-address <owner-address> \  --operator-config-file ~/path/to/operator.yaml
```

Replace `<owner-address>` with your validator pool address. For more details on using `update-validator-network-addresses` (including how to locate your pool address and operator config), see [Connect to the Aptos Network](/network/nodes/validator-node/connect-nodes/connect-to-aptos-network).

Tip

**Wait for the next epoch**  
On-chain network address updates take effect at the start of the next epoch. PFNs will not be able to discover the new address until then.

#### Verify your on-chain registration

[](#verify-your-on-chain-registration)

After the next epoch begins, confirm that the correct addresses are registered on-chain by running:

```
aptos node show-validator-config \  --pool-address <owner-address> \  --profile <your-profile>
```

The output includes `fullnode_network_addresses`, which should reflect your validator's host and the custom port you configured. For example:

```
{  "fullnode_network_addresses,": "/ip4/<validator-host>/tcp/<your-port>/noise-ik/<validator-network-public-key>/handshake/0"}
```

If the value has not updated yet, wait for the next epoch and run the command again.

### Option 3: Reject PFN connections

[](#option-3-reject-pfn-connections)

Caution

**Not Recommended**  
Rejecting PFN connections can be harmful to the network, and degrade ecosystem health. Only use this option if you have a strong operational reason to do so.

If you do not want the validator to accept any PFN connections, set `enable_validator_pfn_connections` to `false` in the `base` section of your validator node config:

validator.yaml

```
base:  enable_validator_pfn_connections: false
```

When this configuration is used, the node will no longer listen for or accept connections from PFNs.

## Step 2: Verify the PFN port is accessible

[](#step-2-verify-the-pfn-port-is-accessible)

After opening the port in your firewall and (re)starting your validator, confirm that the port is reachable from the public internet.

Tip

**Docker deployments**  
If your validator runs in Docker, also publish the port in `docker-compose.yaml` (e.g., `"6182:6182"` under `ports:`), then restart. Opening the port in the OS firewall alone is not sufficient.

From a machine **outside your data center or cloud VPC**, run:

```
nc -zv <Validator-IP-or-DNS> <PFN-Port>
```

Replace `<Validator-IP-or-DNS>` with your validator's public IP address or hostname, and `<PFN-Port>` with the port you configured (default `6182`). A successful connection outputs:

```
nc -zv validator.aptoslabs.com 6182Connection to validator.aptoslabs.com port 6182 [tcp/*] succeeded!
```

If the port is blocked, you will see a `Connection refused` or no output after a timeout instead. Double-check your firewall rules and try again.

Tip

**Prefer telnet?**  
`telnet` is an equivalent alternative. Use the same host and port as above:

```
telnet <Validator-IP-or-DNS> <PFN-Port>
```

The terminal will hang open on success (press `Ctrl+]` then `quit` to exit). `Connection refused` or `timed out` means the port is blocked.

## Step 3: Shut down your VFN

[](#step-3-shut-down-your-vfn)

Danger

**Do not proceed until confirmed by Aptos Labs**  
VFN removal will be rolled out across release groups. Only shut down your VFN after Aptos Labs confirms it is safe to do so. If you have any doubt, contact the team before proceeding.

Once you have received confirmation, you can take the VFN offline safely. You do not need to leave the validator set to shut down the VFN. Only the validator needs to remain online.

Tip

**Backup your VFN data**  
As a precaution, we recommend backing up the VFN keys, identity files, and configuration files before shutting down your VFN.

To stop the VFN, use the appropriate method for your deployment, for example:

*   **Source code:** Kill the `aptos-node` process running the VFN.
*   **Docker:** Run `docker compose down --volumes` in the VFN directory.
*   **Terraform:** Run `terraform destroy` targeting the VFN resources.

## Protecting your validator

[](#protecting-your-validator)

With the VFN removed, your validator will be more exposed to the public internet. This increases the attack surface for network-level attacks, such as DDoS. If you don't already have protections in place, we strongly recommend implementing appropriate safeguards (see the recommendations below).

Caution

**Protecting your validator**  
The recommendations below reflect common practices already used by operators. However, this is not an exhaustive list; operators should evaluate their own risk tolerance and operational requirements.

### Firewall

[](#firewall)

At minimum, we recommend locking down all ports on the validator host except those required for node operation, e.g.:

*   **Consensus port** (default `6180`): Required for validator to validator traffic.
*   **PFN port** (default `6182`): Required for PFN traffic.

All other ports should be blocked by your firewall, including the REST API port, and metrics port. If you need to expose these ports for monitoring, restrict access to trusted IPs or internal networks only.

Popular tools include [ufw](https://help.ubuntu.com/community/UFW) and [firewalld](https://firewalld.org/). Apply the principle of least privilege: deny by default and allow only what is explicitly required.

### Load balancer & reverse proxy

[](#load-balancer--reverse-proxy)

Running a load balancer, or reverse proxy in front of open validator ports adds a layer of indirection that allows traffic shaping, rate limiting, and health checks without exposing the node directly. [HAProxy](https://www.haproxy.org/) is a commonly used option; example configs can be found in the [aptos-core](https://github.com/aptos-labs/aptos-core/blob/main/terraform/helm/aptos-node/files/haproxy.cfg) repository.

### DDoS protection

[](#ddos-protection)

DDoS protection can also be quite useful. Some operators already use a combination of network-level protections and DNS-level protections, e.g., [Cloudflare Spectrum](https://developers.cloudflare.com/spectrum/), [AWS Shield](https://aws.amazon.com/shield/), [GCP Cloud Armor Network Edge](https://docs.cloud.google.com/armor/docs/network-edge-policies), and upstream provider mitigations, including network-level DDoS scrubbing.

### Summary checklist

[](#summary-checklist)

| Defense | Minimum recommendation | | --------------------------------- | --------------------------------------------------------------------- | | **Firewall** | Block all ports except those required (deny by default). | | **Load balancer & reverse proxy** | Place HAProxy (or equivalent) in front of the validator. | | **DDoS protection** | Enable DDOS protection (Cloudflare Spectrum, AWS Shield, or similar). |

# Shutdown Nodes

> Safely shutdown your validator and validator fullnode (VFN) by leaving the validator set and cleaning up resources across different deployment methods.

If you want to shut down your validator and validator fullnode (VFN), follow the instructions below to leave the validator set and clean up the resources used by the nodes.

Caution

**LEAVE THE VALIDATOR SET FIRST**  
It is important to leave the validator set before shutting down your nodes. Otherwise, you will reduce stake participation in the network and risk degrading network health.

## Leave the validator set

[](#leave-the-validator-set)

Before shutting down your nodes, you must leave the validator set. This will ensure that your node is no longer responsible for participating in consensus. Validator nodes can leave the validator set at any time. This also happens automatically when there is insufficient stake in the validator account.

When you leave the validator set, your node will be marked as "inactive" in the next epoch. To leave the validator set, run the following command using the Aptos CLI. You will need to set the `profile` and `owner-address` flags.

```
aptos node leave-validator-set --profile <operator-profile> --pool-address <owner-address>
```

Caution

**WAITING FOR EPOCH CHANGES**  
If you leave the validator set, it will only take effect at the beginning of the next epoch. You will need to wait for the next epoch to start before shutting down your nodes. Similarly, if you leave the validator set and then rejoin in the same epoch, the rejoin will fail. You should wait for the next epoch to start before rejoining the validator set.

## Shutdown methods

[](#shutdown-methods)

Once you have successfully left the validator set, you can shut down your nodes. The method for shutting down your nodes depends on how you deployed them. Choose the appropriate section below to shut down your nodes.

## Using Source Code

[](#using-source-code)

1.  Stop your node by killing the `aptos-node` process. This is sufficient to shut down your node.
2.  (Optional) If you wish to free up space, remove the data directory, e.g., `rm -r <your-data-directory>`.
3.  (Optional) If you wish to reuse your node identity, you should keep the configuration files:
    *   `public-keys.yaml`
    *   `private-keys.yaml`
    *   `validator-identity.yaml`
    *   `validator-full-node-identity.yaml`

## Using Docker

[](#using-docker)

1.  Stop your node and remove the data volumes by running the command: `docker compose down --volumes`. This is sufficient to shut down your node.
2.  (Optional) If you wish to reuse your node identity, you should keep the configuration files:
    *   `public-keys.yaml`
    *   `private-keys.yaml`
    *   `validator-identity.yaml`
    *   `validator-full-node-identity.yaml`

## Using Terraform

[](#using-terraform)

Note

Terraform is commonly used to setup nodes on cloud providers like AWS, Azure, and GCP.

1.  Stop your node and delete all the resources by running the command: `terraform destroy`. This is sufficient to shut down your node.
2.  (Optional) If you wish to reuse your node identity, you should keep the configuration files:
    *   `public-keys.yaml`
    *   `private-keys.yaml`
    *   `validator-identity.yaml`
    *   `validator-full-node-identity.yaml`

# Update Trusted Setup

> Download, verify, and rotate the DKG trusted-setup blobs (digest_key.bin and pp.bin) used by Aptos validator consensus.

Aptos validators consume two trusted-setup blobs at startup: `digest_key.bin` and `pp.bin` (public parameters). The blobs are published by Aptos Labs in the [`aptos-labs/aptos-networks`](https://github.com/aptos-labs/aptos-networks) repository and are loaded by consensus before the node begins participating in DKG. VFNs and PFNs do **not** need these files.

This page covers the steps an existing validator operator should take to roll a new revision of the blobs onto their node. The flow depends on how you deploy:

*   **Source code** — you run the validator binary directly.
*   **Docker (compose)** — you run the upstream `aptos-node` docker-compose stack.
*   **Kubernetes (Helm chart)** — you run the official `aptos-node` Helm chart on AWS / GCP / Azure.

Caution

Every validator in the fleet must load the **same** bytes. Loading a stale or mismatched blob on a subset of validators will prevent the affected nodes from participating in consensus. Always confirm the `blake3` checksum matches the value published below before you start sending traffic to a restarted validator.

## Published checksums

[](#published-checksums)

Testnet checksums correspond to the blobs at [`aptos-networks@8cfc400`](https://github.com/aptos-labs/aptos-networks/tree/8cfc400bc1e42a232b5b36cde779a5b71d4d275b/testnet) (current as of 2026-05-15). This table is updated whenever Aptos Labs publishes a new revision.

| Network | File | Size (bytes) | blake3 | | ------- | ---------------- | ------------------------- | ------------------------------------------------------------------ | | testnet | `digest_key.bin` | `4002048590` | `ffff6ab738c58c1c7eeb697eecbc369205e111c9ef271ab2cbe524869671b441` | | testnet | `pp.bin` | `889521361` | `5094dd22376eefde2febae5f2c9935d7eab0440af93166d246aa5c9f8ecb1b52` | | mainnet | `digest_key.bin` | _TBD — not yet published_ | _TBD — not yet published_ | | mainnet | `pp.bin` | _TBD — not yet published_ | _TBD — not yet published_ |

Note

Both blobs are stored via Git LFS, so download URLs must use `github.com/.../raw/...` (which follows the LFS redirect) rather than `raw.githubusercontent.com` (which returns the 135-byte LFS pointer text). Using the wrong URL will silently break consensus.

## Source code deployment

[](#source-code-deployment)

Use this flow if you run the validator directly from a binary built from `aptos-core`. You pick where the blobs live on disk and point `validator.yaml` at them.

### 1\. Download the blobs

[](#1-download-the-blobs)

Pick a directory on the validator host — anywhere on persistent local storage works. The example below uses `/opt/aptos/genesis/` alongside `genesis.blob` and `waypoint.txt`.

```
wget -O /opt/aptos/genesis/digest_key.bin \  https://github.com/aptos-labs/aptos-networks/raw/main/<network>/digest_key.binwget -O /opt/aptos/genesis/pp.bin \  https://github.com/aptos-labs/aptos-networks/raw/main/<network>/pp.bin
```

Replace `<network>` with the appropriate network (`testnet` or `mainnet`).

### 2\. Verify with the Aptos CLI

[](#2-verify-with-the-aptos-cli)

Confirm each file deserializes correctly and compute its `blake3` checksum:

```
aptos node validate-digest-key --file /opt/aptos/genesis/digest_key.binaptos node validate-public-parameters --file /opt/aptos/genesis/pp.bin
```

Each command prints JSON of the following shape:

```
{  "size": 4002048590,  "blake3": "ffff6ab738c58c1c7eeb697eecbc369205e111c9ef271ab2cbe524869671b441"}
```

Compare both fields against the [Published checksums](#published-checksums) table for your network. If either value differs, **do not restart the validator** — re-download the file (most common cause: truncated transfer or fetching the LFS pointer text via `raw.githubusercontent.com`).

### 3\. Configure validator.yaml

[](#3-configure-validatoryaml)

Confirm the `consensus` block in your `validator.yaml` references both files. Paths must match where you wrote them in step 1.

```
consensus:  digest_key_blob_path: /opt/aptos/genesis/digest_key.bin  public_parameters_blob_path: /opt/aptos/genesis/pp.bin
```

### 4\. Restart the validator

[](#4-restart-the-validator)

Follow your normal restart procedure (see [Upgrade Nodes](/network/nodes/validator-node/modify-nodes/update-validator-node) for deployment-specific steps). The node loads the blobs once during startup; subsequent rotations require another restart.

## Docker (compose) deployment

[](#docker-compose-deployment)

Use this flow if you run the upstream `docker-compose.yaml` from [`aptos-core/docker/compose/aptos-node`](https://github.com/aptos-labs/aptos-core/tree/testnet/docker/compose/aptos-node). The upstream compose file bind-mounts the trusted-setup files from your working directory into the container at `/opt/aptos/genesis/`, and the upstream `validator.yaml` already has the matching `consensus` paths — so you only need to drop the files alongside `genesis.blob` / `waypoint.txt`.

### 1\. Download the blobs into your working directory

[](#1-download-the-blobs-into-your-working-directory)

```
cd ~/$WORKSPACE   # the directory holding genesis.blob and waypoint.txtwget -O digest_key.bin https://github.com/aptos-labs/aptos-networks/raw/main/testnet/digest_key.binwget -O pp.bin https://github.com/aptos-labs/aptos-networks/raw/main/testnet/pp.bin
```

Replace `testnet` with the network you operate on (mainnet blobs are not yet published; see the [Published checksums](#published-checksums) note).

### 2\. Verify with the Aptos CLI

[](#2-verify-with-the-aptos-cli-1)

```
aptos node validate-digest-key --file digest_key.binaptos node validate-public-parameters --file pp.bin
```

Compare `size` and `blake3` against the [Published checksums](#published-checksums) table for your network. If they don't match, re-download — **do not restart the validator** with a bad file.

### 3\. Confirm docker-compose.yaml and validator.yaml are current

[](#3-confirm-docker-composeyaml-and-validatoryaml-are-current)

The upstream files include both bind mounts and the `consensus` block. If you set up the validator before these were added, refresh both files from the `testnet` branch of `aptos-core` (see [Testnet Files](/network/nodes/configure/node-files-all-networks/node-files-testnet)) and reconcile any local modifications. The relevant pieces to confirm:

`docker-compose.yaml` (validator service):

```
volumes:  # …existing mounts (genesis.blob, waypoint.txt, validator.yaml, identity files)…  - type: bind    source: ./digest_key.bin    target: /opt/aptos/genesis/digest_key.bin  - type: bind    source: ./pp.bin    target: /opt/aptos/genesis/pp.bin
```

`validator.yaml`:

```
consensus:  digest_key_blob_path: /opt/aptos/genesis/digest_key.bin  public_parameters_blob_path: /opt/aptos/genesis/pp.bin  # …safety_rules and other consensus settings…
```

### 4\. Restart the validator

[](#4-restart-the-validator-1)

```
docker compose restart validator
```

Or recreate the stack to pick up any `docker-compose.yaml` changes:

```
docker compose up -d
```

## Kubernetes deployment (Helm chart)

[](#kubernetes-deployment-helm-chart)

Use this flow if you deploy the validator via the official `aptos-node` Helm chart (the typical setup on AWS, GCP, and Azure). You do **not** download the blobs manually — the chart's init container fetches them into a persistent volume on first restart and skips on subsequent restarts.

### 1\. Update the `trustedSetup` chart values

[](#1-update-the-trustedsetup-chart-values)

Set the URLs (and optionally override the on-disk path) under the chart's `trustedSetup` block. The chart writes the blobs to `trustedSetup.path` on the persistent `aptos-data` PVC and configures `consensus.digest_key_blob_path` / `public_parameters_blob_path` in `validator.yaml` to match — no further validator config is needed.

```
trustedSetup:  # Persistent location on the aptos-data PVC. Default works for most deployments.  path: /opt/aptos/data/trusted-setup  # Bump this integer to force re-download even when URLs are unchanged. Default 0.  refreshCounter: 0  digestKeyUrl: "https://github.com/aptos-labs/aptos-networks/raw/8cfc400bc1e42a232b5b36cde779a5b71d4d275b/testnet/digest_key.bin"  publicParametersUrl: "https://github.com/aptos-labs/aptos-networks/raw/8cfc400bc1e42a232b5b36cde779a5b71d4d275b/testnet/pp.bin"
```

Tip

**Pin to an `aptos-networks` commit SHA**, not `main`. Pinning makes rotations explicit and diffable, and prevents a silent `main`\-tracking pull from rolling out new bytes on the next pod restart.

### 2\. (Optional) Pre-verify the checksum on a workstation

[](#2-optional-pre-verify-the-checksum-on-a-workstation)

The chart fetches the bytes inside the cluster, so the in-cluster download never sees the `aptos` CLI. To sanity-check the URL before rollout, download a copy locally and run the [source-code verify step](#2-verify-with-the-aptos-cli) on it:

```
wget -O /tmp/digest_key.bin \  https://github.com/aptos-labs/aptos-networks/raw/8cfc400bc1e42a232b5b36cde779a5b71d4d275b/testnet/digest_key.binaptos node validate-digest-key --file /tmp/digest_key.bin
```

Compare the printed `blake3` against the [Published checksums](#published-checksums) table.

### 3\. Apply and restart

[](#3-apply-and-restart)

Run your usual chart-deployment command (`helm upgrade`, `pulumi up`, Terraform apply, etc.). The init container detects that the on-disk `.url` marker no longer matches the new URL, downloads the blob into `trustedSetup.path`, and writes a new marker. The validator container then loads the freshly fetched files.

Note

**First restart pays a one-time download cost.** The blobs total ~4 GiB on testnet, fetched once into the persistent data PVC. Subsequent restarts skip the download via the marker check and start in seconds.

### Force a re-download without changing URLs

[](#force-a-re-download-without-changing-urls)

If you suspect on-disk corruption or want to re-fetch from the same URL (for example, to recover from a half-written download), bump `trustedSetup.refreshCounter` by one and re-apply. The init container wipes the existing markers, which forces every blob to be re-downloaded on the next pod restart.

```
trustedSetup:  refreshCounter: 1 # was 0  # urls unchanged
```

## Confirm fleet consistency

[](#confirm-fleet-consistency)

After your validators have restarted (any flow), two Prometheus metrics expose the `blake3` of each loaded blob as a label:

*   `aptos_dkg_digest_key_blake3{blake3="<hex>"} 1`
*   `aptos_dkg_public_params_blake3{blake3="<hex>"} 1`

Group by the `blake3` label in Grafana across your validator fleet. A healthy rollout shows a single label value per metric matching the [Published checksums](#published-checksums) table. Multiple values indicate at least one validator is running a stale blob.

# Upgrade Nodes

> Keep your validator and VFN up-to-date with simple upgrades and VFN failover techniques to minimize downtime during software updates.

This section contains tutorials for upgrading your validator and validator fullnode (VFN). Upgrades are a common operation for maintaining your nodes. Aptos Labs frequently releases new versions of the Aptos node software, and you should keep your nodes up to date to ensure they are secure and reliable.

Caution

Running old node versions and failing to update your nodes can lead to security vulnerabilities, performance degradation, and network instability. It is important to keep your nodes up to date.

There are two primary ways to upgrade your nodes. The first is a **simple** **upgrade** of the node software, and the second is a more **complex** **failover** process between your validator and VFN. The failover process is useful for minimizing validator downtime when you need to upgrade.

## Simple Upgrade

[](#simple-upgrade)

To perform a simple node upgrade, you can upgrade the validator and VFN individually, one at a time. This process is straightforward and can be repeated for each node. The steps are as follows:

1.  First, stop the node manually (e.g., the validator or VFN). To stop the node, it will depend on your deployment method.
    
2.  Next, update the node software to the latest version. This may require downloading the latest binary or Docker image, or recompiling the source code. Depending on your deployment method, you can perform this step in the background while the node is still running. This should help minimize downtime.
    
3.  Finally, once you have updated the node software, restart the node using the latest software version and the original commands you used to start the node.
    
    Note
    
    **REPEAT FOR EACH NODE**  
    You will need to perform the simple upgrade process for each node individually. This means you will need to upgrade the validator and VFN separately.

## Upgrade via VFN Failover

[](#upgrade-via-vfn-failover)

To minimize validator downtime, you can perform a failover process between your validator and VFN. This process involves upgrading the VFN to the latest version and converting it to the validator. Once the VFN has been converted to the new validator, you can then upgrade the original validator and convert it into the new VFN.

The benefit of this approach is that it minimizes validator downtime by allowing you to prepare the new validator while the original validator is still running.

Caution

**Node differences**  
Before you begin the failover process, it is important to understand that the data maintained by the two nodes (i.e., validator and VFN) is not identical. The VFN is missing the `consensus_db` and the `secure-data.json` file, and both nodes use different configuration files (including identities).

If you are not comfortable with the failover process, you should consider performing a simple upgrade instead.

To perform a VFN failover upgrade, you should follow these steps:

1.  Update your DNS to swap the [network addresses](/network/nodes/validator-node/connect-nodes/connect-to-aptos-network#3-update-on-chain-network-addresses) between the validator and VFN.
    
2.  Stop the VFN and update the node software to the latest version. This may require downloading the latest binary or Docker image, or recompiling the source code. In addition, you will need to copy the `consensus_db` and `secure-data.json` file from the validator to the VFN, as well as the validator configuration file (including validator identities).
    
3.  Once the VFN is primed to become the new validator, you can stop the old validator, and start the new validator immediately. This will minimize validator downtime.
    
    Caution
    
    **ONLY ONE VALIDATOR AT A TIME**  
    It is important to ensure that only a single validator is running at any given time. If you fail to stop the original validator before starting the new validator, you will have two validators running at the same time, and this will lead to consensus failures and performance issues on your nodes.
    
4.  Now, you will have a validator running the new code version. Observe that before DNS changes take effect your new validator will only have outbound connections.
    
5.  Next, prepare the original validator to become the new VFN. This will involve updating the node software to the latest version, and copying the VFN configuration file (including VFN identities) across.
    
6.  Once the original validator is ready to become the new VFN, you can start the new VFN.

Note

Once you have completed the failover process, you should monitor the new validator and VFN to ensure they are running correctly, and that your validator is still participating in consensus.

# Node Requirements

> Hardware, networking, and software requirements for running Aptos validator and validator fullnode (VFN) to ensure optimal performance and stability.

To ensure that your validator and validator fullnode (VFN) operate smoothly, both nodes should meet the requirements specified in this document.

Caution

**Failure to meet requirements**  
Failure to meet the requirements outlined in this document will result in your nodes experiencing degradation under load, consensus failures, reward losses, and general instability.

## Resource isolation

[](#resource-isolation)

When running an Aptos validator and VFN, we strongly recommend that the nodes run on two separate and independent machines. These machines should be well-provisioned, meet the requirements outlined below and be isolated from each other. Maintaining resource isolation between the validator and the VFN is important for security and to ensure that the nodes do not encounter performance degradation, instability or failures when under load.

Note

For deploying the validator and VFN in the cloud, we provide Terraform support on two cloud providers: **GCP** and **AWS**. See [**Running Validator Node**](/network/nodes/validator-node/deploy-nodes).

## Hardware requirements

[](#hardware-requirements)

For running an Aptos validator and VFN in mainnet, we recommend that your hardware be performant enough to maintain ~30,000 transactions per second (TPS). There are two ways to evaluate if your hardware meets this requirement:

1.  Use the reference specs provided below.
2.  Run the performance benchmarking tool provided by Aptos.

Note that both the validator and VFN require sufficient hardware separately (i.e., two separate machines that satisfy the requirements outlined below).

### Reference specs

[](#reference-specs)

**Specifications for Running an Aptos Validator and VFN on Mainnet**

| Component | Specification | | -------------------- | --------------------------------------------------------------------------- | | CPU | 48 threads, 5th Gen AMD EPYC (Turin) or 6th Gen Intel Xeon (Granite Rapids) | | Memory | 128GB RAM | | Storage | 3.0 TB Enterprise NVMe SSD with at least 60K IOPS and 600MiB/s bandwidth | | Networking Bandwidth | 1Gbps |

**Example Machine Types on Various Clouds**

| Cloud Provider | Machine Type | Notes | | -------------- | --------------------------------------------------------- | ------------- | | AWS | c8a.16xlarge + io2 EBS volume or multiple gp3 EBS volumes | With 60K IOPS | | GCP | c4d-standard-48 + hyperdisk-balanced | With 60K IOPS | | Azure | Standard\_F48as\_v7 | With 60K IOPS | | Latitude.sh | f4.metal.large | With 60K IOPS |

### Performance benchmarking

[](#performance-benchmarking)

If you'd prefer to evaluate your hardware for sufficient performance, you can use the performance benchmarking tool. First, clone the `aptos-core` repository and install the required dependencies (see the [**Cloning aptos-core**](/network/nodes/building-from-source#clone-the-aptos-core-repo) section). Then, execute the following commands to run the benchmark:

```
TABULATE_INSTALL=lib-only pip install tabulate
./testsuite/performance_benchmark.sh --short
```

Once the benchmark finishes, it will print out a table, with a column `"t/s"`, which shows the TPS achieved by your hardware. The evaluation criteria is encoded in the tool, and the tool will display a warning if your hardware does not meet the requirements.

**Local SSD vs. network storage**

Cloud deployments require choosing between local storage or network storage, such as, AWS EBS and GCP PD. Loosely speaking, a local SSD often provides lower latency and cost, especially relative to IOPS (input/output operations per second), while network storage requires CPU support to scale IOPS. However, network storage provides better support for backups and offers improved reliability for nodes that stop or fail, thus enabling higher availability. The choice between local SSD and network storage depends on your specific requirements and constraints.

### Motivating hardware requirements

[](#motivating-hardware-requirements)

Hardware requirements for Aptos nodes depend on: (i) the transaction workload being executed; and (ii) the size of the database on each machine. The current hardware requirements have been set using an estimated transaction workload (e.g., 30,000 TPS) and an estimated database growth rate for 2024. These may be subject to change. It is also worth noting that transaction workloads can change frequently, and thus it is necessary to provision your hardware to meet the requirements of the most demanding transaction workloads. This will ensure that your nodes can perform well under load and remain stable.

Generally, the size of the database on each machine is a function of the ledger history (i.e., the number of transactions in the blockchain history) and the number of on-chain states (e.g., accounts and resources). Both the ledger history and the number of on-chain states depend on several additional factors, including the age of the blockchain, the average transaction rate over time, and the configuration of the ledger database pruner. At the time of writing, we estimate that testnet and mainnet require several 100's of GB of storage.

## Network requirements and ports

[](#network-requirements-and-ports)

When you are running a validator and a VFN, you are required to open network ports on your nodes to allow other nodes (i.e., peers) to connect to you. There are different Aptos network types, and each network type uses a different port (see below).

### Network types

[](#network-types)

There are three types of Aptos networks:

1.  **Validator network:** Validators connect to each other over this network. Validator fullnodes (VFNs) and public fullnodes (PFNs) do not use this network.
2.  **VFN network:** The validator fullnode (VFN) network allows a validator and VFN pair to connect to each other. This network is private between the validator and the VFN.
3.  **Public network:** The public network allows VFNs and public fullnodes (PFNs) to connect to other VFNs and PFNs. This allows public node operators to access the blockchain.

Your node can be configured so that each of these networks can operate using a different port on your node. You can configure the port settings using the node configuration YAML file. Here is an [example configuration file](https://github.com/aptos-labs/aptos-core/blob/4ce85456853c7b19b0a751fb645abd2971cc4c0c/docker/compose/aptos-node/fullnode.yaml#L10) for a VFN node that configures the VFN network to use port `6181` and the public network to use port `6182`.

### Port settings

[](#port-settings)

The recommendations described below assume the default port settings used by validators, VFNs and PFNs. If you have changed the default port settings in your configuration file, then you should adjust the recommendations accordingly.

Caution

**Exposing ports**  
Unless explicitly required, we recommend that you do not expose any other ports while operating a node. This is because exposing additional ports can increase the attack surface of your node and make it more vulnerable to adversaries.

#### Running a validator:

[](#running-a-validator)

Assuming default ports are used, the following should be configured for validator nodes:

*   Open the following TCP ports:
    *   `6180` - **Validator network**: Open this port publicly to enable the validator to connect to other validators in the network.
    *   `6181` – **VFN network**: Open this port privately to only be accessible by your VFN.
*   Close the following TCP ports:
    *   `6182` – **Public network**: Close this port to prevent PFN connections.
    *   `9101` – **Inspection service**: Close this port to prevent unauthorized metric inspection.
    *   `9102` – **Admin service**: Close this port to prevent unauthorized admin service interaction.
    *   `80/8080` **REST API**: Close this port to prevent unauthorized REST API access.

#### Running a VFN:

[](#running-a-vfn)

Assuming default ports are used, the following should be configured for VFN nodes:

*   Open the following TCP ports:
    *   `6181` – **VFN network**: Open this port privately to only be accessible by your validator.
    *   `6182` – **Public network**: Open this port publicly to enable PFNs to connect to your VFN.
*   Close the following TCP ports:
    *   `9101` – **Inspection service**: Close this port to prevent unauthorized metric inspection.
    *   `9102` – **Admin service**: Close this port to prevent unauthorized admin service interaction.
    *   `80/8080` **REST API**: Close this port to prevent unauthorized REST API access.

Caution

## Software Requirements

[](#software-requirements)

### Time Service

[](#time-service)

It is highly recommended to enable system clock synchronization using a Network Time Protocol (NTP) service. Accurate timekeeping ensures that nodes participate in consensus promptly and remain synchronized with the rest of the network. Failure to maintain consistent system time may cause nodes to lag behind and validators may even fail to propose blocks.

# Operator

> Complete operator guide for participating in the Aptos network including validator deployment, network connection, staking setup, and maintaining node liveness.

If you are an operator participating in the Aptos network, then use this document to perform the operator tasks such as deploying a validator node and validator fullnode, registering the nodes on the Aptos community platform, and performing the validation.

Note

**Both validator node and validator fullnode are required for mainnet**  
For participating in the Aptos mainnet, you must deploy both a validator node and a validator fullnode.

## Deploy the nodes and register

[](#deploy-the-nodes-and-register)

1.  Read the
    
    Make sure that your hardware, storage and network resources satisfy the node requirements.
    
2.  Deploy the nodes
    
    Follow the detailed node installation steps provided in [**Running Validator Node**](/network/nodes/validator-node/deploy-nodes) and deploy a validator node and a validator fullnode.

Note that your nodes will not be running correctly (not syncing, not participating in consensus), until they're added to the validator set via [staking pool operations](/network/nodes/validator-node/connect-nodes/staking-pool-operations) (below).

## Connect to Aptos network

[](#connect-to-aptos-network)

After deploying your nodes, [connect to the Aptos Network](/network/nodes/validator-node/connect-nodes/connect-to-aptos-network).

## Set up staking and delegation pool operations

[](#set-up-staking-and-delegation-pool-operations)

After connecting your nodes to the Aptos network, establish [staking pool operations](/network/nodes/validator-node/connect-nodes/staking-pool-operations) to add your node to the validator set.

Similarly, conduct [delegation pool operations](/network/nodes/validator-node/connect-nodes/delegation-pool-operations) for APT delegated to your validator. Your node will start syncing and participating in consensus.

## Ensure your nodes are live

[](#ensure-your-nodes-are-live)

After your nodes are deployed and configure, make sure they meet [node liveness criteria](/network/nodes/validator-node/verify-nodes/node-liveness-criteria).

# Monitor Nodes

> Monitor and verify the health, performance, and status of your validator and validator fullnode (VFN) with comprehensive verification guides.

This section contains tutorials for verifying the health and performance of your validator and validator fullnode (VFN). These include:

*   ### [Node Health](/network/nodes/validator-node/verify-nodes/node-liveness-criteria)
    
    [](#node-health)
    
*   ### [Validator Leaderboard](/network/nodes/validator-node/verify-nodes/leaderboard-metrics)
    
    [](#validator-leaderboard)

# Validator Leaderboard

> Understand how validator rewards performance is calculated and displayed on the Aptos Validator Leaderboard including proposal success rates and epoch metrics.

This document explains how the rewards performance for validator nodes are calculated and displayed on the [Aptos Validator Leaderboard](https://explorer.aptoslabs.com/validators/all?network=mainnet).

![Aptos Explorer Validators page showing global node distribution](/_vercel/image?url=_astro%2Fexplorer-validators.CqCsHx6Z.png&w=1280&q=100&dpl=dpl_BVzupKm7aQfXg1N3qg98Mi3YEbWs)

Aptos validator network as of 3/30/2026: 115 nodes across 16 countries. [View live on Explorer](https://explorer.aptoslabs.com/validators?network=mainnet)

## Calculating validator rewards

[](#calculating-validator-rewards)

Validators are rewarded for participating in consensus. The rewards are calculated based on the number of successful proposals made by the validator, and the rewards performance is the percentage of rewards earned by the validator out of the maximum reward earning opportunity.

During an epoch, only the validators in the validator set can propose and vote. The duration of each epoch is set by governance and validators are selected as leaders (in rounds) to make proposals. This occurs multiple times in each epoch, meaning that validators can be selected as leaders multiple times in a single epoch.

On each successful proposal, the proposing validator earns rewards based on their stake and on the reward rate that is configured on-chain. The reward rate is the same for every validator. If all the proposals in an epoch achieve quorum consensus, a validator earns the maximum reward for the epoch. If all the proposals in an epoch fail, a validator earns zero rewards for that epoch. The reward performance is calculated as a percentage of the rewards earned by the validator out of the maximum reward earning opportunity.

Validators are only rewarded for proposing, and not for voting. Rewards are given only at the end of the epoch, not on every block.

### Reward calculation example

[](#reward-calculation-example)

The reward a leader receives is calculated by multiplying the maximum possible reward with the leader's proposal success rate. For example:

*   A leader with 8 successful and 2 failed proposals will receive 80% of maximum reward in the epoch.
*   Similarly, another leader with 80 successful and 20 failed proposals will also receive 80% of maximum reward.
*   Also, two leaders with no failures but one with 10 and another with 100 successful proposals will get the same % of the maximum reward.

Note

**REWARDS RATE**  
Note also that the rewards rate is the same for every validator. Hence, the maximum reward is directly proportional to the staking amount, i.e., the more a validator stakes, the more the validator can earn in absolute terms.

### Rewards performance

[](#rewards-performance)

The **REWARDS** **PERFORMANCE** column on the [Aptos Validator Leaderboard](https://explorer.aptoslabs.com/validators/all?network=mainnet) shows the rewards performance of a validator. It is calculated as a percentage of the rewards earned by the validator out of the maximum reward earning opportunity. This is a cumulative metric across all the epochs, i.e., `(rewards earned across all epochs)/(maximum reward opportunity across all epochs)`

A validator can improve their rewards performance by improving their proposal success rate.

### Last epoch performance

[](#last-epoch-performance)

The **LAST EPOCH PERFORMANCE** column on the [Aptos Validator Leaderboard](https://explorer.aptoslabs.com/validators/all?network=mainnet) shows the rewards performance of a validator in the last epoch. It is calculated as a percentage of the rewards earned by the validator in the last epoch out of the maximum reward earning opportunity in the last epoch, i.e., `(rewards earned in the last epoch)/(maximum reward opportunity in the last epoch)`.

This metric provides an early indicator to see if a validator is improving their reward performance.

# Node Health

> Verify and monitor the health of your validator and validator fullnode (VFN) using runtime metrics, local monitoring tools, and telemetry data.

This document describes how you can verify and monitor the health of your validator and validator fullnode (VFN) in the Aptos network. Many of the methods described here rely on the runtime metrics that your nodes collect and report. These metrics are collected by the Aptos node binary and are exposed via a Prometheus metrics endpoint. For a detailed description of the important metrics, see the [Node Inspection Service](/network/nodes/measure/node-inspection-service) and [Important Node Metrics](/network/nodes/measure/important-metrics) documentation.

## Initial Node Verification

[](#initial-node-verification)

After deploying your nodes and connecting them to the Aptos network, you should verify that your nodes are running correctly.

Note

**FIRST TIME?**  
In some environments, e.g., `mainnet` and `testnet`, your VFN will begin syncing first (before your validator is able to sync). This is normal behaviour. Once your VFN has finished syncing, your validator node will start syncing and eventually start participating in consensus.

You can verify the correctness of your nodes by inspecting several simple metrics. Follow these steps:

1.  Check if your nodes are state syncing by running this command:
    
    ```
    curl 127.0.0.1:9101/metrics 2> /dev/null | grep "aptos_state_sync_version"
    ```
    
    You should expect to see the `synced` or `synced_states` versions increasing. The versions should start increasing for your VFN first, then eventually your validator node will start syncing.
    
    Note
    
    **CLOUD DEPLOYMENT?**  
    You may need to replace `127.0.0.1` with your validator or VFN IP/DNS if deployed on the cloud.
    
2.  Verify that your validator is connecting to other peers on the network.
    
    ```
    curl 127.0.0.1:9101/metrics 2> /dev/null | grep "aptos_connections{.*\"Validator\".*}"
    ```
    
    The command will output the number of inbound and outbound connections of your validator node. For example:
    
    ```
    aptos_connections{direction="inbound",network_id="Validator",peer_id="f326fd30",role_type="validator"} 5aptos_connections{direction="outbound",network_id="Validator",peer_id="f326fd30",role_type="validator"} 2
    ```
    
    As long as one of the metrics is greater than zero, your validator node is connected to at least one of the peers on the network. If your validator is not connected to any peers, make sure your VFN has completed syncing first. Once your VFN has finished syncing, your validator node will start syncing and eventually be able to connect to other peers.
    
3.  After your node syncs to the latest version, you can also check if consensus is making progress, and your node is proposing.
    
    ```
    curl 127.0.0.1:9101/metrics 2> /dev/null | grep "aptos_consensus_current_round"
    curl 127.0.0.1:9101/metrics 2> /dev/null | grep "aptos_consensus_proposals_count"
    ```
    
    You should expect to see these numbers continue to increase.

## Local Monitoring

[](#local-monitoring)

If you are a node operator, there are several tools available to you to verify the health of your node going forward:

*   **Metrics:** You can monitor your local metrics endpoint by running a `curl` command against the [Node Inspection Service](/network/nodes/measure/node-inspection-service) and verify key metrics. For example, you can verify the synchronization status of your node by running the command outlined in the [Verify synchronization](/network/nodes/full-node/verify-pfn#verify-synchronization) section.
    
*   **REST API:** You can also monitor your node's health by querying the REST API. For example, you can verify the current block height of your node by pinging the index page of your node's REST API. For more information, see the [Aptos API Specification](/build/apis/fullnode-rest-api).
    
*   **Monitoring tools:** To improve observability, you can also install monitoring tools that scrape the local metrics endpoint:
    
    *   For Kubernetes based deployments, install the monitoring Helm chart ([https://github.com/aptos-labs/aptos-core/tree/main/terraform/helm/monitoring](https://github.com/aptos-labs/aptos-core/tree/main/terraform/helm/monitoring)).
    *   Locally, you may run Prometheus and Grafana directly. Dashboards that utilize the metrics can be found here: ([https://github.com/aptos-labs/aptos-core/tree/main/dashboards](https://github.com/aptos-labs/aptos-core/tree/main/dashboards)).

## Telemetry

[](#telemetry)

The Aptos Labs team can also monitor your node remotely using [Node Telemetry](/network/nodes/configure/telemetry). When you enable telemetry on your nodes, the Aptos node binary will send telemetry data in the background, which includes the node's metrics. Telemetry data from your node is necessary to evaluate the performance, liveness and health of your nodes.

If your node is using the default config without explicitly disabling telemetry, and has `HTTPS` egress access to the internet, then it will report various key metrics to Aptos Labs. Aptos Labs will also observe the on-chain events such as proposals per hour on your node, as defined in the liveness criteria.

# Latest Aptos Releases

> Find the latest Aptos releases for mainnet, testnet, and devnet with their corresponding GitHub branches

Each Aptos release can be found on the GitHub site for [Aptos-core releases](https://github.com/aptos-labs/aptos-core/releases). Each release is mirrored by the following git branches:

*   [Latest Mainnet Release](https://github.com/aptos-labs/aptos-core/tree/mainnet)
*   [Latest Testnet Release](https://github.com/aptos-labs/aptos-core/tree/testnet)
*   [Latest Devnet Release](https://github.com/aptos-labs/aptos-core/tree/devnet)

Aptos typically conducts multiple devnet releases for each testnet and mainnet release. Hence, devnet releases use commit hashes for tracking rather than version numbers. Testnet and mainnet releases usually have a one-to-one correlation, meaning each testnet release rolls into mainnet.

Hot fixes are exceptions that may occur in mainnet to address urgent issues in production. See the [Aptos Release Process](https://github.com/aptos-labs/aptos-core/blob/main/RELEASE.md) for more details.

## Update nodes

[](#update-nodes)

If you are a node operator, [update your nodes with the new release](/network/nodes/full-node/modify/update-fullnode-with-new-releases).

## Subscribe to Release Announcements

[](#subscribe-to-release-announcements)

### Subscribe via GitHub

[](#subscribe-via-github)

1.  Go to the [aptos-labs/aptos-core](https://github.com/aptos-labs/aptos-core) repository.
2.  Open the **Watch** menu and select **Custom**.
3.  Select the **Releases** checkbox and click **Apply**.

### Subscribe via [Aptos Discord](https://discord.gg/aptosnetwork)

[](#subscribe-via-aptos-discord)

Join the Aptos Discord server to interact with us and our community. We also post upcoming releases in these channels.

*   [#mainnet-release](https://discord.com/channels/945856774056083548/1042502400507916349)
*   [#testnet-release](https://discord.com/channels/945856774056083548/1025614160555413545)
*   [#devnet-release](https://discord.com/channels/945856774056083548/956692649430093904)

### Subscribe via [Aptos Twitter](https://x.com/AptosRelease)

[](#subscribe-via-aptos-twitter)

Follow [@AptosRelease](https://x.com/AptosRelease) on Twitter to get the latest updates about our upcoming mainnet releases and be notified when it is time to update your node. Every couple of days, [@AptosRelease](https://x.com/AptosRelease) will tweet a countdown to remind you to update to the latest version. _Note: We do not post about hotfixes here!_

## Aptos Release Process

[](#aptos-release-process)

To understand how we conduct releases, review the [Aptos Release Process](https://github.com/aptos-labs/aptos-core/blob/main/RELEASE.md).

Aptos Wallet Connection

Aptos Sign and Verify Message