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;
```

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

[Section titled “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`.

```tsx
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)

[Section titled “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`.

```tsx
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

[Section titled “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.

```tsx
{
  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

```tsx
   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:

```tsx
   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

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

[Section titled “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

[Section titled “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.

```typescript
/**
  * 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

[Section titled “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.

```typescript
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

[Section titled “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

[Section titled “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:

```typescript
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.

```typescript
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.

```typescript
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

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

### Dapp API

[Section titled “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/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.

```typescript
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.

```typescript
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:

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

## Key rotation

[Section titled “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

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.

[Section titled “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:

[Section titled “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))

[Section titled “2. Once tested, publish a new npm package for your SDK wallet code by following this guide. (Ex. AptosConnect)”](#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.

[Section titled “3. Update 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.

```shellscript
   git checkout -b your-wallet
   ```

4. Navigate to .

5. Import your SDK wallet npm package.

```shellscript
   pnpm i @yourpackage
   ```

6. Import your wallet in .

For example with AptosConnect:

```tsx
   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).

```tsx
   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.

```tsx
   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

[Section titled “Resources”](#resources)

* Wallet Adapter Demo App

* [Live site](https://aptos-labs.github.io/aptos-wallet-adapter)
  * [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

Note

The feature is currently only available on devnet and testnet and is considered an alpha version; therefore, you can expect breaking changes.

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

[Section titled “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?

[Section titled “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?

[Section titled “How to integrate x-chain accounts in my dApp?”](#how-to-integrate-x-chain-accounts-in-my-dapp)

Currently, the adapter supports Solana and EVM chains

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

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      | ✅            | ✅             |               |

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

1. Install the @aptos-labs/derived-wallet-solana package

```shellscript
     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:

```tsx
     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 fot the AptosWalletAdapterProvider

```tsx
     <AptosWalletAdapterProvider
      dappConfig={{
         network: Network.TESTNET,
         crossChainWallets: true,
       }}
     >
       {children}
     <AptosWalletAdapterProvider/>
     ```

* EVM

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

```shellscript
     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:

```tsx
     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

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

#### Submitting a transaction

[Section titled “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.

```tsx
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 client
const config = new AptosConfig({ network: Network.TESTNET });
const aptos = new Aptos(config);

// Generate a sponsor account or use an existing account
const 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;
```

### Considerations

[Section titled “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

[Section titled “Resources”](#resources)

* X-Chain Accounts Adapter Demo App

* [Live site](https://aptos-labs.github.io/aptos-wallet-adapter/nextjs-cross-chain-example/)
  * [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)

# Smart Contracts

Aptos contracts are written using Move, a next generation language for secure, sandboxed, and formally verified programming which is used for multiple chains. Move allows developers to write programs that flexibly manage and transfer assets while providing security and protections against attacks on those assets.

## 📖 Learn Move

[Section titled “📖 Learn Move”](#-learn-move)

[Why Move? ](/build/smart-contracts/why-move)Learn why Aptos uses the Move Language

[Create Package ](/build/smart-contracts/create-package)Get started by learning how to create a Move package

[Objects ](/build/smart-contracts/objects)Learn how to use the Object standard on Aptos to create composable and flexible primitives on chain

## 👨‍💻 Move Examples

[Section titled “👨‍💻 Move Examples”](#-move-examples)

[Aptos Move Examples ](https://github.com/aptos-labs/aptos-core/tree/main/aptos-move/move-examples)30+ examples on how to develop Move on Aptos

[Move Tutorial ](https://github.com/aptos-labs/aptos-core/tree/main/aptos-move/move-examples/move-tutorial)Covers the basics of programming with Move

[Your first Move Module ](/build/guides/first-move-module)A example of how to publish your first move module

Here is a `hello_blockchain` example of move

hello\_blockchain.move

```move
module hello_blockchain::message {
    use std::error;
    use std::signer;
    use std::string;
    use aptos_framework::event;

//:!:>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 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
        );
    }
}
```

## ⚒️ Developer Resources

[Section titled “⚒️ Developer Resources”](#️-developer-resources)

### FAQ and Discussions

[Section titled “FAQ and Discussions”](#faq-and-discussions)

* [Aptos Dev Discussions](https://github.com/aptos-labs/aptos-developer-discussions/discussions) for Q\&A about Move.

### Move IDE plugins

[Section titled “Move IDE plugins”](#move-ide-plugins)

* [Aptos Move Analyzer](https://marketplace.visualstudio.com/items?itemName=MoveBit.aptos-move-analyzer) for Visual Studio.
* [Move language plugin for JetBrains IDEs](https://plugins.jetbrains.com/plugin/14721-move-language): Supports syntax highlighting, code navigation, renames, formatting, type checks and code generation.

### External Resources

[Section titled “External Resources”](#external-resources)

* [Aptos Move by Example](https://move-developers-dao.gitbook.io/aptos-move-by-example)
* [Teach yourself Move on Aptos](https://github.com/econia-labs/teach-yourself-move).
* [Formal Verification, the Move Language, and the Move Prover](https://www.certik.com/resources/blog/2wSOZ3mC55AB6CYol6Q2rP-formal-verification-the-move-language-and-the-move-prover)
* [Pontem Move Playground](https://playground.pontem.network/)
* [Collection of nestable Move resources](https://github.com/taoheorg/taohe)

We have a new Move on Aptos compiler that supports Move 2. See [this page](/build/smart-contracts/compiler_v2) for more information.

# Aptos Coin Standard (Legacy)

[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

[Section titled “Structures”](#structures)

### Reusability

[Section titled “Reusability”](#reusability)

A coin is defined in Move as:

```move
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

[Section titled “Global store”](#global-store)

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

```move
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:

```move
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

[Section titled “Primitives”](#primitives)

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

### Creators

[Section titled “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

[Section titled “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

[Section titled “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)

[Section titled “Coin”](#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)

[Section titled “CoinInfo”](#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

[Section titled “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.

```move
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

[Section titled “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:

```move
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

[Section titled “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:

```move
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`:

```move
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

[Section titled “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

[Section titled “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:

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

### Merging Coins

[Section titled “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:

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

### Extracting Coins

[Section titled “Extracting Coins”](#extracting-coins)

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

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

### Withdrawing Coins from CoinStore

[Section titled “Withdrawing Coins from CoinStore”](#withdrawing-coins-from-coinstore)

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

```move
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

[Section titled “Depositing Coins into CoinStore”](#depositing-coins-into-coinstore)

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

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

Note

This function will emit a `DepositEvent`.

### Transferring Coins

[Section titled “Transferring Coins”](#transferring-coins)

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

```move
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

[Section titled “Events”](#events)

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

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

# Aptos Standards

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

[Section titled “Move Standards”](#move-standards)

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

[Section titled “Aptos Object”](#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

[Section titled “Asset Standards”](#asset-standards)

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

[Section titled “Digital Asset (DA)”](#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)

[Section titled “Fungible Asset (FA)”](#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

[Section titled “Legacy Standards”](#legacy-standards)

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

[Section titled “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)

[Section titled “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)

## Overview of NFT

[Section titled “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

[Section titled “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

[Section titled “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

[Section titled “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

[Section titled “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

[Section titled “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

[Section titled “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

[Section titled “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.

```json
{
  "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.

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

## Token data model

[Section titled “Token data model”](#token-data-model)

The [following diagram](/docs/aptos-token-standard-flow.svg) 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

[Section titled “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

[Section titled “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

[Section titled “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

[Section titled “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

[Section titled “Token lifecycle”](#token-lifecycle)

### Token creation

[Section titled “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

[Section titled “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

[Section titled “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

[Section titled “Token transfer”](#token-transfer)

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

#### Two-step transfer

[Section titled “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

[Section titled “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

[Section titled “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)

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

[Section titled “Overview”](#overview)

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

## Primitive Types

[Section titled “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)

[Section titled “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

```move
  #[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);
    }
  }
  ```

* Rust

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

// Deserialize
  let val_des = bcs::from_bytes::<bool>(&bytes).unwrap();
  assert_eq!(val_des, true);
  ```

* TypeScript

```typescript
  import { Serializer, Deserializer } from "@aptos-labs/ts-sdk";

// Serialize
  const ser = new Serializer();
  ser.serializeBool(true);
  const bytes = ser.toUint8Array();
  console.log(bytes == Uint8Array.from([1]));

// Deserialize
  const des = new Deserializer(bytes);
  const val = des.deserializeBool();
  console.log(val == true);
  ```

* Go

```go
  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)

[Section titled “U8 (unsigned 8-bit integer)”](#u8-unsigned-8-bit-integer)

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

* Move

```move
  #[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);
    }
  }
  ```

* Rust

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

// Deserialize
  let val_des = bcs::from_bytes::<u8>(&bytes).unwrap();
  assert_eq!(val_des, 1);
  ```

* TypeScript

```typescript
  import { Serializer, Deserializer } from "@aptos-labs/ts-sdk";

// Serialize
  const ser = new Serializer();
  ser.serializeU8(1);
  const bytes = ser.toUint8Array();
  console.log(bytes == Uint8Array.from([1]));

// Deserialize
  const des = new Deserializer(bytes);
  const val = des.deserializeU8();
  console.log(val == 1);
  ```

* Go

```go
  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)

[Section titled “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

```move
  #[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);
   }
  }
  ```

* Rust

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

// Deserialize
  let val_des = bcs::from_bytes::<u16>(&bytes).unwrap();
  assert_eq!(val_des, 1000);
  ```

* TypeScript

```typescript
  import { Serializer, Deserializer } from "@aptos-labs/ts-sdk";

// Serialize
  const ser = new Serializer();
  ser.serializeU16(1000);
  const bytes = ser.toUint8Array();
  console.log(bytes == Uint8Array.from([0xe8, 0x03]));

// Deserialize
  const des = new Deserializer(bytes);
  const val = des.deserializeU16();
  console.log(val == 1000);
  ```

* Go

```go
  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)

[Section titled “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

```move
  #[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);
    }
  }
  ```

* Rust

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

// Deserialize
  let val_des = bcs::from_bytes::<u32>(&bytes).unwrap();
  assert_eq!(val_des, 1000000000);
  ```

* TypeScript

```typescript
  import { Serializer, Deserializer } from "@aptos-labs/ts-sdk";

// Serialize
  const ser = new Serializer();
  ser.serializeU32(1000000000);
  const bytes = ser.toUint8Array();
  console.log(bytes == Uint8Array.from([0x00, 0xca, 0x9a, 0x3b]));

// Deserialize
  const des = new Deserializer(bytes);
  const val = des.deserializeU32();
  console.log(val == 1000000000);
  ```

* Go

```go
  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)

[Section titled “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

```move
  #[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);
    }
  }
  ```

* Rust

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

// Deserialize
  let val_des = bcs::from_bytes::<u64>(&bytes).unwrap();
  assert_eq!(val_des, 10000000000000000);
  ```

* TypeScript

```typescript
  import { Serializer, Deserializer } from "@aptos-labs/ts-sdk";

// Serialize
  const ser = new Serializer();
  ser.serializeU64(10000000000000000n);
  const bytes = ser.toUint8Array();
  console.log(bytes == Uint8Array.from([0x00, 0x40, 0x9c, 0x4f, 0x2c, 0x68, 0x00, 0x00]));

// Deserialize
  const des = new Deserializer(bytes);
  const val = des.deserializeU64();
  console.log(val == 10000000000000000n);
  ```

* Go

```go
  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)

[Section titled “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

```move
  #[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);
    }
  }
  ```

* Rust

```rust
  // Serialize
  let 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]);

// Deserialize
  let val_des = bcs::from_bytes::<u128>(&bytes).unwrap();
  assert_eq!(val_des, 10000000000000000);
  ```

* TypeScript

```typescript
  import { Serializer, Deserializer } from "@aptos-labs/ts-sdk";

// Serialize
  const 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]));

// Deserialize
  const des = new Deserializer(bytes);
  const val = des.deserializeU128();
  console.log(val == 10000000000000000n);
  ```

* Go

```go
  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)

[Section titled “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

```move
  #[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);
    }
  }
  ```

* Rust

```rust
  // Serialize
  let 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]);

// Deserialize
  let val_des = bcs::from_bytes::<U256>(&bytes).unwrap();
  assert_eq!(val_des, U256::from(10000000000000000u64));
  ```

* TypeScript

```typescript
  import { Serializer, Deserializer } from "@aptos-labs/ts-sdk";

// Serialize
  const 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]));

// Deserialize
  const des = new Deserializer(bytes);
  const val = des.deserializeU256();
  console.log(val == 10000000000000000n);
  ```

* Go

```go
  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)

[Section titled “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

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

* Rust

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

* TypeScript

```typescript
  import { Serializer, Deserializer } from "@aptos-labs/ts-sdk";

// Serialize
  const 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]));

// Deserialize
  const des = new Deserializer(bytes2);
  const val = des.deserializeUleb128AsU32();
  console.log(val == 128);
  ```

* Go

```go
  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

[Section titled “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

```move
  #[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]);
    }
  }
  ```

* Rust

```rust
  // Serialize
  let val = vec![1u8, 2u8, 3u8];
  let bytes = bcs::to_bytes(&val).unwrap();
  assert_eq!(bytes, vec![3, 1, 2, 3]);

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

* TypeScript

```typescript
  import { Serializer, Deserializer } from "@aptos-labs/ts-sdk";

// Serialize
  const 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]));

// Deserialize
  const des = new Deserializer(bytes);
  const val = des.deserializeVector((d) => d.deserializeU8());
  console.log(val == [1, 2, 3]);
  ```

* Go

```go
  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

[Section titled “Complex types”](#complex-types)

### String

[Section titled “String”](#string)

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

```rust
// Note that this string has 10 characters but has a byte length of 24
let 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

[Section titled “AccountAddress”](#accountaddress)

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

```plaintext
@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

[Section titled “Struct”](#struct)

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

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

### Option

[Section titled “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.

```rust
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

[Section titled “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.

```rust
#[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

[Section titled “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.

```rust
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

[Section titled “Reference”](#reference)

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

# The Move Book

Welcome to Move, a next generation language for secure, sandboxed, and formally verified programming. It has been used as the smart contract language for several blockchains including Aptos. Move allows developers to write programs that flexibly manage and transfer assets, while providing the security and protections against attacks on those assets. However, Move has been developed with use cases in mind outside a blockchain context as well.

Move takes its cue from [Rust](https://www.rust-lang.org/) by using resource types with move (hence the name) semantics as an explicit representation of digital assets, such as currency.

## Who is Aptos Move Book for?

[Section titled “Who is Aptos Move Book for?”](#who-is-aptos-move-book-for)

Move was designed and created as a secure, verified, yet flexible programming language. The first use of Move is for the implementation of the Diem blockchain, and it is currently being used on Aptos.

This book is suitable for developers with some programming experience and who want to begin understanding the core programming language and see examples of its usage.

## Where Do I Start?

[Section titled “Where Do I Start?”](#where-do-i-start)

Begin with understanding [modules and scripts](/build/smart-contracts/book/modules-and-scripts) and then work through the [Move Tutorial](/build/smart-contracts/book/move-tutorial).

# Abilities

Abilities are a typing feature in Move that control what actions are permissible for values of a given type. This system grants fine-grained control over the “linear” typing behavior of values, as well as if and how values are used in global storage. This is implemented by gating access to certain bytecode instructions so that for a value to be used with the bytecode instruction, it must have the ability required (if one is required at all—not every instruction is gated by an ability).

## The Four Abilities

[Section titled “The Four Abilities”](#the-four-abilities)

The four abilities are:

* [`copy`](#copy)
  * Allows values of types with this ability to be copied.
* [`drop`](#drop)
  * Allows values of types with this ability to be popped/dropped.
* [`store`](#store)
  * Allows values of types with this ability to exist inside a struct in global storage.
* [`key`](#key)
  * Allows the type to serve as a key for global storage operations.

### `copy`

[Section titled “copy”](#copy)

The `copy` ability allows values of types with that ability to be copied. It gates the ability to copy values out of local variables with the [`copy`](/build/smart-contracts/book/variables#move-and-copy) operator and to copy values via references with [dereference `*e`](/build/smart-contracts/book/references#reading-and-writing-through-references).

If a value has `copy`, all values contained inside of that value have `copy`.

### `drop`

[Section titled “drop”](#drop)

The `drop` ability allows values of types with that ability to be dropped. By dropped, we mean that value is not transferred and is effectively destroyed as the Move program executes. As such, this ability gates the ability to ignore values in a multitude of locations, including:

* not using the value in a local variable or parameter
* not using the value in a [sequence via `;`](/build/smart-contracts/book/variables#expression-blocks)
* overwriting values in variables in [assignments](/build/smart-contracts/book/variables#assignments)
* overwriting values via references when [writing `*e1 = e2`](/build/smart-contracts/book/references#reading-and-writing-through-references).

If a value has `drop`, all values contained inside of that value have `drop`.

### `store`

[Section titled “store”](#store)

The `store` ability allows values of types with this ability to exist inside a struct (resource) in global storage, *but* not necessarily as a top-level resource in global storage. This is the only ability that does not directly gate an operation. Instead, it gates the existence in global storage when used in tandem with `key`.

If a value has `store`, all values contained inside of that value have `store`

### `key`

[Section titled “key”](#key)

The `key` ability allows the type to serve as a key for [global storage operations](/build/smart-contracts/book/global-storage-operators). It gates all global storage operations, so in order for a type to be used with `move_to`, `borrow_global`, `move_from`, etc., the type must have the `key` ability. Note that the operations still must be used in the module where the `key` type is defined (in a sense, the operations are private to the defining module).

If a value has `key`, all values contained inside of that value have `store`. This is the only ability with this sort of asymmetry.

## Builtin Types

[Section titled “Builtin Types”](#builtin-types)

Most primitive, builtin types have `copy`, `drop`, and `store` except for `signer`, which just has `drop`

* `bool`, `u8`, `u16`, `u32`, `u64`, `u128`, `u256`, and `address` all have `copy`, `drop`, and `store`.

* `signer` has `drop`
  * Cannot be copied and cannot be put into global storage

* `vector<T>` may have `copy`, `drop`, and `store` depending on the abilities of `T`.
  * See [Conditional Abilities and Generic Types](#conditional-abilities-and-generic-types) for more details.

* Immutable references `&` and mutable references `&mut` both have `copy` and `drop`.

* This refers to copying and dropping the reference itself, not what they refer to.
  * References cannot appear in global storage, hence they do not have `store`.

None of the primitive types have `key`, meaning none of them can be used directly with the [global storage operations](/build/smart-contracts/book/global-storage-operators).

## Annotating Structs

[Section titled “Annotating Structs”](#annotating-structs)

To declare that a `struct` has an ability, it is declared with `has <ability>` after the struct name but before the fields. For example:

```move
module 0x42::example {
  struct Ignorable has drop { f: u64 }

struct Pair has copy, drop, store { x: u64, y: u64 }
}
```

In this case: `Ignorable` has the `drop` ability. `Pair` has `copy`, `drop`, and `store`.

All of these abilities have strong guarantees over these gated operations. The operation can be performed on the value only if it has that ability; even if the value is deeply nested inside some other collection!

As such: when declaring a struct’s abilities, certain requirements are placed on the fields. All fields must satisfy these constraints. These rules are necessary so that structs satisfy the reachability rules for the abilities given above. If a struct is declared with the ability…

* `copy`, all fields must have `copy`.
* `drop`, all fields must have `drop`.
* `store`, all fields must have `store`.
* `key`, all fields must have `store`.
  * `key` is the only ability currently that doesn’t require itself.

For example:

```move
module 0x42::example {
  // A struct without any abilities
  struct NoAbilities {}

struct WantsCopy has copy {
    f: NoAbilities, // ERROR 'NoAbilities' does not have 'copy'
  }
}
```

and similarly:

```move
module 0x42::example {
  // A struct without any abilities
  struct NoAbilities {}

struct MyResource has key {
    f: NoAbilities, // Error 'NoAbilities' does not have 'store'
  }
}
```

## Conditional Abilities and Generic Types

[Section titled “Conditional Abilities and Generic Types”](#conditional-abilities-and-generic-types)

When abilities are annotated on a generic type, not all instances of that type are guaranteed to have that ability. Consider this struct declaration:

```move
module 0x42::example {
  struct Cup<T> has copy, drop, store, key { item: T }
}
```

It might be very helpful if `Cup` could hold any type, regardless of its abilities. The type system can *see* the type parameter, so it should be able to remove abilities from `Cup` if it *sees* a type parameter that would violate the guarantees for that ability.

This behavior might sound a bit confusing at first, but it might be more understandable if we think about collection types. We could consider the builtin type `vector` to have the following type declaration:

```move
vector<T> has copy, drop, store;
```

We want `vector`s to work with any type. We don’t want separate `vector` types for different abilities. So what are the rules we would want? Precisely the same that we would want with the field rules above. So, it would be safe to copy a `vector` value only if the inner elements can be copied. It would be safe to ignore a `vector` value only if the inner elements can be ignored/dropped. And, it would be safe to put a `vector` in global storage only if the inner elements can be in global storage.

To have this extra expressiveness, a type might not have all the abilities it was declared with depending on the instantiation of that type; instead, the abilities a type will have depends on both its declaration **and** its type arguments. For any type, type parameters are pessimistically assumed to be used inside the struct, so the abilities are only granted if the type parameters meet the requirements described above for fields. Taking `Cup` from above as an example:

* `Cup` has the ability `copy` only if `T` has `copy`.
* It has `drop` only if `T` has `drop`.
* It has `store` only if `T` has `store`.
* It has `key` only if `T` has `store`.

Here are examples for this conditional system for each ability:

### Example: conditional `copy`

[Section titled “Example: conditional copy”](#example-conditional-copy)

```move
module 0x42::example {
  struct NoAbilities {}

struct S has copy, drop { f: bool }

struct Cup<T> has copy, drop, store { item: T }

fun example(c_x: Cup<u64>, c_s: Cup<S>) {
    // Valid, 'Cup<u64>' has 'copy' because 'u64' has 'copy'
    let c_x2 = copy c_x;
    // Valid, 'Cup<S>' has 'copy' because 'S' has 'copy'
    let c_s2 = copy c_s;
  }

fun invalid(c_account: Cup<signer>, c_n: Cup<NoAbilities>) {
    // Invalid, 'Cup<signer>' does not have 'copy'.
    // Even though 'Cup' was declared with copy, the instance does not have 'copy'
    // because 'signer' does not have 'copy'
    let c_account2 = copy c_account;
    // Invalid, 'Cup<NoAbilities>' does not have 'copy'
    // because 'NoAbilities' does not have 'copy'
    let c_n2 = copy c_n;
  }
}
```

### Example: conditional `drop`

[Section titled “Example: conditional drop”](#example-conditional-drop)

```move
module 0x42::example {
  struct NoAbilities {}

struct S has copy, drop { f: bool }

struct Cup<T> has copy, drop, store { item: T }

fun unused() {
    Cup<bool> { item: true }; // Valid, 'Cup<bool>' has 'drop'
    Cup<S> { item: S { f: false } }; // Valid, 'Cup<S>' has 'drop'
  }

fun left_in_local(c_account: Cup<signer>): u64 {
    let c_b = Cup<bool> { item: true };
    let c_s = Cup<S> { item: S { f: false } };
    // Valid return: 'c_account', 'c_b', and 'c_s' have values
    // but 'Cup<signer>', 'Cup<bool>', and 'Cup<S>' have 'drop'
    0
  }

fun invalid_unused() {
    // Invalid, Cannot ignore 'Cup<NoAbilities>' because it does not have 'drop'.
    // Even though 'Cup' was declared with 'drop', the instance does not have 'drop'
    // because 'NoAbilities' does not have 'drop'
    Cup<NoAbilities> { item: NoAbilities {} };
  }

fun invalid_left_in_local(): u64 {
    let c_n = Cup<NoAbilities> { item: NoAbilities {} };
    // Invalid return: 'c_n' has a value
    // and 'Cup<NoAbilities>' does not have 'drop'
    0
  }
}
```

### Example: conditional `store`

[Section titled “Example: conditional store”](#example-conditional-store)

```move
module 0x42::example {
  struct Cup<T> has copy, drop, store { item: T }

// 'MyInnerResource' is declared with 'store' so all fields need 'store'
  struct MyInnerResource has store {
    yes: Cup<u64>,
    // Valid, 'Cup<u64>' has 'store'
    // no: Cup<signer>, Invalid, 'Cup<signer>' does not have 'store'
  }

// 'MyResource' is declared with 'key' so all fields need 'store'
  struct MyResource has key {
    yes: Cup<u64>,
    // Valid, 'Cup<u64>' has 'store'
    inner: Cup<MyInnerResource>,
    // Valid, 'Cup<MyInnerResource>' has 'store'
    // no: Cup<signer>, Invalid, 'Cup<signer>' does not have 'store'
  }
}
```

### Example: conditional `key`

[Section titled “Example: conditional key”](#example-conditional-key)

```move
module 0x42::example {
  struct NoAbilities {}

struct MyResource<T> has key { f: T }

fun valid(account: &signer) acquires MyResource {
    let addr = signer::address_of(account);
    // Valid, 'MyResource<u64>' has 'key'
    let has_resource = exists<MyResource<u64>>(addr);
    if (!has_resource) {
      // Valid, 'MyResource<u64>' has 'key'
      move_to(account, MyResource<u64> { f: 0 })
    };
    // Valid, 'MyResource<u64>' has 'key'
    let r = borrow_global_mut<MyResource<u64>>(addr)
    r.f = r.f + 1;
  }

fun invalid(account: &signer) {
    // Invalid, 'MyResource<NoAbilities>' does not have 'key'
    let has_it = exists<MyResource<NoAbilities>>(addr);
    // Invalid, 'MyResource<NoAbilities>' does not have 'key'
    let NoAbilities {} = move_from<NoAbilities>(addr);
    // Invalid, 'MyResource<NoAbilities>' does not have 'key'
    move_to(account, NoAbilities {});
    // Invalid, 'MyResource<NoAbilities>' does not have 'key'
    borrow_global<NoAbilities>(addr);
  }
}
```

# Abort and Assert

[`return`](/build/smart-contracts/book/functions) and `abort` are two control flow constructs that end execution, one for the current function and one for the entire transaction.

More information on [`return` can be found in the linked section](/build/smart-contracts/book/functions)

## `abort`

[Section titled “abort”](#abort)

`abort` is an expression that takes one argument: an **abort code** of type `u64`. For example:

```move
abort 42
```

The `abort` expression halts execution of the current function and reverts all changes made to global state by the current transaction. There is no mechanism for “catching” or otherwise handling an `abort`.

Luckily, in Move transactions are all or nothing, meaning any changes to global storage are made all at once only if the transaction succeeds. Because of this transactional commitment of changes, after an abort there is no need to worry about backing out changes. While this approach is lacking in flexibility, it is incredibly simple and predictable.

Similar to [`return`](/build/smart-contracts/book/functions), `abort` is useful for exiting control flow when some condition cannot be met.

In this example, the function will pop two items off of the vector, but will abort early if the vector does not have two items

```move
script {
  use std::vector;
  fun pop_twice<T>(v: &mut vector<T>): (T, T) {
      if (vector::length(v) < 2) abort 42;

(vector::pop_back(v), vector::pop_back(v))
  }
}
```

This is even more useful deep inside a control-flow construct. For example, this function checks that all numbers in the vector are less than the specified `bound`. And aborts otherwise

```move
script {
  use std::vector;
  fun check_vec(v: &vector<u64>, bound: u64) {
      let i = 0;
      let n = vector::length(v);
      while (i < n) {
          let cur = *vector::borrow(v, i);
          if (cur > bound) abort 42;
          i = i + 1;
      }
  }
}
```

### `assert`

[Section titled “assert”](#assert)

`assert` is a builtin, macro-like operation provided by the Move compiler. It takes two arguments, a condition of type `bool` and a code of type `u64`

```move
assert!(condition: bool, code: u64)
assert!(condition: bool) // Since Move 2.0
```

Since the operation is a macro, it must be invoked with the `!`. This is to convey that the arguments to `assert` are call-by-expression. In other words, `assert` is not a normal function and does not exist at the bytecode level. It is replaced inside the compiler with

```move
if (condition) () else abort code
```

Since Move 2.0, `assert` without an error code is supported. If this assert is used, the abort code `0xCA26CBD9BE0B0000` is generated. In terms of the `std::error` convention, this code has category `std::error::INTERNAL` and reason `0`.

`assert` is more commonly used than just `abort` by itself. The `abort` examples above can be rewritten using `assert`

```move
script {
  use std::vector;
  fun pop_twice<T>(v: &mut vector<T>): (T, T) {
      assert!(vector::length(v) >= 2, 42); // Now uses 'assert'

(vector::pop_back(v), vector::pop_back(v))
  }
}
```

and

```move
script {
  use std::vector;
  fun check_vec(v: &vector<u64>, bound: u64) {
      let i = 0;
      let n = vector::length(v);
      while (i < n) {
          let cur = *vector::borrow(v, i);
          assert!(cur <= bound, 42); // Now uses 'assert'
          i = i + 1;
      }
  }
}
```

Note that because the operation is replaced with this `if-else`, the argument for the `code` is not always evaluated. For example:

```move
assert!(true, 1 / 0)
```

Will not result in an arithmetic error, it is equivalent to

```move
if (true) () else (1 / 0)
```

So the arithmetic expression is never evaluated!

### Abort codes in the Move VM

[Section titled “Abort codes in the Move VM”](#abort-codes-in-the-move-vm)

When using `abort`, it is important to understand how the `u64` code will be used by the VM.

Normally, after successful execution, the Move VM produces a change-set for the changes made to global storage (added/removed resources, updates to existing resources, etc.).

If an `abort` is reached, the VM will instead indicate an error. Included in that error will be two pieces of information:

* The module that produced the abort (address and name)
* The abort code.

For example

```move
module 0x42::example {
  public fun aborts() {
    abort 42
  }
}

script {
  fun always_aborts() {
    0x2::example::aborts()
  }
}
```

If a transaction, such as the script `always_aborts` above, calls `0x2::example::aborts`, the VM would produce an error that indicated the module `0x2::example` and the code `42`.

This can be useful for having multiple aborts being grouped together inside a module.

In this example, the module has two separate error codes used in multiple functions

```move
module 0x42::example {

use std::vector;

const EMPTY_VECTOR: u64 = 0;
  const INDEX_OUT_OF_BOUNDS: u64 = 1;

// move i to j, move j to k, move k to i
  public fun rotate_three<T>(v: &mut vector<T>, i: u64, j: u64, k: u64) {
    let n = vector::length(v);
    assert!(n > 0, EMPTY_VECTOR);
    assert!(i < n, INDEX_OUT_OF_BOUNDS);
    assert!(j < n, INDEX_OUT_OF_BOUNDS);
    assert!(k < n, INDEX_OUT_OF_BOUNDS);

vector::swap(v, i, k);
    vector::swap(v, j, k);
  }

public fun remove_twice<T>(v: &mut vector<T>, i: u64, j: u64): (T, T) {
    let n = vector::length(v);
    assert!(n > 0, EMPTY_VECTOR);
    assert!(i < n, INDEX_OUT_OF_BOUNDS);
    assert!(j < n, INDEX_OUT_OF_BOUNDS);
    assert!(i > j, INDEX_OUT_OF_BOUNDS);

(vector::remove<T>(v, i), vector::remove<T>(v, j))
  }
}
```

## The type of `abort`

[Section titled “The type of abort”](#the-type-of-abort)

The `abort i` expression can have any type! This is because both constructs break from the normal control flow, so they never need to evaluate to the value of that type.

The following are not useful, but they will type check

```move
let y: address = abort 0;
```

This behavior can be helpful in situations where you have a branching instruction that produces a value on some branches, but not all. For example:

```move
script {
  fun example() {
    let b =
        if (x == 0) false
        else if (x == 1) true
        else abort 42;
    //       ^^^^^^^^ `abort 42` has type `bool`
  }
}
```

# Address

`address` is a built-in type in Move that is used to represent locations (sometimes called accounts) in global storage. An `address` value is a 256-bit (32-byte) identifier. At a given address, two things can be stored: [Modules](/build/smart-contracts/book/modules-and-scripts) and [Resources](/build/smart-contracts/book/structs-and-resources).

Although an `address` is a 256-bit integer under the hood, Move addresses are intentionally opaque---they cannot be created from integers, they do not support arithmetic operations, and they cannot be modified. Even though there might be interesting programs that would use such a feature (e.g., pointer arithmetic in C fills a similar niche), Move does not allow this dynamic behavior because it has been designed from the ground up to support static verification.

You can use runtime address values (values of type `address`) to access resources at that address. You *cannot* access modules at runtime via address values.

## Addresses and Their Syntax

[Section titled “Addresses and Their Syntax”](#addresses-and-their-syntax)

Addresses come in two flavors, named or numerical. The syntax for a named address follows the same rules for any named identifier in Move. The syntax of a numerical address is not restricted to hex-encoded values, and any valid [`u256` numerical value](/build/smart-contracts/book/integers) can be used as an address value, e.g., `42`, `0xCAFE`, and `2021` are all valid numerical address literals.

To distinguish when an address is being used in an expression context or not, the syntax when using an address differs depending on the context where it’s used:

* When an address is used as an expression the address must be prefixed by the `@` character, i.e., [`@<numerical_value>`](/build/smart-contracts/book/integers) or `@<named_address_identifier>`.
* Outside of expression contexts, the address may be written without the leading `@` character, i.e., [`<numerical_value>`](/build/smart-contracts/book/integers) or `<named_address_identifier>`.

In general, you can think of `@` as an operator that takes an address from being a namespace item to being an expression item.

## Named Addresses

[Section titled “Named Addresses”](#named-addresses)

Named addresses are a feature that allow identifiers to be used in place of numerical values in any spot where addresses are used, and not just at the value level. Named addresses are declared and bound as top level elements (outside of modules and scripts) in Move Packages, or passed as arguments to the Move compiler.

Named addresses only exist at the source language level and will be fully substituted for their value at the bytecode level. Because of this, modules and module members *must* be accessed through the module’s named address and not through the numerical value assigned to the named address during compilation, e.g., `use my_addr::foo` is *not* equivalent to `use 0x2::foo` even if the Move program is compiled with `my_addr` set to `0x2`. This distinction is discussed in more detail in the section on [Modules and Scripts](/build/smart-contracts/book/modules-and-scripts).

### Examples

[Section titled “Examples”](#examples)

```move
script {
  fun example() {
    let a1: address = @0x1; // shorthand for 0x0000000000000000000000000000000000000000000000000000000000000001
    let a2: address = @0x42; // shorthand for 0x0000000000000000000000000000000000000000000000000000000000000042
    let a3: address = @0xDEADBEEF; // shorthand for 0x00000000000000000000000000000000000000000000000000000000DEADBEEF
    let a4: address = @0x000000000000000000000000000000000000000000000000000000000000000A;
    let a5: address = @std; // Assigns `a5` the value of the named address `std`
    let a6: address = @66;
    let a7: address = @0x42;
  }
}

module 66::some_module {   // Not in expression context, so no @ needed
    use 0x1::other_module; // Not in expression context so no @ needed
    use std::vector;       // Can use a named address as a namespace item when using other modules
    ...
}

module std::other_module {  // Can use a named address as a namespace item to declare a module
    ...
}
```

## Global Storage Operations

[Section titled “Global Storage Operations”](#global-storage-operations)

The primary purpose of `address` values are to interact with the global storage operations.

`address` values are used with the `exists`, `borrow_global`, `borrow_global_mut`, and `move_from` [operations](/build/smart-contracts/book/global-storage-operators).

The only global storage operation that *does not* use `address` is `move_to`, which uses [`signer`](/build/smart-contracts/book/signer).

## Ownership

[Section titled “Ownership”](#ownership)

As with the other scalar values built-in to the language, `address` values are implicitly copyable, meaning they can be copied without an explicit instruction such as [`copy`](/build/smart-contracts/book/variables#move-and-copy).

# Bool

`bool` is Move’s primitive type for boolean `true` and `false` values.

## Literals

[Section titled “Literals”](#literals)

Literals for `bool` are either `true` or `false`.

## Operations

[Section titled “Operations”](#operations)

### Logical

[Section titled “Logical”](#logical)

`bool` supports three logical operations:

| Syntax | Description                  | Equivalent Expression                            |
| ------ | ---------------------------- | ------------------------------------------------ |
| `&&`   | short-circuiting logical and | `p && q` is equivalent to `if (p) q else false`  |
| `\|\|` | short-circuiting logical or  | `p \|\| q` is equivalent to `if (p) true else q` |
| `!`    | logical negation             | `!p` is equivalent to `if (p) false else true`   |

### Control Flow

[Section titled “Control Flow”](#control-flow)

`bool` values are used in several of Move’s control-flow constructs:

* [`if (bool) { ... }`](/build/smart-contracts/book/conditionals)
* [`while (bool) { .. }`](/build/smart-contracts/book/loops)
* [`assert!(bool, u64)`](/build/smart-contracts/book/abort-and-assert)

## Ownership

[Section titled “Ownership”](#ownership)

As with the other scalar values built into the language, boolean values are implicitly copyable, meaning they can be copied without an explicit instruction such as [`copy`](/build/smart-contracts/book/variables#move-and-copy).

# Move Coding Conventions

This section lays out some basic coding conventions for Move that the Move team has found helpful. These are only recommendations, and you should feel free to use other formatting guidelines and conventions if you have a preference for them.

## Naming

[Section titled “Naming”](#naming)

* **Module names**: should be lowercase snake case, e.g., `fixed_point32`, `vector`.
* **Type names**: should be camel case if they are not a native type, e.g., `Coin`, `RoleId`.
* **Function names**: should be lowercase snake case, e.g., `destroy_empty`.
* **Constant names**: should be upper camel case and begin with an `E` if they represent error codes (e.g., `EIndexOutOfBounds`) and upper snake case if they represent a non-error value (e.g., `MIN_STAKE`).
*
* **Generic type names**: should be descriptive, or anti-descriptive where appropriate, e.g., `T` or `Element` for the Vector generic type parameter. Most of the time the “main” type in a module should be the same name as the module e.g., `option::Option`, `fixed_point32::FixedPoint32`.
* **Module file names**: should be the same as the module name e.g., `option.move`.
* **Script file names**: should be lowercase snake case and should match the name of the “main” function in the script.
* **Mixed file names**: If the file contains multiple modules and/or scripts, the file name should be lowercase snake case, where the name does not match any particular module/script inside.

## Imports

[Section titled “Imports”](#imports)

* All module `use` statements should be at the top of the module.
* Functions should be imported and used fully qualified from the module in which they are declared, and not imported at the top level.
* Types should be imported at the top-level. Where there are name clashes, `as` should be used to rename the type locally as appropriate.

For example, if there is a module:

```move
module 0x1::foo {
  struct Foo { }
  const CONST_FOO: u64 = 0;
  public fun do_foo(): Foo { Foo{} }
  // ...
}
```

this would be imported and used as:

```move
module 0x1::bar {
  use 0x1::foo::{Self, Foo};

public fun do_bar(x: u64): Foo {
    if (x == 10) {
      foo::do_foo()
    } else {
      abort 0
    }
  }
  // ...
}
```

And, if there is a local name-clash when importing two modules:

```move
module 0x1::other_foo {
  struct Foo {}
  // ...
}

module 0x1::importer {
  use 0x1::other_foo::Foo as OtherFoo;
  use 0x1::foo::Foo;
  // ...
}
```

## Comments

[Section titled “Comments”](#comments)

* Each module, struct, and public function declaration should be commented.
* Move has doc comments `///`, regular single-line comments `//`, block comments `/* */`, and block doc comments `/** */`.
* Starting Aptos CLI 7.4.0, UTF-8 characters are allowed in comments.

### Comments Example

[Section titled “Comments Example”](#comments-example)

Doc comments must be directly above the item they are commenting on. For example, the following is valid:

```move
/// My awesome module, doc comment can be used here
module 0x42::example { // double slash can be anywhere

// Double slash can be anywhere

/// My awesome constant
  const MY_VALUE: u64 = 5;

/// My awesome error message
  const E_MY_ERROR: u64 = 10;

#[view]
  /// My awesome view function
  fun show_me_the_money() {
    // ...
  }

/* Similarly block comments can be anywhere */
}
```

Below here are examples of doc comments `///` that will fail

```move
module 0x42::example {

/// My awesome view function <- must be below the annotation, right above the thing commented
  #[view]
  fun show_me_the_money() {
    // ...
    /// Within a function
  }

/// Not attached to anything
}
```

## Formatting

[Section titled “Formatting”](#formatting)

The Move team plans to write an auto-formatter to enforce formatting conventions. However, in the meantime:

* Four space indentation should be used except for `script` and `address` blocks whose contents should not be indented.
* Lines should be broken if they are longer than 100 characters.
* Structs and constants should be declared before all functions in a module.

# Conditionals

An `if` expression specifies that some code should only be evaluated if a certain condition is true. For example:

```move
script {
  fun example() {
    if (x > 5) x = x - 5
  }
}
```

The condition must be an expression of type `bool`.

An `if` expression can optionally include an `else` clause to specify another expression to evaluate when the condition is false.

```move
script {
  fun example() {
    if (y <= 10) y = y + 1 else y = 10
  }
}
```

Either the “true” branch or the “false” branch will be evaluated, but not both. Either branch can be a single expression or an expression block.

The conditional expressions may produce values so that the `if` expression has a result.

```move
script {
  fun example() {
    let z = if (x < 100) x else 100;
  }
}
```

The expressions in the true and false branches must have compatible types. For example:

```move
script {
  fun example() {
    // x and y must be u64 integers
    let maximum: u64 = if (x > y) x else y;

// ERROR! branches different types
    let z = if (maximum < 10) 10u8 else 100u64;

// ERROR! branches different types, as default false-branch is () not u64
    if (maximum >= 10) maximum;
  }
}
```

If the `else` clause is not specified, the false branch defaults to the unit value. The following are equivalent:

```move
script {
  fun example() {
    if (condition) true_branch // implied default: else ()
    if (condition) true_branch else ()
  }
}
```

Commonly, [`if` expressions](/build/smart-contracts/book/conditionals) are used in conjunction with expression blocks.

```move
script {
  fun example() {
    let maximum = if (x > y) x else y;
    if (maximum < 10) {
        x = x + 10;
        y = y + 10;
    } else if (x >= 10 && y >= 10) {
        x = x - 10;
        y = y - 10;
    }
  }
}
```

## Grammar for Conditionals

[Section titled “Grammar for Conditionals”](#grammar-for-conditionals)

> *if-expression* → **if (** *expression* **)** *expression* *else-clause**opt*

> *else-clause* → **else** *expression*

# Constants

Constants are a way of giving a name to shared, static values inside of a `module` or `script`.

The constant’s must be known at compilation. The constant’s value is stored in the compiled module or script. And each time the constant is used, a new copy of that value is made.

## Declaration

[Section titled “Declaration”](#declaration)

Constant declarations begin with the `const` keyword, followed by a name, a type, and a value. They can exist in either a script or module

```text
const <name>: <type> = <expression>;
```

For example

```move
script {
  const MY_ERROR_CODE: u64 = 0;

fun main(input: u64) {
    assert!(input > 0, MY_ERROR_CODE);
  }
}

module 0x42::example {
  const MY_ADDRESS: address = @0x42;

public fun permissioned(s: &signer) {
    assert!(std::signer::address_of(s) == MY_ADDRESS, 0);
  }
}
```

## Naming

[Section titled “Naming”](#naming)

Constants must start with a capital letter `A` to `Z`. After the first letter, constant names can contain underscores `_`, letters `a` to `z`, letters `A` to `Z`, or digits `0` to `9`.

```move
script {
  const FLAG: bool = false;
  const MY_ERROR_CODE: u64 = 0;
  const ADDRESS_42: address = @0x42;
}
```

Even though you can use letters `a` to `z` in a constant. The [general style guidelines](/build/smart-contracts/book/coding-conventions) are to use just uppercase letters `A` to `Z`, with underscores `_` between each word.

This naming restriction of starting with `A` to `Z` is in place to give room for future language features. It may or may not be removed later.

## Visibility

[Section titled “Visibility”](#visibility)

`public` constants are not currently supported. `const` values can be used only in the declaring module.

## Valid Expressions

[Section titled “Valid Expressions”](#valid-expressions)

Currently, constants are limited to the primitive types `bool`, `u8`, `u16`, `u32`, `u64`, `u128`, `u256`, `address`, and `vector<u8>`. Future support for other `vector` values (besides the “string”-style literals) will come later.

### Values

[Section titled “Values”](#values)

Commonly, `const`s are assigned a simple value, or literal, of their type. For example

```move
script {
  const MY_BOOL: bool = false;
  const MY_ADDRESS: address = @0x70DD;
  const BYTES: vector<u8> = b"hello world";
  const HEX_BYTES: vector<u8> = x"DEADBEEF";
}
```

### Complex Expressions

[Section titled “Complex Expressions”](#complex-expressions)

In addition to literals, constants can include more complex expressions, as long as the compiler is able to reduce the expression to a value at compile time.

Currently, equality operations, all boolean operations, all bitwise operations, and all arithmetic operations can be used.

```move
script {
  const RULE: bool = true && false;
  const CAP: u64 = 10 * 100 + 1;
  const SHIFTY: u8 = {
    (1 << 1) * (1 << 2) * (1 << 3) * (1 << 4)
  };
  const HALF_MAX: u128 = 340282366920938463463374607431768211455 / 2;
  const REM: u256 = 57896044618658097711785492504343953926634992332820282019728792003956564819968 % 654321;
  const EQUAL: bool = 1 == 1;
}
```

If the operation results in a runtime exception, the compiler will give an error that it is unable to generate the constant’s value

```move
script {
  const DIV_BY_ZERO: u64 = 1 / 0; // error!
  const SHIFT_BY_A_LOT: u64 = 1 << 100; // error!
  const NEGATIVE_U64: u64 = 0 - 1; // error!
}
```

Note that constants cannot currently refer to other constants. This feature, along with support for other expressions, will be added in the future.

# Enums

*Since language version 2.0*

Enum types are similar to struct types but support defining multiple *variants* of the data layout. Each variant has its distinct set of fields. Enum variants are supported in expressions, tools for testing, matching, and deconstructing.

## Declaration of Enum Types

[Section titled “Declaration of Enum Types”](#declaration-of-enum-types)

An enum type declaration lists the number of different variants, as seen in the example below:

```move
enum Shape {
    Circle{radius: u64},
    Rectangle{width: u64, height: u64}
}
```

There can be zero or more fields for an enum variant. If no arguments are given, the braces can also be omitted, declaring simple values:

```move
enum Color {
  Red, Blue, Green
}
```

Like struct types, enum types can have abilities. For example, the `Color` enum type would be appropriately declared as copyable, droppable, and storable, like primitive number types:

```move
enum Color has copy, drop, store, key { Red, Blue, Green }
```

Enum types can also have the `key` ability and appear as roots of data in global storage. A common usage of enums in this context is versioning of data:

```move
enum VersionedData has key {
  V1{name: String}
  V2{name: String, age: u64}
}
```

Similar to structs, enum types can be generic and take positional arguments. For example, the type below represents a generic result type, where the variant constructors use positional instead of named arguments (see also [positional structs](/build/smart-contracts/book/structs-and-resources#positional-structs)).

```move
enum Result<T> has copy, drop, store {
  Err(u64),
  Ok(T)
}
```

## Constructing Enum Values

[Section titled “Constructing Enum Values”](#constructing-enum-values)

An enum value is constructed similarly to a struct value:

```move
let s: String;
let data = VersionedData::V1{name: s};
```

If the enum variant has no fields, the braces can also be omitted:

```move
let color = Color::Blue;
```

## Name Resolution for Enum Variants

[Section titled “Name Resolution for Enum Variants”](#name-resolution-for-enum-variants)

The variant names for an enum need to be qualified by the enum type name, as in `VersionedData::V1`.

> Note: Aliasing via the `use` clause is currently not supported for enum variants, but will be added in later language versions

In certain cases (such as match expressions, below), the Move compiler can infer the enum type from the context, and the qualification by the type name may be omitted:

```move
fun f(data: VersionedData) {
  match (data) { V1{..} => .., ..} // simple variant name OK
}
```

## Matching Enum Values

[Section titled “Matching Enum Values”](#matching-enum-values)

The value of an enum value can be inspected using a match expression. For example:

```move
fun area(self: &Shape): u64 {
    match (self) {
        Circle{radius}           => mul_with_pi(*radius * *radius),
        Rectangle{width, height} => *width * *height
    }
}
```

Notice above that the value matched is an immutable reference to an enum value. A match expression can also consume a value, or match over a mutable reference for interior updates:

```move
fun scale_radius(self: &mut Shape, factor:  u64) {
    match (self) {
        Circle{radius: r} => *r = *r * factor,
        _                 => {} // do nothing if not a Circle
  }
}
```

The patterns provided in the match expression are evaluated sequentially, in order of textual occurrence, until a match is found. It is a compile time error if not all known patterns are covered.

Patterns can be nested and contain conditions, as in the following example:

```move
let r : Result<Result<u64>> = Ok(Err(42));
let v = match (r) {
  Ok(Err(c)) if c < 42  => 0,
  Ok(Err(c)) if c >= 42 => 1,
  Ok(_)                 => 2,
  _                     => 3
};
assert!(v == 1);
```

Notice that in the above example, the last match clause (`_`) covers both patterns `Ok(Err(_))` and `Err(_)`. Although at execution time, the earlier clauses match `Ok(Err(c))` for all values of `c`, the compiler cannot be sure all cases are covered due to the conditionals: conditions in match expressions are not considered when tracking coverage. Thus the first two clauses in the match expression above are not sufficient for match completeness, and an additional clause is required to avoid a compiler error.

## Testing Enum Variants

[Section titled “Testing Enum Variants”](#testing-enum-variants)

With the `is` operator, one can examine whether a given enum value is of a given variant:

```move
let data: VersionedData;
if (data is VersionedData::V1) { .. }
```

The operator allows specifying a list of variants, separated by “`|`” characters. The variants need not be qualified by the enum name if the type of the expression being tested is known:

```move
assert!(data is V1|V2);
```

## Selecting From Enum Values

[Section titled “Selecting From Enum Values”](#selecting-from-enum-values)

It is possible to directly select a field from an enum value. Recall the definition of versioned data:

```move
enum VersionedData has key {
  V1{name: String}
  V2{name: String, age: u64}
}
```

One can write code as below to directly select the fields of variants:

```move
let s: String;
let data1 = VersionedData::V1{name: s};
let data2 = VersionedData::V2{name: s, age: 20};
assert!(data1.name == data2.name)
assert!(data2.age == 20);
```

Notice that field selection aborts if the enum value has no variant with the given field. This is the case for `data1.age`. The abort code used for this case is `0xCA26CBD9BE0B0001`. In terms of the `std::error` convention, this code has category `std::error::INTERNAL` and reason `1`.

Field selection is only possible if the field is uniquely named and typed throughout all variants. Thus, the following yields a compile time error:

```move
enum VersionedData has key {
  V1{name: String}
  V2{name: u64}
}

data.name
 // ^^^^^ compile time error that `name` field selection is ambiguous
```

## Using Enums Patterns in Lets

[Section titled “Using Enums Patterns in Lets”](#using-enums-patterns-in-lets)

An enum variant pattern may be used in a `let` statement:

```move
let data: VersionData;
let V1{name} = data;
```

Unpacking the enum value will abort if the variant is not the expected one. To ensure that all variants of an enum are handled, a `match` expression is recommended instead of a `let`. The `match` is checked at compile time, ensuring that all variants are covered. In some cases, tools like the Move Prover can be used to verify that unexpected aborts cannot happen with a `let`.

## Destroying Enums via Pattern Matching

[Section titled “Destroying Enums via Pattern Matching”](#destroying-enums-via-pattern-matching)

Similar to struct values, enum values can be destroyed by explicitly unpacking them. Enums can be unpacked with pattern matching in a `match` expression, enum pattern in a `let` binding, or enum pattern in an assignment.

```move
// Note: `Shape` has no `drop` ability, so must be destroyed with explicit unpacking.
enum Shape {
    Circle{radius: u64},
    Rectangle{width: u64, height: u64}
}

fun destroy_empty(self: Shape) {
    match (self) {
        Shape::Circle{radius} => assert!(radius == 0),
        Shape::Rectangle{width, height: _} => assert!(width == 0),
    }
}

fun example_destroy_shapes() {
    let c = Shape::Circle{radius: 0};
    let r = Shape::Rectangle{width: 0, height: 0};
    c.destroy_empty();
    r.destroy_empty();
}
```

## Enum Type Upgrade Compatibility

[Section titled “Enum Type Upgrade Compatibility”](#enum-type-upgrade-compatibility)

An enum type can be upgraded by another enum type if the new type only adds new variants at the end of the variant list. All variants present in the old enum type must also appear in the new type, in the same order and starting from the beginning. Consider the `VersionedData` type, which might have begun with a single version:

```move
enum VersionedData has key {
  V1{name: String}
}
```

This type could be upgraded to the version we used so far in this text:

```move
enum VersionedData has key {
  V1{name: String}
  V2{name: String, age: u64}
}
```

The following upgrade would not be allowed, since the order of variants must be preserved:

```move
enum VersionedData has key {
  V2{name: String, age: u64}   // not a compatible upgrade
  V1{name: String}
}
```

# Equality

Move supports two equality operations `==` and `!=`

## Operations

[Section titled “Operations”](#operations)

| Syntax | Operation | Description                                                                 |
| ------ | --------- | --------------------------------------------------------------------------- |
| `==`   | equal     | Returns `true` if the two operands have the same value, `false` otherwise   |
| `!=`   | not equal | Returns `true` if the two operands have different values, `false` otherwise |

### Typing

[Section titled “Typing”](#typing)

Both the equal (`==`) and not-equal (`!=`) operations only work if both operands are the same type

```move
script {
  fun example() {
    0 == 0; // `true`
    1u128 == 2u128; // `false`
    b"hello" != x"00"; // `true`
  }
}
```

Equality and non-equality also work over user defined types!

```move
module 0x42::example {
    struct S has copy, drop { f: u64, s: vector<u8> }

fun always_true(): bool {
        let s = S { f: 0, s: b"" };
        // parens are not needed but added for clarity in this example
        (copy s) == s
    }

fun always_false(): bool {
        let s = S { f: 0, s: b"" };
        // parens are not needed but added for clarity in this example
        (copy s) != s
    }
}
```

If the operands have different types, there is a type checking error

```move
script {
  fun example() {
    1u8 == 1u128; // ERROR!
    //     ^^^^^ expected an argument of type 'u8'
    b"" != 0; // ERROR!
    //     ^ expected an argument of type 'vector<u8>'
  }
}
```

### Typing with references

[Section titled “Typing with references”](#typing-with-references)

When comparing [references](/build/smart-contracts/book/references), the type of the reference (immutable or mutable) does not matter. This means that you can compare an immutable `&` reference with a mutable one `&mut` of the same underlying type.

```move
script {
  fun example() {
    let i = &0;
    let m = &mut 1;

i == m; // `false`
    m == i; // `false`
    m == m; // `true`
    i == i; // `true`
  }
}
```

The above is equivalent to applying an explicit freeze to each mutable reference where needed

```move
script {
  fun example() {
    let i = &0;
    let m = &mut 1;

i == freeze(m); // `false`
    freeze(m) == i; // `false`
    m == m; // `true`
    i == i; // `true`
  }
}
```

But again, the underlying type must be the same type

```move
script {
  fun example() {
    let i = &0;
    let s = &b"";

i == s; // ERROR!
    //   ^ expected an argument of type '&u64'
  }
}
```

## Restrictions

[Section titled “Restrictions”](#restrictions)

Both `==` and `!=` consume the value when comparing them. As a result, the type system enforces that the type must have [`drop`](/build/smart-contracts/book/abilities). Recall that without the [`drop` ability](/build/smart-contracts/book/abilities), ownership must be transferred by the end of the function, and such values can only be explicitly destroyed within their declaring module. If these were used directly with either equality `==` or non-equality `!=`, the value would be destroyed which would break [`drop` ability](/build/smart-contracts/book/abilities) safety guarantees!

```move
module 0x42::example {
  struct Coin has store { value: u64 }
  fun invalid(c1: Coin, c2: Coin) {
    c1 == c2 // ERROR!
//  ^^    ^^ These resources would be destroyed!
  }
}
```

But, a programmer can *always* borrow the value first instead of directly comparing the value, and reference types have the [`drop` ability](/build/smart-contracts/book/abilities). For example

```move
module 0x42::example {
  struct Coin has store { value: u64 }
  fun swap_if_equal(c1: Coin, c2: Coin): (Coin, Coin) {
    let are_equal = &c1 == &c2; // valid
    if (are_equal) (c2, c1) else (c1, c2)
  }
}
```

## Avoid Extra Copies

[Section titled “Avoid Extra Copies”](#avoid-extra-copies)

While a programmer *can* compare any value whose type has [`drop`](/build/smart-contracts/book/abilities), a programmer should often compare by reference to avoid expensive copies.

```move
script {
  fun example() {
    let v1: vector<u8> = function_that_returns_vector();
    let v2: vector<u8> = function_that_returns_vector();
    assert!(copy v1 == copy v2, 42);
    //     ^^^^       ^^^^
    use_two_vectors(v1, v2);

let s1: Foo = function_that_returns_large_struct();
    let s2: Foo = function_that_returns_large_struct();
    assert!(copy s1 == copy s2, 42);
    //     ^^^^       ^^^^
    use_two_foos(s1, s2);
  }
}
```

This code is perfectly acceptable (assuming `Foo` has [`drop`](/build/smart-contracts/book/abilities)), just not efficient. The highlighted copies can be removed and replaced with borrows

```move
script {
  fun example() {
    let v1: vector<u8> = function_that_returns_vector();
    let v2: vector<u8> = function_that_returns_vector();
    assert!(&v1 == &v2, 42);
    //     ^      ^
    use_two_vectors(v1, v2);

let s1: Foo = function_that_returns_large_struct();
    let s2: Foo = function_that_returns_large_struct();
    assert!(&s1 == &s2, 42);
    //     ^      ^
    use_two_foos(s1, s2);
  }
}
```

The efficiency of the `==` itself remains the same, but the `copy`s are removed and thus the program is more efficient.

# Friends

The `friend` syntax is used to declare modules that are trusted by the current module. A trusted module is allowed to call any function defined in the current module that have the `public(friend)` visibility. For details on function visibilities, please refer to the *Visibility* section in [Functions](/build/smart-contracts/book/functions).

## Friend declaration

[Section titled “Friend declaration”](#friend-declaration)

A module can declare other modules as friends via friend declaration statements, in the format of

* `friend <address::name>` — friend declaration using fully qualified module name like the example below, or

```move
  module 0x42::a {
      friend 0x42::b;
  }
  ```

* `friend <module-name-alias>` — friend declaration using a module name alias, where the module alias is introduced via the `use` statement.

```move
  module 0x42::a {
      use 0x42::b;
      friend b;
  }
  ```

A module may have multiple friend declarations, and the union of all the friend modules forms the friend list. In the example below, both `0x42::B` and `0x42::C` are considered as friends of `0x42::A`.

```move
module 0x42::a {
    friend 0x42::b;
    friend 0x42::c;
}
```

Unlike `use` statements, `friend` can only be declared in the module scope and not in the expression block scope. `friend` declarations may be located anywhere a top-level construct (e.g., `use`, `function`, `struct`, etc.) is allowed. However, for readability, it is advised to place friend declarations near the beginning of the module definition.

Note that the concept of friendship does not apply to Move scripts:

* A Move script cannot declare `friend` modules as doing so is considered meaningless: there is no mechanism to call the function defined in a script.
* A Move module cannot declare `friend` scripts as well because scripts are ephemeral code snippets that are never published to global storage.

### Friend declaration rules

[Section titled “Friend declaration rules”](#friend-declaration-rules)

Friend declarations are subject to the following rules:

* A module cannot declare itself as a friend.

```move
  module 0x42::m {
    friend Self; // ERROR!
  //       ^^^^ Cannot declare the module itself as a friend
  }

module 0x43::m {
    friend 0x43::M; // ERROR
  //       ^^^^^^^ Cannot declare the module itself as a friend
  }
  ```

* Friend modules must be known by the compiler

```move
  module 0x42::m {
    friend 0x42::nonexistent; // ERROR!
    //     ^^^^^^^^^^^^^^^^^ Unbound module '0x42::nonexistent'
  }
  ```

* Friend modules must be within the same account address. (Note: this is not a technical requirement but rather a policy decision which *may* be relaxed later.)

```move
  module 0x42::m {}

module 0x43::n {
    friend 0x42::m; // ERROR!
  //       ^^^^^^^ Cannot declare modules out of the current address as a friend
  }
  ```

* Friends relationships cannot create cyclic module dependencies.

Cycles are not allowed in the friend relationships, e.g., the relation `0x2::a` friends `0x2::b` friends `0x2::c` friends `0x2::a` is not allowed. More generally, declaring a friend module adds a dependency upon the current module to the friend module (because the purpose is for the friend to call functions in the current module). If that friend module is already used, either directly or transitively, a cycle of dependencies would be created.

```move
  address 0x2 {
    module a {
      use 0x2::c;
      friend 0x2::b;

public fun a() {
        c::c()
      }
    }

module b {
      friend 0x2::c; // ERROR!
    //       ^^^^^^ This friend relationship creates a dependency cycle: '0x2::b' is a friend of '0x2::a' uses '0x2::c' is a friend of '0x2::b'
    }

module c {
      public fun c() {}
    }
  }
  ```

* The friend list for a module cannot contain duplicates.

```move
  address 0x42 {
    module a {}

module m {
      use 0x42::a as aliased_a;
      friend 0x42::A;
      friend aliased_a; // ERROR!
    //       ^^^^^^^^^ Duplicate friend declaration '0x42::a'. Friend declarations in a module must be unique
    }
  }
  ```

# Functions

Function syntax in Move is shared between module functions and script functions. Functions inside of modules are reusable, whereas script functions are only used once to invoke a transaction.

## Declaration

[Section titled “Declaration”](#declaration)

Functions are declared with the `fun` keyword followed by the function name, type parameters, parameters, a return type, acquires annotations, and finally the function body.

```text
fun <identifier><[type_parameters: constraint],*>([identifier: type],*): <return_type> <acquires [identifier],*> <function_body>
```

For example

```move
fun foo<T1, T2>(x: u64, y: T1, z: T2): (T2, T1, u64) { (z, y, x) }
```

### Visibility

[Section titled “Visibility”](#visibility)

Module functions, by default, can only be called within the same module. These internal (sometimes called private) functions cannot be called from other modules or from scripts.

```move
address 0x42 {
module m {
    fun foo(): u64 { 0 }

fun calls_foo(): u64 { foo() } // valid
}

module other {
    fun calls_m_foo(): u64 {
        0x42::m::foo() // ERROR!
        //       ^^^^^ `foo` is internal to `0x42::m`
    }
}
}

script {
    fun calls_m_foo(): u64 {
        0x42::m::foo() // ERROR!
        //       ^^^^^ `foo` is internal to `0x42::m`
    }
}
```

To allow access from other modules or from scripts, the function must be declared `public` or `public(friend)`.

#### `public` visibility

[Section titled “public visibility”](#public-visibility)

A `public` function can be called by *any* function defined in *any* module or script. As shown in the following example, a `public` function can be called by:

* other functions defined in the same module,
* functions defined in another module, or
* the function defined in a script.

There are also no restrictions for what the argument types a public function can take and its return type.

```move
address 0x42 {
module m {
    public fun foo(): u64 { 0 }

fun calls_foo(): u64 { foo() } // valid
}

module other {
    fun calls_m_foo(): u64 {
        0x42::m::foo() // valid
    }
}
}

script {
    fun calls_m_foo(): u64 {
        0x42::m::foo() // valid
    }
}
```

### `package` visibility

[Section titled “package visibility”](#package-visibility)

*Since Language Version 2.0*

A `package` function can be only called within the same package. The notion of a package is defined by the hosting environment of Move, and not explicit in the language. Typically, the package is defined by a manifest file `Move.toml` which is processed by the build environment.

The following works, provided the two modules belong to the same package and are at the same address:

```move
module 0x42::m {
  package fun foo(): u64 { 0 }
}

module 0x42::other {
  fun calls_m_foo(): u64 {
    0x42::m::foo() // valid
  }
}
```

An attempt to access `0x42::m::foo` from another package will fail at compile time.

In addition to the notation `package fun`, also the longer notation `public(package) fun` is supported.

Notice that package visibility is a compile time concept which is reduced by the compiler to friend visibility (described [below](#friend-visibility)), which can be verified by the Move VM. The Move VM guarantees that friend functions cannot be called across address boundaries, independent of what package system a compilation environment supports.

#### `public(friend)` visibility

[Section titled “public(friend) visibility”](#publicfriend-visibility)

*Since Language Version 2.0*, `friend fun` replaces `public(friend) fun`. The old notation is still supported.

The `public(friend)` visibility modifier is a more restricted form of the `public` modifier to give more control about where a function can be used. A `public(friend)` function can be called by:

* other functions defined in the same module, or
* functions defined in modules which are explicitly specified in the **friend list** (see [Friends](/build/smart-contracts/book/friends) on how to specify the friend list), and which reside at the same address.

Note that since we cannot declare a script to be a friend of a module, the functions defined in scripts can never call a `public(friend)` function.

```move
address 0x42 {
module m {
    friend 0x42::n;  // friend declaration
    public(friend) fun foo(): u64 { 0 }
    friend fun foo2(): u64 { 0 } // Since Move 2.0

fun calls_foo(): u64 { foo() } // valid
    fun calls_foo2(): u64 { foo2() } // valid, since Move 2.0
}

module n {
    fun calls_m_foo(): u64 {
        0x42::m::foo() // valid
    }

fun calls_m_foo2(): u64 {
        0x42::m::foo2() // valid, since Move 2.0
    }
}

module other {
    fun calls_m_foo(): u64 {
        0x42::m::foo() // ERROR!
        //       ^^^^^ `foo` can only be called from a `friend` of module `0x42::m`
    }

fun calls_m_foo2(): u64 {
        0x42::m::foo2() // ERROR!
        //       ^^^^^^ `foo2` can only be called from a `friend` of module `0x42::m`
    }
}
}

script {
    fun calls_m_foo(): u64 {
        0x42::m::foo() // ERROR!
        //       ^^^^^ `foo` can only be called from a `friend` of module `0x42::m`
    }
}
```

### `entry` modifier

[Section titled “entry modifier”](#entry-modifier)

The `entry` modifier is designed to allow module functions to be safely and directly invoked much like scripts. This allows module writers to specify which functions can be invoked to begin execution. The module writer then knows that any non-`entry` function will be called from a Move program already in execution.

Essentially, `entry` functions are the “main” functions of a module, and they specify where Move programs start executing.

Note though, an `entry` function *can* still be called by other Move functions. So while they *can* serve as the start of a Move program, they aren’t restricted to that case.

For example:

```move
address 0x42 {
module m {
    public entry fun foo() {}

fun calls_foo() { foo(); } // valid!
}

module n {
    fun calls_m_foo() {
        0x42::m::foo(); // valid!
    }
}

module other {
    public entry fun calls_m_foo() {
        0x42::m::foo(); // valid!
    }
}
}

script {
    fun calls_m_foo() {
        0x42::m::foo(); // valid!
    }
}
```

Even internal functions can be marked as `entry`! This lets you guarantee that the function is called only at the beginning of execution (assuming you do not call it elsewhere in your module)

```move
address 0x42 {
module m {
    entry fun foo() {} // valid! entry functions do not have to be public
}

module n {
    fun calls_m_foo() {
        0x42::m::foo(); // ERROR!
        //       ^^^^^ `foo` is internal to `0x42::m`
    }
}

module other {
    public entry fun calls_m_foo() {
        0x42::m::foo(); // ERROR!
        //       ^^^^^ `foo` is internal to `0x42::m`
    }
}
}

script {
    fun calls_m_foo() {
        0x42::m::foo(); // ERROR!
        //       ^^^^^ `foo` is internal to `0x42::m`
    }
}
```

Entry functions can accept parameters that are: primitive types, reference to a `signer`, vectors (where the element type is itself acceptable), and certain standard library types such as `String`, `Object`, and `Option`. Entry functions must not have any return values.

### Name

[Section titled “Name”](#name)

Function names can start with letters `a` to `z` or letters `A` to `Z`. After the first character, function names can contain underscores `_`, letters `a` to `z`, letters `A` to `Z`, or digits `0` to `9`.

```move
module 0x42::example {
    // all valid
    fun FOO() {}

fun bar_42() {}

fun bAZ19() {}

// invalid
    fun _bAZ19() {} // Function names cannot start with '_'
}
```

### Type Parameters

[Section titled “Type Parameters”](#type-parameters)

After the name, functions can have type parameters

```move
module 0x42::example {
    fun id<T>(x: T): T { x }

fun example<T1: copy, T2>(x: T1, y: T2): (T1, T1, T2) { (copy x, x, y) }
}
```

For more details, see [Move generics](/build/smart-contracts/book/generics).

### Parameters

[Section titled “Parameters”](#parameters)

Functions parameters are declared with a local variable name followed by a type annotation

```move
module 0x42::example {
    fun add(x: u64, y: u64): u64 { x + y }
}
```

We read this as `x` has type `u64`

A function does not have to have any parameters at all.

```move
module 0x42::example {
    fun useless() {}
}
```

This is very common for functions that create new or empty data structures

```move
module 0x42::example {
    struct Counter { count: u64 }

fun new_counter(): Counter {
        Counter { count: 0 }
    }
}
```

### Acquires

[Section titled “Acquires”](#acquires)

When a function accesses a resource using `move_from`, `borrow_global`, or `borrow_global_mut`, the function must indicate that it `acquires` that resource. This is then used by Move’s type system to ensure the references into global storage are safe, specifically that there are no dangling references into global storage.

```move
module 0x42::example {

struct Balance has key { value: u64 }

public fun add_balance(s: &signer, value: u64) {
        move_to(s, Balance { value })
    }

public fun extract_balance(addr: address): u64 acquires Balance {
        let Balance { value } = move_from<Balance>(addr); // acquires needed
        value
    }
}
```

`acquires` annotations must also be added for transitive calls within the module. Calls to these functions from another module do not need to annotated with these acquires because one module cannot access resources declared in another module—so the annotation is not needed to ensure reference safety.

```move
module 0x42::example {

struct Balance has key { value: u64 }

public fun add_balance(s: &signer, value: u64) {
        move_to(s, Balance { value })
    }

public fun extract_balance(addr: address): u64 acquires Balance {
        let Balance { value } = move_from<Balance>(addr); // acquires needed
        value
    }

public fun extract_and_add(sender: address, receiver: &signer) acquires Balance {
        let value = extract_balance(sender); // acquires needed here
        add_balance(receiver, value)
    }
}

module 0x42::other {
    fun extract_balance(addr: address): u64 {
        0x42::example::extract_balance(addr) // no acquires needed
    }
}
```

A function can `acquire` as many resources as it needs to

```move
module 0x42::example {
    use std::vector;

struct Balance has key { value: u64 }

struct Box<T> has key { items: vector<T> }

public fun store_two<Item1: store, Item2: store>(
        addr: address,
        item1: Item1,
        item2: Item2,
    ) acquires Balance, Box {
        let balance = borrow_global_mut<Balance>(addr); // acquires needed
        balance.value = balance.value - 2;
        let box1 = borrow_global_mut<Box<Item1>>(addr); // acquires needed
        vector::push_back(&mut box1.items, item1);
        let box2 = borrow_global_mut<Box<Item2>>(addr); // acquires needed
        vector::push_back(&mut box2.items, item2);
    }
}
```

### Return type

[Section titled “Return type”](#return-type)

After the parameters, a function specifies its return type.

```move
module 0x42::example {
    fun zero(): u64 { 0 }
}
```

Here `: u64` indicates that the function’s return type is `u64`.

Note

A function can return an immutable `&` or mutable `&mut` [reference](/build/smart-contracts/book/references) if derived from an input reference. Keep in mind, this means that a function [cannot return a reference to global storage](/build/smart-contracts/book/references#references-cannot-be-stored) unless it is an [inline function](#inline-functions).

Using tuples, a function can return multiple values:

```move
module 0x42::example {
    fun one_two_three(): (u64, u64, u64) { (0, 1, 2) }
}
```

If no return type is specified, the function has an implicit return type of unit `()`. These functions are equivalent:

```move
module 0x42::example {
    fun just_unit1(): () { () }

fun just_unit2() { () }

fun just_unit3() {}
}
```

`script` functions must have a return type of unit `()`:

```move
script {
    fun do_nothing() {}
}
```

As mentioned in the [tuples section](/build/smart-contracts/book/tuples), these tuple “values” are virtual and do not exist at runtime. So for a function that returns unit `()`, it will not be returning any value at all during execution.

### Function body

[Section titled “Function body”](#function-body)

A function’s body is an expression block. The return value of the function is the last value in the sequence

```move
module 0x42::example {
    fun example(): u64 {
        let x = 0;
        x = x + 1;
        x // returns 'x'
    }
}
```

See [the section below for more information on returns](#returning-values)

For more information on expression blocks, see [Move variables](/build/smart-contracts/book/variables).

### Native Functions

[Section titled “Native Functions”](#native-functions)

Some functions do not have a body specified, and instead have the body provided by the VM. These functions are marked `native`.

Without modifying the VM source code, a programmer cannot add new native functions. Furthermore, it is the intent that `native` functions are used for either standard library code or for functionality needed for the given Move environment.

Most `native` functions you will likely see are in standard library code such as `vector`

```move
module std::vector {
    native public fun empty<Element>(): vector<Element>;
    // ...
}
```

## Calling

[Section titled “Calling”](#calling)

When calling a function, the name can be specified either through an alias or fully qualified

```move
module 0x42::example {
    public fun zero(): u64 { 0 }
}

script {
    use 0x42::example::{Self, zero};

fun call_zero() {
        // With the `use` above all of these calls are equivalent
        0x42::example::zero();
        example::zero();
        zero();
    }
}
```

When calling a function, an argument must be given for every parameter.

```move
module 0x42::example {
    public fun takes_none(): u64 { 0 }

public fun takes_one(x: u64): u64 { x }

public fun takes_two(x: u64, y: u64): u64 { x + y }

public fun takes_three(x: u64, y: u64, z: u64): u64 { x + y + z }
}

script {
    use 0x42::example;

fun call_all() {
        example::takes_none();
        example::takes_one(0);
        example::takes_two(0, 1);
        example::takes_three(0, 1, 2);
    }
}
```

Type arguments can be either specified or inferred. Both calls are equivalent.

```move
module 0x42::example {
    public fun id<T>(x: T): T { x }
}

script {
    use 0x42::example;

fun call_all() {
        example::id(0);
        example::id<u64>(0);
    }
}
```

For more details, see [Move generics](/build/smart-contracts/book/generics).

## Returning values

[Section titled “Returning values”](#returning-values)

The result of a function, its “return value”, is the final value of its function body. For example

```move
module 0x42::example {
    fun add(x: u64, y: u64): u64 {
        x + y
    }
}
```

[As mentioned above](#function-body), the function’s body is an [expression block](/build/smart-contracts/book/variables). The expression block can be a sequence of various statements, and the final expression in the block will be the value of that block.

```move
module 0x42::example {
    fun double_and_add(x: u64, y: u64): u64 {
        let double_x = x * 2;
        let double_y = y * 2;
        double_x + double_y
    }
}
```

The return value here is `double_x + double_y`

### `return` expression

[Section titled “return expression”](#return-expression)

A function implicitly returns the value that its body evaluates to. However, functions can also use the explicit `return` expression:

```move
module 0x42::example {
    fun f1(): u64 { return 0 }

fun f2(): u64 { 0 }
}
```

These two functions are equivalent. In this slightly more involved example, the function subtracts two `u64` values, but returns early with `0` if the second value is too large:

```move
module 0x42::example {
    fun safe_sub(x: u64, y: u64): u64 {
        if (y > x) return 0;
        x - y
    }
}
```

Note that the body of this function could also have been written as `if (y > x) 0 else x - y`.

However, where `return` really shines is in exiting deep within other control flow constructs. In this example, the function iterates through a vector to find the index of a given value:

```move
module 0x42::example {
    use std::vector;
    use std::option::{Self, Option};

fun index_of<T>(v: &vector<T>, target: &T): Option<u64> {
        let i = 0;
        let n = vector::length(v);
        while (i < n) {
            if (vector::borrow(v, i) == target) return option::some(i);
            i = i + 1
        };

option::none()
    }
}
```

Using `return` without an argument is shorthand for `return ()`. That is, the following two functions are equivalent:

```move
module 0x42::example {
    fun foo1() { return }

fun foo2() { return () }
}
```

## Inline Functions

[Section titled “Inline Functions”](#inline-functions)

Inline functions are functions whose bodies are expanded in place at the caller location during compile time. Thus, inline functions do not appear in Move bytecode as a separate functions: all calls to them are expanded away by the compiler. In certain circumstances, they may lead to faster execution and save gas. However, users should be aware that they could lead to larger bytecode size: excessive inlining potentially triggers various size restrictions.

One can define an inline function by adding the `inline` keyword to a function declaration as shown below:

```move
module 0x42::example {
    inline fun percent(x: u64, y: u64): u64 { x * 100 / y }
}
```

If we call this inline function as `percent(2, 200)`, the compiler will replace this call with the inline function’s body, as if the user has written `2 * 100 / 200`.

### Function parameters and lambda expressions

[Section titled “Function parameters and lambda expressions”](#function-parameters-and-lambda-expressions)

Inline functions support *function parameters*, which accept lambda expressions (i.e., anonymous functions) as arguments. This feature allows writing several common programming patterns elegantly. Similar to inline functions, lambda expressions are also expanded at call site.

A lambda expression includes a list of parameter names (enclosed within `||`) followed by the body. Some simple examples are: `|x| x + 1`, `|x, y| x + y`, `|| 1`, `|| { 1 }`. A lambda’s body can refer to variables available in the scope where the lambda is defined: this is also known as capturing. Such variables can be read or written (if mutable) by the lambda expression.

The type of function parameter is written as `|<list of parameter types>| <return type>`. For example, when the function parameter type is `|u64, u64| bool`, any lambda expression that takes two `u64` parameters and returns a `bool` value can be provided as the argument.

Below is an example that showcases many of these concepts in action (this example is taken from the `std::vector` module):

```move
module 0x42::example {
    /// Fold the function over the elements.
    /// E.g, `fold(vector[1,2,3], 0, f)` is the same as `f(f(f(0, 1), 2), 3)`.
    public inline fun fold<Accumulator, Element>(
        v: vector<Element>,
        init: Accumulator,
        f: |Accumulator, Element|Accumulator
    ): Accumulator {
        let accu = init;
        // Note: `for_each` is an inline function, but is not shown here.
        for_each(v, |elem| accu = f(accu, elem));
        accu
    }
}
```

The type signature of the elided public inline function `for_each` is `fun for_each<Element>(v: vector<Element>, f: |Element|)`. Its second parameter `f` is a function parameter which accepts any lambda expression that consumes an `Element` and returns nothing. In the code example, we use the lambda expression `|elem| accu = f(accu, elem)` as an argument to this function parameter. Note that this lambda expression captures the variable `accu` from the outer scope.

### Current restrictions

[Section titled “Current restrictions”](#current-restrictions)

There are plans to loosen some of these restrictions in the future, but for now,

* Only inline functions can have function parameters.

* Only explicit lambda expressions can be passed as an argument to an inline function’s function parameters.

* Inline functions and lambda expressions

* cannot have `return` expressions; or free `break` or `continue` expressions (occurring outside of a loop)
  * cannot return lambda expressions.

* Cyclic recursion involving only inline functions is not allowed.

* Parameters in lambda expressions must not be type annotated (e.g., `|x: u64| x + 1` is not allowed): their types are inferred.

### Additional considerations

[Section titled “Additional considerations”](#additional-considerations)

* Avoid using module-private constants/methods in public inline functions. When such inline functions are called outside of that module, an in-place expansion at call site leads to invalid access of the private constants/methods.
* Avoid marking large functions that are called at different locations as inline. Also avoid inline functions calling lots of other inline functions transitively. These may lead to excessive inlining and increase the bytecode size.
* Inline functions can be useful for returning references to global storage, which non-inline functions cannot do.

### Inline functions and references

[Section titled “Inline functions and references”](#inline-functions-and-references)

As mentioned briefly [in a “tip” above](#return-type) `inline` functions can use references more freely than normal functions.

For example, actual arguments to a call to a non-`inline` function may not be aliased unsafely (multiple `&` parameters referring to the same object, with at least one of them `&mut`), but calls to `inline` functions do not necessarily have that restriction, as long as no reference usage conflicts remain after the function is inlined.

```move
inline fun add(dest: &mut u64, a: &u64, b: &u64) {
    *dest = *a + *b;
}

fun user(...) {
    ...
    x = 3;
    add(&mut x, &x, &x);  // legal only because of inlining
    ...
}
```

A reference-typed value returned from a non-inline function must be derived from a reference parameter passed to the function, but this need not be the case for an inline function, as long as the referred value is in the function scope after inlining.

The exact details of reference safety and “borrow checking” are complex and documented elsewhere. Advanced Move users find new expressiveness by understanding that “borrow checking” happens only after all `inline` function calls are expanded.

However, with this power comes new responsibility: documentation of a nontrivial `inline` function should probably explain any underlying restrictions on reference parameters and results at a call site.

## Dot (receiver) function call style

[Section titled “Dot (receiver) function call style”](#dot-receiver-function-call-style)

*Since language version 2.0*

By using the well-known name `self` as the first parameter for a function declaration, one can enable calling this function with the `.` syntax — often also called receiver style syntax. Example:

```move
module 0x42::example {
    struct S {}

fun foo(self: &S, x: u64) { /* ... */ }

//...

fun example() {
        let s = S {};
        s.foo(1);
    }
}
```

The call `s.foo(1)` is syntactic sugar for `foo(&s, 1)`. Notice that the compiler automatically inserts the reference operator. The 2nd, old notation is still available for `foo`, so one can incrementally introduce the new call style without breaking existing code.

The type of the `self` argument can be a struct or an immutable or mutable reference to a struct. The struct must be declared in the same module as the function.

Notice that you do not need to `use` the modules which introduce receiver functions. The compiler will find those functions automatically based on the argument type of `s` in a call like `s.foo(1)`. This, in combination with the automatic insertion of reference operators, can make code using this syntax significantly more concise.

The receiver style syntax can also be used on generic functions, like shown below for the generic function `std::vector::remove<T>(self: &mut vector<T>, i: u64): T`.

```move
module 0x42::example {
   fun bar() {
       let v = vector[1, 2, 3];
       let e1 = v.remove(0); // type params inferred for `remove<T>`
       assert!(e1 == 1);
       let e2 = v.remove::<u8>(0); // type params explicitly specified
       assert!(e2 == 2);
   }
}
```

## Function Values

[Section titled “Function Values”](#function-values)

*Since language version 2.2* (preview)

Move supports *function values* as first-class citizen of the language. A function value is constructed from the name of a function or by a lambda expression, and is evaluated by passing parameters to it and causing the underlying function to be executed. This feature is often also called *dynamic dispatch*. Which concrete function is called, is not known to the caller, and determined from the runtime value. Dynamic dispatch is an important tool for composing applications. Move makes dynamic dispatch safe by providing builtin protection mechanisms against reentrancy, which can be further refined by user choice.

### Function Types

[Section titled “Function Types”](#function-types)

The type of functions values is already known from [inline functions](#function-parameters-and-lambda-expressions). A function type is denoted, for example, as `|u64|bool`, indicating a function which takes a number and returns a boolean. Lists of types are separated by comma, as in `|u64, bool|(bool,u4)`.

Function types can have associated abilities, written as `|u64|bool has copy`. Multiple abilities are separated by plus, as in `|u64|bool has copy+drop`. If no abilities are provided, the value can be only moved around and evaluated (for evaluation of function values, see [below](#function-evaluation)).

Function values can be stored in fields of structs or enums. In this case, the field type inherits the abilities of the struct:

```move
struct S has key {
  func: |u64| bool /* has store */  // not needed since inherited
}
```

### Operations on Functions

[Section titled “Operations on Functions”](#operations-on-functions)

A function value is evaluated by providing the corresponding number of parameters, similar as when calling a named function. During evaluation, the function value is *consumed*. Hence if the value needs to be evaluated multiple times, its type must have the `copy` ability:

```move
let f: |u64|bool has copy = |x| x > 0;
assert!(f(1) == f(2))
```

Function values support equality and ordering. Note that those relations are based on the name of the underlying function behind a runtime value, and do not reflect semantic equivalence.

### Function Type Wrappers

[Section titled “Function Type Wrappers”](#function-type-wrappers)

Function types, specifically if they come together with abilities, can be verbose, and if the same type of function type is used many times in the code, repetitive. For this purpose, Move recognizes struct wrappers around function types as a special case. They can be used to effectively create named function types:

```move
struct Predicate<T>(|&T|bool) has copy;
```

Move supports this feature by automatically converting function values into the wrapper type and vice versa. Examples:

```move
let f: Predicate<u64> = |x| *x > 0; // lambda converts to Predicate
assert!(f(&22)) // Predicate callable
```

### Denoting Function Values

[Section titled “Denoting Function Values”](#denoting-function-values)

Function values can be constructed by directly using a function name. The resulting function type is derived from the signature of the underlying function, with abilities `copy+drop`. If the function is public, those function values have the `store` ability as well:

```move
public fun is_even(x: u64): bool { x % 2 == 0 }
fun is_odd(x: u64): bool { x % 2 == 1 }
...
let f: |u64|bool has copy+drop+store = is_even;
let g: |u64|bool has copy+drop = is_odd;
```

A *persistent* function is required to build a storable function value because it needs to be guaranteed that the underlying function exists and can be safely restored from storage at any point in the future. However, code upgrade may change the underlying implementation of the function, while its signature is persistent.

While `public` and `entry` functions are persistent by default, a none-public function needs to be marked with the attribute `#[persistent]` to become storable:

```move
#[persistent] fun is_odd(x: u64): bool { x % 2 == 1 }
...
let g: |u64|bool has copy+drop+store = is_odd;
```

Using the `#[persistent]` attribute is preferred if the only objective is to make a function storable, avoiding security implications with public or entry visibility.

### Lambda Expressions and Closures

[Section titled “Lambda Expressions and Closures”](#lambda-expressions-and-closures)

Function values can be denoted by *lambda expressions* (as also available as parameters for [inline functions](#function-parameters-and-lambda-expressions)). Lambda expressions can capture context variables *by value*: those values are moved (or copied) into a *closure*, from where they are produced when the function is evaluated. Examples:

```move
struct S(u64); // cannot be copied or dropped
...
let s = S(1);
let add = |y| { let S(x) = s; x + y }; // s will be moved into the closure
assert!(add(2) == 3)
```

Closures with captured values are lexicographical ordered using first the name of the underlying function (which maybe generated from lambda lifting), and then the captured values.

The type of the closure constructed by a lambda expression is inferred from the expression (for example, the type of `add` in the example above is inferred as `|u64|u64`). The abilities of this function type are derived as follows. By default, the function underlying a closure is a private function, so the function itself is `copy+drop` (and not `store`). This is intersected with the abilities of all the captured context variables. However, there is a special case for lambdas where instead of a private function an underlying persistent function can be identified, such that the lambda just ‘delays’ certain arguments of this function. This pattern is also called ‘currying’ in functional programming (named after the mathematician Curry). Here are some examples:

```move
#[persistent] fun add(x: u64, y: u64) { x + y }
...
let x = 22;
let f: |u64|u64 has copy+drop+store = |y| add(x, y);  // 1st argument captured, 2nd argument delayed
let f: |u64|u64 has copy+drop+store = |y| add(y, x);  // 1st argument delayed, 2nd argument captured
```

Notice it is not possible to *capture* reference values at this point of time in Move. Thus, the following code does not compile:

```move
let x = &22;
let f = |y| add(*x, y) // DOES NOT COMPILE
```

Related, it is not possible to mutate any locals in the context of a lambda. Specifically, the following pattern as known from lambdas with inline functions, is not supported:

```move
let x = 0;
collection.for_each(|e| x += e) // DOES NOT COMPILE
```

However, the actual parameters of lambdas can be references, only captured values are restricted. For example:

```move
let x = 22;
let f : |&u64|u64 = |y| add(x, *y)
```

### Reentrancy Check

[Section titled “Reentrancy Check”](#reentrancy-check)

Via dynamic dispatch of function values, reentrancy of modules in a chain of function calls is possible. If module `m1` uses module `m2`, and `m1` calls `m2::f` passing a function value to it, this function value can callback into `m1`. This situation is called *reentrancy*, and is not possible in Move without function values, since the module usage relation is acyclic.

The Move VM dynamically detects reentrancy of a module, and *locks* all resources declared in this module from being accessed. Thus during reentrancy of `m`, calling resource operations like `&m::R[addr]`, `&mut m::R[addr]`, and `move_from<m::R>` lead to an abort. Here is an example:

```move
module 0x42::caller {
  use 0x42::callee;
  struct R{ count: u64 } has key;
  fun calling() acquires R {
     let r = &mut R[@addr];
     // This callback is OK, because `R` is not accessed
     callee::call_me(r, |x| do_something(x))
     // This callback will lead to reentrancy runtime error
     callee::call_me(r, |_| R[@addr].count += 1)
     r.call_count += 1
  }
  fun do_something(r: &mut R) { .. }
}

module 0x42::callee {
  fun call_me<T(x: &mut T, action: |&mut T|) {
    action(x)
  }
}
```

Notice that dispatching a function value to a concrete function in the same module is also considered to be reentrancy. If the function `callee::call_me` would be moved into the module `caller`, the same semantics is in effect.

The default reentrancy check ensures consistency of Move’s reference semantics and suppresses side effects of reentrancy for the resources owned by the re-entered module. However, re-entered code is allowed to still access resource state managed by modules outside the reentrancy path. Such state accesses can be considered bad design, but they exist. For these purposes, the `#[module_lock]` attribute can be attached to a function:

```move
module 0x42::account { ... }
module 0x42::caller {
  #[module_lock] // without this lock, the notify call could withdraw more than intended.
  fun transfer(from: address, to: address, amount: u64, notify: |u64|) {
    // Oops. This should be really differently designed, using `Coin` type and moving it.
    assert!(account::balance(from) - MIN_BALANCE >= amount);
    account::deposit(to, amount)
    notify(amount); // attempt to re-enter `transfer` is blocked
    account::withdraw(from, amount);
  }
}
```

While a function with this attribute is running, all calls reentering any module will lead to an abort, given a stronger protection.

The attribute `#[module_lock]` restriction is not the default behavior since it is too strong for typical patterns of higher-order programming. For example, `collection.find(|x| cond(x))` will lead to a reentrancy of the module which contains this expression, from the module which defines the collection type.

# Generics

Generics can be used to define functions and structs over different input data types. This language feature is sometimes referred to as *parametric polymorphism*. In Move, we will often use the term generics interchangeably with type parameters and type arguments.

Generics are commonly used in library code, such as in vector, to declare code that works over any possible instantiation (that satisfies the specified constraints). In other frameworks, generic code can sometimes be used to interact with global storage many different ways that all still share the same implementation.

## Declaring Type Parameters

[Section titled “Declaring Type Parameters”](#declaring-type-parameters)

Both functions and structs can take a list of type parameters in their signatures, enclosed by a pair of angle brackets `<...>`.

### Generic Functions

[Section titled “Generic Functions”](#generic-functions)

Type parameters for functions are placed after the function name and before the (value) parameter list. The following code defines a generic identity function that takes a value of any type and returns that value unchanged.

```move
module 0x42::example {
  fun id<T>(x: T): T {
    // this type annotation is unnecessary but valid
    (x: T)
  }
}
```

Once defined, the type parameter `T` can be used in parameter types, return types, and inside the function body.

### Generic Structs

[Section titled “Generic Structs”](#generic-structs)

Type parameters for structs are placed after the struct name, and can be used to name the types of the fields.

```move
module 0x42::example {
  struct Foo<T> has copy, drop { x: T }

struct Bar<T1, T2> has copy, drop {
    x: T1,
    y: vector<T2>,
  }
}
```

Note that [type parameters do not have to be used](#unused-type-parameters)

## Type Arguments

[Section titled “Type Arguments”](#type-arguments)

### Calling Generic Functions

[Section titled “Calling Generic Functions”](#calling-generic-functions)

When calling a generic function, one can specify the type arguments for the function’s type parameters in a list enclosed by a pair of angle brackets.

```move
module 0x42::example {
  fun foo() {
    let x = id<bool>(true);
  }
}
```

If you do not specify the type arguments, Move’s [type inference](#type-inference) will supply them for you.

### Using Generic Structs

[Section titled “Using Generic Structs”](#using-generic-structs)

Similarly, one can attach a list of type arguments for the struct’s type parameters when constructing or destructing values of generic types.

```move
module 0x42::example {
  fun foo() {
    let foo = Foo<bool> { x: true };
    let Foo<bool> { x } = foo;
  }
}
```

If you do not specify the type arguments, Move’s [type inference](#type-inference) will supply them for you.

### Type Argument Mismatch

[Section titled “Type Argument Mismatch”](#type-argument-mismatch)

If you specify the type arguments, and they conflict with the actual values supplied, an error will be given:

```move
module 0x42::example {
  fun foo() {
    let x = id<u64>(true); // error! true is not a u64
  }
}
```

and similarly:

```move
module 0x42::example {
  fun foo() {
    let foo = Foo<bool> { x: 0 }; // error! 0 is not a bool
    let Foo<address> { x } = foo; // error! bool is incompatible with address
  }
}
```

## Type Inference

[Section titled “Type Inference”](#type-inference)

In most cases, the Move compiler will be able to infer the type arguments, so you don’t have to write them down explicitly. Here’s what the examples above would look like if we omit the type arguments:

```move
module 0x42::example {
  fun foo() {
    let x = id(true);
    //        ^ <bool> is inferred

let foo = Foo { x: true };
    //           ^ <bool> is inferred

let Foo { x } = foo;
    //     ^ <bool> is inferred
  }
}
```

Note: when the compiler is unable to infer the types, you’ll need annotate them manually. A common scenario is to call a function with type parameters appearing only at return positions.

```move
module 0x2::m {
  use std::vector;

fun foo() {
    // let v = vector::new();
    //                    ^ The compiler cannot figure out the element type.

let v = vector::new<u64>();
    //                 ^~~~~ Must annotate manually.
  }
}
```

However, the compiler will be able to infer the type if that return value is used later in that function:

```move
module 0x2::m {
  use std::vector;

fun foo() {
    let v = vector::new();
    //                 ^ <u64> is inferred
    vector::push_back(&mut v, 42);
  }
}
```

## Unused Type Parameters

[Section titled “Unused Type Parameters”](#unused-type-parameters)

For a struct definition, an unused type parameter is one that does not appear in any field defined in the struct, but is checked statically at compile time. Move allows unused type parameters so the following struct definition is valid:

```move
module 0x2::m {
  struct Foo<T> {
    foo: u64
  }
}
```

This can be convenient when modeling certain concepts. Here is an example:

```move
module 0x2::m {
  // Currency Specifiers
  struct Currency1 {}
  struct Currency2 {}

// A generic coin type that can be instantiated using a currency
  // specifier type.
  //   e.g. Coin<Currency1>, Coin<Currency2> etc.
  struct Coin<Currency> has store {
    value: u64
  }

// Write code generically about all currencies
  public fun mint_generic<Currency>(value: u64): Coin<Currency> {
    Coin { value }
  }

// Write code concretely about one currency
  public fun mint_concrete(value: u64): Coin<Currency1> {
    Coin { value }
  }
}
```

In this example, `struct Coin<Currency>` is generic on the `Currency` type parameter, which specifies the currency of the coin and allows code to be written either generically on any currency or concretely on a specific currency. This genericity applies even when the `Currency` type parameter does not appear in any of the fields defined in `Coin`.

### Phantom Type Parameters

[Section titled “Phantom Type Parameters”](#phantom-type-parameters)

In the example above, although `struct Coin` asks for the `store` ability, neither `Coin<Currency1>` nor `Coin<Currency2>` will have the `store` ability. This is because of the rules for [Conditional Abilities and Generic Types](/build/smart-contracts/book/abilities#conditional-abilities-and-generic-types) and the fact that `Currency1` and `Currency2` don’t have the `store` ability, despite the fact that they are not even used in the body of `struct Coin`. This might cause some unpleasant consequences. For example, we are unable to put `Coin<Currency1>` into a wallet in the global storage.

One possible solution would be to add spurious ability annotations to `Currency1` and `Currency2` (i.e., `struct Currency1 has store {}`). But, this might lead to bugs or security vulnerabilities because it weakens the types with unnecessary ability declarations. For example, we would never expect a resource in the global storage to have a field in type `Currency1`, but this would be possible with the spurious `store` ability. Moreover, the spurious annotations would be infectious, requiring many functions generic on the unused type parameter to also include the necessary constraints.

Phantom type parameters solve this problem. Unused type parameters can be marked as *phantom* type parameters, which do not participate in the ability derivation for structs. In this way, arguments to phantom type parameters are not considered when deriving the abilities for generic types, thus avoiding the need for spurious ability annotations. For this relaxed rule to be sound, Move’s type system guarantees that a parameter declared as `phantom` is either not used at all in the struct definition, or it is only used as an argument to type parameters also declared as `phantom`.

#### Declaration

[Section titled “Declaration”](#declaration)

In a struct definition a type parameter can be declared as phantom by adding the `phantom` keyword before its declaration. If a type parameter is declared as phantom we say it is a phantom type parameter. When defining a struct, Move’s type checker ensures that every phantom type parameter is either not used inside the struct definition or it is only used as an argument to a phantom type parameter.

More formally, if a type is used as an argument to a phantom type parameter we say the type appears in *phantom position*. With this definition in place, the rule for the correct use of phantom parameters can be specified as follows: **A phantom type parameter can only appear in phantom position**.

The following two examples show valid uses of phantom parameters. In the first one, the parameter `T1` is not used at all inside the struct definition. In the second one, the parameter `T1` is only used as an argument to a phantom type parameter.

```move
module 0x2::m {
  struct S1<phantom T1, T2> { f: u64 }
  //                ^^
  //                Ok: T1 does not appear inside the struct definition

struct S2<phantom T1, T2> { f: S1<T1, T2> }
  //                                ^^
  //                                Ok: T1 appears in phantom position
}
```

The following code shows examples of violations of the rule:

```move
module 0x2::m {
  struct S1<phantom T> { f: T }
  //                        ^
  //                        Error: Not a phantom position

struct S2<T> { f: T }

struct S3<phantom T> { f: S2<T> }
  //                           ^
  //                           Error: Not a phantom position
}
```

#### Instantiation

[Section titled “Instantiation”](#instantiation)

When instantiating a struct, the arguments to phantom parameters are excluded when deriving the struct abilities. For example, consider the following code:

```move
module 0x2::m {
  struct S<T1, phantom T2> has copy { f: T1 }
  struct NoCopy {}
  struct HasCopy has copy {}
}
```

Consider now the type `S<HasCopy, NoCopy>`. Since `S` is defined with `copy` and all non-phantom arguments have `copy` then `S<HasCopy, NoCopy>` also has `copy`.

#### Phantom Type Parameters with Ability Constraints

[Section titled “Phantom Type Parameters with Ability Constraints”](#phantom-type-parameters-with-ability-constraints)

Ability constraints and phantom type parameters are orthogonal features in the sense that phantom parameters can be declared with ability constraints. When instantiating a phantom type parameter with an ability constraint, the type argument has to satisfy that constraint, even though the parameter is phantom. For example, the following definition is perfectly valid:

```move
module 0x2::m {
  struct S<phantom T: copy> {}
}
```

The usual restrictions apply and `T` can only be instantiated with arguments having `copy`.

## Constraints

[Section titled “Constraints”](#constraints)

In the examples above, we have demonstrated how one can use type parameters to define “unknown” types that can be plugged in by callers at a later time. This however means the type system has little information about the type and has to perform checks in a very conservative way. In some sense, the type system must assume the worst case scenario for an unconstrained generic. Simply put, by default generic type parameters have no [abilities](/build/smart-contracts/book/abilities).

This is where constraints come into play: they offer a way to specify what properties these unknown types have so the type system can allow operations that would otherwise be unsafe.

### Declaring Constraints

[Section titled “Declaring Constraints”](#declaring-constraints)

Constraints can be imposed on type parameters using the following syntax.

```move
// T is the name of the type parameter
T: <ability> (+ <ability>)*
```

The `<ability>` can be any of the four [abilities](/build/smart-contracts/book/abilities), and a type parameter can be constrained with multiple abilities at once. So all the following would be valid type parameter declarations:

```move
T: copy
T: copy + drop
T: copy + drop + store + key
```

### Verifying Constraints

[Section titled “Verifying Constraints”](#verifying-constraints)

Constraints are checked at call sites so the following code won’t compile.

```move
module 0x2::m {
  struct Foo<T: key> { x: T }

struct Bar { x: Foo<u8> }
  //                  ^ error! u8 does not have 'key'

struct Baz<T> { x: Foo<T> }
  //                     ^ error! T does not have 'key'
}
```

```move
module 0x2::m {
  struct R {}

fun unsafe_consume<T>(x: T) {
    // error! x does not have 'drop'
  }

fun consume<T: drop>(x: T) {
    // valid!
    // x will be dropped automatically
  }

fun foo() {
    let r = R {};
    consume<R>(r);
    //      ^ error! R does not have 'drop'
  }
}
```

```move
module 0x2::m {
  struct R {}

fun unsafe_double<T>(x: T) {
    (copy x, x)
    // error! x does not have 'copy'
  }

fun double<T: copy>(x: T) {
    (copy x, x) // valid!
  }

fun foo(): (R, R) {
    let r = R {};
    double<R>(r)
    //     ^ error! R does not have 'copy'
  }
}
```

For more information, see the abilities section on [conditional abilities and generic types](/build/smart-contracts/book/abilities#conditional-abilities-and-generic-types).

## Limitations on Recursions

[Section titled “Limitations on Recursions”](#limitations-on-recursions)

### Recursive Structs

[Section titled “Recursive Structs”](#recursive-structs)

Generic structs can not contain fields of the same type, either directly or indirectly, even with different type arguments. All the following struct definitions are invalid:

```move
module 0x2::m {
  struct Foo<T> {
    x: Foo<u64> // error! 'Foo' containing 'Foo'
  }

struct Bar<T> {
    x: Bar<T> // error! 'Bar' containing 'Bar'
  }

// error! 'A' and 'B' forming a cycle, which is not allowed either.
  struct A<T> {
    x: B<T, u64>
  }

struct B<T1, T2> {
    x: A<T1>,
    y: A<T2>
  }
}
```

### Advanced Topic: Type-level Recursions

[Section titled “Advanced Topic: Type-level Recursions”](#advanced-topic-type-level-recursions)

Move allows generic functions to be called recursively. However, when used in combination with generic structs, this could create an infinite number of types in certain cases, and allowing this means adding unnecessary complexity to the compiler, vm and other language components. Therefore, such recursions are forbidden.

Allowed:

```move
module 0x2::m {
  struct A<T> {}

// Finitely many types -- allowed.
  // foo1<T> -> foo1<T> -> foo1<T> -> ... is valid
  fun foo1<T>() {
    foo1<T>();
  }

// Finitely many types -- allowed.
  // foo2<T> -> foo2<A<u64>> -> foo2<A<u64>> -> ... is valid
  fun foo2<T>() {
    foo2<A<u64>>();
  }
}
```

Not allowed:

```move
module 0x2::m {
  struct A<T> {}

// Infinitely many types -- NOT allowed.
  // error!
  // foo<T> -> foo<A<T>> -> foo<A<A<T>>> -> ...
  fun foo<T>() {
    foo<A<T>>();
  }
}
```

```move
module 0x2::n {
  struct A<T> {}

// Infinitely many types -- NOT allowed.
  // error!
  // foo<T1, T2> -> bar<T2, T1> -> foo<T2, A<T1>>
  //   -> bar<A<T1>, T2> -> foo<A<T1>, A<T2>>
  //   -> bar<A<T2>, A<T1>> -> foo<A<T2>, A<A<T1>>>
  //   -> ...
  fun foo<T1, T2>() {
    bar<T2, T1>();
  }

fun bar<T1, T2>() {
    foo<T1, A<T2>>();
  }
}
```

Note, the check for type level recursions is based on a conservative analysis on the call sites and does NOT take control flow or runtime values into account.

```move
module 0x2::m {
  struct A<T> {}

fun foo<T>(n: u64) {
    if (n > 0) {
      foo<A<T>>(n - 1);
    };
  }
}
```

The function in the example above will technically terminate for any given input and therefore only creating finitely many types, but it is still considered invalid by Move’s type system.

# Global Storage - Operators

Move programs can create, delete, and update [resources](/build/smart-contracts/book/structs-and-resources) in global storage using the following five instructions:

| Operation                               | Description                                                     | Aborts?                                 |
| --------------------------------------- | --------------------------------------------------------------- | --------------------------------------- |
| `move_to<T>(&signer,T)`                 | Publish `T` under `signer.address`                              | If `signer.address` already holds a `T` |
| `move_from<T>(address): T`              | Remove `T` from `address` and return it                         | If `address` does not hold a `T`        |
| `borrow_global_mut<T>(address): &mut T` | Return a mutable reference to the `T` stored under `address`    | If `address` does not hold a `T`        |
| `borrow_global<T>(address): &T`         | Return an immutable reference to the `T` stored under `address` | If `address` does not hold a `T`        |
| `exists<T>(address): bool`              | Return `true` if a `T` is stored under `address`                | Never                                   |

Each of these instructions is parameterized by a type `T` with the [`key` ability](/build/smart-contracts/book/abilities). However, each type `T` *must be declared in the current module*. This ensures that a resource can only be manipulated via the API exposed by its defining module. The instructions also take either an [`address`](/build/smart-contracts/book/address) or [`&signer`](/build/smart-contracts/book/signer) representing the account address where the resource of type `T` is stored.

See also [index notation (`[]`)](#index-notation-for-storage-operators) for accessing global storage.

## References to resources

[Section titled “References to resources”](#references-to-resources)

References to global resources returned by `borrow_global` or `borrow_global_mut` mostly behave like references to local storage: they can be extended, read, and written using ordinary [reference operators](/build/smart-contracts/book/references) and passed as arguments to other function. However, there is one important difference between local and global references: **a function cannot return a reference that points into global storage**. For example, these two functions will each fail to compile:

```move
module 0x42::example {
  struct R has key { f: u64 }
  // will not compile
  fun ret_direct_resource_ref_bad(a: address): &R {
    borrow_global<R>(a) // error!
  }
  // also will not compile
  fun ret_resource_field_ref_bad(a: address): &u64 {
    &borrow_global<R>(a).f // error!
  }
}
```

Move must enforce this restriction to guarantee absence of dangling references to global storage. [This section](#reference-safety-for-global-resources) contains much more detail for the interested reader.

## Global storage operators with generics

[Section titled “Global storage operators with generics”](#global-storage-operators-with-generics)

Global storage operations can be applied to generic resources with both instantiated and uninstantiated generic type parameters:

```move
module 0x42::example {
  struct Container<T> has key { t: T }

// Publish a Container storing a type T of the caller's choosing
  fun publish_generic_container<T>(account: &signer, t: T) {
    move_to<Container<T>>(account, Container { t })
  }

/// Publish a container storing a u64
  fun publish_instantiated_generic_container(account: &signer, t: u64) {
    move_to<Container<u64>>(account, Container { t })
  }
}
```

The ability to index into global storage via a type parameter chosen at runtime is a powerful Move feature known as *storage polymorphism*. For more on the design patterns enabled by this feature, see [Move generics](/build/smart-contracts/book/generics).

## Example: `Counter`

[Section titled “Example: Counter”](#example-counter)

The simple `Counter` module below exercises each of the five global storage operators. The API exposed by this module allows:

* Anyone to publish a `Counter` resource under their account
* Anyone to check if a `Counter` exists under any address
* Anyone to read or increment the value of a `Counter` resource under any address
* An account that stores a `Counter` resource to reset it to zero
* An account that stores a `Counter` resource to remove and delete it

```move
module 0x42::counter {
  use std::signer;

/// Resource that wraps an integer counter
  struct Counter has key { i: u64 }

/// Publish a `Counter` resource with value `i` under the given `account`
  public fun publish(account: &signer, i: u64) {
    // "Pack" (create) a Counter resource. This is a privileged operation that
    // can only be done inside the module that declares the `Counter` resource
    move_to(account, Counter { i })
  }

/// Read the value in the `Counter` resource stored at `addr`
  public fun get_count(addr: address): u64 acquires Counter {
    borrow_global<Counter>(addr).i
  }

/// Increment the value of `addr`'s `Counter` resource
  public fun increment(addr: address) acquires Counter {
    let c_ref = &mut borrow_global_mut<Counter>(addr).i;
    *c_ref = *c_ref + 1
  }

/// Reset the value of `account`'s `Counter` to 0
  public fun reset(account: &signer) acquires Counter {
    let c_ref = &mut borrow_global_mut<Counter>(signer::address_of(account)).i;
    *c_ref = 0
  }

/// Delete the `Counter` resource under `account` and return its value
  public fun delete(account: &signer): u64 acquires Counter {
    // remove the Counter resource
    let c = move_from<Counter>(signer::address_of(account));
    // "Unpack" the `Counter` resource into its fields. This is a
    // privileged operation that can only be done inside the module
    // that declares the `Counter` resource
    let Counter { i } = c;
    i
  }

/// Return `true` if `addr` contains a `Counter` resource
  public fun exists_at(addr: address): bool {
    exists<Counter>(addr)
  }
}
```

## Annotating functions with `acquires`

[Section titled “Annotating functions with acquires”](#annotating-functions-with-acquires)

*Note: Since language version 2.2, acquires annotations are optional. If no acquires is given, it will be inferred.*

In the `counter` example, you might have noticed that the `get_count`, `increment`, `reset`, and `delete` functions are annotated with `acquires Counter`. A Move function `m::f` must be annotated with `acquires T` if and only if:

* The body of `m::f` contains a `move_from<T>`, `borrow_global_mut<T>`, or `borrow_global<T>` instruction, or
* The body of `m::f` invokes a function `m::g` declared in the same module that is annotated with `acquires`

For example, the following function inside `Counter` would need an `acquires` annotation:

```move
module 0x42::example {
  // Needs `acquires` because `increment` is annotated with `acquires`
  fun call_increment(addr: address): u64 acquires Counter {
    counter::increment(addr)
  }
}
```

However, the same function *outside* `Counter` would not need an annotation:

```move
module 0x43::m {
  use 0x42::counter;

// Ok. Only need annotation when resource acquired by callee is declared
  // in the same module
  fun call_increment(addr: address): u64 {
    counter::increment(addr)
  }
}
```

If a function touches multiple resources, it needs multiple `acquires`:

```move
module 0x42::two_resources {
  struct R1 has key { f: u64 }
  struct R2 has key { g: u64 }

fun double_acquires(a: address): u64 acquires R1, R2 {
    borrow_global<R1>(a).f + borrow_global<R2>(a).g
  }
}
```

The `acquires` annotation does not take generic type parameters into account:

```move
module 0x42::m {
  struct R<T> has key { t: T }

// `acquires R`, not `acquires R<T>`
  fun acquire_generic_resource<T: store>(a: address) acquires R {
    let _ = borrow_global<R<T>>(a);
  }

// `acquires R`, not `acquires R<u64>
  fun acquire_instantiated_generic_resource(a: address) acquires R {
    let _ = borrow_global<R<u64>>(a);
  }
}
```

Finally: redundant `acquires` are not allowed. Adding this function inside `Counter` will result in a compilation error:

```move
module 0x42::m {
  // This code will not compile because the body of the function does not use a global
  // storage instruction or invoke a function with `acquires`
  fun redundant_acquires_bad() acquires Counter {}
}
```

For more information on `acquires`, see [Move functions](/build/smart-contracts/book/functions).

## Reference Safety For Global Resources

[Section titled “Reference Safety For Global Resources”](#reference-safety-for-global-resources)

Move prohibits returning global references and requires the `acquires` annotation to prevent dangling references. This allows Move to live up to its promise of static reference safety (i.e., no dangling references, no `null` or `nil` dereferences) for all [reference](/build/smart-contracts/book/references) types.

This example illustrates how the Move type system uses `acquires` to prevent a dangling reference:

```move
module 0x42::dangling {
  struct T has key { f: u64 }

fun borrow_then_remove_bad(a: address) acquires T {
    let t_ref: &mut T = borrow_global_mut<T>(a);
    let t = remove_t(a); // type system complains here
    // t_ref now dangling!
    let uh_oh = *&t_ref.f;
  }

fun remove_t(a: address): T acquires T {
    move_from<T>(a)
  }
}
```

In this code, line 6 acquires a reference to the `T` stored at address `a` in global storage. The callee `remove_t` then removes the value, which makes `t_ref` a dangling reference.

Fortunately, this cannot happen because the type system will reject this program. The `acquires` annotation on `remove_t` lets the type system know that line 7 is dangerous, without having to recheck or introspect the body of `remove_t` separately!

The restriction on returning global references prevents a similar, but even more insidious problem:

```move
address 0x42 {
  module m1 {
    struct T has key {}

public fun ret_t_ref(a: address): &T acquires T {
      borrow_global<T>(a) // error! type system complains here
    }

public fun remove_t(a: address) acquires T {
      let T {} = move_from<T>(a);
    }
  }

module m2 {
    fun borrow_then_remove_bad(a: address) {
      let t_ref = m1::ret_t_ref(a);
      let t = m1::remove_t(a); // t_ref now dangling!
    }
  }
}
```

Line 16 acquires a reference to a global resource `m1::T`, then line 17 removes that same resource, which makes `t_ref` dangle. In this case, `acquires` annotations do not help us because the `borrow_then_remove_bad` function is outside the `m1` module that declares `T` (recall that `acquires` annotations can only be used for resources declared in the current module). Instead, the type system avoids this problem by preventing the return of a global reference at line 6.

Fancier type systems that would allow returning global references without sacrificing reference safety are possible, and we may consider them in future iterations of Move. We chose the current design because it strikes a good balance between being expressive, annotation burden, and type system complexity.

## Index Notation for Storage Operators

[Section titled “Index Notation for Storage Operators”](#index-notation-for-storage-operators)

*Since language version 2.0*

Instead of the verbose `borrow_global` and `borrow_global_mut` functions, one can also use index notations to access global storage.

The table below gives an overview of index notations for storage:

| Indexing Syntax         | Storage Operation                          |
| ----------------------- | ------------------------------------------ |
| `&T[address]`           | `borrow_global<T>(address)`                |
| `&mut T[address]`       | `borrow_global_mut<T>(address)`            |
| `T[address]`            | `*borrow_global<T>(address)`               |
| `T[address] = x`        | `*borrow_global_mut<T>(address) = x`       |
| `&T[address].field`     | `&borrow_global<T>(address).field`         |
| `&mut T[address].field` | `&mut borrow_global_mut<T>(address).field` |
| `T[address].field`      | `borrow_global<T>(address).field`          |
| `T[address].field = x`  | `borrow_global_mut<T>(address).field = x`  |

Here `T` represents a generic resource type that can take type parameters.

Notice that `T[address].field` fetches a reference to the resource from storage and then makes a copy of the field value (which must have the copy ability); it is a shortcut for `*&T[address].field`.

Examples:

```move
struct R has key, drop { value: bool }

fun f1() acquires R {
  let x = &mut R[@0x1];
  x.value = false;
  assert!(R[@0x1].value == false);
  R[@0x1].value = true;
  assert!(R[@0x1].value == true);
}
```

# Global Storage - Structure

The purpose of Move programs is to [read from and write to](/build/smart-contracts/book/global-storage-operators) tree-shaped persistent global storage. Programs cannot access the filesystem, network, or any other data outside of this tree.

In pseudocode, the global storage looks something like:

```move
module 0x42::example {
  struct GlobalStorage {
    resources: Map<(address, ResourceType), ResourceValue>,
    modules: Map<(address, ModuleName), ModuleBytecode>
  }
}
```

Structurally, global storage is a [forest](https://en.wikipedia.org/wiki/Tree_$graph_theory$) consisting of trees rooted at an account [`address`](/build/smart-contracts/book/address). Each address can store both [resource](/build/smart-contracts/book/structs-and-resources) data values and [module](/build/smart-contracts/book/modules-and-scripts) code values. As the pseudocode above indicates, each `address` can store at most one resource value of a given type and at most one module with a given name.

# Integers

Move supports six unsigned integer types: `u8`, `u16`, `u32`, `u64`, `u128`, and `u256`. Values of these types range from 0 to a maximum that depends on the size of the type.

| Type                             | Value Range   |
| -------------------------------- | ------------- |
| Unsigned 8-bit integer, `u8`     | 0 to 28 - 1   |
| Unsigned 16-bit integer, `u16`   | 0 to 216 - 1  |
| Unsigned 32-bit integer, `u32`   | 0 to 232 - 1  |
| Unsigned 64-bit integer, `u64`   | 0 to 264 - 1  |
| Unsigned 128-bit integer, `u128` | 0 to 2128 - 1 |
| Unsigned 256-bit integer, `u256` | 0 to 2256 - 1 |

## Literals

[Section titled “Literals”](#literals)

Literal values for these types are specified either as a sequence of digits (e.g.,`112`) or as hex literals, e.g., `0xFF`. The type of the literal can optionally be added as a suffix, e.g., `112u8`. If the type is not specified, the compiler will try to infer the type from the context where the literal is used. If the type cannot be inferred, it is assumed to be `u64`.

Number literals can be separated by underscores for grouping and readability. (e.g.,`1_234_5678`, `1_000u128`, `0xAB_CD_12_35`).

If a literal is too large for its specified (or inferred) size range, an error is reported.

### Examples

[Section titled “Examples”](#examples)

```move
script {
  fun example() {
    // literals with explicit annotations;
    let explicit_u8 = 1u8;
    let explicit_u16 = 1u16;
    let explicit_u32 = 1u32;
    let explicit_u64 = 2u64;
    let explicit_u128 = 3u128;
    let explicit_u256 = 1u256;
    let explicit_u64_underscored = 154_322_973u64;

// literals with simple inference
    let simple_u8: u8 = 1;
    let simple_u16: u16 = 1;
    let simple_u32: u32 = 1;
    let simple_u64: u64 = 2;
    let simple_u128: u128 = 3;
    let simple_u256: u256 = 1;

// literals with more complex inference
    let complex_u8 = 1; // inferred: u8
    // right hand argument to shift must be u8
    let _unused = 10 << complex_u8;

let x: u8 = 38;
    let complex_u8 = 2; // inferred: u8
    // arguments to `+` must have the same type
    let _unused = x + complex_u8;

let complex_u128 = 133_876; // inferred: u128
    // inferred from function argument type
    function_that_takes_u128(complex_u128);

// literals can be written in hex
    let hex_u8: u8 = 0x1;
    let hex_u16: u16 = 0x1BAE;
    let hex_u32: u32 = 0xDEAD80;
    let hex_u64: u64 = 0xCAFE;
    let hex_u128: u128 = 0xDEADBEEF;
    let hex_u256: u256 = 0x1123_456A_BCDE_F;
  }
}
```

## Operations

[Section titled “Operations”](#operations)

### Arithmetic

[Section titled “Arithmetic”](#arithmetic)

Each of these types supports the same set of checked arithmetic operations. For all of these operations, both arguments (the left and right side operands) *must* be of the same type. If you need to operate over values of different types, you will need to first perform a [cast](#casting). Similarly, if you expect the result of the operation to be too large for the integer type, perform a [cast](#casting) to a larger size before performing the operation.

All arithmetic operations abort instead of behaving in a way that mathematical integers would not (e.g., overflow, underflow, divide-by-zero).

| Syntax | Operation           | Aborts If                                |
| ------ | ------------------- | ---------------------------------------- |
| `+`    | addition            | Result is too large for the integer type |
| `-`    | subtraction         | Result is less than zero                 |
| `*`    | multiplication      | Result is too large for the integer type |
| `%`    | modular division    | The divisor is `0`                       |
| `/`    | truncating division | The divisor is `0`                       |

### Bitwise

[Section titled “Bitwise”](#bitwise)

The integer types support the following bitwise operations that treat each number as a series of individual bits, either 0 or 1, instead of as numerical integer values.

Bitwise operations do not abort.

| Syntax | Operation   | Description                                           |
| ------ | ----------- | ----------------------------------------------------- |
| `&`    | bitwise and | Performs a boolean and for each bit pairwise          |
| `\|`   | bitwise or  | Performs a boolean or for each bit pairwise           |
| `^`    | bitwise xor | Performs a boolean exclusive or for each bit pairwise |

### Bit Shifts

[Section titled “Bit Shifts”](#bit-shifts)

Similar to the bitwise operations, each integer type supports bit shifts. But unlike the other operations, the right-hand side operand (how many bits to shift by) must *always* be a `u8` and need not match the left side operand (the number you are shifting).

Bit shifts abort if the number of bits to shift by is greater than or equal to `8`, `16`, `32`, `64`, `128` or `256` for `u8`, `u16`, `u32`, `u64`, `u128` and `u256` respectively.

| Syntax | Operation   | Aborts if                                                                           |
| ------ | ----------- | ----------------------------------------------------------------------------------- |
| `<<`   | shift left  | Number of bits to shift by is greater than or equal to the size of the integer type |
| `>>`   | shift right | Number of bits to shift by is greater than or equal to the size of the integer type |

### Comparisons

[Section titled “Comparisons”](#comparisons)

Integer types are the *only* types in Move that can use the comparison operators. Both arguments need to be of the same type. If you need to compare integers of different types, you will need to [cast](#casting) one of them first.

Comparison operations do not abort.

| Syntax | Operation                |
| ------ | ------------------------ |
| `<`    | less than                |
| `>`    | greater than             |
| `<=`   | less than or equal to    |
| `>=`   | greater than or equal to |

### Equality

[Section titled “Equality”](#equality)

Like all types with [`drop`](/build/smart-contracts/book/abilities) in Move, all integer types support the [“equal”](/build/smart-contracts/book/equality) and [“not equal”](/build/smart-contracts/book/equality) operations. Both arguments need to be of the same type. If you need to compare integers of different types, you will need to [cast](#casting) one of them first.

Equality operations do not abort.

| Syntax | Operation |
| ------ | --------- |
| `==`   | equal     |
| `!=`   | not equal |

For more details see the section on [equality](/build/smart-contracts/book/equality)

## Casting

[Section titled “Casting”](#casting)

Integer types of one size can be cast to integer types of another size. Integers are the only types in Move that support casting.

Casts *do not* truncate. Casting will abort if the result is too large for the specified type

| Syntax     | Operation                                            | Aborts if                              |
| ---------- | ---------------------------------------------------- | -------------------------------------- |
| `(e as T)` | Cast integer expression `e` into an integer type `T` | `e` is too large to represent as a `T` |

Here, the type of `e` must be `8`, `16`, `32`, `64`, `128` or `256` and `T` must be `u8`, `u16`, `u32`, `u64`, `u128` or `u256`.

For example:

* `(x as u8)`
* `(y as u16)`
* `(873u16 as u32)`
* `(2u8 as u64)`
* `(1 + 3 as u128)`
* `(4/2 + 12345 as u256)`

Notice that since Language Version 2.0, casts don’t always need to be in parentheses. Thus, `x as u8` is a valid expression.

## Ownership

[Section titled “Ownership”](#ownership)

As with the other scalar values built-in to the language, integer values are implicitly copyable, meaning they can be copied without an explicit instruction such as [`copy`](/build/smart-contracts/book/variables#move-and-copy).

# While, For, and Loop

Move offers three constructs for looping: `while`, `for`, and `loop`.

## `while` loops

[Section titled “while loops”](#while-loops)

The `while` construct repeats the body (an expression of type unit) until the condition (an expression of type `bool`) evaluates to `false`.

Here is an example of simple `while` loop that computes the sum of the numbers from `1` to `n`:

```move
script {
  fun sum(n: u64): u64 {
    let sum = 0;
    let i = 1;
    while (i <= n) {
      sum = sum + i;
      i = i + 1
    };

sum
  }
}
```

Infinite loops are allowed:

```move
script {
  fun foo() {
    while (true) { }
  }
}
```

### `break`

[Section titled “break”](#break)

The `break` expression can be used to exit a loop before the condition evaluates to `false`. For example, this loop uses `break` to find the smallest factor of `n` that’s greater than 1:

```move
script {
  fun smallest_factor(n: u64): u64 {
    // assuming the input is not 0 or 1
    let i = 2;
    while (i <= n) {
      if (n % i == 0) break;
      i = i + 1
    };

i
  }
}
```

The `break` expression cannot be used outside of a loop.

### `continue`

[Section titled “continue”](#continue)

The `continue` expression skips the rest of the loop and continues to the next iteration. This loop uses `continue` to compute the sum of `1, 2, ..., n`, except when the number is divisible by 10:

```move
script {
  fun sum_intermediate(n: u64): u64 {
    let sum = 0;
    let i = 0;
    while (i < n) {
      i = i + 1;
      if (i % 10 == 0) continue;
      sum = sum + i;
    };

sum
  }
}
```

The `continue` expression cannot be used outside of a loop.

### The type of `break` and `continue`

[Section titled “The type of break and continue”](#the-type-of-break-and-continue)

`break` and `continue`, much like `return` and `abort`, can have any type. The following examples illustrate where this flexible typing can be helpful:

```move
script {
  fun pop_smallest_while_not_equal(
    v1: vector<u64>,
    v2: vector<u64>,
  ): vector<u64> {
    let result = vector::empty();
    while (!vector::is_empty(&v1) && !vector::is_empty(&v2)) {
      let u1 = *vector::borrow(&v1, vector::length(&v1) - 1);
      let u2 = *vector::borrow(&v2, vector::length(&v2) - 1);
      let popped =
        if (u1 < u2) vector::pop_back(&mut v1)
        else if (u2 < u1) vector::pop_back(&mut v2)
        else break; // Here, `break` has type `u64`
      vector::push_back(&mut result, popped);
    };

result
  }
}
```

```move
script {
  fun pick(
    indexes: vector<u64>,
    v1: &vector<address>,
    v2: &vector<address>
  ): vector<address> {
    let len1 = vector::length(v1);
    let len2 = vector::length(v2);
    let result = vector::empty();
    while (!vector::is_empty(&indexes)) {
      let index = vector::pop_back(&mut indexes);
      let chosen_vector =
        if (index < len1) v1
        else if (index < len2) v2
        else continue; // Here, `continue` has type `&vector<address>`
      vector::push_back(&mut result, *vector::borrow(chosen_vector, index))
    };

result
  }
}
```

## The `for` expression

[Section titled “The for expression”](#the-for-expression)

The `for` expression iterates over a range defined using integer-typed `lower_bound` (inclusive) and `upper_bound` (non-inclusive) expressions, executing its loop body for each element of the range. `for` is designed for scenarios where the number of iterations of a loop is determined by a specific range.

Here is an example of a `for` loop that computes the sum of the elements in a range from `0` to `n-1`:

```move
script {
  fun sum(n: u64): u64 {
    let sum = 0;
    for (i in 0..n) {
      sum = sum + i;
    };

sum
  }
}
```

The loop iterator variable (`i` in the above example) currently must be a numeric type (inferred from the bounds), and the bounds `0` and `n` here can be replaced by arbitrary numeric expressions. Each is only evaluated once at the start of the loop. The iterator variable `i` is assigned the `lower_bound` (in this case `0`) and incremented after each loop iteration; the loop exits when the iterator `i` reaches or exceeds `upper_bound` (in this case `n`).

### `break` and `continue` in `for` loops

[Section titled “break and continue in for loops”](#break-and-continue-in-for-loops)

Similar to `while` loops, the `break` expression can be used in `for` loops to exit prematurely. The `continue` expression can be used to skip the current iteration and move to the next. Here’s an example that demonstrates the use of both `break` and `continue`. The loop will iterate through numbers from `0` to `n-1`, summing up them up. It will skip numbers that are divisible by `3` (using `continue`) and stop when it encounters a number greater than `10` (using `break`):

```move
script {
  fun sum_conditional(n: u64): u64 {
    let sum = 0;
    for (iter in 0..n) {
      if (iter > 10) {
        break; // Exit the loop if the number is greater than 10
      };
      if (iter % 3 == 0) {
        continue; // Skip the current iteration if the number is divisible by 3
      };

sum = sum + iter;
    };

sum
  }
}
```

## The `loop` expression

[Section titled “The loop expression”](#the-loop-expression)

The `loop` expression repeats the loop body (an expression with type `()`) until it hits a `break`

Without a `break`, the loop will continue forever

```move
script {
  fun foo() {
    let i = 0;
    loop { i = i + 1 }
  }
}
```

Here is an example that uses `loop` to write the `sum` function:

```move
script {
  fun sum(n: u64): u64 {
    let sum = 0;
    let i = 0;
    loop {
      i = i + 1;
      if (i > n) break;
      sum = sum + i
    };

sum
  }
}
```

As you might expect, `continue` can also be used inside a `loop`. Here is `sum_intermediate` from above rewritten using `loop` instead of `while`

```move
script {
  fun sum_intermediate(n: u64): u64 {
    let sum = 0;
    let i = 0;
    loop {
      i = i + 1;
      if (i % 10 == 0) continue;
      if (i > n) break;
      sum = sum + i
    };

sum
  }
}
```

## The type of `while`, `loop`, and `for` expression

[Section titled “The type of while, loop, and for expression”](#the-type-of-while-loop-and-for-expression)

Move loops are typed expressions. The `while` and `for` expression always has type `()`.

```move
script {
  fun example() {
    let () = while (i < 10) { i = i + 1 };
    let () = for (i in 0..10) {};
  }
}
```

If a `loop` contains a `break`, the expression has type unit `()`

```move
script {
  fun example() {
    (loop { if (i < 10) i = i + 1 else break }: ());
    let () = loop { if (i < 10) i = i + 1 else break };
  }
}
```

If `loop` does not have a `break`, `loop` can have any type much like `return`, `abort`, `break`, and `continue`.

```move
script {
  fun example() {
    (loop (): u64);
    (loop (): address);
    (loop (): &vector<vector<u8>>);
  }
}
```

## Loop Labels

[Section titled “Loop Labels”](#loop-labels)

*Since language version 2.1*

A `while` or `loop` statement can have a label which can be referred to by a `break` or `continue` statement. In the presence of nested loops, this allows to refer to outer loops. Example:

```move
script {
  fun example(x: u64): u64 {
    'label1: while (x > 10) {
      loop {
        if (x % 2 == 0) {
          x -= 1;
          continue 'label1;
        } else if (x < 10) {
          break 'label1
        } else
          x -= 2
      }
    };
    x
  }
}
```

# Modules and Scripts

Move has two different types of programs: \***Modules**\* and \*\**Scripts*\*\*. Modules are libraries that define struct types along with functions that operate on these types. Struct types define the schema of Move’s [global storage](/build/smart-contracts/book/global-storage-structure), and module functions define the rules for updating storage. Modules themselves are also stored in global storage. A scripts is an executable entrypoint similar to a `main` function in a conventional language. A script typically calls functions of a published module that perform updates to global storage. Scripts are ephemeral code snippets that are not published in global storage.

A Move source file (or **compilation unit**) may contain multiple modules and scripts. However, publishing a module or executing a script are separate VM operations.

## Syntax

[Section titled “Syntax”](#syntax)

### Scripts

[Section titled “Scripts”](#scripts)

Note

To learn how to publish and execute a Move script, follow the [Move Scripts](/build/smart-contracts/scripts/script-tutorial) example.

A script has the following structure:

```text
script {
    <use>*
    <constants>*
    fun <identifier><[type parameters: constraint]*>([identifier: type]*) <function_body>
}
```

A `script` block must start with all of its [`use`](/build/smart-contracts/book/uses) declarations, followed by any [constants](/build/smart-contracts/book/constants) and (finally) the main [function](/build/smart-contracts/book/functions) declaration. The main function can have any name (i.e., it need not be called `main`), is the only function in a script block, can have any number of arguments, and must not return a value. Here is an example with each of these components:

```move
script {
    // Import the debug module published at the named account address std.
    use std::debug;

const ONE: u64 = 1;

fun main(x: u64) {
        let sum = x + ONE;
        debug::print(&sum)
    }
}
```

Scripts have very limited power—they cannot declare friends, struct types or access global storage. Their primary purpose is to invoke module functions.

### Modules

[Section titled “Modules”](#modules)

A module has the following syntax:

```move
module <address>::<identifier> {
    (<use> | <friend> | <type> | <function> | <constant>)*
}
```

where `<address>` is a valid [named or literal address](/build/smart-contracts/book/address).

For example:

```move
module 0x42::example {
    struct Example has copy, drop { i: u64 }

use std::debug;
    friend 0x42::another_example;

const ONE: u64 = 1;

public fun print(x: u64) {
        let sum = x + ONE;
        let example = Example { i: sum };
        debug::print(&sum)
    }
}
```

The `module 0x42::example` part specifies that the module `example` will be published under the [account address](/build/smart-contracts/book/address) `0x42` in [global storage](/build/smart-contracts/book/global-storage-structure).

Modules can also be declared using [named addresses](/build/smart-contracts/book/address). For example:

```move
module example_addr::example {
    struct Example has copy, drop { a: address }

use std::debug;
    friend example_addr::another_example;

public fun print() {
        let example = Example { a: @example_addr };
        debug::print(&example)
    }
}
```

Because named addresses only exist at the source language level and during compilation, named addresses will be fully substituted for their value at the bytecode level. For example if we had the following code:

```move
script {
    fun example() {
        my_addr::m::foo(@my_addr);
    }
}
```

and we compiled it with `my_addr` set to `0xC0FFEE`, then it would be equivalent to the following operationally:

```move
script {
    fun example() {
        0xC0FFEE::m::foo(@0xC0FFEE);
    }
}
```

However, at the source level, these *are not equivalent*—the function `m::foo` *must* be accessed through the `my_addr` named address, and not through the numerical value assigned to that address.

Module names can start with letters `a` to `z` or letters `A` to `Z`. After the first character, module names can contain underscores `_`, letters `a` to `z`, letters `A` to `Z`, or digits `0` to `9`.

```move
module my_module {}
module foo_bar_42 {}
```

Typically, module names start with a lowercase letter. A module named `my_module` should be stored in a source file named `my_module.move`.

All elements inside a `module` block can appear in any order. Fundamentally, a module is a collection of [`types`](/build/smart-contracts/book/structs-and-resources) and [`functions`](/build/smart-contracts/book/functions). The [`use`](/build/smart-contracts/book/uses) keyword is used to import types from other modules. The [`friend`](/build/smart-contracts/book/friends) keyword specifies a list of trusted modules. The [`const`](/build/smart-contracts/book/constants) keyword defines private constants that can be used in the functions of a module.

# Move 2 Release Notes

The Move 2 language releases are described on this page. The reference documentation of the new features is integrated into the book, and marked in the text with “*Since language version 2.n*”.

## Move 2.2

[Section titled “Move 2.2”](#move-22)

The Move 2.2 language release adds the following features to Move:

* **Optional Acquires**: The `acquires` annotation on function declarations can be omitted, to be inferred by the compiler.
* **Function Values**: Move now supports function values, which can be passed around as parameters and stored in resources. See the [reference doc here](/build/smart-contracts/book/functions#function-values).

## Move 2.1

[Section titled “Move 2.1”](#move-21)

The Move 2.1 language release adds the following features to Move:

* **Compound Assignments** One can now use `x += n`, `x -= n`, etc. to combine assignments and arithmetic operations. See [reference doc here](/build/smart-contracts/book/variables#compound-assignments) for the supported operations.

* **Loop Labels** One can now use labels for loops and have a `break` or `continue` expression refer to those labels. This allows to continue or break outer loops from within nested loops. See [reference doc here](/build/smart-contracts/book/loops#loop-labels).

* **Underscore function parameters are wildcards, not symbols** Function parameters named `_` no longer act like variables: they do not bind a value, and multiple such parameters to a function does not cause a conflict. Using `_` in a value expression will yield an error, as it has no value. This makes the behavior of `_` more like the wildcard it is in patterns and let expressions, where it does not bind a value.

## Move 2.0

[Section titled “Move 2.0”](#move-20)

The Move 2.0 language release adds the following features to Move:

* **Enum Types** add the option to define different variants of data layout in one storable type. They are documented in the [Enum Type section](/build/smart-contracts/book/enums).

* **Receiver Style Functions** add the ability to call functions in the familiar notation `value.func(arg)`. They are documented in [this section](/build/smart-contracts/book/functions#dot-receiver-function-call-style).

* **Index Notation** allows access to [elements of vectors](/build/smart-contracts/book/vector#index-notation-for-vectors) and of [resource storage](/build/smart-contracts/book/global-storage-operators#index-notation-for-storage-operators) with notations like `&mut vector[index]`, or `&mut Resource[addr]`, respectively.

* **Positional Structs** allow to define wrapper types such as `struct Wrapped(u64)`. Positional structs are described [here](/build/smart-contracts/book/structs-and-resources#positional-structs). Enum variants are also allowed to be positional.

* **Dot-dot pattern wildcards** enable statements like `let Struct{x, ..} = value` to match selective parts of data. They are described [here](/build/smart-contracts/book/structs-and-resources#partial-patterns). Those patterns are also allowed for enum variants.

* **Package visibility** allows to declare a function to be visible anywhere inside, but not outside a package. Friend functions continue to be supported, although package visibility is in many cases more suitable. As a more concise notation, package and friend functions can be simply declared as `package fun` or `friend fun`, respectively, instead of the longer `public(package) fun` and `public(friend) fun`. This feature is documented [here](/build/smart-contracts/book/functions#package-visibility).

* **Assert abort code optional** The `assert!` macro can now be used with just one argument, omitting the abort code, in which case a default code will be chosen. See also [here](/build/smart-contracts/book/abort-and-assert#assert).

* **New Cast Syntax** Until now, casts had to always be in parentheses, requiring code like `function((x as u256))`. This requirement is now dropped and casts can be top-level expressions without parenthesis, as in `function(x as u256)`. One still needs to write `(x as u64) + (y as u64)` in expressions. This similarly applies to the new enum variant test, `data is VersionedData::V1`.

* **Well-defined evaluation order** The evaluation order in the cases below is now well-defined (these were previously unspecified):

* The (a) arguments to a function call, and the (b) operand expressions in a binary operation, are both evaluated from left-to-right.
  * Given a “mutate” expression (see [mutating through a reference](/build/smart-contracts/book/variables#mutating-through-a-reference)) of the form `*lexp = rexp`, where `lexp` is an expression of type `&mut T` and `rexp` is an expression of type `T`, `rexp` is evaluated first, followed by `lexp`.

* **Bug fix for acquires annotation** [A function should be annotated with `acquires`](/build/smart-contracts/book/functions#acquires) if and only if it accesses a resource using `move_from`, `borrow_global`, or `borrow_global_mut`, either directly or transitively through a call. Otherwise, it is an error. Previously, when the transitive call graph included a cycle, such errors were not reported: this was incorrect behavior. We have now corrected this behavior to report these errors even when the transitive call graph has cycles.

# Move Tutorial

Please refer to the [Move Core Language Tutorial](https://github.com/aptos-labs/aptos-core/tree/main/aptos-move/move-examples/move-tutorial).

# Package Upgrades

Move code (e.g., Move modules) on the Aptos blockchain can be upgraded. This allows code owners and module developers to update and evolve their contracts under a single, stable, well-known account address that doesn’t change. If a module upgrade happens, all consumers of that module will automatically receive the latest version of the code (e.g., the next time they interact with it).

The Aptos blockchain natively supports different *upgrade policies*, which allow move developers to explicitly define the constraints around how their move code can be upgraded. The default policy is *backwards compatible*. This means that code upgrades are accepted only if they guarantee that no existing resource storage or public APIs are broken by the upgrade (including public functions). This compatibility checking is possible because of Move’s strongly typed bytecode semantics.

We note, however, that even compatible upgrades can have hazardous effects on applications and dependent Move code (for example, if the semantics of the underlying module are modified). As a result, developers should be careful when depending on third-party Move code that can be upgraded on-chain. See [Security considerations for dependencies](#security-considerations-for-dependencies) for more details.

## How it works

[Section titled “How it works”](#how-it-works)

Move code upgrades on the Aptos blockchain happen at the [Move package](/build/smart-contracts/book/packages) granularity. A package specifies an upgrade policy in the `Move.toml` manifest:

```toml
[package]
name = "MyApp"
version = "0.0.1"
upgrade_policy = "compatible"
...
```

Note

Aptos checks compatibility at the time a Move package is published via an Aptos transaction. This transaction will abort if deemed incompatible.

## How to upgrade

[Section titled “How to upgrade”](#how-to-upgrade)

To upgrade already published Move code, simply attempt to republish the code at the same address that it was previously published. This can be done by following the instructions for code compilation and publishing using the [Aptos CLI](/build/cli/working-with-move-contracts). For an example, see the [Your First Move Module](/build/guides/first-move-module) tutorial.

## Upgrade policies

[Section titled “Upgrade policies”](#upgrade-policies)

There are two different upgrade policies currently supported by Aptos:

* `compatible`: these upgrades must be backwards compatible, specifically:

* For storage, all old struct declarations must be the same in the new code. This ensures that the existing state of storage is correctly interpreted by the new code. However, new struct declarations can be added.
  * For APIs, all existing public functions must have the same signature as before. New functions, including public and entry functions, can be added.

* `immutable`: the code is not upgradeable and is guaranteed to stay the same forever.

Those policies are ordered regarding strength such that `compatible < immutable`, i.e., compatible is weaker than immutable. The policy of a package on-chain can only get stronger, not weaker. Moreover, the policy of all dependencies of a package must be stronger or equal to the policy of the given package. For example, an `immutable` package cannot refer directly or indirectly to a `compatible` package. This gives users the guarantee that no unexpected updates can happen under the hood.

Note that there is one exception to the above rule: framework packages installed at addresses `0x1` to `0xa` are exempted from the dependency check. This is necessary so one can define an `immutable` package based on the standard libraries, which have the `compatible` policy to allow critical upgrades and fixes.

## Compatibility rules

[Section titled “Compatibility rules”](#compatibility-rules)

When using `compatible` upgrade policy, a module package can be upgraded. However, updates to existing modules already published previously need to be compatible and follow the rules below:

* All existing structs’ fields cannot be updated. This means no new fields can be added and existing fields cannot be modified.
* All public and entry functions cannot change their signature (argument types, type argument, return types). However, argument names can change.
* `public(friend)` functions are treated as private and thus their signature can arbitrarily change. This is safe as only modules in the same package can call friend functions anyway, and they need to be updated if the signature changes.
* [Enum type upgrade compatibility rules](/build/smart-contracts/book/enums#enum-type-upgrade-compatibility).
* Existing abilities on a struct/enum type cannot be removed (but abilities can be added).

When updating your modules, if you see an incompatible error, make sure to check the above rules and fix any violations.

## Security considerations for dependencies

[Section titled “Security considerations for dependencies”](#security-considerations-for-dependencies)

As mentioned above, even compatible upgrades can have disastrous effects for applications that depend on the upgraded code. These effects can come from bugs, but they can also be the result of malicious upgrades. For example, an upgraded dependency can suddenly make all functions abort, breaking the operation of your Move code. Alternatively, an upgraded dependency can make all functions suddenly cost much more gas to execute then before the upgrade. As result, dependencies to upgradeable packages need to be handled with care:

* The safest dependency is, of course, an `immutable` package. This guarantees that the dependency will never change, including its transitive dependencies. In order to update an immutable package, the owner would have to introduce a new major version, which is practically like deploying a new, separate and independent package. This is because major versioning can be expressed only by name (e.g., `module feature_v1` and `module feature_v2`). However, not all package owners like to publish their code as `immutable`, because this takes away the ability to fix bugs and update the code in place.
* If you have a dependency to a `compatible` package, it is highly recommended you know and understand the entity publishing the package. The highest level of assurance is when the package is governed by a Decentralized Autonomous Organization (DAO) where no single user can initiate an upgrade; a vote or similar has to be taken. This is the case for the Aptos framework.

## Programmatic upgrade

[Section titled “Programmatic upgrade”](#programmatic-upgrade)

In general, Aptos offers, via the Move module `aptos_framework::code`, ways to publish code from anywhere in your smart contracts. However, notice that code published in the current transaction can be executed only after that transaction ends.

The Aptos framework itself, including all the on-chain administration logic, is an example for programmatic upgrade. The framework is marked as `compatible`. Upgrades happen via specific generated governance scripts. For more details, see [Aptos Governance](/network/blockchain/governance).

# Packages

Packages allow Move programmers to more easily re-use code and share it across projects. The Move package system allows programmers to easily do the following:

* Define a package containing Move code;
* Parameterize a package by [named addresses](/build/smart-contracts/book/address);
* Import and use packages in other Move code and instantiate named addresses;
* Build packages and generate associated compilation artifacts from packages; and
* Work with a common interface around compiled Move artifacts.

## Package Layout and Manifest Syntax

[Section titled “Package Layout and Manifest Syntax”](#package-layout-and-manifest-syntax)

A Move package source directory contains a `Move.toml` package manifest file along with a set of subdirectories:

* a\_move\_package/

* Move.toml

* sources (required)/

* module.move
    * \*.move

* examples (optional, test & dev mode)/

* scripts (optional, can also put in sources)/

* doc\_templates (optional)/

* tests (optional, test mode)/

The directories marked `required` *must* be present in order for the directory to be considered a Move package and to be compiled. Optional directories can be present, and if so will be included in the compilation process. Depending on the mode that the package is built with (`test` or `dev`), the `tests` and `examples` directories will be included as well.

The `sources` directory can contain both Move modules and Move scripts (both Move scripts and modules containing script functions). The `examples` directory can hold additional code to be used only for development and/or tutorial purposes that will not be included when compiled outside `test` or `dev` mode.

A `scripts` directory is supported so Move scripts can be separated from modules if that is desired by the package author. The `scripts` directory will always be included for compilation if it is present. Documentation will be built using any documentation templates present in the `doc_templates` directory.

### Move.toml

[Section titled “Move.toml”](#movetoml)

The Move package manifest is defined within the `Move.toml` file and has the following syntax. Optional fields are marked with `*`, `+` denotes one or more elements:

```toml
[package]
name = <string>                  # e.g., "MoveStdlib"
version = "<uint>.<uint>.<uint>" # e.g., "0.1.1"
license* = <string>              # e.g., "MIT", "GPL", "Apache 2.0"
authors* = [<string>]            # e.g., ["Joe Smith (joesmith@noemail.com)", "Jane Smith (janesmith@noemail.com)"]

[addresses]  # (Optional section) Declares named addresses in this package and instantiates named addresses in the package graph
# One or more lines declaring named addresses in the following format
<addr_name> = "_" | "<hex_address>" # e.g., std = "_" or my_addr = "0xC0FFEECAFE"

[dependencies] # (Optional section) Paths to dependencies and instantiations or renamings of named addresses from each dependency
# One or more lines declaring dependencies in the following format
<string> = { local = <string>, addr_subst* = { (<string> = (<string> | "<hex_address>"))+ } } # local dependencies
<string> = { git = <URL ending in .git>, subdir=<path to dir containing Move.toml inside git repo>, rev=<git commit hash or branch name>, addr_subst* = { (<string> = (<string> | "<hex_address>"))+ } } # git dependencies

[dev-addresses] # (Optional section) Same as [addresses] section, but only included in "dev" and "test" modes
# One or more lines declaring dev named addresses in the following format
<addr_name> = "_" | "<hex_address>" # e.g., std = "_" or my_addr = "0xC0FFEECAFE"

[dev-dependencies] # (Optional section) Same as [dependencies] section, but only included in "dev" and "test" modes
# One or more lines declaring dev dependencies in the following format
<string> = { local = <string>, addr_subst* = { (<string> = (<string> | <address>))+ } }
```

An example of a minimal package manifest with one local dependency and one git dependency:

```toml
[package]
name = "AName"
version = "0.0.0"
```

An example of a more standard package manifest that also includes the Move standard library and instantiates the named address `Std` from it with the address value `0x1`:

```toml
[package]
name = "AName"
version = "0.0.0"
license = "Apache 2.0"

[addresses]
address_to_be_filled_in = "_"
specified_address = "0xB0B"

[dependencies]
# Local dependency
LocalDep = { local = "projects/move-awesomeness", addr_subst = { "std" = "0x1" } }
# Git dependency
MoveStdlib = { git = "https://github.com/aptos-labs/aptos-framework", subdir="move-stdlib", rev = "mainnet" }

[dev-addresses] # For use when developing this module
address_to_be_filled_in = "0x101010101"
```

Most of the sections in the package manifest are self-explanatory, but named addresses can be a bit difficult to understand, so it’s worth examining them in a bit more detail.

## Named Addresses During Compilation

[Section titled “Named Addresses During Compilation”](#named-addresses-during-compilation)

Recall that Move has [named addresses](/build/smart-contracts/book/address) and that named addresses cannot be declared in Move. Because of this, until now named addresses and their values needed to be passed to the compiler on the command line. With the Move package system this is no longer needed, and you can declare named addresses in the package, instantiate other named addresses in scope, and rename named addresses from other packages within the Move package system manifest file. Let’s go through each of these individually:

### Declaration

[Section titled “Declaration”](#declaration)

Let’s say we have a Move module in `example_pkg/sources/A.move` as follows:

```move
module named_addr::A {
  public fun x(): address { @named_addr }
}
```

We could in `example_pkg/Move.toml` declare the named address `named_addr` in two different ways. The first:

```toml
[package]
name = "ExamplePkg"
# ...
[addresses]
named_addr = "_"
```

Declares `named_addr` as a named address in the package `ExamplePkg` and that *this address can be any valid address value*. Therefore, an importing package can pick the value of the named address `named_addr` to be any address it wishes. Intuitively you can think of this as parameterizing the package `ExamplePkg` by the named address `named_addr`, and the package can then be instantiated later on by an importing package.

`named_addr` can also be declared as:

```toml
[package]
name = "ExamplePkg"
# ...
[addresses]
named_addr = "0xCAFE"
```

which states that the named address `named_addr` is exactly `0xCAFE` and cannot be changed. This is useful so other importing packages can use this named address without needing to worry about the exact value assigned to it.

With these two different declaration methods, there are two ways that information about named addresses can flow in the package graph:

* The former (“unassigned named addresses”) allows named address values to flow from the importation site to the declaration site.
* The latter (“assigned named addresses”) allows named address values to flow from the declaration site upwards in the package graph to usage sites.

With these two methods for flowing named address information throughout the package graph the rules around scoping and renaming become important to understand.

## Scoping and Renaming of Named Addresses

[Section titled “Scoping and Renaming of Named Addresses”](#scoping-and-renaming-of-named-addresses)

A named address `N` in a package `P` is in scope if:

1. It declares a named address `N`; or
2. A package in one of `P`’s transitive dependencies declares the named address `N` and there is a dependency path in the package graph between `P` and the declaring package of `N` with no renaming of `N`.

Additionally, every named address in a package is exported. Because of this and the above scoping rules each package can be viewed as coming with a set of named addresses that will be brought into scope when the package is imported, e.g., if the `ExamplePkg` package was imported, that importation would bring into scope the `named_addr` named address. Because of this, if `P` imports two packages `P1` and `P2` both of which declare a named address `N` an issue arises in `P`: which “`N`” is meant when `N` is referred to in `P`? The one from `P1` or `P2`? To prevent this ambiguity around which package a named address is coming from, we enforce that the sets of scopes introduced by all dependencies in a package are disjoint, and provide a way to *rename named addresses* when the package that brings them into scope is imported.

Renaming a named address when importing can be done as follows in our `P`, `P1`, and `P2` example above:

```toml
[package]
name = "P"
# ...
[dependencies]
P1 = { local = "some_path_to_P1", addr_subst = { "P1N" = "N" } }
P2 = { local = "some_path_to_P2"  }
```

With this renaming `N` refers to the `N` from `P2` and `P1N` will refer to `N` coming from `P1`:

```move
module N::A {
    public fun x(): address { @P1N }
}
```

It is important to note that *renaming is not local*: once a named address `N` has been renamed to `N2` in a package `P` all packages that import `P` will not see `N` but only `N2` unless `N` is reintroduced from outside of `P`. This is why rule (2) in the scoping rules at the start of this section specifies a “dependency path in the package graph between `P` and the declaring package of `N` with no renaming of `N`.”

### Instantiation

[Section titled “Instantiation”](#instantiation)

Named addresses can be instantiated multiple times across the package graph as long as it is always with the same value. It is an error if the same named address (regardless of renaming) is instantiated with differing values across the package graph.

A Move package can only be compiled if all named addresses resolve to a value. This presents issues if the package wishes to expose an uninstantiated named address. This is what the `[dev-addresses]` section solves. This section can set values for named addresses, but cannot introduce any named addresses. Additionally, only the `[dev-addresses]` in the root package are included in `dev` mode. For example a root package with the following manifest would not compile outside of `dev` mode since `named_addr` would be uninstantiated:

```toml
[package]
name = "ExamplePkg"
# ...
[addresses]
named_addr = "_"

[dev-addresses]
named_addr = "0xC0FFEE"
```

## Usage, Artifacts, and Data Structures

[Section titled “Usage, Artifacts, and Data Structures”](#usage-artifacts-and-data-structures)

The Move package system comes with a command line option as part of the Move CLI `move <flags> <command> <command_flags>`. Unless a particular path is provided, all package commands will run in the current working directory. The full list of commands and flags for the Move CLI can be found by running `move --help`.

### Usage

[Section titled “Usage”](#usage)

A package can be compiled either through the Move CLI commands, or as a library command in Rust with the function `compile_package`. This will create a `CompiledPackage` that holds the compiled bytecode along with other compilation artifacts (source maps, documentation, ABIs) in memory. This `CompiledPackage` can be converted to an `OnDiskPackage` and vice versa — the latter being the data of the `CompiledPackage` laid out in the file system in the following format:

* a\_move\_package/

* …/

* …

* build/

* dependency\_name/

* BuildInfo.yaml

* bytecode\_modules/

* module\_name.mv
        * \*.mv

* source\_maps/

* module\_name.mvsm
        * \*.mvsm

* bytecode\_scripts/

* script\_name.mv
        * \*.mv

* abis/

* script\_name.abi

* \*.abi

* module\_name/

* function\_name.abi
          * \*.abi

* sources/

* module\_name.move

* dependency\_name2 …/

See the `move-package` crate for more information on these data structures and how to use the Move package system as a Rust library.

## Using Bytecode for Dependencies

[Section titled “Using Bytecode for Dependencies”](#using-bytecode-for-dependencies)

Move bytecode can be used as dependencies when the Move source code for those dependencies are not available locally. To use this feature, you will need co-locate the files in directories at the same level and then specify their paths in the corresponding `Move.toml` files.

## Requirements and limitations

[Section titled “Requirements and limitations”](#requirements-and-limitations)

Using local bytecode as dependencies requires bytecode files to be downloaded locally, and the actual address for each named address must be specified in either `Move.toml` or through `--named-addresses`.

Note, both `aptos move prove` and `aptos move test` commands, currently, do not support bytecode as dependencies.

## Recommended structure

[Section titled “Recommended structure”](#recommended-structure)

We use an example to illustrate the development flow of using this feature. Suppose we want to compile the package `A`. The package layout is:

* A/

* Move.toml

* sources/

* AModule.move

`A.move` is defined below, depending on the modules `Bar` and `Foo`:

```move
module A::AModule {
    use B::Bar;
    use C::Foo;
    public fun foo(): u64 {
        Bar::foo() + Foo::bar()
    }
}
```

Suppose the source of `Bar` and `Foo` are not available but the corresponding bytecode `Bar.mv` and `Foo.mv` are available locally. To use them as dependencies, we would:

Specify `Move.toml` for `Bar` and `Foo`. Note that named addresses are already instantiated with the actual address in the bytecode. In our example, the actual address for `C` is already bound to `0x3`. As a result, `[addresses]` must be specified `C` as `0x3`, as shown below:

```toml
[package]
name = "Foo"
version = "0.0.0"

[addresses]
C = "0x3"
```

Place the bytecode file and the corresponding `Move.toml` file in the same directory with the bytecode in a `build` subdirectory. Note an empty `sources` directory is **required**. For instance, the layout of the folder `B` (for the package `Bar`) and `C` (for the package `Foo`) would resemble:

* workspace/

* A/

* Move.toml

* sources/

* AModule.move

* B/

* Move.toml

* sources/

* …

* build/

* Bar.mv

* C/

* Move.toml

* sources/

* …

* build/

* Foo/

* bytecode\_modules/

* Foo.mv

Specify `[dependencies]` in the `Move.toml` of the target (first) package with the location of the dependent (secondary) packages. For instance, assuming all three package directories are at the same level, `Move.toml` of `A` would resemble:

```toml
[package]
name = "A"
version = "0.0.0"

[addresses]
A = "0x2"

[dependencies]
Bar = { local = "../B" }
Foo = { local = "../C" }
```

Note that if both the bytecode and the source code of the same package exist in the search paths, the compiler will complain that the declaration is duplicated.

## Overriding the Standard Libraries

[Section titled “Overriding the Standard Libraries”](#overriding-the-standard-libraries)

When working with third-party packages, you might encounter issues where different versions of the Move and Aptos standard library packages are referenced.

This can lead to package resolution failures.

```plaintext
"Error": "Move compilation failed:
  Unable to resolve packages for package 'C':
    While resolving dependency 'B' in package 'C':
      Unable to resolve package dependency 'B':
        While resolving dependency 'AptosFramework' in package 'B':
          Unable to resolve package dependency 'AptosFramework':
            Conflicting dependencies found: package 'AptosFramework' conflicts with 'AptosFramework'
```

To resolve this, you can override the standard library packages using a command-line option. This allows you to enforce a specific version of the standard libraries across your entire dependency tree.

You can apply the override to commands like `aptos move compile`, `aptos move run`, and others. Here is the syntax:

```plaintext
--override-std <network name>
```

Where `network_name` can be one of the following:

* devnet
* testnet
* mainnet

# References

Move has two types of references: immutable `&` and mutable `&mut`. Immutable references are read only, and cannot modify the underlying value (or any of its fields). Mutable references allow for modifications via a write through that reference. Move’s type system enforces an ownership discipline that prevents reference errors.

For more details on the rules of references, see [Structs and Resources](/build/smart-contracts/book/structs-and-resources)

## Reference Operators

[Section titled “Reference Operators”](#reference-operators)

Move provides operators for creating and extending references as well as converting a mutable reference to an immutable one. Here and elsewhere, we use the notation `e: T` for “expression `e` has type `T`”.

| Syntax      | Type                                                  | Description                                                    |
| ----------- | ----------------------------------------------------- | -------------------------------------------------------------- |
| `&e`        | `&T` where `e: T` and `T` is a non-reference type     | Create an immutable reference to `e`                           |
| `&mut e`    | `&mut T` where `e: T` and `T` is a non-reference type | Create a mutable reference to `e`.                             |
| `&e.f`      | `&T` where `e.f: T`                                   | Create an immutable reference to field `f` of struct `e`.      |
| `&mut e.f`  | `&mut T` where `e.f: T`                               | Create a mutable reference to field `f` of struct`e`.          |
| `freeze(e)` | `&T` where `e: &mut T`                                | Convert the mutable reference `e` into an immutable reference. |

The `&e.f` and `&mut e.f` operators can be used both to create a new reference into a struct or to extend an existing reference:

```move
script {
  fun example() {
    let s = S { f: 10 };
    let f_ref1: &u64 = &s.f; // works
    let s_ref: &S = &s;
    let f_ref2: &u64 = &s_ref.f; // also works
  }
}
```

A reference expression with multiple fields works as long as both structs are in the same module:

```move
module 0x42::example {
  struct A { b: B }
  struct B { c : u64 }

fun f(a: &A): &u64 {
    &a.b.c
  }
}
```

Finally, note that references to references are not allowed:

```move
script {
  fun example() {
    let x = 7;
    let y: &u64 = &x;
    let z: &&u64 = &y; // will not compile
  }
}
```

## Reading and Writing Through References

[Section titled “Reading and Writing Through References”](#reading-and-writing-through-references)

Both mutable and immutable references can be read to produce a copy of the referenced value.

Only mutable references can be written. A write `*x = v` discards the value previously stored in `x` and updates it with `v`.

Both operations use the C-like `*` syntax. However, note that a read is an expression, whereas a write is a mutation that must occur on the left hand side of an equals.

| Syntax     | Type                                | Description                         |
| ---------- | ----------------------------------- | ----------------------------------- |
| `*e`       | `T` where `e` is `&T` or `&mut T`   | Read the value pointed to by `e`    |
| `*e1 = e2` | `()` where `e1: &mut T` and `e2: T` | Update the value in `e1` with `e2`. |

In order for a reference to be read, the underlying type must have the [`copy` ability](/build/smart-contracts/book/abilities) as reading the reference creates a new copy of the value. This rule prevents the copying of resource values:

```move
module 0x42::coin {
  struct Coin {} // Note does not have copy

fun copy_resource_via_ref_bad(c: Coin) {
      let c_ref = &c;
      let counterfeit: Coin = *c_ref; // not allowed!
      pay(c);
      pay(counterfeit);
  }
}
```

Dually: in order for a reference to be written to, the underlying type must have the [`drop` ability](/build/smart-contracts/book/abilities) as writing to the reference will discard (or “drop”) the old value. This rule prevents the destruction of resource values:

```move
module 0x42::coin {
  struct Coin {} // Note does not have drop

fun destroy_resource_via_ref_bad(ten_coins: Coin, c: Coin) {
      let ref = &mut ten_coins;
      *ref = c; // not allowed--would destroy 10 coins!
  }
}
```

## `freeze` inference

[Section titled “freeze inference”](#freeze-inference)

A mutable reference can be used in a context where an immutable reference is expected:

```move
script {
  fun example() {
    let x = 7;
    let y: &u64 = &mut x;
  }
}
```

This works because the under the hood, the compiler inserts `freeze` instructions where they are needed. Here are a few more examples of `freeze` inference in action:

```move
module 0x42::example {
  fun takes_immut_returns_immut(x: &u64): &u64 { x }

// freeze inference on return value
  fun takes_mut_returns_immut(x: &mut u64): &u64 { x }

fun expression_examples() {
    let x = 0;
    let y = 0;
    takes_immut_returns_immut(&x); // no inference
    takes_immut_returns_immut(&mut x); // inferred freeze(&mut x)
    takes_mut_returns_immut(&mut x); // no inference

assert!(&x == &mut y, 42); // inferred freeze(&mut y)
  }

fun assignment_examples() {
    let x = 0;
    let y = 0;
    let imm_ref: &u64 = &x;

imm_ref = &x; // no inference
    imm_ref = &mut y; // inferred freeze(&mut y)
  }
}
```

### Subtyping

[Section titled “Subtyping”](#subtyping)

With this `freeze` inference, the Move type checker can view `&mut T` as a subtype of `&T`. As shown above, this means that anywhere for any expression where a `&T` value is used, a `&mut T` value can also be used. This terminology is used in error messages to concisely indicate that a `&mut T` was needed where a `&T` was supplied. For example

```move
module 0x42::example {
  fun read_and_assign(store: &mut u64, new_value: &u64) {
    *store = *new_value
  }

fun subtype_examples() {
    let x: &u64 = &0;
    let y: &mut u64 = &mut 1;

x = &mut 1; // valid
    y = &2; // invalid!

read_and_assign(y, x); // valid
    read_and_assign(x, y); // invalid!
  }
}
```

will yield the following error messages

```shellscript
error:

┌── example.move:12:9 ───
    │
 12 │         y = &2; // invalid!
    │         ^ Invalid assignment to local 'y'
    ·
 12 │         y = &2; // invalid!
    │             -- The type: '&{integer}'
    ·
  9 │         let y: &mut u64 = &mut 1;
    │                -------- Is not a subtype of: '&mut u64'
    │

error:

┌── example.move:15:9 ───
    │
 15 │         read_and_assign(x, y); // invalid!
    │         ^^^^^^^^^^^^^^^^^^^^^ Invalid call of '0x42::example::read_and_assign'. Invalid argument for parameter 'store'
    ·
  8 │         let x: &u64 = &0;
    │                ---- The type: '&u64'
    ·
  3 │     fun read_and_assign(store: &mut u64, new_value: &u64) {
    │                                -------- Is not a subtype of: '&mut u64'
    │
```

The only other types currently that has subtyping are [tuples](/build/smart-contracts/book/tuples)

## Ownership

[Section titled “Ownership”](#ownership)

Both mutable and immutable references can always be copied and extended *even if there are existing copies or extensions of the same reference*:

```move
script {
  fun reference_copies(s: &mut S) {
    let s_copy1 = s; // ok
    let s_extension = &mut s.f; // also ok
    let s_copy2 = s; // still ok
    // ...
  }
}
```

This might be surprising for programmers familiar with Rust’s ownership system, which would reject the code above. Move’s type system is more permissive in its treatment of [copies](/build/smart-contracts/book/variables#move-and-copy), but equally strict in ensuring unique ownership of mutable references before writes.

### References Cannot Be Stored

[Section titled “References Cannot Be Stored”](#references-cannot-be-stored)

References and tuples are the *only* types that cannot be stored as a field value of structs, which also means that they cannot exist in global storage. All references created during program execution will be destroyed when a Move program terminates; they are entirely ephemeral. This invariant is also true for values of types without the `store` [ability](/build/smart-contracts/book/abilities), but note that references and tuples go a step further by never being allowed in structs in the first place.

This is another difference between Move and Rust, which allows references to be stored inside of structs.

Currently, Move cannot support this because references cannot be [serialized](https://en.wikipedia.org/wiki/Serialization), but *every Move value must be serializable*. This requirement comes from Move’s [persistent global storage](/build/smart-contracts/book/global-storage-structure), which needs to serialize values to persist them across program executions. Structs can be written to global storage, and thus they must be serializable.

One could imagine a fancier, more expressive, type system that would allow references to be stored in structs *and* ban those structs from existing in global storage. We could perhaps allow references inside of structs that do not have the `store` [ability](/build/smart-contracts/book/abilities), but that would not completely solve the problem: Move has a fairly complex system for tracking static reference safety, and this aspect of the type system would also have to be extended to support storing references inside of structs. In short, Move’s type system (particularly the aspects around reference safety) would have to expand to support stored references. But it is something we are keeping an eye on as the language evolves.

# Signer

`signer` is a built-in Move resource type. A `signer` is a [capability](https://en.wikipedia.org/wiki/Object-capability_model) that allows the holder to act on behalf of a particular `address`. You can think of the native implementation as being:

```move
module 0x1::signer {
  struct signer has drop { a: address }
}
```

A `signer` is somewhat similar to a Unix [UID](https://en.wikipedia.org/wiki/User_identifier) in that it represents a user authenticated by code *outside* of Move (e.g., by checking a cryptographic signature or password).

## Comparison to `address`

[Section titled “Comparison to address”](#comparison-to-address)

A Move program can create any `address` value without special permission using address literals:

```move
script {
  fun example() {
    let a1 = @0x1;
    let a2 = @0x2;
    // ... and so on for every other possible address
  }
}
```

However, `signer` values are special because they cannot be created via literals or instructions—only by the Move VM. Before the VM runs a script with parameters of type `signer`, it will automatically create `signer` values and pass them into the script:

```move
script {
    use std::signer;
    fun main(s: signer) {
        assert!(signer::address_of(&s) == @0x42, 0);
    }
}
```

This script will abort with code `0` if the script is sent from any address other than `0x42`.

A Move script can have an arbitrary number of `signer`s as long as the `signer`s are a prefix to any other arguments. In other words, all of the `signer` arguments must come first:

```move
script {
    use std::signer;
    fun main(s1: signer, s2: signer, x: u64, y: u8) {
        // ...
    }
}
```

This is useful for implementing *multi-signer scripts* that atomically act with the authority of multiple parties. For example, an extension of the script above could perform an atomic currency swap between `s1` and `s2`.

## `signer` Operators

[Section titled “signer Operators”](#signer-operators)

The `std::signer` standard library module provides two utility functions over `signer` values:

| Function                                    | Description                                                    |
| ------------------------------------------- | -------------------------------------------------------------- |
| `signer::address_of(&signer): address`      | Return the `address` wrapped by this `&signer`.                |
| `signer::borrow_address(&signer): &address` | Return a reference to the `address` wrapped by this `&signer`. |

In addition, the `move_to<T>(&signer, T)` [global storage operator](/build/smart-contracts/book/global-storage-operators) requires a `&signer` argument to publish a resource `T` under `signer.address`’s account. This ensures that only an authenticated user can elect to publish a resource under their `address`.

## Ownership

[Section titled “Ownership”](#ownership)

Unlike simple scalar values, `signer` values are not copyable, meaning they cannot be copied from any operation whether it be through an explicit [`copy`](/build/smart-contracts/book/variables#move-and-copy) instruction or through a [dereference `*`](/build/smart-contracts/book/references#reading-and-writing-through-references).

# Libraries

Aptos provides multiple useful libraries for developers. The complete up-to-date docs can be found [here](/build/smart-contracts/move-reference).

# Structs and Resources

A *struct* is a user-defined data structure containing typed fields. Structs can store any non-reference type, including other structs.

We often refer to struct values as *resources* if they cannot be copied and cannot be dropped. In this case, resource values must have ownership transferred by the end of the function. This property makes resources particularly well served for defining global storage schemas or for representing important values (such as a token).

By default, structs are linear and ephemeral. By this we mean that they: cannot be copied, cannot be dropped, and cannot be stored in global storage. This means that all values have to have ownership transferred (linear) and the values must be dealt with by the end of the program’s execution (ephemeral). We can relax this behavior by giving the struct [abilities](/build/smart-contracts/book/abilities) which allow values to be copied or dropped and also to be stored in global storage or to define global storage schemas.

## Defining Structs

[Section titled “Defining Structs”](#defining-structs)

Structs must be defined inside a module:

```move
module 0x2::m {
    struct Foo { x: u64, y: bool }
    struct Bar {}
    struct Baz { foo: Foo, }
    //                   ^ note: it is fine to have a trailing comma
}
```

Structs cannot be recursive, so the following definition is invalid:

```move
module 0x2::m {
  struct Foo { x: Foo }
  //              ^ error! Foo cannot contain Foo
}
```

For positional structs which used numbered instead of named fields, see the [positional structs](#positional-structs) section.

As mentioned above: by default, a struct declaration is linear and ephemeral. So to allow the value to be used with certain operations (that copy it, drop it, store it in global storage, or use it as a storage schema), structs can be granted [abilities](/build/smart-contracts/book/abilities) by annotating them with `has <ability>`:

```move
module 0x2::m {
  struct Foo has copy, drop { x: u64, y: bool }
}
```

For more details, see the [annotating structs](/build/smart-contracts/book/abilities#annotating-structs) section.

### Naming

[Section titled “Naming”](#naming)

Structs must start with a capital letter `A` to `Z`. After the first letter, struct names can contain underscores `_`, letters `a` to `z`, letters `A` to `Z`, or digits `0` to `9`.

```move
module 0x2::m {
  struct Foo {}
  struct BAR {}
  struct B_a_z_4_2 {}
}
```

This naming restriction of starting with `A` to `Z` is in place to give room for future language features. It may or may not be removed later.

## Using Structs

[Section titled “Using Structs”](#using-structs)

### Creating Structs

[Section titled “Creating Structs”](#creating-structs)

Values of a struct type can be created (or “packed”) by indicating the struct name, followed by value for each field:

```move
module 0x2::m {
  struct Foo has drop { x: u64, y: bool }
  struct Baz has drop { foo: Foo }

fun example() {
    let foo = Foo { x: 0, y: false };
    let baz = Baz { foo };
  }
}
```

If you initialize a struct field with a local variable whose name is the same as the field, you can use the following shorthand:

```move
module 0x2::m {
  fun example() {
    let baz = Baz { foo: foo };
    // is equivalent to
    let baz = Baz { foo };
  }
}
```

This is sometimes called “field name punning”.

### Destroying Structs via Pattern Matching

[Section titled “Destroying Structs via Pattern Matching”](#destroying-structs-via-pattern-matching)

Struct values can be destroyed by binding or assigning them patterns.

```move
module 0x2::m {
  struct Foo { x: u64, y: bool }
  struct Bar { foo: Foo }
  struct Baz {}

fun example_destroy_foo() {
    let foo = Foo { x: 3, y: false };
    let Foo { x, y: foo_y } = foo;
    //        ^ shorthand for `x: x`

// two new bindings
    //   x: u64 = 3
    //   foo_y: bool = false
  }

fun example_destroy_foo_wildcard() {
    let foo = Foo { x: 3, y: false };
    let Foo { x, y: _ } = foo;

// only one new binding since y was bound to a wildcard
    //   x: u64 = 3
  }

fun example_destroy_foo_assignment() {
    let x: u64;
    let y: bool;
    Foo { x, y } = Foo { x: 3, y: false };

// mutating existing variables x & y
    //   x = 3, y = false
  }

fun example_foo_ref() {
    let foo = Foo { x: 3, y: false };
    let Foo { x, y } = &foo;

// two new bindings
    //   x: &u64
    //   y: &bool
  }

fun example_foo_ref_mut() {
    let foo = Foo { x: 3, y: false };
    let Foo { x, y } = &mut foo;

// two new bindings
    //   x: &mut u64
    //   y: &mut bool
  }

fun example_destroy_bar() {
    let bar = Bar { foo: Foo { x: 3, y: false } };
    let Bar { foo: Foo { x, y } } = bar;
    //             ^ nested pattern

// two new bindings
    //   x: u64 = 3
    //   y: bool = false
  }

fun example_destroy_baz() {
    let baz = Baz {};
    let Baz {} = baz;
  }
}
```

### Borrowing Structs and Fields

[Section titled “Borrowing Structs and Fields”](#borrowing-structs-and-fields)

The `&` and `&mut` operator can be used to create references to structs or fields. These examples include some optional type annotations (e.g., `: &Foo`) to demonstrate the type of operations.

```move
module 0x2::m {
  fun example() {
    let foo = Foo { x: 3, y: true };
    let foo_ref: &Foo = &foo;
    let y: bool = foo_ref.y;  // reading a field via a reference to the struct
    let x_ref: &u64 = &foo.x;

let x_ref_mut: &mut u64 = &mut foo.x;
    *x_ref_mut = 42;  // modifying a field via a mutable reference
  }
}
```

It is possible to borrow inner fields of nested structs:

```move
module 0x2::m {
  fun example() {
    let foo = Foo { x: 3, y: true };
    let bar = Bar { foo };

let x_ref = &bar.foo.x;
  }
}
```

You can also borrow a field via a reference to a struct:

```move
module 0x2::m {
  fun example() {
    let foo = Foo { x: 3, y: true };
    let foo_ref = &foo;
    let x_ref = &foo_ref.x;
    // this has the same effect as let x_ref = &foo.x
  }
}
```

### Reading and Writing Fields

[Section titled “Reading and Writing Fields”](#reading-and-writing-fields)

If a field is copyable, you can read and copy a field’s value by dereferencing the borrowed field:

```move
module 0x2::m {
  fun example() {
    let foo = Foo { x: 3, y: true };
    let bar = Bar { foo: copy foo };
    let x: u64 = *&foo.x;
    let y: bool = *&foo.y;
    let foo2: Foo = *&bar.foo;
  }
}
```

The dot operator can be used to read and copy any copyable field of a struct without explicit borrowing and dereferencing:

```move
module 0x2::m {
  fun example() {
    let foo = Foo { x: 3, y: true };
    let x = foo.x;  // x == 3
    let y = foo.y;  // y == true

let bar = Bar { foo };
    let foo2: Foo = *&bar.foo; // `Foo` must be copyable
    let foo3: Foo = bar.foo;   // same as the statement above
  }
}
```

Dot operators can be chained to access nested fields:

```move
module 0x2::m {
  fun example() {
    let baz = Baz { foo: Foo { x: 3, y: true } };
    let x = baz.foo.x; // x = 3;
  }
}
```

Furthermore, the dot syntax can be used to modify fields.

```move
module 0x2::m {
  fun example() {
    let foo = Foo { x: 3, y: true };
    foo.x = 42;     // foo = Foo { x: 42, y: true }
    foo.y = !foo.y; // foo = Foo { x: 42, y: false }
    let bar = Bar { foo };            // bar = Bar { foo: Foo { x: 42, y: false } }
    bar.foo.x = 52;                   // bar = Bar { foo: Foo { x: 52, y: false } }
    bar.foo = Foo { x: 62, y: true }; // bar = Bar { foo: Foo { x: 62, y: true } }
  }
}
```

The dot syntax also works via a reference to a struct:

```move
module 0x2::m {
  fun example() {
    let foo = Foo { x: 3, y: true };
    let foo_ref = &mut foo;
    foo_ref.x = foo_ref.x + 1;
  }
}
```

## Privileged Struct Operations

[Section titled “Privileged Struct Operations”](#privileged-struct-operations)

Most struct operations on a struct type `T` can only be performed inside the module that declares `T`:

* Struct types can only be created (“packed”), destroyed (“unpacked”) inside the module that defines the struct.
* The fields of a struct are only accessible inside the module that defines the struct.

Following these rules, if you want to modify your struct outside the module, you will need to provide public APIs for them. The end of the chapter contains some examples of this.

However, struct *types* are always visible to another module or script:

m.move

```move
module 0x2::m {
  struct Foo has drop { x: u64 }

public fun new_foo(): Foo {
    Foo { x: 42 }
  }
}
```

n.move

```move
module 0x2::n {
  use 0x2::m;

struct Wrapper has drop {
    foo: m::Foo
  }

fun f1(foo: m::Foo) {
    let x = foo.x;
    //      ^ error! cannot access fields of `foo` here
  }

fun f2() {
    let foo_wrapper = Wrapper { foo: m::new_foo() };
  }
}
```

Note that structs do not have visibility modifiers (e.g., `public` or `private`).

## Ownership

[Section titled “Ownership”](#ownership)

As mentioned above in [Defining Structs](#defining-structs), structs are by default linear and ephemeral. This means they cannot be copied or dropped. This property can be very useful when modeling real world resources like money, as you do not want money to be duplicated or get lost in circulation.

```move
module 0x2::m {
  struct Foo { x: u64 }

public fun copying_resource() {
    let foo = Foo { x: 100 };
    let foo_copy = copy foo; // error! 'copy'-ing requires the 'copy' ability
    let foo_ref = &foo;
    let another_copy = *foo_ref // error! dereference requires the 'copy' ability
  }

public fun destroying_resource1() {
    let foo = Foo { x: 100 };

// error! when the function returns, foo still contains a value.
    // This destruction requires the 'drop' ability
  }

public fun destroying_resource2(f: &mut Foo) {
    *f = Foo { x: 100 } // error!
                        // destroying the old value via a write requires the 'drop' ability
  }
}
```

To fix the second example (`fun destroying_resource1`), you would need to manually “unpack” the resource:

```move
module 0x2::m {
  struct Foo { x: u64 }

public fun destroying_resource1_fixed() {
    let foo = Foo { x: 100 };
    let Foo { x: _ } = foo;
  }
}
```

Recall that you are only able to deconstruct a resource within the module in which it is defined. This can be leveraged to enforce certain invariants in a system, for example, conservation of money.

If on the other hand, your struct does not represent something valuable, you can add the abilities `copy` and `drop` to get a struct value that might feel more familiar from other programming languages:

```move
module 0x2::m {
  struct Foo has copy, drop { x: u64 }

public fun run() {
    let foo = Foo { x: 100 };
    let foo_copy = copy foo;
    // ^ this code copies foo, whereas `let x = foo` or
    // `let x = move foo` both move foo

let x = foo.x;            // x = 100
    let x_copy = foo_copy.x;  // x = 100

// both foo and foo_copy are implicitly discarded when the function returns
  }
}
```

## Positional Structs

[Section titled “Positional Structs”](#positional-structs)

*Since language version 2.0*

A struct can be declared to have *positional fields*, fields which are not named but numbered. Positional structs behave similar to regular structs, except providing a different syntax which may be more suitable for use cases with only a few fields.

Fields of positional structs are assigned in the order they appear. In the below example, field `0` is of type `u64` and field `1` of type `u8`:

```move
module 0x2::m {
  struct Pair(u64, u8);
}
```

Abilities for positional structs are declared *after* and not before the field list,

```move
module 0x2::m {
  struct Pair(u64, u8) has copy, drop;
}
```

For pure type tags, often used for phantom types in Move code, the list of arguments can be also completely omitted:

```move
module 0x2::m {
  struct TypeTag has copy, drop;
}
```

Values of positional structs are created and deconstructed as shown below: using `PositionalStructs(arguments)`:

```move
module 0x2::m {
  fun work() {
    let value = Pair(1, true);
    let Pair(number, boolean) = value;
    assert!(number == 1 && boolean == true);
  }
}
```

Fields of positional structs can be accessed using the position as a field selector. For example, in the above code example, `value.0` and `value.1` can be used to access the two fields without deconstructing the `value`. `positional_struct.0`.

## Partial Patterns

[Section titled “Partial Patterns”](#partial-patterns)

*Since language version 2.0*

Patterns can use the `..` notation to match any remaining, non-listed fields in structs or variants with named fields, and omitted fields at either the beginning or end of a struct or variant with positional fields. Here are some examples:

```move
module 0x2::m {
  struct Foo{ x: u8, y: u16, z: u32 }
  struct Bar(u8, u16, u32);

fun foo_get_x(self: &Foo): u16 {
    let Foo{y, ..} = self;
    x
  }

fun bar_get_0(self: &Foo): u8 {
    let Bar(x, ..) = self;
    x
  }

fun bar_get_2(self: &Foo): u52 {
    // For positional structs, one can also put the
    // .. at the beginning.
    let Bar(.., z) = self;
    z
  }
}
```

Notice that partial patterns can currently not be used as the left-hand side of assignment. While one can use `let Bar(x, ..) = v`, we do not yet support `let x; Bar(x, ..) = v`.

## Storing Resources in Global Storage

[Section titled “Storing Resources in Global Storage”](#storing-resources-in-global-storage)

Structs with the `key` ability can be saved directly in [persistent global storage](/build/smart-contracts/book/global-storage-operators). All values stored within those `key` structs must have the `store` ability. See the [ability](/build/smart-contracts/book/abilities) and [global storage](/build/smart-contracts/book/global-storage-operators) chapters for more detail.

## Examples

[Section titled “Examples”](#examples)

Here are two short examples of how you might use structs to represent valuable data (in the case of `Coin`) or more classical data (in the case of `Point` and `Circle`).

### Example 1: Coin

[Section titled “Example 1: Coin”](#example-1-coin)

```move
module 0x2::m {
  // We do not want the Coin to be copied because that would be duplicating this "money",
  // so we do not give the struct the 'copy' ability.
  // Similarly, we do not want programmers to destroy coins, so we do not give the struct the
  // 'drop' ability.
  // However, we *want* users of the modules to be able to store this coin in persistent global
  // storage, so we grant the struct the 'store' ability. This struct will only be inside of
  // other resources inside of global storage, so we do not give the struct the 'key' ability.
  struct Coin has store {
    value: u64,
  }

public fun mint(value: u64): Coin {
    // You would want to gate this function with some form of access control to prevent
    // anyone using this module from minting an infinite amount of coins.
    Coin { value }
  }

public fun withdraw(coin: &mut Coin, amount: u64): Coin {
    assert!(coin.value >= amount, 1000);
    coin.value = coin.value - amount;
    Coin { value: amount }
  }

public fun deposit(coin: &mut Coin, other: Coin) {
    let Coin { value } = other;
    coin.value = coin.value + value;
  }

public fun split(coin: Coin, amount: u64): (Coin, Coin) {
    let other = withdraw(&mut coin, amount);
    (coin, other)
  }

public fun merge(coin1: Coin, coin2: Coin): Coin {
    deposit(&mut coin1, coin2);
    coin1
  }

public fun destroy_zero(coin: Coin) {
    let Coin { value } = coin;
    assert!(value == 0, 1001);
  }
}
```

### Example 2: Geometry

[Section titled “Example 2: Geometry”](#example-2-geometry)

```move
module 0x2::point {
  struct Point has copy, drop, store {
    x: u64,
    y: u64,
  }

public fun new(x: u64, y: u64): Point {
    Point {
      x, y
    }
  }

public fun x(p: &Point): u64 {
    p.x
  }

public fun y(p: &Point): u64 {
    p.y
  }

fun abs_sub(a: u64, b: u64): u64 {
    if (a < b) {
      b - a
    }
    else {
      a - b
    }
  }

public fun dist_squared(p1: &Point, p2: &Point): u64 {
    let dx = abs_sub(p1.x, p2.x);
    let dy = abs_sub(p1.y, p2.y);
    dx*dx + dy*dy
  }
}
```

```move
module 0x2::circle {
  use 0x2::point::{Self, Point};

struct Circle has copy, drop, store {
    center: Point,
    radius: u64,
  }

public fun new(center: Point, radius: u64): Circle {
    Circle { center, radius }
  }

public fun overlaps(c1: &Circle, c2: &Circle): bool {
    let dist_squared_value = point::dist_squared(&c1.center, &c2.center);
    let r1 = c1.radius;
    let r2 = c2.radius;
    dist_squared_value <= r1*r1 + 2*r1*r2 + r2*r2
  }
}
```

# Table of Contents

## Getting Started

[Section titled “Getting Started”](#getting-started)

* [Modules and Scripts](/build/smart-contracts/book/modules-and-scripts)
* [Move Tutorial](/build/smart-contracts/book/move-tutorial)

## Language Release Notes

[Section titled “Language Release Notes”](#language-release-notes)

* [Move 2](/build/smart-contracts/book/move-2)

## Primitive Types

[Section titled “Primitive Types”](#primitive-types)

* [Integers](/build/smart-contracts/book/integers)
* [Bool](/build/smart-contracts/book/bool)
* [Address](/build/smart-contracts/book/address)
* [Vector](/build/smart-contracts/book/vector)
* [Signer](/build/smart-contracts/book/signer)
* [References](/build/smart-contracts/book/references)
* [Tuples and Unit](/build/smart-contracts/book/tuples)

## Basic Concepts

[Section titled “Basic Concepts”](#basic-concepts)

* [Local Variables and Scopes](/build/smart-contracts/book/variables)
* [Equality](/build/smart-contracts/book/equality)
* [Abort and Assert](/build/smart-contracts/book/abort-and-assert)
* [Conditionals](/build/smart-contracts/book/conditionals)
* [While, For, and Loop](/build/smart-contracts/book/loops)
* [Functions](/build/smart-contracts/book/functions)
* [Structs and Resources](/build/smart-contracts/book/structs-and-resources)
* [Enum Types](/build/smart-contracts/book/enums)
* [Constants](/build/smart-contracts/book/constants)
* [Generics](/build/smart-contracts/book/generics)
* [Type Abilities](/build/smart-contracts/book/abilities)
* [Uses and Aliases](/build/smart-contracts/book/uses)
* [Friends](/build/smart-contracts/book/friends)
* [Packages](/build/smart-contracts/book/packages)
* [Package Upgrades](/build/smart-contracts/book/package-upgrades)
* [Unit Tests](/build/smart-contracts/book/unit-testing)

## Global Storage

[Section titled “Global Storage”](#global-storage)

* [Global Storage Structure](/build/smart-contracts/book/global-storage-structure)
* [Global Storage Operators](/build/smart-contracts/book/global-storage-operators)

## Reference

[Section titled “Reference”](#reference)

* [Standard Library](/build/smart-contracts/book/standard-library)
* [Coding Conventions](/build/smart-contracts/book/coding-conventions)

# Tuples and Unit

Move does not fully support tuples as one might expect coming from another language with them as a [first-class value](https://en.wikipedia.org/wiki/First-class_citizen). However, in order to support multiple return values, Move has tuple-like expressions. These expressions do not result in a concrete value at runtime (there are no tuples in the bytecode), and as a result they are very limited: they can only appear in expressions (usually in the return position for a function); they cannot be bound to local variables; they cannot be stored in structs; and tuple types cannot be used to instantiate generics.

Similarly, [unit `()`](https://en.wikipedia.org/wiki/Unit_type) is a type created by the Move source language in order to be expression based. The unit value `()` does not result in any runtime value. We can consider unit`()` to be an empty tuple, and any restrictions that apply to tuples also apply to unit.

It might feel weird to have tuples in the language at all given these restrictions. But one of the most common use cases for tuples in other languages is for functions to allow functions to return multiple values. Some languages work around this by forcing the users to write structs that contain the multiple return values. However, in Move, you cannot put references inside of [structs](/build/smart-contracts/book/structs-and-resources). This required Move to support multiple return values. These multiple return values are all pushed on the stack at the bytecode level. At the source level, these multiple return values are represented using tuples.

## Literals

[Section titled “Literals”](#literals)

Tuples are created by a comma separated list of expressions inside of parentheses.

| Syntax          | Type                                                                         | Description                                                  |
| --------------- | ---------------------------------------------------------------------------- | ------------------------------------------------------------ |
| `()`            | `(): ()`                                                                     | Unit, the empty tuple, or the tuple of arity 0               |
| `(e1, ..., en)` | `(e1, ..., en): (T1, ..., Tn)` where `e_i: Ti` s.t. `0 < i <= n` and `n > 0` | A `n`-tuple, a tuple of arity `n`, a tuple with `n` elements |

Note that `(e)` does not have type `(e): (t)`, in other words there is no tuple with one element. If there is only a single element inside the parentheses, the parentheses are only used for disambiguation and do not carry any other special meaning.

Sometimes, tuples with two elements are called “pairs” and tuples with three elements are called “triples.”

### Examples

[Section titled “Examples”](#examples)

```move
module 0x42::example {
  // all 3 of these functions are equivalent

// when no return type is provided, it is assumed to be `()`
  fun returns_unit_1() { }

// there is an implicit () value in empty expression blocks
  fun returns_unit_2(): () { }

// explicit version of `returns_unit_1` and `returns_unit_2`
  fun returns_unit_3(): () { () }

fun returns_3_values(): (u64, bool, address) {
    (0, false, @0x42)
  }
  fun returns_4_values(x: &u64): (&u64, u8, u128, vector<u8>) {
    (x, 0, 1, b"foobar")
  }
}
```

## Operations

[Section titled “Operations”](#operations)

The only operation that can be done on tuples currently is destructuring.

### Destructuring

[Section titled “Destructuring”](#destructuring)

For tuples of any size, they can be destructured in either a `let` binding or in an assignment.

For example:

```move
module 0x42::example {
  // all 3 of these functions are equivalent
  fun returns_unit() {}
  fun returns_2_values(): (bool, bool) { (true, false) }
  fun returns_4_values(x: &u64): (&u64, u8, u128, vector<u8>) { (x, 0, 1, b"foobar") }

fun examples(cond: bool) {
    let () = ();
    let (x, y): (u8, u64) = (0, 1);
    let (a, b, c, d) = (@0x0, 0, false, b"");

() = ();
    (x, y) = if (cond) (1, 2) else (3, 4);
    (a, b, c, d) = (@0x1, 1, true, b"1");
  }

fun examples_with_function_calls() {
    let () = returns_unit();
    let (x, y): (bool, bool) = returns_2_values();
    let (a, b, c, d) = returns_4_values(&0);

() = returns_unit();
    (x, y) = returns_2_values();
    (a, b, c, d) = returns_4_values(&1);
  }
}
```

For more details, see [Move Variables](/build/smart-contracts/book/variables).

## Subtyping

[Section titled “Subtyping”](#subtyping)

Along with references, tuples are the only other type that have [subtyping](https://en.wikipedia.org/wiki/Subtyping) in Move. Tuples have subtyping only in the sense that they subtype with references (in a covariant way).

For example:

```move
script {
  fun example() {
    let x: &u64 = &0;
    let y: &mut u64 = &mut 1;

// (&u64, &mut u64) is a subtype of (&u64, &u64)
    // since &mut u64 is a subtype of &u64
    let (a, b): (&u64, &u64) = (x, y);

// (&mut u64, &mut u64) is a subtype of (&u64, &u64)
    // since &mut u64 is a subtype of &u64
    let (c, d): (&u64, &u64) = (y, y);

// error! (&u64, &mut u64) is NOT a subtype of (&mut u64, &mut u64)
    // since &u64 is NOT a subtype of &mut u64
    let (e, f): (&mut u64, &mut u64) = (x, y);
  }
}
```

## Ownership

[Section titled “Ownership”](#ownership)

As mentioned above, tuple values don’t really exist at runtime. And currently they cannot be stored into local variables because of this (but it is likely that this feature will come soon). As such, tuples can only be moved currently, as copying them would require putting them into a local variable first.

# Unit Tests

Unit testing for Move adds three new annotations to the Move source language:

* `#[test]`
* `#[test_only]`, and
* `#[expected_failure]`.

They respectively mark a function as a test, mark a module or module member (`use`, function, or struct) as code to be included for testing only, and mark that a test is expected to fail. These annotations can be placed on a function with any visibility. Whenever a module or module member is annotated as `#[test_only]` or `#[test]`, it will not be included in the compiled bytecode unless it is compiled for testing.

## Testing Annotations: Their Meaning and Usage

[Section titled “Testing Annotations: Their Meaning and Usage”](#testing-annotations-their-meaning-and-usage)

Both the `#[test]` and `#[expected_failure]` annotations can be used either with or without arguments.

Without arguments, the `#[test]` annotation can only be placed on a function with no parameters. This annotation simply marks this function as a test to be run by the unit testing harness.

```move
module 0x42::example {
  #[test] // OK
  fun this_is_a_test() { /* ... */ }

#[test] // Will fail to compile since the test takes an argument
  fun this_is_not_correct(arg: signer) { /* ... */ }
}
```

### Expected Failure

[Section titled “Expected Failure”](#expected-failure)

A test can also be annotated as an `#[expected_failure]`. This annotation marks that the test is expected to raise an error.

You can ensure that a test is aborting with a specific abort `<code>` by annotating it with `#[expected_failure(abort_code = <code>)]`, corresponding to the parameter to an `abort` statement (or failing `assert!` macro).

Instead of an `abort_code`, an `expected_failure` may specify program execution errors, such as `arithmetic_error`, `major_status`, `vector_error`, and `out_of_gas`. For more specificity, a `minor_status` may optionally be specified.

If the error is expected from a specific location, that may also be specified: `#[expected_failure(abort_code = <code>, location = <loc>)]`. If the test then fails with the right error but in a different module, the test will also fail. Note that `<loc>` can be `Self`(in the current module) or a qualified name, e.g. `vector::std`.

Only functions that have the `#[test]` annotation can also be annotated as an #`[expected_failure]`.

```move
module 0x42::example {
  #[test]
  #[expected_failure]
  public fun this_test_will_abort_and_pass() { abort 1 }

#[test]
  #[expected_failure]
  public fun test_will_error_and_pass() { 1/0; }

#[test]
  #[expected_failure(abort_code = 0, location = Self)]
  public fun test_will_error_and_fail() { 1/0; }

#[test, expected_failure] // Can have multiple in one attribute. This test will pass.
  public fun this_other_test_will_abort_and_pass() { abort 1 }

#[test]
  #[expected_failure(vector_error, minor_status = 1, location = Self)]
  fun borrow_out_of_range() { /* ... */ }
  #[test]
  #[expected_failure(abort_code = 26113, location = extensions::table)]
  fun test_destroy_fails() { /* ... */ }
}
```

### Test parameters

[Section titled “Test parameters”](#test-parameters)

With arguments, a test annotation takes the form `#[test(<param_name_1> = <address>, ..., <param_name_n> = <address>)]`. If a function is annotated in such a manner, the function’s parameters must be a permutation of the parameters `<param_name_1>, ..., <param_name_n>`, i.e., the order of these parameters as they occur in the function and their order in the test annotation do not have to be the same, but they must be able to be matched up with each other by name.

Only parameters with a type of `signer` are supported as test parameters. If a parameter other than `signer` is supplied, the test will result in an error when run.

```move
module 0x42::example {
  #[test(arg = @0xC0FFEE)] // OK
  fun this_is_correct_now(arg: signer) { /* ... */ }

#[test(wrong_arg_name = @0xC0FFEE)] // Not correct: arg name doesn't match
  fun this_is_incorrect(arg: signer) { /* ... */ }

#[test(a = @0xC0FFEE, b = @0xCAFE)] // OK. We support multiple signer arguments, but you must always provide a value for that argument
  fun this_works(a: signer, b: signer) { /* ... */ }

// somewhere a named address is declared
  #[test_only] // test-only named addresses are supported
  address TEST_NAMED_ADDR = @0x1;
  ...
  #[test(arg = @TEST_NAMED_ADDR)] // Named addresses are supported!
  fun this_is_correct_now(arg: signer) { /* ... */ }
}
```

### Arbitrary code to support tests

[Section titled “Arbitrary code to support tests”](#arbitrary-code-to-support-tests)

A module and any of its members can be declared as test only. In such a case the item will only be included in the compiled Move bytecode when compiled in test mode. Additionally, when compiled outside of test mode, any non-test `use`s of a `#[test_only]` module will raise an error during compilation.

```move
#[test_only] // test only attributes can be attached to modules
module 0x42::abc { /*... */ }

module 0x42::other {
  #[test_only] // test only attributes can be attached to named addresses
  address ADDR = @0x1;

#[test_only] // .. to uses
  use 0x1::some_other_module;

#[test_only] // .. to structs
  struct SomeStruct { /* ... */ }

#[test_only] // .. and functions. Can only be called from test code, but not a test
  fun test_only_function(/* ... */) { /* ... */ }
}
```

## Running Unit Tests

[Section titled “Running Unit Tests”](#running-unit-tests)

Unit tests for a Move package can be run with the `aptos move test` command. See [package](/build/smart-contracts/book/packages) for more info.

When running tests, every test will either `PASS`, `FAIL`, or `TIMEOUT`. If a test case fails, the location of the failure along with the function name that caused the failure will be reported if possible. You can see an example of this below.

A test will be marked as timing out if it exceeds the maximum number of instructions that can be executed for any single test. This bound can be changed using the options below, and its default value is set to 100000 instructions. Additionally, while the result of a test is always deterministic, tests are run in parallel by default, so the ordering of test results in a test run is non-deterministic unless running with only one thread (see `OPTIONS` below).

There are also a number of options that can be passed to the unit testing binary to fine-tune testing and to help debug failing tests. These can be found using the help flag:

```shellscript
$ aptos move test -h
```

## Example

[Section titled “Example”](#example)

A simple module using some of the unit testing features is shown in the following example:

First create an empty package inside an empty directory:

```shellscript
$ aptos move init --name TestExample
```

Next add the following to the `Move.toml`:

```toml
[dependencies]
MoveStdlib = { git = "https://github.com/aptos-labs/aptos-framework.git", subdir="aptos-move/framework/move-stdlib", rev = "main", addr_subst = { "std" = "0x1" } }
```

Next add the following module under the `sources` directory:

sources/my\_module.move

```move
module 0x1::my_module {

struct MyCoin has key { value: u64 }

public fun make_sure_non_zero_coin(coin: MyCoin): MyCoin {
    assert!(coin.value > 0, 0);
    coin
  }

public fun has_coin(addr: address): bool {
    exists<MyCoin>(addr)
  }

#[test]
  fun make_sure_non_zero_coin_passes() {
    let coin = MyCoin { value: 1 };
    let MyCoin { value: _ } = make_sure_non_zero_coin(coin);
  }

#[test]
  // Or #[expected_failure] if we don't care about the abort code
  #[expected_failure(abort_code = 0, location = Self)]
  fun make_sure_zero_coin_fails() {
    let coin = MyCoin { value: 0 };
    let MyCoin { value: _ } = make_sure_non_zero_coin(coin);
  }

#[test_only] // test only helper function
  fun publish_coin(account: &signer) {
    move_to(account, MyCoin { value: 1 })
  }

#[test(a = @0x1, b = @0x2)]
  fun test_has_coin(a: signer, b: signer) {
    publish_coin(&a);
    publish_coin(&b);
    assert!(has_coin(@0x1), 0);
    assert!(has_coin(@0x2), 1);
    assert!(!has_coin(@0x3), 1);
  }
}
```

### Running Tests

[Section titled “Running Tests”](#running-tests)

You can then run these tests with the `aptos move test` command:

```shellscript
$ aptos move test
BUILDING MoveStdlib
BUILDING TestExample
Running Move unit tests
[ PASS    ] 0x1::my_module::make_sure_non_zero_coin_passes
[ PASS    ] 0x1::my_module::make_sure_zero_coin_fails
[ PASS    ] 0x1::my_module::test_has_coin
Test result: OK. Total tests: 3; passed: 3; failed: 0
```

### Using Test Flags

[Section titled “Using Test Flags”](#using-test-flags)

#### `-f <str>` or `--filter <str>`

[Section titled “-f \<str> or --filter \<str>”](#-f-str-or---filter-str)

This will only run tests whose fully qualified name contains `<str>`. For example if we wanted to only run tests with `"zero_coin"` in their name:

```shellscript
$ aptos move test -f zero_coin
CACHED MoveStdlib
BUILDING TestExample
Running Move unit tests
[ PASS    ] 0x1::my_module::make_sure_non_zero_coin_passes
[ PASS    ] 0x1::my_module::make_sure_zero_coin_fails
Test result: OK. Total tests: 2; passed: 2; failed: 0
```

#### `--coverage`

[Section titled “--coverage”](#--coverage)

This will compute code being covered by test cases and generate coverage summary.

```shellscript
$ aptos move test --coverage
INCLUDING DEPENDENCY AptosFramework
INCLUDING DEPENDENCY AptosStdlib
INCLUDING DEPENDENCY MoveStdlib
BUILDING TestExample
Running Move unit tests
[ PASS    ] 0x1::my_module::make_sure_non_zero_coin_passes
[ PASS    ] 0x1::my_module::make_sure_zero_coin_fails
[ PASS    ] 0x1::my_module::test_has_coin
Test result: OK. Total tests: 3; passed: 3; failed: 0
+-------------------------+
| Move Coverage Summary   |
+-------------------------+
Module 0000000000000000000000000000000000000000000000000000000000000001::my_module
>>> % Module coverage: 100.00
+-------------------------+
| % Move Coverage: 100.00  |
+-------------------------+
Please use `aptos move coverage -h` for more detailed source or bytecode test coverage of this package
```

Then by running `aptos move coverage`, we can get more detailed coverage information. These can be found using the help flag:

```shellscript
$ aptos move coverage -h
```

# Uses and Aliases

The `use` syntax can be used to create aliases to members in other modules. `use` can be used to create aliases that last either for the entire module, or for a given expression block scope.

## Syntax

[Section titled “Syntax”](#syntax)

There are several different syntax cases for `use`. Starting with the most simple, we have the following for creating aliases to other modules

```move
use <address>::<module name>;
use <address>::<module name> as <module alias name>;
```

For example

```move
script {
  use std::vector;
  use std::vector as V;
}
```

`use std::vector;` introduces an alias `vector` for `std::vector`. This means that anywhere you would want to use the module name `std::vector` (assuming this `use` is in scope), you could use `vector` instead. `use std::vector;` is equivalent to `use std::vector as vector;`

Similarly `use std::vector as V;` would let you use `V` instead of `std::vector`

```move
module 0x42::example {
  use std::vector;
  use std::vector as V;

fun new_vecs(): (vector<u8>, vector<u8>, vector<u8>) {
    let v1 = std::vector::empty();
    let v2 = vector::empty();
    let v3 = V::empty();
    (v1, v2, v3)
  }
}
```

If you want to import a specific module member (such as a function, struct, or constant). You can use the following syntax.

```move
use <address>::<module name>::<module member>;
use <address>::<module name>::<module member> as <member alias>;
```

For example

```move
script {
  use std::vector::empty;
  use std::vector::empty as empty_vec;
}
```

This would let you use the function `std::vector::empty` without full qualification. Instead, you could use `empty` and `empty_vec` respectively. Again, `use std::vector::empty;` is equivalent to `use std::vector::empty as empty;`

```move
module 0x42::example {
  use std::vector::empty;
  use std::vector::empty as empty_vec;

fun new_vecs(): (vector<u8>, vector<u8>, vector<u8>) {
    let v1 = std::vector::empty();
    let v2 = empty();
    let v3 = empty_vec();
    (v1, v2, v3)
  }
}
```

If you want to add aliases for multiple module members at once, you can do so with the following syntax

```move
use <address>::<module name>::{<module member>, <module member> as <member alias> ... };
```

For example

```move
module 0x42::example {
  use std::vector::{push_back, length as len, pop_back};

fun swap_last_two<T>(v: &mut vector<T>) {
    assert!(len(v) >= 2, 42);
    let last = pop_back(v);
    let second_to_last = pop_back(v);
    push_back(v, last);
    push_back(v, second_to_last)
  }
}
```

If you need to add an alias to the Module itself in addition to module members, you can do that in a single `use` using `Self`. `Self` is a member of sorts that refers to the module.

```move
script {
  use std::vector::{Self, empty};
}
```

For clarity, all the following are equivalent:

```move
script {
  use std::vector;
  use std::vector as vector;
  use std::vector::Self;
  use std::vector::Self as vector;
  use std::vector::{Self};
  use std::vector::{Self as vector};
}
```

If needed, you can have as many aliases for any item as you like

```move
module 0x42::example {
  use std::vector::{
    Self,
    Self as V,
    length,
    length as len,
  };

fun pop_twice<T>(v: &mut vector<T>): (T, T) {
    // all options available given the `use` above
    assert!(vector::length(v) > 1, 42);
    assert!(V::length(v) > 1, 42);
    assert!(length(v) > 1, 42);
    assert!(len(v) > 1, 42);

(vector::pop_back(v), vector::pop_back(v))
  }
}
```

## Inside a `module`

[Section titled “Inside a module”](#inside-a-module)

Inside a `module` all `use` declarations are usable regardless of the order of declaration.

```move
module 0x42::example {
  use std::vector;

fun example(): vector<u8> {
    let v = empty();
    vector::push_back(&mut v, 0);
    vector::push_back(&mut v, 10);
    v
  }

use std::vector::empty;
}
```

The aliases declared by `use` in the module are usable within that module.

Additionally, the aliases introduced cannot conflict with other module members. See [Uniqueness](#uniqueness) for more details

## Inside an expression

[Section titled “Inside an expression”](#inside-an-expression)

You can add `use` declarations to the beginning of any expression block

```move
module 0x42::example {

fun example(): vector<u8> {
    use std::vector::{empty, push_back};

let v = empty();
    push_back(&mut v, 0);
    push_back(&mut v, 10);
    v
  }
}
```

As with `let`, the aliases introduced by `use` in an expression block are removed at the end of that block.

```move
module 0x42::example {

fun example(): vector<u8> {
    let result = {
      use std::vector::{empty, push_back};
      let v = empty();
      push_back(&mut v, 0);
      push_back(&mut v, 10);
      v
    };
    result
  }
}
```

Attempting to use the alias after the block ends will result in an error

```move
module 0x42::example {
  fun example(): vector<u8> {
    let result = {
      use std::vector::{empty, push_back};
      let v = empty();
      push_back(&mut v, 0);
      push_back(&mut v, 10);
      v
    };
    let v2 = empty(); // ERROR!
//           ^^^^^ unbound function 'empty'
    result
  }
}
```

Any `use` must be the first item in the block. If the `use` comes after any expression or `let`, it will result in a parsing error

```move
script {
  fun example() {
    {
      let x = 0;
      use std::vector; // ERROR!
      let v = vector::empty();
    }
  }
}
```

## Naming rules

[Section titled “Naming rules”](#naming-rules)

Aliases must follow the same rules as other module members. This means that aliases to structs or constants must start with `A` to `Z`

```move
address 0x42 {
  module data {
    struct S {}
    const FLAG: bool = false;
    fun foo() {}
  }
  module example {
    use 0x42::data::{
      S as s, // ERROR!
      FLAG as fLAG, // ERROR!
      foo as FOO,  // valid
      foo as bar, // valid
    };
  }
}
```

## Uniqueness

[Section titled “Uniqueness”](#uniqueness)

Inside a given scope, all aliases introduced by `use` declarations must be unique.

For a module, this means aliases introduced by `use` cannot overlap

```move
module 0x42::example {
  use std::vector::{empty as foo, length as foo}; // ERROR!
  //                                        ^^^ duplicate 'foo'

use std::vector::empty as bar;
  use std::vector::length as bar; // ERROR!
  //                         ^^^ duplicate 'bar'
}
```

And, they cannot overlap with any of the module’s other members

```move
address 0x42 {
  module data {
    struct S {}
  }
  module example {
    use 0x42::data::S;

struct S { value: u64 } // ERROR!
    //     ^ conflicts with alias 'S' above
  }
}
```

Inside an expression block, they cannot overlap with each other, but they can [shadow](#shadowing) other aliases or names from an outer scope

## Shadowing

[Section titled “Shadowing”](#shadowing)

`use` aliases inside of an expression block can shadow names (module members or aliases) from the outer scope. As with shadowing of locals, the shadowing ends at the end of the expression block;

```move
module 0x42::example {

struct WrappedVector { vec: vector<u64> }

fun empty(): WrappedVector {
    WrappedVector { vec: std::vector::empty() }
  }

fun example1(): (WrappedVector, WrappedVector) {
    let vec = {
      use std::vector::{empty, push_back};
      // 'empty' now refers to std::vector::empty

let v = empty();
      push_back(&mut v, 0);
      push_back(&mut v, 1);
      push_back(&mut v, 10);
      v
    };
    // 'empty' now refers to Self::empty

(empty(), WrappedVector { vec })
  }

fun example2(): (WrappedVector, WrappedVector) {
    use std::vector::{empty, push_back};
    let w: WrappedVector = {
      use 0x42::example::empty;
      empty()
    };
    push_back(&mut w.vec, 0);
    push_back(&mut w.vec, 1);
    push_back(&mut w.vec, 10);

let vec = empty();
    push_back(&mut vec, 0);
    push_back(&mut vec, 1);
    push_back(&mut vec, 10);

(w, WrappedVector { vec })
  }
}
```

## Unused Use or Alias

[Section titled “Unused Use or Alias”](#unused-use-or-alias)

An unused `use` will result in an error

```move
module 0x42::example {
  use std::vector::{empty, push_back}; // ERROR!
  //                       ^^^^^^^^^ unused alias 'push_back'

fun example(): vector<u8> {
    empty()
  }
}
```

# Local Variables and Scope

Local variables in Move are lexically (statically) scoped. New variables are introduced with the keyword `let`, which will shadow any previous local with the same name. Locals are mutable and can be updated both directly and via a mutable reference.

## Declaring Local Variables

[Section titled “Declaring Local Variables”](#declaring-local-variables)

### `let` bindings

[Section titled “let bindings”](#let-bindings)

Move programs use `let` to bind variable names to values:

```move
script {
  fun example() {
    let x = 1;
    let y = x + x;
  }
}
```

`let` can also be used without binding a value to the local.

```move
script {
  fun example() {
    let x;
  }
}
```

The local can then be assigned a value later.

```move
script {
  fun example() {
    let x;
    if (cond) {
      x = 1
    } else {
      x = 0
    }
  }
}
```

This can be very helpful when trying to extract a value from a loop when a default value cannot be provided.

```move
script {
  fun example() {
    let x;
    let cond = true;
    let i = 0;
    loop {
      (x, cond) = foo(i);
      if (!cond) break;
      i = i + 1;
    }
  }
}
```

### Variables must be assigned before use

[Section titled “Variables must be assigned before use”](#variables-must-be-assigned-before-use)

Move’s type system prevents a local variable from being used before it has been assigned.

```move
script {
  fun example() {
    let x;
    x + x; // ERROR!
  }
}
```

```move
script {
  fun example() {
    let x;
    if (cond) x = 0;
    x + x; // ERROR!
  }
}
```

```move
script {
  fun example() {
    let x;
    while (cond) x = 0;
    x + x; // ERROR!
  }
}
```

### Valid variable names

[Section titled “Valid variable names”](#valid-variable-names)

Variable names can contain underscores `_`, letters `a` to `z`, letters `A` to `Z`, and digits `0` to `9`. Variable names must start with either an underscore `_` or a letter `a` through `z`. They *cannot* start with uppercase letters.

```move
script {
  fun example() {
    // all valid
    let x = e;
    let _x = e;
    let _A = e;
    let x0 = e;
    let xA = e;
    let foobar_123 = e;

// all invalid
    let X = e; // ERROR!
    let Foo = e; // ERROR!
  }
}
```

### Type annotations

[Section titled “Type annotations”](#type-annotations)

The type of local variable can almost always be inferred by Move’s type system. However, Move allows explicit type annotations that can be useful for readability, clarity, or debuggability. The syntax for adding a type annotation is:

```move
script {
  fun example() {
    let x: T = e; // "Variable x of type T is initialized to expression e"
  }
}
```

Some examples of explicit type annotations:

```move
module 0x42::example {

struct S { f: u64, g: u64 }

fun annotated() {
    let u: u8 = 0;
    let b: vector<u8> = b"hello";
    let a: address = @0x0;
    let (x, y): (&u64, &mut u64) = (&0, &mut 1);
    let S { f, g: f2 }: S = S { f: 0, g: 1 };
  }
}
```

Note that the type annotations must always be to the right of the pattern:

```move
script {
  fun example() {
    let (x: &u64, y: &mut u64) = (&0, &mut 1); // ERROR! should be let (x, y): ... =
  }
}
```

### When annotations are necessary

[Section titled “When annotations are necessary”](#when-annotations-are-necessary)

In some cases, a local type annotation is required if the type system cannot infer the type. This commonly occurs when the type argument for a generic type cannot be inferred. For example:

```move
script {
  fun example() {
    let _v1 = vector::empty(); // ERROR!
    //        ^^^^^^^^^^^^^^^ Could not infer this type. Try adding an annotation
    let v2: vector<u64> = vector::empty(); // no error
  }
}
```

In a rarer case, the type system might not be able to infer a type for divergent code (where all the following code is unreachable). Both `return` and [`abort`](/build/smart-contracts/book/abort-and-assert) are expressions and can have any type. A [`loop`](/build/smart-contracts/book/loops) has type `()` if it has a `break`, but if there is no break out of the `loop`, it could have any type. If these types cannot be inferred, a type annotation is required. For example, this code:

```move
script {
  fun example() {
    let a: u8 = return ();
    let b: bool = abort 0;
    let c: signer = loop ();

let x = return (); // ERROR!
    //  ^ Could not infer this type. Try adding an annotation
    let y = abort 0; // ERROR!
    //  ^ Could not infer this type. Try adding an annotation
    let z = loop (); // ERROR!
    //  ^ Could not infer this type. Try adding an annotation
  }
}
```

Adding type annotations to this code will expose other errors about dead code or unused local variables, but the example is still helpful for understanding this problem.

### Multiple declarations with tuples

[Section titled “Multiple declarations with tuples”](#multiple-declarations-with-tuples)

`let` can introduce more than one local at a time using tuples. The locals declared inside the parenthesis are initialized to the corresponding values from the tuple.

```move
script {
  fun example() {
    let () = ();
    let (x0, x1) = (0, 1);
    let (y0, y1, y2) = (0, 1, 2);
    let (z0, z1, z2, z3) = (0, 1, 2, 3);
  }
}
```

The type of the expression must match the arity of the tuple pattern exactly.

```move
script {
  fun example() {
    let (x, y) = (0, 1, 2); // ERROR!
    let (x, y, z, q) = (0, 1, 2); // ERROR!
  }
}
```

You cannot declare more than one local with the same name in a single `let`.

```move
script {
  fun example() {
    let (x, x) = 0; // ERROR!
  }
}
```

### Multiple declarations with structs

[Section titled “Multiple declarations with structs”](#multiple-declarations-with-structs)

`let` can also introduce more than one local at a time when destructuring (or matching against) a struct. In this form, the `let` creates a set of local variables that are initialized to the values of the fields from a struct. The syntax looks like this:

```move
script {
  fun example() {
    struct T { f1: u64, f2: u64 }
  }
}
```

```move
script {
  fun example() {
    let T { f1: local1, f2: local2 } = T { f1: 1, f2: 2 };
    // local1: u64
    // local2: u64
  }
}
```

Here is a more complicated example:

```move
module 0x42::example {
  struct X { f: u64 }
  struct Y { x1: X, x2: X }

fun new_x(): X {
    X { f: 1 }
  }

fun example() {
    let Y { x1: X { f }, x2 } = Y { x1: new_x(), x2: new_x() };
    assert!(f + x2.f == 2, 42);

let Y { x1: X { f: f1 }, x2: X { f: f2 } } = Y { x1: new_x(), x2: new_x() };
    assert!(f1 + f2 == 2, 42);
  }
}
```

Fields of structs can serve double duty, identifying the field to bind *and* the name of the variable. This is sometimes referred to as punning.

```move
script {
  fun example() {
    let X { f } = e;
  }
}
```

is equivalent to:

```move
script {
  fun example() {
    let X { f: f } = e;
  }
}
```

As shown with tuples, you cannot declare more than one local with the same name in a single `let`.

```move
script {
  fun example() {
    let Y { x1: x, x2: x } = e; // ERROR!
  }
}
```

### Destructuring against references

[Section titled “Destructuring against references”](#destructuring-against-references)

In the examples above for structs, the bound value in the let was moved, destroying the struct value and binding its fields.

```move
script {
  fun example() {
    struct T { f1: u64, f2: u64 }
  }
}
```

```move
script {
  fun example() {
    let T { f1: local1, f2: local2 } = T { f1: 1, f2: 2 };
    // local1: u64
    // local2: u64
  }
}
```

In this scenario the struct value `T { f1: 1, f2: 2 }` no longer exists after the `let`.

If you wish instead to not move and destroy the struct value, you can borrow each of its fields. For example:

```move
script {
  fun example() {
    let t = T { f1: 1, f2: 2 };
    let T { f1: local1, f2: local2 } = &t;
    // local1: &u64
    // local2: &u64
  }
}
```

And similarly with mutable references:

```move
script {
  fun example() {
    let t = T { f1: 1, f2: 2 };
    let T { f1: local1, f2: local2 } = &mut t;
    // local1: &mut u64
    // local2: &mut u64
  }
}
```

This behavior can also work with nested structs.

```move
module 0x42::example {
  struct X { f: u64 }
  struct Y { x1: X, x2: X }

fun new_x(): X {
    X { f: 1 }
  }

fun example() {
    let y = Y { x1: new_x(), x2: new_x() };

let Y { x1: X { f }, x2 } = &y;
    assert!(*f + x2.f == 2, 42);

let Y { x1: X { f: f1 }, x2: X { f: f2 } } = &mut y;
    *f1 = *f1 + 1;
    *f2 = *f2 + 1;
    assert!(*f1 + *f2 == 4, 42);
  }
}
```

### Ignoring Values

[Section titled “Ignoring Values”](#ignoring-values)

In `let` bindings, it is often helpful to ignore some values. Local variables that start with `_` will be ignored and not introduce a new variable

```move
module 0x42::example {
  fun three(): (u64, u64, u64) {
    (0, 1, 2)
  }

fun example() {
    let (x1, _, z1) = three();
    let (x2, _y, z2) = three();
    assert!(x1 + z1 == x2 + z2, 42);
  }
}
```

This can be necessary at times as the compiler will error on unused local variables

```move
module 0x42::example {
  fun example() {
    let (x1, y, z1) = three(); // ERROR!
    //       ^ unused local 'y'
  }
}
```

### General `let` grammar

[Section titled “General let grammar”](#general-let-grammar)

All the different structures in `let` can be combined! With that we arrive at this general grammar for `let` statements:

> *let-binding* → **let** *pattern-or-list* *type-annotation**opt* *initializer**opt*

> *pattern-or-list* → *pattern* | **(** *pattern-list* **)**

> *pattern-list* → *pattern* **,***opt* | *pattern* **,** *pattern-list*

> *type-annotation* → **:** *type*

> *initializer* → **=** *expression*

The general term for the item that introduces the bindings is a *pattern*. The pattern serves to both destructure data (possibly recursively) and introduce the bindings. The pattern grammar is as follows:

> *pattern* → *local-variable* | *struct-type* **{** *field-binding-list* **}**

> *field-binding-list* → *field-binding* **,***opt* | *field-binding* **,** *field-binding-list*

> *field-binding* → *field* | *field* **:** *pattern*

A few concrete examples with this grammar applied:

```move
script {
  fun example() {
    let (x, y): (u64, u64) = (0, 1);
    //       ^                           local-variable
    //       ^                           pattern
    //          ^                        local-variable
    //          ^                        pattern
    //          ^                        pattern-list
    //       ^^^^                        pattern-list
    //      ^^^^^^                       pattern-or-list
    //            ^^^^^^^^^^^^           type-annotation
    //                         ^^^^^^^^  initializer
    //  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ let-binding

let Foo { f, g: x } = Foo { f: 0, g: 1 };
    //      ^^^                                    struct-type
    //            ^                                field
    //            ^                                field-binding
    //               ^                             field
    //                  ^                          local-variable
    //                  ^                          pattern
    //               ^^^^                          field-binding
    //            ^^^^^^^                          field-binding-list
    //      ^^^^^^^^^^^^^^^                        pattern
    //      ^^^^^^^^^^^^^^^                        pattern-or-list
    //                      ^^^^^^^^^^^^^^^^^^^^   initializer
    //  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ let-binding
  }
}
```

## Mutations

[Section titled “Mutations”](#mutations)

### Assignments

[Section titled “Assignments”](#assignments)

After the local is introduced (either by `let` or as a function parameter), the local can be modified via an assignment:

```move
script {
  fun example(e: u8) {
    let x = 0;
    x = e
  }
}
```

Unlike `let` bindings, assignments are expressions. In some languages, assignments return the value that was assigned, but in Move, the type of any assignment is always `()`.

```move
script {
  fun example(e: u8) {
    let x = 0;
    (x = e) == ()
  }
}
```

Practically, assignments being expressions means that they can be used without adding a new expression block with braces (`{`…`}`).

```move
script {
  fun example(e: u8) {
    let x = 0;
    if (cond) x = 1 else x = 2;
  }
}
```

The assignment uses the same pattern syntax scheme as `let` bindings:

```move
module 0x42::example {
    struct X { f: u64 }

fun new_x(): X {
        X { f: 1 }
    }

// This example will complain about unused variables and assignments.
    fun example() {
       let (x, _, z) = (0, 1, 3);
       let (x, y, f, g);

(X { f }, X { f: x }) = (new_x(), new_x());
       assert!(f + x == 2, 42);

(x, y, z, f, _, g) = (0, 0, 0, 0, 0, 0);
    }
}
```

Note that a local variable can only have one type, so the type of the local cannot change between assignments.

```move
script {
  fun example() {
    let x;
    x = 0;
    x = false; // ERROR!
  }
}
```

### Mutating through a reference

[Section titled “Mutating through a reference”](#mutating-through-a-reference)

In addition to directly modifying a local with assignment, a local can be modified via a mutable reference `&mut`.

```move
script {
  fun example() {
    let x = 0;
    let r = &mut x;
    *r = 1;
    assert!(x == 1, 42);
  }
}
```

This is particularly useful if either:

(1) You want to modify different variables depending on some condition.

```move
script {
  fun example() {
    let x = 0;
    let y = 1;
    let r = if (cond) {
      &mut x
    } else {
      &mut y
    };
    *r = *r + 1;
  }
}
```

(2) You want another function to modify your local value.

```move
script {
  fun example() {
    let x = 0;
    modify_ref(&mut x);
  }
}
```

This sort of modification is how you modify structs and vectors!

```move
script {
  use 0x1::vector;

fun example() {
    let v = vector::empty();
    vector::push_back(&mut v, 100);
    assert!(*vector::borrow(&v, 0) == 100, 42);
  }
}
```

For more details, see [Move references](/build/smart-contracts/book/references).

### Compound Assignments

[Section titled “Compound Assignments”](#compound-assignments)

*Since language version 2.1*

Move also supports compound assignment operators. These are like an assignment to a variable, or a mutation through a reference, except that the assigned location must already have a value, which is read and operated on before being stored back into the location. Currently these are only applicable to numeric values.

| Syntax | Description                                                  |
| ------ | ------------------------------------------------------------ |
| `+=`   | Performs addition and updates the left-hand value            |
| `-=`   | Performs subtraction and updates the left-hand value         |
| `*=`   | Performs multiplication and updates the left-hand value      |
| `%=`   | Performs modular division and updates the left-hand value    |
| `/=`   | Performs truncating division and updates the left-hand value |
| `&=`   | Performs bitwise and updates the left-hand value             |
| `\|=`  | Performs bitwise or and updates the left-hand value          |
| `^=`   | Performs bitwise xor and updates the left-hand value         |
| `<<=`  | Performs shift left and updates the left-hand value          |
| `>>=`  | Performs shift right and updates the left-hand value         |

For `e1 += e2`, the **modifying operand** `e2` is evaluated first, followed by the **assigned operand** `e1`. The result of performing `+` on the operand values is then stored in the left-hand side location. The assigned operand is only evaluated once. Similarly for all other operations listed in the table above.

```move
module 0x42::example {
  struct S { f: u64 }

fun example() {
    let x = 41;
    x += 1;
    assert!(x == 42);

let y = 41;
    let p = &mut y;
    *p += 1;
    assert!(*p == 42);

let z = S { f: 41 };
    z.f += 1;
    assert!(z.f == 42);
  }
}
```

## Scopes

[Section titled “Scopes”](#scopes)

Any local declared with `let` is available for any subsequent expression, *within that scope*. Scopes are declared with expression blocks, `{`…`}`.

Locals cannot be used outside the declared scope.

```move
script {
  fun example() {
    let x = 0;
    {
      let y = 1;
    };
    x + y // ERROR!
    //  ^ unbound local 'y'
  }
}
```

But, locals from an outer scope *can* be used in a nested scope.

```move
script {
  fun example() {
    {
      let x = 0;
      {
        let y = x + 1; // valid
      }
    }
  }
}
```

Locals can be mutated in any scope where they are accessible. That mutation survives with the local, regardless of the scope that performed the mutation.

```move
script {
  fun example() {
    let x = 0;
    x = x + 1;
    assert!(x == 1, 42);
    {
      x = x + 1;
      assert!(x == 2, 42);
    };
    assert!(x == 2, 42);
  }
}
```

### Expression Blocks

[Section titled “Expression Blocks”](#expression-blocks)

An expression block is a series of statements separated by semicolons (`;`). The resulting value of an expression block is the value of the last expression in the block.

```move
script {
  fun example() {
    { let x = 1; let y = 1; x + y }
  }
}
```

In this example, the result of the block is `x + y`.

A statement can be either a `let` declaration or an expression. Remember that assignments (`x = e`) are expressions of type `()`.

```move
script {
  fun example() {
    { let x; let y = 1; x = 1; x + y }
  }
}
```

Function calls are another common expression of type `()`. Function calls that modify data are commonly used as statements.

```move
script {
  fun example() {
    { let v = vector::empty(); vector::push_back(&mut v, 1); v }
  }
}
```

This is not just limited to `()` types---any expression can be used as a statement in a sequence!

```move
script {
  fun example() {
    {
      let x = 0;
      x + 1; // value is discarded
      x + 2; // value is discarded
      b"hello"; // value is discarded
    }
  }
}
```

But! If the expression contains a resource (a value without the `drop` [ability](/build/smart-contracts/book/abilities)), you will get an error. This is because Move’s type system guarantees that any value that is dropped has the `drop` [ability](/build/smart-contracts/book/abilities). (Ownership must be transferred or the value must be explicitly destroyed within its declaring module.)

```move
script {
  fun example() {
    {
      let x = 0;
      Coin { value: x }; // ERROR!
      //  ^^^^^^^^^^^^^^^^^ unused value without the `drop` ability
      x
    }
  }
}
```

If a final expression is not present in a block---that is, if there is a trailing semicolon `;`, there is an implicit [unit `()` value](https://en.wikipedia.org/wiki/Unit_type). Similarly, if the expression block is empty, there is an implicit unit `()` value.

```move
script {
  fun example() {
    // Both are equivalent
    { x = x + 1; 1 / x; };
    { x = x + 1; 1 / x; () };
  }
}
```

```move
script {
  fun example() {
    // Both are equivalent
    {}
    { () }
  }
}
```

An expression block is itself an expression and can be used anyplace an expression is used. (Note: The body of a function is also an expression block, but the function body cannot be replaced by another expression.)

```move
script {
  fun example() {
    let my_vector: vector<vector<u8>> = {
      let v = vector::empty();
      vector::push_back(&mut v, b"hello");
      vector::push_back(&mut v, b"goodbye");
      v
    };
  }
}
```

(The type annotation is not needed in this example and only added for clarity.)

### Shadowing

[Section titled “Shadowing”](#shadowing)

If a `let` introduces a local variable with a name already in scope, that previous variable can no longer be accessed for the rest of this scope. This is called *shadowing*.

```move
script {
  fun example() {
    let x = 0;
    assert!(x == 0, 42);

let x = 1; // x is shadowed
    assert!(x == 1, 42);
  }
}
```

When a local is shadowed, it does not need to retain the same type as before.

```move
script {
  fun example() {
    let x = 0;
    assert!(x == 0, 42);

let x = b"hello"; // x is shadowed
    assert!(x == b"hello", 42);
  }
}
```

After a local is shadowed, the value stored in the local still exists, but will no longer be accessible. This is important to keep in mind with values of types without the [`drop` ability](/build/smart-contracts/book/abilities), as ownership of the value must be transferred by the end of the function.

```move
module 0x42::example {
  struct Coin has store { value: u64 }

fun unused_resource(): Coin {
    let x = Coin { value: 0 }; // ERROR!
    //  ^ This local still contains a value without the `drop` ability
    x.value = 1;
    let x = Coin { value: 10 };
    x
    // ^ Invalid return
  }
}
```

When a local is shadowed inside a scope, the shadowing only remains for that scope. The shadowing is gone once that scope ends.

```move
script {
  fun example() {
    let x = 0;
    {
      let x = 1;
      assert!(x == 1, 42);
    };
    assert!(x == 0, 42);
  }
}
```

Remember, locals can change type when they are shadowed.

```move
script {
  fun example() {
    let x = 0;
    {
      let x = b"hello";
      assert!(x = b"hello", 42);
    };
    assert!(x == 0, 42);
  }
}
```

## Move and Copy

[Section titled “Move and Copy”](#move-and-copy)

All local variables in Move can be used in two ways, either by `move` or `copy`. If one or the other is not specified, the Move compiler is able to infer whether a `copy` or a `move` should be used. This means that in all the examples above, a `move` or a `copy` would be inserted by the compiler. A local variable cannot be used without the use of `move` or `copy`.

`copy` will likely feel the most familiar coming from other programming languages, as it creates a new copy of the value inside the variable to use in that expression. With `copy`, the local variable can be used more than once.

```move
script {
  fun example() {
    let x = 0;
    let y = copy x + 1;
    let z = copy x + 2;
  }
}
```

Any value with the `copy` [ability](/build/smart-contracts/book/abilities) can be copied in this way.

`move` takes the value out of the local variable *without* copying the data. After a `move` occurs, the local variable is unavailable.

```move
script {
  fun example() {
    let x = 1;
    let y = move x + 1;
    //      ------ Local was moved here
    let z = move x + 2; // Error!
    //      ^^^^^^ Invalid usage of local 'x'
    y + z;
  }
}
```

### Safety

[Section titled “Safety”](#safety)

Move’s type system will prevent a value from being used after it is moved. This is the same safety check described in [`let` declaration](#let-bindings) that prevents local variables from being used before it is assigned a value.

### Inference

[Section titled “Inference”](#inference)

As mentioned above, the Move compiler will infer a `copy` or `move` if one is not indicated. The algorithm for doing so is quite simple:

* Any value with the `copy` [ability](/build/smart-contracts/book/abilities) is given a `copy`.
* Any reference (both mutable `&mut` and immutable `&`) is given a `copy`.
  * Except under special circumstances where it is made a `move` for predictable borrow checker errors.
* Any other value is given a `move`.
* If the compiler can prove that the source value with copy ability is not used after the assignment, then a move may be used instead of a copy for performance, but this will be invisible to the programmer (except in possible decreased time or gas cost).

For example:

```move
module 0x42::example {
  struct Foo {
    f: u64
  }

struct Coin has copy {
    value: u64
  }

fun example() {
    let s = b"hello";
    let foo = Foo { f: 0 };
    let coin = Coin { value: 0 };

let s2 = s; // copy
    let foo2 = foo; // move
    let coin2 = coin; // copy

let x = 0;
    let b = false;
    let addr = @0x42;
    let x_ref = &x;
    let coin_ref = &mut coin2;

let x2 = x; // copy
    let b2 = b; // copy
    let addr2 = @0x42; // copy
    let x_ref2 = x_ref; // copy
    let coin_ref2 = coin_ref; // copy
  }
}
```

# Vector

`vector<T>` is the only primitive collection type provided by Move. A `vector<T>` is a homogeneous collection of `T`’s that can grow or shrink by pushing/popping values off the “end”.

A `vector<T>` can be instantiated with any type `T`. For example, `vector<u64>`, `vector<address>`, `vector<0x42::MyModule::MyResource>`, and `vector<vector<u8>>` are all valid vector types.

## Literals

[Section titled “Literals”](#literals)

### General `vector` Literals

[Section titled “General vector Literals”](#general-vector-literals)

Vectors of any type can be created with `vector` literals.

| Syntax                | Type                                                                          | Description                                |
| --------------------- | ----------------------------------------------------------------------------- | ------------------------------------------ |
| `vector[]`            | `vector[]: vector<T>` where `T` is any single, non-reference type             | An empty vector                            |
| `vector[e1, ..., en]` | `vector[e1, ..., en]: vector<T>` where `e_i: T` s.t. `0 < i <= n` and `n > 0` | A vector with `n` elements (of length `n`) |

In these cases, the type of the `vector` is inferred, either from the element type or from the vector’s usage. If the type cannot be inferred, or simply for added clarity, the type can be specified explicitly:

```move
vector<T>[]: vector<T>
vector<T>[e1, ..., en]: vector<T>
```

#### Example Vector Literals

[Section titled “Example Vector Literals”](#example-vector-literals)

```move
script {
  fun example() {
    (vector[]: vector<bool>);
    (vector[0u8, 1u8, 2u8]: vector<u8>);
    (vector<u128>[]: vector<u128>);
    (vector<address>[@0x42, @0x100]: vector<address>);
  }
}
```

### `vector<u8>` literals

[Section titled “vector\<u8> literals”](#vectoru8-literals)

A common use-case for vectors in Move is to represent “byte arrays”, which are represented with `vector<u8>`. These values are often used for cryptographic purposes, such as a public key or a hash result. These values are so common that specific syntax is provided to make the values more readable, as opposed to having to use `vector[]` where each individual `u8` value is specified in numeric form.

There are currently two supported types of `vector<u8>` literals, *byte strings* and *hex strings*.

#### Byte Strings

[Section titled “Byte Strings”](#byte-strings)

Byte strings are quoted string literals prefixed by a `b`, e.g. `b"Hello!\n"`.

These are ASCII encoded strings that allow for escape sequences. Currently, the supported escape sequences are:

| Escape Sequence | Description                                    |
| --------------- | ---------------------------------------------- |
| `\n`            | New line (or Line feed)                        |
| `\r`            | Carriage return                                |
| `\t`            | Tab                                            |
| `\\`            | Backslash                                      |
| `\0`            | Null                                           |
| `\"`            | Quote                                          |
| `\xHH`          | Hex escape, inserts the hex byte sequence `HH` |

#### Hex Strings

[Section titled “Hex Strings”](#hex-strings)

Hex strings are quoted string literals prefixed by a `x`, e.g. `x"48656C6C6F210A"`.

Each byte pair, ranging from `00` to `FF`, is interpreted as hex encoded `u8` value. So each byte pair corresponds to a single entry in the resulting `vector<u8>`.

#### Example String Literals

[Section titled “Example String Literals”](#example-string-literals)

```move
script {
  fun byte_and_hex_strings() {
    assert!(b"" == x"", 0);
    assert!(b"Hello!\n" == x"48656C6C6F210A", 1);
    assert!(b"\x48\x65\x6C\x6C\x6F\x21\x0A" == x"48656C6C6F210A", 2);
    assert!(
        b"\"Hello\tworld!\"\n \r \\Null=\0" ==
            x"2248656C6C6F09776F726C6421220A200D205C4E756C6C3D00",
        3
    );
  }
}
```

## Operations

[Section titled “Operations”](#operations)

`vector` provides several operations via the `std::vector` module in the Move standard library, as shown below. More operations may be added over time. Up-to-date document on `vector` can be found [here](https://github.com/aptos-labs/aptos-core/blob/main/aptos-move/framework/move-stdlib/doc/vector.md).

| Function                                                                              | Description                                                                                                                                                        | Aborts?                                                  |
| ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------- |
| `vector::empty<T>(): vector<T>`                                                       | Create an empty vector that can store values of type `T`                                                                                                           | Never                                                    |
| `vector::is_empty<T>(self: &vector<T>): bool`                                         | Return `true` if the vector `self` has no elements and `false` otherwise.                                                                                          | Never                                                    |
| `vector::singleton<T>(t: T): vector<T>`                                               | Create a vector of size 1 containing `t`                                                                                                                           | Never                                                    |
| `vector::length<T>(self: &vector<T>): u64`                                            | Return the length of the vector `self`                                                                                                                             | Never                                                    |
| `vector::push_back<T>(self: &mut vector<T>, t: T)`                                    | Add `t` to the end of `self`                                                                                                                                       | Never                                                    |
| `vector::pop_back<T>(self: &mut vector<T>): T`                                        | Remove and return the last element in `self`                                                                                                                       | If `self` is empty                                       |
| `vector::borrow<T>(self: &vector<T>, i: u64): &T`                                     | Return an immutable reference to the element at index `i`                                                                                                          | If `i` is not in bounds                                  |
| `vector::borrow_mut<T>(self: &mut vector<T>, i: u64): &mut T`                         | Return a mutable reference to the element at index `i`                                                                                                             | If `i` is not in bounds                                  |
| `vector::destroy_empty<T>(self: vector<T>)`                                           | Delete `self`                                                                                                                                                      | If `self` is not empty                                   |
| `vector::append<T>(self: &mut vector<T>, other: vector<T>)`                           | Add the elements in `other` to the end of `self`                                                                                                                   | Never                                                    |
| `vector::reverse_append<T>(self: &mut vector<T>, other: vector<T>)`                   | Pushes all of the elements of the `other` vector into the `self` vector, in the reverse order as they occurred in `other`                                          | Never                                                    |
| `vector::contains<T>(self: &vector<T>, e: &T): bool`                                  | Return true if `e` is in the vector `self`. Otherwise, returns `false`                                                                                             | Never                                                    |
| `vector::swap<T>(self: &mut vector<T>, i: u64, j: u64)`                               | Swaps the elements at the `i`th and `j`th indices in the vector `self`                                                                                             | If `i` or `j` is out of bounds                           |
| `vector::reverse<T>(self: &mut vector<T>)`                                            | Reverses the order of the elements in the vector `self` in place                                                                                                   | Never                                                    |
| `vector::reverse_slice<T>(self: &mut vector<T>, l: u64, r: u64)`                      | Reverses the order of the elements `[l, r)` in the vector `self` in place                                                                                          | If `l > r` or if `l` or `r` is out of bounds             |
| `vector::index_of<T>(self: &vector<T>, e: &T): (bool, u64)`                           | Return `(true, i)` if `e` is in the vector `self` at index `i`. Otherwise, returns `(false, 0)`                                                                    | Never                                                    |
| `vector::insert<T>(self: &mut vector<T>, i: u64, e: T)`                               | Insert a new element `e` at position `0 <= i <= length`, using `O(length - i)` time                                                                                | If `i` is out of bounds                                  |
| `vector::remove<T>(self: &mut vector<T>, i: u64): T`                                  | Remove the `i`th element of the vector `self`, shifting all subsequent elements. This is O(n) and preserves ordering of elements in the vector                     | If `i` is out of bounds                                  |
| `vector::swap_remove<T>(self: &mut vector<T>, i: u64): T`                             | Swap the `i`th element of the vector `self` with the last element and then pop the element, This is O(1), but does not preserve ordering of elements in the vector | If `i` is out of bounds                                  |
| `vector::trim<T>(self: &mut vector<T>, new_len: u64): vector<T>`                      | Trim the vector `self` to the smaller size `new_len` and return the evicted elements in order                                                                      | If `new_len > self.length()`                             |
| `vector::trim_reverse<T>(self: &mut vector<T>, new_len: u64): vector<T>`              | Trim the vector `self` to the smaller size `new_len` and return the evicted elements in the reverse order                                                          | If `new_len > self.length()`                             |
| `vector::rotate<T>(self: &mut vector<T>, rot: u64): u64`                              | `rotate(&mut [1, 2, 3, 4, 5], 2) -> [3, 4, 5, 1, 2]` in place, returns the split point i.e., `3` in this example                                                   | If `rot <= self.length()` does not hold                  |
| `vector::rotate_slice<T>(self: &mut vector<T>, left: u64, rot: u64, right: u64): u64` | rotate a slice `[left, right)` with `left <= rot <= right` in place, returns the split point                                                                       | If `left <= rot <= right <= self.length()` does not hold |

Example:

```move
script {
  use std::vector;

fun example() {
    let v = vector::empty<u64>();
    vector::push_back(&mut v, 5);
    vector::push_back(&mut v, 6);

assert!(*vector::borrow(&v, 0) == 5, 42);
    assert!(*vector::borrow(&v, 1) == 6, 42);
    assert!(vector::pop_back(&mut v) == 6, 42);
    assert!(vector::pop_back(&mut v) == 5, 42);
  }
}
```

## Index Notation for Vectors

[Section titled “Index Notation for Vectors”](#index-notation-for-vectors)

*Since language version 2.0*

Index notation using square brackets (`[]`) is available for vector operations, simplifying syntax and making programs easier to understand. The index notation is simply syntactic sugar which is reduced to existing operations by the compiler; the named operations are also still supported.

The table below gives an overview of index notations for vectors:

| Indexing Syntax   | Vector Operation                           |
| ----------------- | ------------------------------------------ |
| `&v[i]`           | `vector::borrow(&v, i)`                    |
| `&mut v[i]`       | `vector::borrow_mut(&mut v, i)`            |
| `v[i]`            | `*vector::borrow(&v, i)`                   |
| `v[i] = x`        | `*vector::borrow_mut(&mut v, i) = x`       |
| `&v[i].field`     | `&vector::borrow(&v, i).field`             |
| `&mut v[i].field` | `&mut vector::borrow_mut(&mut v, i).field` |
| `v[i].field`      | `vector::borrow(&v, i).field`              |
| `v[i].field = x`  | `vector::borrow_mut(&mut v, i).field = x`  |

As an example, here is a bubble sort algorithm for vectors using index notation:

```move
fun bubble_sort(v: vector<u64>) {
  use std::vector;
  let n = vector::length(&v);
  let i = 0;

while (i < n) {
    let j = 0;
    while (j < n - i - 1) {
      if (v[j] > v[j + 1]) {
        let t = v[j];
        v[j] = v[j + 1];
        v[j + 1] = t;
      };
      j = j + 1;
    };
    i = i + 1;
  };
}
```

## Destroying and copying vectors

[Section titled “Destroying and copying vectors”](#destroying-and-copying-vectors)

Some behaviors of `vector<T>` depend on the abilities of the element type, `T`. For example, vectors containing elements that do not have `drop` cannot be implicitly discarded like `v` in the example above—they must be explicitly destroyed with `vector::destroy_empty`.

Note that `vector::destroy_empty` will abort at runtime unless `vec` contains zero elements:

```move
script {
  fun destroy_any_vector<T>(vec: vector<T>) {
    vector::destroy_empty(vec) // deleting this line will cause a compiler error
  }
}
```

But no error would occur for dropping a vector that contains elements with `drop`:

```move
script {
  fun destroy_droppable_vector<T: drop>(vec: vector<T>) {
    // valid!
    // nothing needs to be done explicitly to destroy the vector
  }
}
```

Similarly, vectors cannot be copied unless the element type has `copy`. In other words, a `vector<T>` has `copy` if and only if `T` has `copy`.

For more details see the sections on [type abilities](/build/smart-contracts/book/abilities) and [generics](/build/smart-contracts/book/generics).

## Ownership

[Section titled “Ownership”](#ownership)

As mentioned [above](#destroying-and-copying-vectors), `vector` values can be copied only if the elements can be copied.

# Move On Aptos Compiler

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](/build/smart-contracts/book/move-2) 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

[Section titled “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

[Section titled “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

[Section titled “Using Move on Aptos Compiler”](#using-move-on-aptos-compiler)

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

```shellscript
aptos update aptos # on supported OS
brew upgrade aptos # on MacOS
```

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

```shellscript
aptos move compile
aptos move test
aptos move prove
```

# Compiling (Move)

Note

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

## `aptos move compile`

[Section titled “aptos move compile”](#aptos-move-compile)

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

```shellscript
aptos move compile
```

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

```shellscript
{
  "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:

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

## Unpacking Build

[Section titled “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`

[Section titled “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`

[Section titled “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)

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

[Section titled “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:

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

## Confidential Balance

[Section titled “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

[Section titled “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:

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

### Encryption and Decryption

[Section titled “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

[Section titled “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

[Section titled “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

[Section titled “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

[Section titled “Entry functions”](#entry-functions)

### Register

[Section titled “Register”](#register)

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

```move
#[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.

```move
#[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

[Section titled “Deposit”](#deposit)

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

```move
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.

```move
#[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

[Section titled “Rollover Pending Balance”](#rollover-pending-balance)

```move
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.

```move
#[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

[Section titled “Confidential Transfer”](#confidential-transfer)

```move
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.

```move
#[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);

// 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

[Section titled “Withdraw”](#withdraw)

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

```move
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.

```move
#[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

[Section titled “Rotate Encryption Key”](#rotate-encryption-key)

```move
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>)
```

```move
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>)
```

```move
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.

```move
#[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

[Section titled “Normalize”](#normalize)

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

```move
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.

```move
#[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

[Section titled “Useful Resources”](#useful-resources)

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

# Create Package (Move)

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:

```shellscript
   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

```toml
   [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

```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

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

[Section titled “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 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) is satisfied on a public statement x without leaking the secret witness w 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](/build/smart-contracts/book/functions#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

[Section titled “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

[Section titled “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⋅64            | n⋅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 t-out-of-n 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, σ, can be mauled into a different yet still valid signature, σ, for the same message m.

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: t-out-of-n 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

[Section titled “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](/build/smart-contracts/book/functions#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 [`aptos_std::bls12381_algebra`](https://github.com/aptos-labs/aptos-core/blob/main/aptos-move/framework/aptos-stdlib/sources/cryptography/bls12381_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

[Section titled “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 Σ-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

[Section titled “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 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)), more curves will be supported into the future (e.g., BN254, 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](/build/smart-contracts/book/functions#type-parameters) for the curve type in their implementation:

```rust
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:

```rust
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

[Section titled “Building powerful cryptographic applications”](#building-powerful-cryptographic-applications)

### Veiled coins

[Section titled “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

[Section titled “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.

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

[Section titled “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> \[^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/> \[^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> \[^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>

# Debugging Move

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

[Section titled “Debugging with the Aptos CLI”](#debugging-with-the-aptos-cli)

### Simulation on transaction submission

[Section titled “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:

```shellscript
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:

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

### Local Simulation

[Section titled “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](https://aptos.dev/en/build/cli/working-with-move-contracts#printing-debugging-information).

```shellscript
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

[Section titled “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:

```shellscript
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:

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

## Evaluating performance

[Section titled “Evaluating performance”](#evaluating-performance)

```shellscript
aptos move run --function-id 0x1::aptos_account::transfer --args address:0x1 u64:1 --benchmark

Benchmarking transaction locally...
Running time (cold code cache): 22.144458ms
Running 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

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](/build/smart-contracts/book/packages).

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

[Section titled “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`.

```toml
   [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.

```shellscript
   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.

```shellscript
   aptos move deploy-object --address-name <named_address>
   ```

**An example can be found below:**

```shellscript
   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:**

```shellscript
   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.

```shellscript
   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:

```typescript
   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.

```shellscript
   aptos move upgrade-object --address-name <named_address> --object-address <code_object_addr>
   ```

Example of the command above:

```shellscript
   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:**

```shellscript
   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

Content for build/smart-contracts/digital-asset could not be fully rendered due to component compatibility issues.

# Aptos Error Codes

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

[Section titled “Frequent Errors”](#frequent-errors)

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

[Section titled “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

[Section titled “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

[Section titled “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

[Section titled “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)

[Section titled “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)

[Section titled “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

[Section titled “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

[Section titled “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

[Section titled “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

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)

[Section titled “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:

```move
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:

```move
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:

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

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

```move
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

[Section titled “Reference Docs”](#reference-docs)

You can find the complete set of functions that the Fungible Asset Standard provides [here](https://aptos.dev/reference/move/?branch=mainnet\&page=aptos-framework/doc/fungible_asset.md).

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

### Withdraw

[Section titled “Withdraw”](#withdraw)

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

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

This function will emit a `WithdrawEvent`.

### Deposit

[Section titled “Deposit”](#deposit)

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

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

This function will emit a `DepositEvent`.

### Transfer

[Section titled “Transfer”](#transfer)

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

```move
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

[Section titled “Check Balance”](#check-balance)

To check the balance of a primary store, call:

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

### Check Frozen Status

[Section titled “Check Frozen Status”](#check-frozen-status)

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

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

### Events

[Section titled “Events”](#events)

FAs have three events emitted from the above basic functions:

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

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

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

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

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

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

## Dispatchable Fungible Asset (Advanced)

[Section titled “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

[Section titled “Implementing the Hook Function”](#implementing-the-hook-function)

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

```move
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

[Section titled “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

[Section titled “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.

```move
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:

```move
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:

```move
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

[Section titled “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)

[Section titled “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:

```move
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:

```move
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:

```move
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

[Section titled “Migration from Coin to the Fungible Asset Standard”](#migration-from-coin-to-the-fungible-asset-standard)

### Smart Contract Migration

[Section titled “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:

```move
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:

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

Similarly, a function exists for reverse lookup:

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

### Off-chain Migration

[Section titled “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

[Section titled “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](https://aptos.dev/en/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](https://aptos.dev/en/build/apis/fullnode-rest-api-reference#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](https://aptos.dev/en/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

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

[Section titled “Lint Checks”](#lint-checks)

### `aborting_overflow_checks`

[Section titled “aborting\_overflow\_checks”](#aborting_overflow_checks)

Checks for patterns that look like overflow checks done in a C style:

```move
// Overflow check
if (x > x + y) {
  abort 1;
};

// Underflow check
if (x < x - y) {
  abort 1;
};
```

This pattern in Move does not make sense, as it either aborts immediately or is always true/false.

### `almost_swapped`

[Section titled “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`

[Section titled “assert\_const”](#assert_const)

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

### `avoid_copy_on_identity_comparison`

[Section titled “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](/build/smart-contracts/book/equality#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`

[Section titled “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:

```move
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.

# `equal_operands_in_bin_op`

[Section titled “equal\_operands\_in\_bin\_op”](#equal_operands_in_bin_op)

Checks for binary operations where both operands are the same, which is likely a mistake. 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 suggests replacing these with a more appropriate value or expression, such as `0`, `true`, or `false`.

This lint does not catch cases where the operands are vector access.

### `find_unnecessary_casts`

[Section titled “find\_unnecessary\_casts”](#find_unnecessary_casts)

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

For example:

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

The above can be simplified to:

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

### `known_to_abort`

[Section titled “known\_to\_abort”](#known_to_abort)

Checks for expressions that will always abort at runtime due to known constant values that violate runtime constraints. This lint helps identify code that will deterministically fail before it reaches production.

The following cases 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` is of 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`

[Section titled “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`

[Section titled “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_mutable_reference`

[Section titled “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.

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

### `needless_ref_deref`

[Section titled “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`

[Section titled “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;`

### `nested_if`

[Section titled “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.

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

This pattern can be simplified to:

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

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

### `nonminimal_bool`

[Section titled “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.

### `null_effects`

[Section titled “null\_effects”](#null_effects)

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

* `42;`
* `*(&mut 0) = /*...*/;`
* `pure_function(21);`

It also checks for more complex cases, such as

```move
{
    let x = 0;
    x += 1;
    x
};
```

and

```move
{
    let x = 0;
    function_that_modifies_its_argument(&mut x);
    x
};
```

### `self_assignment`

[Section titled “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`

[Section titled “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`

[Section titled “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`

[Section titled “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`

[Section titled “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`

[Section titled “while\_true”](#while_true)

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

## Suppressing Lint Warnings

[Section titled “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.

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

# Maps

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

[Section titled “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

[Section titled “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

[Section titled “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:

[Section titled “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

[Section titled “Creating Maps”](#creating-maps)

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

#### Destroying Maps

[Section titled “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

[Section titled “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

[Section titled “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

[Section titled “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

[Section titled “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

[Section titled “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

[Section titled “Example Usage”](#example-usage)

### Creating and Using a OrderedMap

[Section titled “Creating and Using a OrderedMap”](#creating-and-using-a-orderedmap)

```move
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`

[Section titled “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

[Section titled “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`

[Section titled “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

[Section titled “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

[Section titled “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

[Section titled “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

[Section titled “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

Aptos allows for permissionless publishing of [modules](/build/smart-contracts/book/modules-and-scripts) within a [package](/build/smart-contracts/book/packages) as well as [upgrading](/build/smart-contracts/book/package-upgrades) 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.
* Only when a module is being published for the first time, and not during an upgrade, will the VM search for and execute an `init_module(account: &signer)` function. The signer of the account that is publishing the module is passed into the `init_module` function of the contract. **This function must be private and not return any value.**

Note

`init_module` is optional It is only necessary if you want to initialize data when publishing a module for the first time.

# Move Reference

# Move Security Guidelines

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

[Section titled “Access Control”](#access-control)

### Object Ownership Check

[Section titled “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

[Section titled “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.

```move
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

[Section titled “Example Secure Code”](#example-secure-code)

Ensure that the signer owns the object.

```move
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);

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

[Section titled “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

[Section titled “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.

```move
module 0x42::example {
  struct Object has key{
    data: vector<u8>
  }

public fun delete(user: &signer, obj: Object) {
    let Object { data } = obj;
  }
}
```

#### Example Secure Code

[Section titled “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.

```move
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

[Section titled “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.

```move
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.

```move
module 0x42::example {
  friend package::mod;

public(friend) fun sample_function() { /* ... */ }
}
```

* `public` functions are callable by any published module or script.

```move
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.

```move
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.

```move
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)`

```move
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

[Section titled “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

[Section titled “Types and Data Structures”](#types-and-data-structures)

### Generics type check

[Section titled “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](/build/smart-contracts/book/generics) about generics.

Unchecked generics can lead to unauthorized actions or transaction aborts, potentially compromising the integrity of the protocol.

#### Example Insecure Code

[Section titled “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.

```move
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>(&coin) >= rec.amount, 0);
    deposit(coin);
  }
}
```

#### Example Secure Code

[Section titled “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](/build/smart-contracts/book/generics#phantom-type-parameters) about `phantom` type parameters.

```move
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.

```move
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>(&coin) >= rec.amount, 0);
    deposit(coin);
  }
}
```

### Resource management and Unbounded Execution

[Section titled “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

[Section titled “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

[Section titled “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:

```move
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

[Section titled “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.

```move
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

[Section titled “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](/build/smart-contracts/book/abilities) 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

[Section titled “Example Insecure Code”](#example-insecure-code-4)

```move
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.

## Arithmetic Operations

[Section titled “Arithmetic Operations”](#arithmetic-operations)

***

### Division Precision

[Section titled “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

[Section titled “Example Insecure Code”](#example-insecure-code-5)

```move
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

[Section titled “Example Secure Code”](#example-secure-code-4)

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.

```move
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.

```move
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

[Section titled “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](/build/smart-contracts/book/integers#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

[Section titled “Aptos Objects”](#aptos-objects)

***

### ConstructorRef leak

[Section titled “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

[Section titled “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.

```move
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

[Section titled “Example Secure Code”](#example-secure-code-5)

Don’t return `CostructorRef` in the `mint` function:

```move
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

[Section titled “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

[Section titled “Example Insecure Code”](#example-insecure-code-6)

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`.

```move
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

[Section titled “Example Secure Code”](#example-secure-code-6)

In this example, objects should be stored at separate object accounts:

```move
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

[Section titled “Business logic”](#business-logic)

### Front-running

[Section titled “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

[Section titled “Example Insecure Code”](#example-insecure-code-7)

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.

```move
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

[Section titled “Example Secure Code”](#example-secure-code-7)

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.

```move
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

[Section titled “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

[Section titled “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

[Section titled “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

[Section titled “Example Insecure Code”](#example-insecure-code-8)

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.

```move
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

[Section titled “Example Secure Code”](#example-secure-code-8)

`object::object_address` returns an unique identifier for each `Object<Metadata>`

```move
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, seed)
  }
}
```

## Operations

[Section titled “Operations”](#operations)

***

### Pausing functionality

[Section titled “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

[Section titled “Example Secure Code”](#example-secure-code-9)

Example of how to integrate a pause functionality

```move
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

[Section titled “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

[Section titled “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](https://aptos.dev/guides/randomness/).

***

### Randomness - test-and-abort

[Section titled “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

[Section titled “Example Vulnerable code”](#example-vulnerable-code-1)

```move
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.

```move
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

[Section titled “Example Secure Code”](#example-secure-code-10)

```move
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

[Section titled “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

[Section titled “Example Vulnerable code”](#example-vulnerable-code-2)

```move
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

[Section titled “Example Secure Code”](#example-secure-code-11)

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.

# Creating objects

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

[Section titled “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:

```move
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:

```move
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:

```move
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_sticky_object(caller_address);
    // ...
  }
}
```

## Customizing Object Features

[Section titled “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

[Section titled “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.

```move
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`)

[Section titled “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.

```move
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`)

[Section titled “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.

```move
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`)

[Section titled “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.

```move
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`)

[Section titled “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.

```move
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

[Section titled “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

[Section titled “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.dev/reference/move?branch=mainnet\&page=aptos-framework/doc/object.md).

You can also explore how to use Objects once they are constructed [here](/build/smart-contracts/object/using-objects).

# Using objects

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

[Section titled “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.

```move
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:

```move
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

[Section titled “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:

```move
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

[Section titled “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,

```move
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

[Section titled “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:

```move
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

[Section titled “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:

```move
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

[Section titled “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:

```move
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:

```move
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

[Section titled “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

[Section titled “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

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:

```move
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

[Section titled “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

[Section titled “Examples with Object contracts”](#examples-with-object-contracts)

# Overview

The Move Prover supports formal [specification](/build/smart-contracts/prover/spec-lang) and [verification](/build/smart-contracts/prover/prover-guide) 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](/build/smart-contracts/prover/prover-guide)
* [Move Specification Language](/build/smart-contracts/prover/spec-lang)
* [Move Prover Supporting Resources](/build/smart-contracts/prover/supporting-resources)

# Move Prover User Guide

This is the user guide for the Move Prover. This document accompanies the [Move specification language](/build/smart-contracts/prover/spec-lang). See the sections below for details.

## Running the Move Prover

[Section titled “Running the Move Prover”](#running-the-move-prover)

The Move Prover is invoked via the [Aptos CLI](/build/cli). In order to call the CLI, you must have a [*Move package*](/build/smart-contracts/book/packages) in place. In the simplest case, a Move package is defined by a directory with a set of `.move` files in it and a manifest of the name `Move.toml`. You can create a new Move package at a given location by running the command: `aptos move init --name <name>`

Once the package exists, call the Move Prover from the directory to be tested or by supplying its path to the `--package-dir` argument:

* Prove the sources of the package in the current directory:

```shellscript
  aptos move prove
  ```

* Prove the sources of the package in a specific directly:

```shellscript
  aptos move prove --package-dir <path>
  ```

See example output and other available options in the [Proving Move](/build/cli/working-with-move-contracts#6-optional-formally-verifying-move-scripts) section of Use Aptos CLI.

### Target filtering

[Section titled “Target filtering”](#target-filtering)

By default, the `aptos move prove` command verifies all files of a package. During iterative development of larger packages, it is often more effective to focus verification on particular files with the `-f` (`--filter`) option, like so:

```shellscript
aptos move prove -f coin
```

In general, if the string provided to the `-f` option is contained somewhere in the file name of a source, that source will be included for verification.

> NOTE: the Move Prover ensures there is no semantic difference between verifying modules one-by-one or all at once. However, if your goal is to verify all modules, verifying them in a single `aptos move prove` run will be significantly faster than sequentially.

### Prover options

[Section titled “Prover options”](#prover-options)

The Move Prover has a number of options (such as the filter option above) that you pass with an invocation of: `aptos move prove <options>`. The most commonly used option is the `-t` (`--trace`) option that causes the Move Prover to produce richer diagnosis when it encounters errors:

```shellscript
aptos move prove -f coin -t
```

To see the list of all command line options, run: `aptos move prove --help`

### Prover configuration file

[Section titled “Prover configuration file”](#prover-configuration-file)

You can also create a Move Prover configuration file named `Prover.toml` that lives side-by-side with the `Move.toml` manifest file in the root of the package directory. For example, to enable tracing by default for a package, add a `Prover.toml` file with the following configuration:

```toml
[prover]
auto_trace_level = "VerifiedFunction"
```

Find the most commonly used options in the example `.toml` below, which you can cut and paste and adopt for your needs (adjusting the defaults shown in the displayed values as needed):

```toml
# Verbosity level
# Possible values: "ERROR", "WARN", "INFO", "DEBUG". Each level subsumes the output of the previous one.
verbosity_level = "INFO"

[prover]
# Set auto-tracing level, which enhances the diagnosis the Move Prover produces on verification errors.
# Possible values: "Off", "VerifiedFunction", "AllFunctions"
auto_trace_level = "Off"

# Minimal severity level for diagnosis to be reported.
# Possible values: "Error", "Warning", "Note"
report_severity = "Warning"

[backend]
# Timeout in seconds for the solver backend. Note that this is a soft timeout and may not always
# be respected.
vc_timeout = 40

# Random seed for the solver backend. Different seeds can result in different verification run times,
# as the solver uses heuristics.
random_seed = 1

# The number of processor cores to assume for concurrent check of verification conditions.
proc_cores = 4
```

> HINT: For local verification, you may want to set `proc_cores` to an aggressive number (your actual cores) to speed up the turnaround cycle.

## Prover diagnosis

[Section titled “Prover diagnosis”](#prover-diagnosis)

When the Move Prover finds a verification error, it prints diagnosis to standard output in a style similar to a compiler or a debugger. We explain the different types of diagnoses below, based on the following evolving example:

```move
module 0x42::m {
  struct Counter has key {
    value: u8,
  }

public fun increment(a: address) acquires Counter {
    let r = borrow_global_mut<Counter>(a);
    r.value = r.value + 1;
  }

spec increment {
    aborts_if !exists<Counter>(a);
    ensures global<Counter>(a).value == old(global<Counter>(a)).value + 1;
  }
}
```

We will modify this example as we demonstrate different types of diagnoses.

### Unexpected abort

[Section titled “Unexpected abort”](#unexpected-abort)

If we run the Move Prover on the example immediately above, we get the following error:

```shellscript
error: abort not covered by any of the `aborts_if` clauses
   ┌─ m.move:11:5
   │
 8 │           r.value = r.value + 1;
   │                             - abort happened here with execution failure
   ·
11 │ ╭     spec increment {
12 │ │         aborts_if !exists<Counter>(a);
13 │ │         ensures global<Counter>(a).value == old(global<Counter>(a)).value + 1;
14 │ │     }
   │ ╰─────^
   │
   =     at m.move:6: increment
   =         a = 0x29
   =     at m.move:7: increment
   =         r = &mmm.Counter{value = 255u8}
   =     at m.move:8: increment
   =         ABORTED

{
  "Error": "Move Prover failed: exiting with verification errors"
}
```

The Move Prover has generated an example counter that leads to an overflow when adding 1 to the value of 255 for an `u8`. This overflow occurs if the function specification calls for abort behavior, but the condition under which the function is aborting is not covered by the specification. And in fact, with `aborts_if !exists<Counter>(a)`, we only cover the abort caused by the absence of the resource, but not the abort caused by the arithmetic overflow.

Let’s fix the above and add the following condition:

```move
module 0x42::m {
  spec increment {
    aborts_if global<Counter>(a).value == 255;
    // ...
  }
}
```

With this, the Move Prover will succeed without any errors.

### Post-condition failure

[Section titled “Post-condition failure”](#post-condition-failure)

Let us inject an error into the `ensures` condition of the above example:

```move
module 0x42::m {
  spec increment {
    ensures global<Counter>(a).value == /*old*/(global<Counter>(a).value) + 1;
  }
}
```

With this, the Move Prover will produce the following diagnosis:

```shellscript
error: post-condition does not hold
   ┌─ m.move:14:9
   │
14 │         ensures global<Counter>(a).value == /*old*/(global<Counter>(a).value) + 1;
   │         ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
   │
   =     at m.move:6: increment
   =         a = 0x29
   =     at m.move:7: increment
   =         r = &mmm.Counter{value = 0u8}
   =     at m.move:8: increment
   =     at m.move:9: increment
   =     at m.move:12: increment (spec)
   =     at m.move:15: increment (spec)
   =     at m.move:13: increment (spec)
   =     at m.move:14: increment (spec)

{
  "Error": "Move Prover failed: exiting with verification errors"
}
```

While we know what the error is (as we just injected it), this is not particularly obvious in the output This is because we don’t directly see on which values the `ensures` condition was actually evaluated. To see this, use the `-t` (`--trace`) option; this is not enabled by default because it makes the verification problem slightly harder for the solver.

Instead or in addition to the `--trace` option, you can use the built-in function `TRACE(exp)` in conditions to explicitly mark expressions whose values should be printed on verification failures.

> NOTE: Expressions that depend on quantified symbols cannot be traced. Also, expressions appearing in specification functions can not currently be traced.

## Debugging the Move Prover

[Section titled “Debugging the Move Prover”](#debugging-the-move-prover)

The Move Prover is an evolving tool with bugs and deficiencies. Sometimes it might be necessary to debug a problem based on the output the Move Prover passes to the underlying backends. If you pass the option `--dump`, the Move Prover will output the original Move bytecode, as well as the Move Prover bytecode, as the former is transformed during compilation.

# Move Specification Language

This document describes the *Move specification language (MSL)*, a subset of the [Move](/build/smart-contracts) language that supports specification of the behavior of Move programs. MSL works together with the [Move Prover](/build/smart-contracts/prover), a tool that can statically verify the correctness of MSL specifications against Move programs. In contrast to traditional testing, verification of MSL is exhaustive and holds for all possible inputs and global states of a [Move module](/network/glossary#move-module) or [Move script](/network/glossary#move-script). At the same time, this verification of MSL is fast and automated enough that it can be used at a similar place in the developer workflow where tests are typically conducted (for example, for qualification of pull requests in continuous integration).

While the Move programming language at this point is stable, the subset represented by MSL should be considered evolving. This has no impact on platform stability, since MSL is not running in production; yet MSL is used for offline quality assurance where it is continuously improved for evolving objectives.

This document describes the language only; see [Use the Move Prover](/build/smart-contracts/prover/prover-guide) for instructions. The reader is expected to have basic knowledge of the Move language, as well as basic principles of pre- and post-condition specifications. (See for example the [Design by contract](https://en.wikipedia.org/wiki/Design_by_contract)). For examples of specifications, we refer to the [Aptos framework](https://github.com/aptos-labs/aptos-core/blob/main/aptos-move/framework/aptos-framework/doc/overview.md) documentation, which has specifications embedded.

# Expressions

[Section titled “Expressions”](#expressions)

Expressions in MSL are a subset of Move program expressions plus a set of additional constructs, as discussed in the following sections.

## Type System

[Section titled “Type System”](#type-system)

The type system of MSL is similar to that of Move, with the following differences:

* There are two types of encodings for integer types: `num` and `bv` (bit vector). If an integer (either a constant or a variable) is not involved in any bitwise operations directly or indirectly, regardless of its type in Move (`u8`, `u16`, `u32`, `u64`, `u128` and `u256`), it is treated as the same type. In specifications, this type is called `num`, which is an arbitrary precision *signed* integer type. When MSL refers to a Move name that represents an `u8` or such, it will be automatically widened to `num`. This allows writing MSL expressions like `x + 1 <= MAX_U128` or `x - y >= 0` without needing to worry about overflow or underflow. Different from `num`, `bv` cannot and does not need to be explicitly used in specifications: if an integer is involved in bitwise operations such as `&`, `|` or `^`, it will be automatically encoded as `bv`at the backend. Moreover, a `bv` integer has a fixed precision, which is consistent with its precision in Move (`bv8`, `bv16`, `bv32`, `bv64`, `bv128` and `bv256`). Note that, in general using `bv` is not so efficient as `num` in the [SMT](https://en.wikipedia.org/wiki/Satisfiability_modulo_theories) solver such as [Z3](https://github.com/Z3Prover/z3). Consequently, the Move Prover has some restrictions when using bitwise operations, which are stated in detail below.
* The Move types `&T`, `&mut T`, and `T` are considered equivalent for MSL. Equality is interpreted as value equality. There is no need to worry about dereferencing a reference from the Move program: these are automatically dereferenced as needed. This simplification is possible because MSL cannot modify values from a Move program, and the program cannot directly reason about reference equality (which eliminates the need for doing so in MSL). (Note there is also a restriction in expressiveness coming with this, namely for [functions which return `&mut T`](#expressiveness). However, this is rarely hit in practice, and there are workarounds).
* There is the additional type `type`, which is the type of all types. It can be used only in quantifiers.
* There is the additional type `range`, which represents an integer range (and the notation `n..m` to denote a value).

## Naming

[Section titled “Naming”](#naming)

Name resolution in MSL works similar to the Move language. `use` declarations can introduce aliases for imported names. MSL functions and variable names must start with a lowercase letter. Schema names are treated like types and must start with a capital letter. ([Schemas](#schemas) are a named construct discussed later).

Move functions, MSL functions, Move types, and schemas all share the same namespace and are therefore unambiguous if aliased via a Move `use` clause. Because of the common name space, an MSL function cannot have the same name as a Move function. This is often handled via the convention to prefix MSL functions as in `spec_has_access` when the related Move function is called `has_access`.

## Operators

[Section titled “Operators”](#operators)

All Move operators are supported in MSL, except `&`, `&mut`, and `*` (dereference).

In addition to the existing operators, vector subscript `v[i]`, slicing `v[i..j]`, and range construction `i..j` are supported (the type of integer ranges is a new builtin type called `range`). Moreover, boolean implication `p ==> q` is supported as a more intuitive form than `!p || q`.

## Function calls

[Section titled “Function calls”](#function-calls)

In MSL expressions, functions can be called like in Move. However, the callee must either be an [MSL helper function](#helper-functions) or a **pure** Move function.

Move functions are considered pure if they do not modify global state and do not use Move expression features that are not supported in MSL expressions (as defined in this document).

There is one extension. If a Move function definition contains a direct `assert`, this will be ignored when it is called from an MSL expression, and the function will be considered pure. For example:

```move
module 0x42::m {
  fun get(addr: address): &T {
    assert(exists<T>(addr), ERROR_CODE);
    borrow_global<T>(addr)
  }
}
```

This function is pure and can be called from an MSL expression. The assertion will be ignored, and the function will be interpreted as:

```move
module 0x42::m {
  spec fun get(addr: address): T { global<T>(addr) }
}
```

This is justified by that MSL having [*partial semantics*](#partial-semantics).

## Statements

[Section titled “Statements”](#statements)

Limited sequencing of the form `{ let x = foo(); x + x }` is supported, as well as if-then-else. Other statement forms of the Move language are not supported.

## Pack and unpack

[Section titled “Pack and unpack”](#pack-and-unpack)

Pack expressions are supported. Unpack expressions are currently *not* supported.

## Quantifiers

[Section titled “Quantifiers”](#quantifiers)

Universal and existential quantification is supported. The general form is:

```move
forall <binding>, ..., <binding> [ where <exp> ] : <exp>
exists <binding>, ..., <binding> [ where <exp> ] : <exp>
```

* Bindings can either be of the form `name: <type>` or `name in <exp>`. For the second form, the expression must either be a `range` or a vector.
* The optional constraint `where <exp>` allows to restrict the quantified range. `forall x: T where p: q` is equivalent to `forall x: T : p ==> q` and `exists x: T where p: q` is equivalent to `exists x: T : p && q`.

## Choice operator

[Section titled “Choice operator”](#choice-operator)

The choice operator allows selecting a value that satisfies a predicate:

```move
choose a: address where exists<R>(a) && global<R>(a).value > 0
```

If the predicate is not satisfiable, the result of the choice will be undetermined. (See [partial semantics](#partial-semantics)).

The choice also comes in a form to select the *minimal* value from a set of integers, as in:

```move
choose min i: num where in_range(v, i) && v[i] == 2
```

## Cast operator

[Section titled “Cast operator”](#cast-operator)

In the specification language, we can use the same syntax `(e as T)` to cast an expression `e` with one integer type to `T`, an integer type of another size.

## Shift operator

[Section titled “Shift operator”](#shift-operator)

Shift operators `<<` and `>>` are supported in the specification language, and both of them have the same semantics with the Move language. As for abort, if a value `v` has width `n`, then `v << m` or `v >> m` will abort if `m >= n`.

## Bitwise operators

[Section titled “Bitwise operators”](#bitwise-operators)

Move programs using bitwise operators `&`, `|` and `^` can be verified in the prover, and these operators are also supported in the specification language. Due to encoding and efficiency issues, using bitwise operators has more caveats:

* Integers involved in bitwise operations are encoded as `bv` types at the backend, and two encodings of integers are not compatible. For instance, if a variable `v` is involved in a bitwise operation such as `v & 2` or `v = a ^ b`, then when it is used in an arithmetic operation `v * w` or a shift operation `v << w`, `w` will be implicitly cast to a `bv` type in the Move program. However, the specification language does not support implicit type cast so users must explicitly use the built-in function `int2bv` in the specification: `v << int2bv(w)`. Not that since each `bv` type has a fixed length (from 8 to 256), values with type `num` cannot be converted into `bv`.

* Verification of `bv` types is not efficient and may lead to timeout. As a result, users may prefer isolating bitwise operations from other operations and not using `int2bv` if possible. Moreover, users need to use pragmas to explicitly specify which integer-typed function arguments or struct fields will be used in bitwise computations:

```move
module 0x42::m {
  struct C has drop {
    a: u64,
    b: u64
  }
  spec C {
    // b, the second field of C, will be of bv type
    pragma bv = b"1";
  }
  public fun foo_generic<T>(i: T): T {
    i
  }

spec foo_generic {
    // The first parameter will be of bv type if T is instantiated as a number type
    pragma bv = b"0";
    // The first return value will be of bv type if T is instantiated as a number type
    pragma bv_ret = b"0";
  }

public fun test(i: C): u64 {
    let x1 = foo_generic(C.b);
    x1 ^ x1
  }

spec test {
    // Explicit type cast is mandatory for generating correct boogie program
    ensures result == (0 as u64);
  }
}
```

Note that if arguments or fields of a generic function or struct are specified with `bv` types, they will be of `bv` types in all instances of the function or the struct when the instantiated type is an integer type.

* Values with integer types in vectors and tables can be encoded as `bv` types; indices and keys in tables cannot be `bv` types for now. Using other types will lead to internal errors.

## Built-in functions

[Section titled “Built-in functions”](#built-in-functions)

MSL supports a number of built-in constants and functions. Most of them are not available in the Move language:

* `MAX_U8: num`, `MAX_U64: num`, `MAX_U128: num` returns the maximum value of the corresponding type.
* `exists<T>(address): bool` returns true if the resource T exists at address.
* `global<T>(address): T` returns the resource value at address.
* `len<T>(vector<T>): num` returns the length of the vector.
* `update<T>(vector<T>, num, T>): vector<T>` returns a new vector with the element replaced at the given index.
* `vec<T>(): vector<T>` returns an empty vector.
* `vec<T>(x): vector<T>` returns a singleton vector.
* `concat<T>(vector<T>, vector<T>): vector<T>` returns the concatenation of the parameters.
* `contains<T>(vector<T>, T): bool` returns true if element is in vector.
* `index_of<T>(vector<T>, T): num` returns the index of the element in the vector, or the length of the vector if it does not contain it.
* `range<T>(vector<T>): range` returns the index range of the vector.
* `in_range<T>(vector<T>, num): bool` returns true if the number is in the index range of the vector.
* `in_range<T>(range, num): bool` returns true if the number is in the range.
* `update_field(S, F, T): S` updates a field in a struct, preserving the values of other fields, where `S` is some struct, `F` the name of a field in `S`, and `T` a value for this field.
* `old(T): T` delivers the value of the passed argument at point of entry into a Move function. This is allowed in `ensures` post-conditions, inline spec blocks (with additional restrictions), and certain forms of invariants, as discussed later.
* `TRACE(T): T` is semantically the identity function and causes visualization of the argument’s value in error messages created by the prover.
* `int2bv(v)` explicitly converts an integer `v` into its `bv` representation.
* `bv2int(b)` explicitly converts a ‘bv’ integer ‘b’ into the `num` representation. However, it is not encouraged to use it due to efficiency issue.

Built-in functions live in an unnamed outer scope of a module. If the module defines a function `len`, then this definition will shadow that of the according built-in function. To access the built-in function in such a situation, one can use the notation `::len(v)`.

## Partial semantics

[Section titled “Partial semantics”](#partial-semantics)

In MSL, expressions have partial semantics. This is in contrast to Move program expressions, which have total semantics, since they either deliver a value or abort.

An expression `e[X]` that depends on some variables `X` may have a known interpretation for some assignments to variables in `X` but is unknown for others. An unknown interpretation for a sub-expression causes no issue if its value is not needed for the overall expression result. Therefore, it does not matter if we say `y != 0 && x / y > 0` or `x / y > 0 && y != 0`: boolean operators are commutative.

This basic principle inherits to higher-level language constructs. For example, in specifications, it does not matter in which order conditions are supplied: `aborts_if y != 0; ensures result == x / y;` is the same as `ensures result == x / y; aborts_if y != 0;`. Also, `aborts_if P; aborts_if Q;` is the same as `aborts_if Q || P` .

Moreover, the principle of partial semantics is inherited to [specification helper functions](#helper-functions), which behave transparently. Specifically, inlining those functions is equivalent to calling them (call-by-expression parameter passing semantics).

# Specifications

[Section titled “Specifications”](#specifications)

Specifications are contained in so-called *specification blocks* (abbreviated **spec block**) that can appear as module members and inside Move functions. The various types of spec blocks are shown below, and will be discussed in subsequent sections.

```move
module addr::M {
  struct Counter has key {
    value: u8,
  }

public fun increment(a: address) acquires Counter {
    let r = borrow_global_mut<Counter>(a);
    spec {
      // spec block targeting this code position
      // ...
    };
    r.value = r.value + 1;
  }

spec increment {
    // spec block targeting function increment
    // ...
  }

spec Counter {
    // spec block targeting struct Counter
    // ...
  }

spec schema Schema {
    // spec block declaring a schema
    // ...
  }

spec fun f(x: num): num {
    // spec block declaring a helper function
    // ...
  }

spec module {
    // spec block targeting the whole module
    // ...
  }
}
```

Apart from spec blocks inside Move functions, the textual position of spec block is irrelevant. Also, a spec block for a struct, function, or module can be repeated multiple times, accumulating the content.

## Separating specifications

[Section titled “Separating specifications”](#separating-specifications)

Instead of putting specifications into the same module as the regular Move definitions, one can also put them into a separate “specification” module, which can live in the same or a different file:

```move
module addr::M {
    //...
}
spec addr::M {
    spec increment { /* ... */ }
}
```

The syntax of a specification module is the same as for a regular module; however, Move functions and structures are not allowed.

A specification module must be compiled together with the Move module it is targeting and cannot be compiled and verified standalone.

In case Move definitions are far apart (e.g., in different files), it is possible to augment the specification of a Move function with a signature of this function to give sufficient context to understand the specification. This syntax is optionally enabled in regular and in specification modules:

```move
module 0x42::m {
  public fun increment(a: address) acquires Counter { /* ... */ }
  // ...
  spec increment(a: address) { /* ... */ }
}
```

## Pragmas and properties

[Section titled “Pragmas and properties”](#pragmas-and-properties)

Pragmas and properties are a generic mechanism to influence interpretation of specifications. They are also an extension point to experiment with new concepts before they become part of the mainstream syntax. Here we give a brief introduction into their general syntax; individual instances are discussed later.

The general form of a pragma is:

```move
module 0x42::m {
  spec item {
    pragma <name> = <literal>;
  }
}
```

The general form of a property is:

```move
module 0x42::m {
  spec item {
  <directive> [<name> = <literal>] <content>; // ensures, aborts_if, include, etc..
  }
}
```

The `<literal>` can be any value supported by MSL (or the Move language). A value assignment can also be omitted, in which case a default is used. For example, it is common to use `pragma option;` as a shortcut for `pragma option = true;`.

Instead of a single pragma or property, a list can also be provided, as in `invariant [global, isolated] P`.

### Pragma inheritance

[Section titled “Pragma inheritance”](#pragma-inheritance)

A pragma in a module spec block sets a value that applies to all other spec blocks in the module. A pragma in a function or struct spec block can override this value for the function or struct. Furthermore, the default value of some pragmas can be defined via the prover configuration.

As an example, we look at the `verify` pragma. This pragma is used to turn verification on or off.

```move
module 0x42::m {
  spec module {
    pragma verify = false; // By default, do not verify specs in this module ...
  }

spec increment {
    pragma verify = true; // ... but do verify this function.
    // ...
  }
}
```

### General pragmas and properties

[Section titled “General pragmas and properties”](#general-pragmas-and-properties)

A number of pragmas control general behavior of verification. Those are listed in the table below.

| Name                       | Description                                                                                                                                                             |
| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `verify`                   | Turns on or off verification.                                                                                                                                           |
| `intrinsic`                | Marks a function to skip the Move implementation and use a prover native implementation. This makes a function behave like a native function even if it not so in Move. |
| `timeout`                  | Sets a timeout (in seconds) for function or module. Overrides the timeout provided by command line flags.                                                               |
| `verify_duration_estimate` | Sets an estimate (in seconds) for how long the verification of function takes. If the configured `timeout` is less than this value, verification will be skipped.       |
| `seed`                     | Sets a random seed for function or module. Overrides the seed provided by command line flags.                                                                           |

The following properties control general behavior of verification:

| Name            | Description                                          |
| --------------- | ---------------------------------------------------- |
| `[deactivated]` | Excludes the associated condition from verification. |

## Pre and post state

[Section titled “Pre and post state”](#pre-and-post-state)

Multiple conditions in spec blocks work with a *pre* and *post* state, relating them to each other. Function specifications are one example of this: in the `ensures P` condition, the pre-state (at function entry) and the post-state (at function exit) are related via the predicate `P`. However, the concept is more general and also applied for invariants, where the pre-state is before and post-state after a global update.

In contexts where a pre/post-state is active, expressions are evaluated implicitly in the post-state. To evaluate an expression in a pre-state, one uses the built-in function `old(exp)`, which evaluates its parameter in the pre-state and returns its value. It is important to understand that every sub-expression in `exp` is computed in the pre-state as well, including calls to helper functions.

The ‘state’ in question here consists of assignments to global resource memory, as well as to any parameters of the function of type `&mut T`. Examples:

```move
module 0x42::m {
  fun increment(counter: &mut u64) { *counter = *counter + 1 }
  spec increment {
    ensures counter == old(counter) + 1;
  }

fun increment_R(addr: address) {
    let r = borrow_global_mut<R>(addr);
    r.value = r.value + 1;
  }
  spec increment_R {
    ensures global<R>(addr).value == old(global<R>(addr).value) + 1;
  }
}
```

## Helper functions

[Section titled “Helper functions”](#helper-functions)

MSL allows defining helper functions. Those functions can then be used in expressions.

Helper functions are defined using the following syntax:

```move
module 0x42::m {
  spec fun exists_balance<Currency>(a: address): bool { exists<Balance<Currency>>(a) }
}
```

As seen in the example, helper functions can be generic. Moreover, they can access global state.

Definitions of helper functions are neutral regarding whether they apply to a [pre- or post-state](#pre-and-post-state). They are evaluated in the currently active state. For instance, in order to see whether a balance existed in the pre-state, one uses `old(exists_balance<Currency>(a))`. Consequently, the expression `old(..)` is not allowed within the definition of a helper function.

Helper functions are partial functions; see the discussion of [partial semantics](#partial-semantics).

### Uninterpreted functions

[Section titled “Uninterpreted functions”](#uninterpreted-functions)

A helper function can be defined as **uninterpreted** by simply omitting its body:

```move
module 0x42::m {
  spec fun something(x: num): num;
}
```

An uninterpreted function is one of the prover is allowed to assign some arbitrary meaning to, as long as it is consistent within a given verification context. Uninterpreted functions are a useful tool for abstraction in specifications (see also [abstract specifications](#abstract-specifications)).

### Axioms

[Section titled “Axioms”](#axioms)

The meaning of helper functions can be further constrained by using **axioms**. Currently, axioms must be contained in module spec blocks:

```move
module 0x42::m {
  spec module {
    axiom forall x: num: something(x) == x + 1;
  }
}
```

Axioms should be used with care as they can introduce unsoundness in the specification logic via contradicting assumptions. The Move Prover supports a smoke test for detecting unsoundness via the `--check-inconsistency` flag.

## Let bindings

[Section titled “Let bindings”](#let-bindings)

A spec block can contain let bindings that introduce names for expressions:

```move
module 0x42::m {
  fun get_R(account: signer): R { /* ... */ }
  spec get_R {
    let addr = signer::spec_address_of(account);
    aborts_if addr != ROOT;
    ensures result == global<R>(addr);
  }
}
```

In a spec block that has a pre-state and post-state (like a function specification), the `let name = e` form will evaluate `e` in the pre-state. In order to evaluate an expression in the post-state, use `let post name = e`. In the rhs expression of this form, one can use `old(..)` to refer to the pre-state.

## Aborts\_if condition

[Section titled “Aborts\_if condition”](#aborts_if-condition)

The `aborts_if` condition is a spec block member that can appear only in a function context. It specifies conditions under which the function aborts.

In the following example, we specify that the function `increment` aborts if the `Counter` resource does not exist at address `a` (recall that `a` is the name of the parameter of `increment`).

```move
module 0x42::m {
  spec increment {
    aborts_if !exists<Counter>(a);
  }
}
```

If a function has more than one `aborts_if` condition, those conditions are or-ed with each other. The evaluation of the combined aborts condition (or-ed from each individual condition) depends on the value of the pragma `aborts_if_is_partial`. If this value is false (the default), the function aborts *if and only if* the combined aborts condition is true. In this case, the above aborts specification for `increment` will lead to a verification error, since there are additional situations where `increment` can abort, namely if incrementing `Counter.value` would lead to an overflow. To fix this, the specification can be completed like this:

```move
module 0x42::m {
  spec increment {
    pragma aborts_if_is_partial = false; // This is the default, but added here for illustration.
    aborts_if !exists<Counter>(a);
    aborts_if global<Counter>(a).value == 255;
  }
}
```

If the value of `aborts_if_is_partial` is true, the combined aborts condition (the or-ed individual conditions) only *implies* that the function aborts. Formally, if `A` is the combined aborts condition, then with `aborts_if_is_partial = true`, we have `A ==> function_aborts`; otherwise we have `A <==> function_aborts`. Therefore, the following does verify:

```move
module 0x42::m {
  spec increment {
    pragma aborts_if_is_partial = true;
    aborts_if !exists<Counter>(a);
  }
}
```

[]()

> Note that there is a certain risk in setting `aborts_if_is_partial` to true, and best practice is to avoid it in specifications of public functions and Move scripts once those are considered finalized. This is because changing the code after finalization of the spec can add new (non-trivial, undesired) abort situations the original specification did not anticipate yet will nevertheless silently pass verification.

If no aborts condition is specified for a function, abort behavior is unspecified. The function may or may not abort, and verification will not raise any errors, whether `aborts_if_is_partial` is set or not. In order to state that a function never aborts, use `aborts_if false`. One can use the pragma `aborts_if_is_strict` to change this behavior; this is equivalent to an `aborts_if false` being added to each function that does not have an explicit `aborts_if` clause.

### Aborts\_if condition with code

[Section titled “Aborts\_if condition with code”](#aborts_if-condition-with-code)

The `aborts_if` condition can be augmented with code:

```move
module 0x42::m {
  fun get_value(addr: address): u64 {
    aborts(exists<Counter>(addr), 3);
    borrow_global<Counter>(addr).value
  }
  spec get_value {
    aborts_if !exists<Counter>(addr) with 3;
  }
}
```

It is a verification error if the above function does not abort with code `3` under the given condition.

In order to specify a direct VM abort, one can use the special constant `EXECUTION_FAILURE`:

```move
module 0x42::m {
  fun get(addr: address): &Counter acquires Counter {
    borrow_global<Counter>(addr)
  }
  spec get {
    aborts_if !exists<Counter>(addr) with EXECUTION_FAILURE;
  }
}
```

This same constant can be used for all other VM failures (division by zero, overflow, etc.).

## Aborts\_with condition

[Section titled “Aborts\_with condition”](#aborts_with-condition)

The `aborts_with` condition allows specifying with which codes a function can abort, independent under which condition. It is similar to a ‘throws’ clause in languages like Java.

```move
module 0x42::m {
  fun get_one_off(addr: address): u64 {
    aborts(exists<Counter>(addr), 3);
    borrow_global<Counter>(addr).value - 1
  }
  spec get_one_off {
    aborts_with 3, EXECUTION_FAILURE;
  }
}
```

If the function aborts with any other or none of the specified codes, a verification error will be produced.

The `aborts_with` condition can be combined with `aborts_if` conditions. In this case, the `aborts_with` specifies any other codes with which the function may abort, in addition to the ones given in the `aborts_if`:

```move
module 0x42::m {
  spec get_one_off {
    aborts_if !exists<Counter>(addr) with 3;
    aborts_with EXECUTION_FAILURE;
  }
}
```

## Requires condition

[Section titled “Requires condition”](#requires-condition)

The `requires` condition is a spec block member that postulates a pre-condition for a function. The Move Prover will produce verification errors for functions that are called with violating pre-conditions.

A `requires` is different from an `aborts_if`: in the latter case, the function can be called, and any aborts it produces will be propagated to the caller context. In the `requires` case, the Move Prover will not allow the function to be called in the first place. Nevertheless, the function can *still be called at runtime* if verification is skipped. Because of this, `requires` are rare in Move specifications, and `aborts_if` are more common. Specifically, `requires` should be avoided for public APIs.

An example of `requires` is:

```move
module 0x42::m {
  spec increment {
    requires global<Counter>(a).value < 255;
  }
}
```

## Ensures condition

[Section titled “Ensures condition”](#ensures-condition)

The `ensures` condition postulates a post-condition for a function that must be satisfied when the function terminates successfully (i.e., does not abort). The Move Prover will verify each `ensures` to this end.

An example for the `ensures` condition is the following:

```move
module 0x42::m {
  spec increment {
    ensures global<Counter>(a) == old(global<Counter>(a)) + 1;
  }
}
```

Within the expression for the `ensures` condition, one can use the `old` function, as discussed in [Pre and post state](#pre-and-post-state).

## Modifies condition

[Section titled “Modifies condition”](#modifies-condition)

The `modifies` condition is used to provide permissions to a function to modify global storage. The annotation itself comprises a list of global access expressions. It is specifically used together with [opaque function specifications](#opaque-specifications).

```move
module 0x42::m {
  struct S has key {
    x: u64
  }

fun mutate_at(addr: address) acquires S {
    let s = borrow_global_mut<S>(addr);
    s.x = 2;
  }
  spec mutate_at {
    pragma opaque;
    modifies global<S>(addr);
  }
}
```

In general, a global access expression has the form `global<type_expr>(address_expr)`. The address-valued expression is evaluated in the pre-state of the annotated function.

```move
module 0x42::m {
  fun read_at(addr: address): u64 acquires S {
    let s = borrow_global<S>(addr);
    s.x
  }

fun mutate_S_test(addr1: address, addr2: address): bool acquires T {
    assert(addr1 != addr2, 43);
    let x = read_at(addr2);
    mutate_at(
      addr1
    ); // Note we are mutating a different address than the one read before and after
    x == read_at(addr2)
  }
  spec mutate_S_test {
    aborts_if addr1 == addr2;
    ensures result == true;
  }
}
```

In the function `mutate_S_test`, the assertion in the spec block is expected to hold. A benefit of the modifies specification on `mutate_at` is that this assertion can be proved whether `mutate_at` is inlined.

If the modifies annotation is omitted on a function, then that function is deemed to have all possible permissions for those resources it may modify during its execution. The set of all resources that may be modified by a function is obtained via an interprocedural analysis of the code. In the example above, `mutate_S_test` does not have a modifies specification and modifies resource `S` via the call to `mutate_at`. Therefore, it is considered to have modified `S` at any possible address. Instead, if the programmer adds `modifies global<S>(addr1)` to the specification of `mutate_S_test`, then the call to `mutate_at` is checked to make sure that modify permissions granted to `mutate_S_test` cover the permissions it grants to `mutate_at`.

## Invariant condition

[Section titled “Invariant condition”](#invariant-condition)

The invariant condition can be applied on structs and on global level.

### Function invariants

[Section titled “Function invariants”](#function-invariants)

The `invariant` condition on a function is simply a shortcut for a `requires` and `ensures` with the same predicate.

Thus, the following spec block:

```move
module 0x42::m {
  spec increment {
    invariant global<Counter>(a).value < 128;
  }
}
```

… is equivalent to:

```move
module 0x42::m {
  spec increment {
    requires global<Counter>(a).value < 128;
    ensures global<Counter>(a).value < 128;
  }
}
```

### Struct invariants

[Section titled “Struct invariants”](#struct-invariants)

When the `invariant` condition is applied to a struct, it expresses a well-formedness property of the struct data. Any instance of this struct that is currently not mutated will satisfy this property (with exceptions as outlined below).

For example, we can postulate an invariant on our counter that it never must exceed the value of 127:

```move
module 0x42::m {
  spec Counter {
    invariant value < 128;
  }
}
```

A struct invariant is checked by the Move Prover whenever the struct value is constructed (packed). While the struct is mutated (e.g., via a `&mut Counter`) the invariant does *not* hold (but see exception below). In general, we consider mutation as an implicit unpack, and end of mutation as a pack.

The Move language semantics unambiguously identifies the point when mutation ends and starts. This follows from the borrow semantics of Move and includes mutation via an enclosing struct. (The mutation of an inner struct ends when the mutation of the root struct where mutation started ends).

There is one exception to this rule. When a mutable reference to a struct declared in module M is passed into a *public* function of M which does by itself *not* return any other mutable reference (which could be borrowed from the input parameter), we treat this parameter as “packed”. That means, on function entry, we will unpack it and on function exit we will pack again, enforcing the invariant. This reflects that in Move, struct data can be mutated only within the module that declares the struct; so for an outside caller of the public function, the mutable reference can actually not be mutated unless by calling public functions of module M again. It is a significant simplification of the verification problem to exploit this in the semantics.

### Global invariants

[Section titled “Global invariants”](#global-invariants)

A global invariant appears as a member of module. It can express a condition over the global state of the Move program, as represented by resources stored in memory. For example, the below invariant states that a `Counter` resource stored at any given address can never be zero:

```move
module addr::M {
    invariant forall a: addr where exists<Counter>(a): global<Counter>(a).value > 0;
}
```

A global invariant is assumed to hold when data is read from the global state, and is asserted (and may fail to verify) at the moment the state is updated. For example, the below function will never abort with arithmetic underflow because the counter value is always greater than zero; however, it will create a verification error since the counter can drop to zero:

```move
module 0x42::m {
  fun decrement_ad(addr: address) acquires Counter {
    let counter = borrow_global_mut<Counter>(addr);
    let new_value = counter.value - 1;   // Will not abort because counter.value > 0
    *counter.value = new_value;          // Fails verification since value can drop to zero
  }
}
```

Notice that type parameters are supported in global invariants. For example, the invariant above can be rewritten into the below one if `Counter` is generic:

```move
module addr::M {
    invariant<T> forall a: addr where exists<Counter<T>>(a): global<Counter<T>>(a).value > 0;
}
```

#### Disabling invariants

[Section titled “Disabling invariants”](#disabling-invariants)

There are times when a global invariant holds almost everywhere, except for a brief interval inside a function. In current Move code, this often occurs when something (e.g., an account) is being set up and several structs are published together. Almost everywhere, an invariant holds that all the structs are published or none of them are. But the code that publishes the structs must do so sequentially. While the structs are being published, there will be a point where some are published and others are not.

In order to verify invariants that hold except during small regions, there is a feature to allow users to disable invariants temporarily. Consider the following code fragment:

```move
module 0x42::m {
  fun setup() {
    publish1();
    publish2();
  }
}
```

where `publish1` and `publish2` publish two different structs, `T1` and `T2` at address `a`.

```move
module addr::M {
    invariant [global] exists<T1>(a) == exists<T2>(a)
}
```

As written, the Move Prover will report that the invariant is violated after the call to `publish1` and before the call to `publish2`. If either of `publish1` or `publish2` is without the other, the Move Prover will also report a violation of the invariant.

By default, a global invariant is checked immediately after the instruction `I` that touches the resources mentioned in the global invariant. The `[suspendable]` attribute (at the invariant side) together with two pragmas (specified in function spec block) provide fine-grained control on where we hope this invariant to be checked:

* `disable_invariants_in_body`: the invariant will be checked at the end of the function where `I` resides.
* `delegate_invariants_to_caller`: the invariant will be checked by all callers of the function where `I` resides.

For the example above, we can add the pragma `disable_invariants_in_body`:

```move
module 0x42::m {
  spec setup {
    pragma disable_invariants_in_body;
  }
}
```

which says that invariants are not required to hold while `setup` is executing but are assumed to hold on entry to and exit from `setup`.

This pragma changes the Move Prover’s behavior. The invariants are assumed on entry to `setup` but not proved during or after `publish1` and `publish2`. Instead, all invariants that could be invalidated in the body of `setup` are asserted and proved at the point of return from `setup`. A consequence of this processing is that the user may need to provide stronger post-conditions on `publish1` and `publish2` to make it possible to prove the invariants on exit from `setup`.

Another consequence of this processing is that invariants cannot safely be assumed to hold during the execution of `publish1` and `publish2` (unless nothing in the body of `setup` changes state mentioned in the invariant). Therefore, if proving a post-condition requires the invariant to be assumed, the post-condition will fail.

In the example, invariants hold at the call sites of `setup` but not in the body. For `publish1`, invariants don’t necessarily hold at the call site *or* in the body of the function. In the example, that behavior is implied because `publish1` is called in a context where invariants are disabled.

When invariants are disabled in `setup` in the above example, the Move Prover cannot assume them on entry to `publish1` and `publish2` and should not try to prove them on exit from those functions. The Move Prover would have the same behavior for any functions called by `publish1` or `publish2`. The Move Prover *automatically* adopts this behavior when invariants are disabled in a calling function, but it is possible for the user to declare that a function be treated like `publish1`.

For example, if `publish2` is *only* called from the setup function above, and we did *not* disable invariants in `setup`, we could achieve a similar effect by using the pragma `delegate_invariants_to_caller`, instead.

```move
module 0x42::m {
  spec setup {
    pragma delegate_invariants_to_caller;
  }
}
```

This would be legal only if `setup` is a private or `public (friend)` function. The difference between this and disabling invariants in `setup` is that the invariants would not be assumed at the beginning of `setup` and would be proved after `setup` returns at each site where it is called.

While both pragmas disable invariants in the body of a function, the difference is that `disable_invariants_in_body` assumes invariants on entry and proves them on exit, while `delegate_invariants_to_caller` does neither.

There are some limitations on how these pragmas can be used. `disable_invariants_in_body` cannot be declared for functions where invariants are delegated to a caller, either explicitly via the pragma or implicitly because the function is called in a context where invariants have been disabled. (This restriction is to ensure consistent processing, because on pragma assumes that invariants hold in the calling context and the other does not). Second, it is illegal for a public or script function to delegate invariant checking to its callers (since the Move Prover does not know all the call sites), *unless* the function cannot possibly invalidate an invariant because it doesn’t change any of the state mentioned in `exists` and `global` expressions appearing in the invariant.

#### Update invariants

[Section titled “Update invariants”](#update-invariants)

The `update` form of a global invariant allows to express a relation between [pre-state and post-state](#pre-and-post-state) of a global state update. For example, the following invariant states that the counter must decrease monotonically whenever it is updated:

```move
module addr::M {
    invariant update [global] forall a: addr where old(exists<Counter>(a)) && exists<Counter>(addr):
        global<Counter>(a).value <= old(global<Counter>(a));
}
```

#### Isolated global invariants

[Section titled “Isolated global invariants”](#isolated-global-invariants)

A global invariant can be marked as `[isolated]` to indicate that it is not relevant for proving other properties of the program. An isolated global invariant will not be assumed when the related global state is read. It will only be assumed before the state is updated to help prove that the invariant still holds after the update. This feature is for improving performance in situations where there are many global invariants, but they have no direct influence on verification.

#### Modular verification and global invariants

[Section titled “Modular verification and global invariants”](#modular-verification-and-global-invariants)

Certain usage of global invariants leads to verification problems that cannot be checked in a modular fashion. “Modular” here means that a module can be verified standalone and proven to be universally correct in all usage contexts (if preconditions are met).

A non-modular verification problem may arise if a global invariant refers to state from multiple modules. Consider a situation where module `M1` uses module `M2`, and `M1` contains the following invariant, with the helper function `condition` referring to global state of each respective module:

```move
module addr::M1 {
    invariant M1::condition() ==> M2::condition();
}
```

When we verify `M1` standalone, the Move Prover will determine that it also needs to verify functions in `M2`, namely those which update the M2 memory such that the invariant in M1 can fail.

## Assume and assert conditions in code

[Section titled “Assume and assert conditions in code”](#assume-and-assert-conditions-in-code)

A spec block might also occur anywhere an ordinary Move statement block can occur. Here is an example:

```move
module 0x42::m {
  fun simple1(x: u64, y: u64) {
    let z;
    y = x;
    z = x + y;
    spec {
      assert x == y;
      assert z == 2 * x;
    }
  }
}
```

In such inline spec blocks, only a subset of conditions are permitted:

* `assume` and `assert` statements are allowed in any code locations.
* loop `invariant` statements are allowed only in code locations that represent loop headers.

An assert statement inside a spec block indicates a condition that must hold when control reaches that block. If the condition does not hold, an error is reported by the Move Prover. An `assume` statement, on the other hand, blocks executions violating the condition in the statement. The function `simple2` shown below is verified by the Move Prover. However, if the first spec block containing the assume statement is removed, Move Prover will show a violation to the `assert` statement in the second spec block.

```move
module 0x42::m {
  fun simple2(x: u64, y: u64) {
    let z: u64;
    spec {
      assume x > y;
    };
    z = x + y;
    spec {
      assert z > 2 * y;
    }
  }
}
```

### Loop invariants

[Section titled “Loop invariants”](#loop-invariants)

An `invariant` statement encodes a loop invariant and must be placed at a loop head, as in the following example:

```move
module 0x42::m {
  fun simple3(n: u64) {
    let x = 0;
    loop {
      spec {
        invariant x <= n;
      };
      if (x < n) {
        x = x + 1
      } else {
        break
      }
    };
    spec {
      assert x == n;
    }
  }
}
```

A loop invariant is translated into two `assert` statements and one `assume` statement to facilitate the inductive reasoning of properties about the loop. In break down, a loop invariant is translated to:

* An `assert` statement that confirms the invariant holds when the loop is first encountered in the execution — establishing the base case.
* An `assume` statement that encodes the property that the invariant holds at loop iteration `I`.
* An `assert` statement that checks whether the invariant continues to hold at loop iteration `I+1`.

### Referring to pre-state

[Section titled “Referring to pre-state”](#referring-to-pre-state)

Occasionally, we would like to refer to the pre-state of a mutable function argument in inline spec blocks. In MSL, this can be done with the `old(T)` expression. Similar to the semantics of `old(..)` in post conditions, an `old(T)` expression in an `assume` or `assert` statement always yields the value of `T` at the function entry point. Here is an example that illustrate the use of `old(..)` in an inline spec block:

```move
module 0x42::m {
  fun swap(x: &mut u64, y: &mut u64) {
    let t = *x;
    *x = *y;
    *y = t;
    spec {
      assert x == old(y);
      assert y == old(x);
    };
  }
}
```

The above example is trivial as the same property can be expressed with post conditions (i.e., `ensures`) too. But there are cases where we must use `old(..)` to refer to the pre-state, especially in the specification of loop invariants. Consider the following example where we verify that the `vector_reverse` function properly reverses the order of all elements in a vector:

```move
module 0x42::m {
  fun verify_reverse<Element>(v: &mut vector<Element>) {
    let vlen = vector::length(v);
    if (vlen == 0) return;

Note the usage of `old(v)` in the loop invariants. Without them, it is hard to express the invariant that the vector is partially reversed while the loop is iterating and the rest remain unchanged.

However, unlike the `old(T)` expressions in `ensures` conditions where `T` can be any valid expression (e.g., `old(v[i])` is allowed), the `old(T)` expressions in `assert` and `assumes` statements accept only a single variable as `T` and that variable must be a function argument of a mutable reference type. In the above example, `old(v[i])` is not allowed, and we should use `old(v)[i]` instead.

## Specification variables

[Section titled “Specification variables”](#specification-variables)

MSL supports *spec variables*, also called *ghost variables* in the verification community. These variables are used only in specifications and represent information derived from the global state of resources. An example use case is to compute the sum of all coins available in the system and specify that the sum can be changed only in certain scenarios.

We illustrate this feature by introducing a spec variable that maintains the sum of all `Counter` resources from our running example. First, a spec variable is introduced via spec module block as follows:

```move
module 0x42::m {
  spec module {
    global sum_of_counters: num;
  }
}
```

This value is going to be updated whenever a `Counter` is packed or unpacked. (Recall that mutation is interpreted as an implicit unpack and pack):

```move
module 0x42::m {
  spec Counter {
    invariant pack sum_of_counters = sum_of_counters + value;
    invariant unpack sum_of_counters = sum_of_counters - value;
  }
}
```

> TODO: `invariant pack` and `invariant unpack` are currently not implemented

Now we may for example want to specify that the sum of all Counter instances in the global state should never exceed a particular value. We can do this as follows:

```move
module 0x42::m {
  spec module {
    invariant [global] sum_of_counters < 4711;
  }
}
```

Note that spec variables can also be referenced from helper functions. Moreover, spec variables can be generic:

```move
module 0x42::m {
  spec module {
    global some_generic_var<T>: num;
  }
}
```

When using such a spec variable, a type parameter must be provided, as in `some_generic_var<u64>`. Effectively, a generic spec variable is like a family of variables indexed by types.

## Schemas

[Section titled “Schemas”](#schemas)

Schemas are a means for structuring specifications by grouping properties together. Semantically, they are just syntactic sugar that expand to conditions on functions, structs, or modules.

### Basic Schema Usage

[Section titled “Basic Schema Usage”](#basic-schema-usage)

Schemas are used as such:

```move
module 0x42::m {
  spec schema IncrementAborts {
    a: address;
    aborts_if !exists<Counter>(a);
    aborts_if global<Counter>(a).value == 255;
  }

spec increment {
    include IncrementAborts;
  }
}
```

Each schema may declare a number of typed variable names and a list of conditions over those variables. All supported condition types can be used in schemas. The schema can then be included in another spec block:

* If that spec block is for a function or a struct, all variable names the schema declares must be matched against existing names of compatible type in the context.
* If a schema is included in another schema, existing names are matched and must have the same type, but non-existing names will be added as new declarations to the inclusion context.

When a schema is included in another spec block, it will be checked whether the conditions it contains are allowed in this block. For example, including the schema `IncrementAborts` into a struct spec block will lead to a compile-time error.

When a schema is included, the names it declares can also bound by expressions. For example, one can write `include IncrementAborts{a: some_helper_address()}`. Effectively, not providing a binding is equivalent to writing `IncrementAborts{a: a}` if `a` is an existing name in scope.

Schemas can be generic. Generic schemas must be fully instantiated where they are included; type inference is not available for schemas.

### Schema expressions

[Section titled “Schema expressions”](#schema-expressions)

When a schema is included, one can use a limited set of Boolean operators as follows:

* `P ==> SchemaExp`: all conditions in the schema will be prefixed with `P ==> ..`. Conditions that are not based on Boolean expressions will be rejected.
* `if (P) SchemaExp1 else SchemaExp2`: this is treated similar to including both `P ==> SchemaExp1` and `!P ==> SchemaExp2`.
* `SchemaExp1 && SchemaExp2`: this is treated as two includes for both schema expressions.

### Schema apply operation

[Section titled “Schema apply operation”](#schema-apply-operation)

One of the main use cases for schemas is to be able to name a group of properties and then apply those to a set of functions. This is achieved by the `apply` operator. The `apply` spec block member can appear only in module spec blocks.

The general form of the apply operator is `apply Schema to FunctionPattern, .. except FunctionPattern, ..`. Here, `Schema` can be a schema name or a schema name plus formal type arguments. `FunctionPatterns` consists of an optional visibility modifier `public` or `internal` (if not provided, both visibilities will match), a name pattern in the style of a shell file pattern ( e.g., `*`, `foo*`, `foo*bar`, etc.), and finally an optional type argument list. All type arguments provided to `Schema` must be bound in this list and vice versa.

The `apply` operator includes the given schema in all function spec blocks that match the patterns, except those excluded via the `except` patterns.

A typical use of the `apply` operator is to provide common pre-conditions and post-conditions to all functions in a module with some exceptions. Example:

```move
module 0x42::m {
  spec schema Unchanged {
    let resource = global<R>(ADDR);
    ensures resource == old(resource);
  }

spec module {
    // Enforce Unchanged for all functions except the initialize function.
    apply Unchanged to * except initialize;
  }
}
```

Notice that while with [global invariants](#global-invariants) we can express similar things, we *cannot* express the restriction of the invariant to only specific functions.

## Opaque specifications

[Section titled “Opaque specifications”](#opaque-specifications)

With the pragma `opaque`, a function is declared to be solely defined by its specification at caller sides. In contrast, if this pragma is not provided, then the function’s implementation will be used as the basis to verify the caller.

Using `opaque` requires the specification to be sufficiently complete for the verification problem at hand. Without `opaque`, the Move Prover will use the implementation as the source of truth for the definition of the function. But with `opaque`, if there is an aspect of the function definition unspecified, an arbitrary meaning will be assumed. For example, with the specification below, the `increment` function can abort under arbitrary conditions:

```move
module 0x42::m {
  spec increment {
    pragma opaque;
    // aborts_if !exists<Counter>(a);  // We need to add this to make the function not abort arbitrarily
    ensures global<Counter>(a) == old(global<Counter>(a)) + 1;
  }
}
```

In general, `opaque` functions enable modular verification, as they abstract from the implementation of functions, resulting in much faster verification.

If an `opaque` function modifies state, it is advised to use the [`modifies` condition](#modifies-condition) in its specification. If this is omitted, verification of the state changes will fail.

## Abstract specifications

[Section titled “Abstract specifications”](#abstract-specifications)

The `[abstract]` property allows specifying a function such that abstract semantics are used at the caller side that is different from the actual implementation. This is useful if the implementation is too complex for verification, and abstract semantics are sufficient for verification goals. The `[concrete]` property, in turn, still allows specifying conditions that are verified against the implementation but not used at the caller side.

Consider the following example of a hash function. The actual value of the hash is not relevant for verification of callers, and we use an [uninterpreted helper function](#uninterpreted-functions) delivering an arbitrary value chosen by the Move Prover. We can still specify the concrete implementation and verify its correctness:

```move
module 0x42::m {
  fun hash(v: vector<u8>): u64 {
    <<sum up values>>(v)
  }
  spec hash {
    pragma opaque;
    aborts_if false;
    ensures [concrete] result == << sum up values >> (v);
    ensures [abstract] result == spec_hash_abstract(v);
  }
  spec fun abstract_hash(v: vector<u8>): u64; // uninterpreted function
}
```

The soundness of the abstraction is the responsibility of the specifier and not verified by the Move Prover.

> NOTE: The abstract/concrete properties should only be used with opaque specifications, but the Move Prover will currently not generate an error message even though they are not used with opaque specifications.

> NOTE: The `modifies` clause does not currently support abstract/concrete. Also, if no modifies is given, the modified state will be computed from the implementation anyway, possibly conflicting with `[abstract]` properties.

## Documentation generation

[Section titled “Documentation generation”](#documentation-generation)

The organization of specification blocks in a file is relevant for documentation generation — even though it is not for the semantics.

# Expressiveness

[Section titled “Expressiveness”](#expressiveness)

The Move specification language is expressive enough to represent the full Move language semantics (formal argument outstanding) with one exception: functions that return a `&mut T` type.

Consider the following code:

```move
module 0x42::m {
  struct S { x: u64, y: u64 }

fun x_or_y(b: bool, s: &mut S): &mut u64 {
    if (b) &mut s.x else &mut s.y
  }
  spec x_or_y {
    ensures b ==> result == s.x;
    ensures !b ==> result == s.y;
  }
}
```

We are not able to specify the *full* semantics of `x_or_y` in MSL because we cannot capture the semantics of mutable references. While we can say something about the value behind the reference at function exit, subsequent effects as in `*x_or_y(b, &mut s) = 2` cannot be specified.

However, the Move Prover *does* understand the meaning of such functions — the restriction is only in what we can specify. Practically, this means we cannot make the function `x_or_y` opaque and must let verification rely on that the Move Prover directly works with the implementation. Specifically, we can verify the following (which can then be opaque):

```move
module 0x42::m {
  fun x_or_y_test(s: S): S {
    *x_or_y(true, &mut s) = 2;
    s
  }
  spec x_or_y_test {
    pragma opaque;
    ensures result.x == 2;
    ensures result.y == s.y;
  }
}
```

## Supporting resources

[Section titled “Supporting resources”](#supporting-resources)

* [Design by contract PRE\_POST\_REFERENCE](https://en.wikipedia.org/wiki/Design_by_contract)
* [APTOS\_FRAMEWORK](https://github.com/aptos-labs/aptos-core/blob/main/aptos-move/framework/aptos-framework/doc/overview.md)

# Supporting Resources

## Standard Library and Framework Specifications

[Section titled “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

[Section titled “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

[Section titled “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

[Section titled “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

[Section titled “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/>
* 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/>
* 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>

# Randomness API

## What does it do: a quick example

[Section titled “What does it do: a quick example”](#what-does-it-do-a-quick-example)

### How random numbers have been obtained, insecurely/awkwardly

[Section titled “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):

```move
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.

```move
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

[Section titled “Achieve simplicity + security with Aptos randomness API”](#achieve-simplicity--security-with-aptos-randomness-api)

Using Aptos randomness API, the implementation will look like this:

```move
module module_owner::lottery {
    // ...

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

[Section titled “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

[Section titled “How to use Aptos randomness API”](#how-to-use-aptos-randomness-api)

### Prerequisites

[Section titled “Prerequisites”](#prerequisites)

Ensure you have the latest [aptos-cli](https://aptos.dev/en/build/cli) installed.

### Keep undergasing attacks in mind

[Section titled “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

[Section titled “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.

```move
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

[Section titled “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.

```move
module module_owner::lottery {
    // ...

#[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`.

```move
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

[Section titled “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

[Section titled “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.

```move
module module_owner::lottery {
    // ...

#[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.

```move
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]`.

```move
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

[Section titled “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

[Section titled “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

[Section titled “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.

# Move Reference

# Resource Accounts

[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

[Section titled “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

[Section titled “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

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:

```move
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

[Section titled “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

[Section titled “More details”](#more-details)

For more details on Move Scripts, checkout:

* [Move Book on Scripts](/build/smart-contracts/book/modules-and-scripts)
* [Tutorial on Scripts](/build/smart-contracts/scripts/script-tutorial)

# Compiling Move Scripts

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:

```shellscript
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`

```move
script {
  use std::signer;
  use aptos_framework::coin;
  use aptos_framework::aptos_account;

// Send half to the receiver
    let half = balance / 2;
    aptos_account::transfer_coins<Coin>(caller, receiver_address, half);
  }
}
```

Additionally, there is a convenience function for a package with exactly one script with the below command:

```shellscript
aptos move compile-script
```

Providing output like below returning the exact location of the script and a hash for convenience

```shellscript
Compiling, may take a little while to download git dependencies...
UPDATING GIT DEPENDENCY https://github.com/aptos-labs/aptos-framework.git
INCLUDING DEPENDENCY AptosFramework
INCLUDING DEPENDENCY AptosStdlib
INCLUDING DEPENDENCY MoveStdlib
BUILDING 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

Move scripts are supported in the Aptos TypeScript SDK, Aptos Wallet Adapter, and in the Aptos CLI.

## Running scripts with the TypeScript SDK

[Section titled “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.

```typescript
import { readFileSync } from "fs";
import { Aptos, Account, AccountAddress } from "@aptos-labs/ts-sdk";

// Setup client, and account to sign
const aptos = new Aptos();
const account = Account.generate();

// Load script bytecode
const buffer = readFileSync("./transfer_half.mv", "buffer");
const bytecode = new Uint8Array.from(buffer);

// Build a transaction with the bytecode of the script
const 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 complete
const pendingTxn = await aptos.signAndSubmitTransaction({
  signer: account,
  transaction,
});
await aptos.waitForTransaction({ transactionHash: pendingTxn.hash });
```

## Running scripts with the Aptos Wallet Adapter

[Section titled “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`.

```typescript
import { useWallet } from "@aptos-labs/wallet-adapter-react";

//...

// Load the bytecode either as a uint8array or a hex encoded string
const 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

[Section titled “Running scripts with the CLI”](#running-scripts-with-the-cli)

Running scripts with the CLI can be run with the command

```shellscript
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:

```shellscript
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`

```shellscript
aptos move run-script --script-path ./sources/transfer_half.move
```

# Move Scripts Tutorial

This tutorial explains how to write and execute a [Move script](/build/smart-contracts/book/modules-and-scripts). 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

[Section titled “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`.

```move
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

[Section titled “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:

```shellscript
   mkdir testing
   cd testing
   ```

2. Set up the Aptos CLI and [create an account](/build/cli/setup-cli):

```shellscript
   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:

```shellscript
   ---
   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:

```shellscript
   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:

```move
   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:

```shellscript
   $ aptos move compile --named-addresses addr=cb265645385819f3dbe71aac266e319e7f77aed252cacf2930b68102828bf615
   Compiling, may take a little while to download git dependencies...
   INCLUDING DEPENDENCY AptosFramework
   INCLUDING DEPENDENCY AptosStdlib
   INCLUDING DEPENDENCY MoveStdlib
   BUILDING 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`:

```toml
   [addresses]
   addr = "cb265645385819f3dbe71aac266e319e7f77aed252cacf2930b68102828bf615"
   ```

6. Run the compiled script:

```shellscript
   $ aptos move run-script --compiled-script-path build/run_script/bytecode_scripts/main.mv --args address:b078d693856a65401d492f99ca0d6a29a0c5c0e371bc2521570a86e40d95f823 --args u64:5
   Do 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

[Section titled “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:

```shellscript
$ 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?

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

[Section titled “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

[Section titled “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:

```move
script {
  use std::signer;
  use aptos_framework::coin;
  use aptos_framework::aptos_account;

// Send half to the receiver
    let half = balance / 2;
    aptos_account::transfer_coins<Coin>(caller, receiver_address, half);
  }
}
```

For more specific details see: [Move Book on Scripts](/build/smart-contracts/book/modules-and-scripts)

# Smart Table

## Core Features of SmartTable

[Section titled “Core Features of SmartTable”](#core-features-of-smarttable)

### Structure

[Section titled “Structure”](#structure)

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

### Constants

[Section titled “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

[Section titled “API Overview”](#api-overview)

#### Creating Tables

[Section titled “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

[Section titled “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

[Section titled “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

[Section titled “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

[Section titled “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

[Section titled “Example Usage”](#example-usage)

### Creating and Using a SmartTable

[Section titled “Creating and Using a SmartTable”](#creating-and-using-a-smarttable)

```move
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

[Section titled “Adding Multiple Entries to a SmartTable”](#adding-multiple-entries-to-a-smarttable)

```move
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

[Section titled “Updating and Clearing Table”](#updating-and-clearing-table)

```move
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

[Section titled “Converting to Simple Map”](#converting-to-simple-map)

```move
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

[Section titled “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

[Section titled “Other Examples”](#other-examples)

# Smart Vector

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`

[Section titled “Core Features of SmartVector”](#core-features-of-smartvector)

### Structure

[Section titled “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

[Section titled “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

[Section titled “API Overview”](#api-overview)

### Creating Vectors

[Section titled “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

[Section titled “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

[Section titled “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

[Section titled “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

[Section titled “Example Usage”](#example-usage)

### Creating and Using a SmartVector

[Section titled “Creating and Using a SmartVector”](#creating-and-using-a-smartvector)

```move
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

[Section titled “Appending Vectors”](#appending-vectors)

```move
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

[Section titled “Removing Elements”](#removing-elements)

```move
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

[Section titled “Clearing the Vector”](#clearing-the-vector)

```move
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

[Section titled “Swapping Elements”](#swapping-elements)

```move
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

[Section titled “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

[Section titled “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

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

[Section titled “Core Features of Table”](#core-features-of-table)

### Structure

[Section titled “Structure”](#structure)

The `Table` struct is designed to handle large-scale storage with efficiency:

* `handle`: An address that uniquely identifies the table.

### Constants

[Section titled “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

[Section titled “API Overview”](#api-overview)

#### Creating Tables

[Section titled “Creating Tables”](#creating-tables)

* `new<K: copy + drop, V: store>(): Table<K, V>`: Creates a new table.

#### Managing Entries

[Section titled “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

[Section titled “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

[Section titled “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

[Section titled “Example Usage”](#example-usage)

### Creating and Using a Table

[Section titled “Creating and Using a Table”](#creating-and-using-a-table)

```move
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

[Section titled “Adding and Upserting Multiple Entries”](#adding-and-upserting-multiple-entries)

```move
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

[Section titled “Borrowing Mutable References”](#borrowing-mutable-references)

```move
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

[Section titled “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

[Section titled “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

Third party dependencies are external [modules](/build/smart-contracts/book/modules-and-scripts) that a controlled module interacts with. Typically, these external modules exist under different accounts.

## Multi-DEX router example

[Section titled “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](/build/smart-contracts/book/functions#entry-modifier) functions within a swap route, a module (or [script](/build/smart-contracts/book/modules-and-scripts#scripts)) 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

[Section titled “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

[Section titled “Git Repository”](#git-repository)

The default `Move.toml` includes `AptosFramework` as a git repository dependency:

```toml
  [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

[Section titled “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

[Section titled “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:

```shellscript
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

[Section titled “Bytecode”](#bytecode)

The Aptos CLI allows for downloading a [package’s](/build/smart-contracts/book/packages) bytecode.

```shellscript
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:

```move
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.

```shellscript
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

```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.

```toml
[package]
name = "invoking_code"
[addresses]
invoker = "_"
[dependencies]
aptos_token = { local = "../aptos_token_objects_addr" }
```

### ABI

[Section titled “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):

```json
{
"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:

```move
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

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

[Section titled “Data models”](#data-models)

To understand tokens, we begin by comparing the data models across different blockchains.

### Ethereum

[Section titled “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

[Section titled “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

[Section titled “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

[Section titled “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

[Section titled “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

[Section titled “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

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

[Section titled “Core Features of Vector”](#core-features-of-vector)

### Structure

[Section titled “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

[Section titled “Constants”](#constants)

The following constants define various error codes used within the module:

* `EINDEX_OUT_OF_BOUNDS`: 0x20000

### API Overview

[Section titled “API Overview”](#api-overview)

#### Creating Vectors

[Section titled “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

[Section titled “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

[Section titled “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

[Section titled “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

[Section titled “Example Usage”](#example-usage)

### Creating and Using a Vector

[Section titled “Creating and Using a Vector”](#creating-and-using-a-vector)

```move
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

[Section titled “Appending Vectors”](#appending-vectors)

```move
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

[Section titled “Removing Elements”](#removing-elements)

```move
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

[Section titled “Swapping Elements”](#swapping-elements)

```move
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

[Section titled “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

[Section titled “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?

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?

[Section titled “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

[Section titled “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

[Section titled “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 two major IDEs: [Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=MoveBit.aptos-move-analyzer) 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.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |

# ThemedImage Component

> A reusable Astro component that displays different images for light and dark themes, with automatic optimization using Astro's built-in Image component.

## Features

[Section titled “Features”](#features)

* ✅ Supports both light and dark mode images
* ✅ Uses Astro’s optimized Image component for performance
* ✅ Supports the `~/images` alias path
* ✅ Automatic image optimization and processing
* ✅ TypeScript support with strict typing
* ✅ Follows Starlight’s theming conventions (`light:sl-hidden` and `dark:sl-block`)

## Live Demo

[Section titled “Live Demo”](#live-demo)

Try switching between light and dark mode to see the component in action:

![Staking Flow](/_astro/staking-light.tXXsfFR-.svg) ![Staking Flow](/_astro/staking-dark.DVUrnYgo.svg)

## Usage

[Section titled “Usage”](#usage)

### Basic Usage

[Section titled “Basic Usage”](#basic-usage)

```astro
---
import ThemedImage from '~/components/ThemedImage';
---

<ThemedImage
  alt="Staking Flow"
  sources={{
    light: '~/images/staking-light.svg',
    dark: '~/images/staking-dark.svg',
  }}
/>
```

### With Custom Dimensions

[Section titled “With Custom Dimensions”](#with-custom-dimensions)

![Aptos Token Standard Flow](/_astro/aptos-token-standard-flow.Bpdeog-M.svg) ![Aptos Token Standard Flow](/_astro/aptos-token-standard-flow-dark.Bn_ol96l.svg)

```astro
<ThemedImage
  alt="Aptos Token Standard Flow"
  sources={{
    light: '~/images/aptos-token-standard-flow.svg',
    dark: '~/images/aptos-token-standard-flow-dark.svg',
  }}
  width={600}
  height={400}
/>
```

### With Custom CSS Class

[Section titled “With Custom CSS Class”](#with-custom-css-class)

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

```astro
<ThemedImage
  alt="Digital Asset"
  sources={{
    light: '~/images/digital-asset-light.svg',
    dark: '~/images/digital-asset-dark.svg',
  }}
  class="rounded-lg shadow-md"
/>
```

### Using Imported Images

[Section titled “Using Imported Images”](#using-imported-images)

```astro
---
import lightImage from '~/images/my-light-image.png';
import darkImage from '~/images/my-dark-image.png';
import ThemedImage from '~/components/ThemedImage';
---

<ThemedImage
  alt="My Image"
  sources={{
    light: lightImage,
    dark: darkImage,
  }}
/>
```

## Props

[Section titled “Props”](#props)

| Prop       | Type                                                                | Required | Default   | Description                                         |
| ---------- | ------------------------------------------------------------------- | -------- | --------- | --------------------------------------------------- |
| `alt`      | `string`                                                            | ✅        | -         | Alt text for the image (required for accessibility) |
| `sources`  | `{ light: string \| ImageMetadata, dark: string \| ImageMetadata }` | ✅        | -         | Object containing light and dark mode image sources |
| `width`    | `number`                                                            | ❌        | -         | Image width in pixels                               |
| `height`   | `number`                                                            | ❌        | -         | Image height in pixels                              |
| `loading`  | `'lazy' \| 'eager'`                                                 | ❌        | `'lazy'`  | Image loading strategy                              |
| `decoding` | `'async' \| 'sync' \| 'auto'`                                       | ❌        | `'async'` | Image decoding strategy                             |
| `class`    | `string`                                                            | ❌        | `''`      | Additional CSS classes to apply                     |

## How It Works

[Section titled “How It Works”](#how-it-works)

The component renders two `<Image>` components:

1. **Light mode image**: Visible in light theme, hidden in dark theme (`light:sl-block dark:sl-hidden`)
2. **Dark mode image**: Hidden in light theme, visible in dark theme (`light:sl-hidden dark:sl-block`)

Both images use Astro’s optimized `<Image>` component, which provides:

* Automatic image optimization
* WebP/AVIF format conversion
* Responsive image generation
* Lazy loading by default
* Cumulative Layout Shift (CLS) prevention

## Image Path Aliases

[Section titled “Image Path Aliases”](#image-path-aliases)

The component supports the `~/images` alias configured in your Astro project:

astro.config.mjs

```javascript
export default defineConfig({
  vite: {
    resolve: {
      alias: {
        "~/images": fileURLToPath(new URL("./src/assets/images", import.meta.url)),
      },
    },
  },
});
```

This allows you to use paths like `~/images/my-image.svg` instead of relative paths.

## CSS Classes

[Section titled “CSS Classes”](#css-classes)

The component uses Starlight’s theming classes:

* `light:sl-block` - Shows element in light mode
* `dark:sl-hidden` - Hides element in dark mode
* `light:sl-hidden` - Hides element in light mode
* `dark:sl-block` - Shows element in dark mode

## More Examples

[Section titled “More Examples”](#more-examples)

Here are additional examples showing different use cases:

![Indexer Architecture](/_astro/indexer-architecture-light.DkJkKlqr.svg) ![Indexer Architecture](/_astro/indexer-architecture-dark.BhX5FZZG.svg)

![GitHub Logo](data:image/svg+xml,%3csvg%20width='98'%20height='96'%20xmlns='http://www.w3.org/2000/svg'%3e%3cpath%20fill-rule='evenodd'%20clip-rule='evenodd'%20d='M48.854%200C21.839%200%200%2022%200%2049.217c0%2021.756%2013.993%2040.172%2033.405%2046.69%202.427.49%203.316-1.059%203.316-2.362%200-1.141-.08-5.052-.08-9.127-13.59%202.934-16.42-5.867-16.42-5.867-2.184-5.704-5.42-7.17-5.42-7.17-4.448-3.015.324-3.015.324-3.015%204.934.326%207.523%205.052%207.523%205.052%204.367%207.496%2011.404%205.378%2014.235%204.074.404-3.178%201.699-5.378%203.074-6.6-10.839-1.141-22.243-5.378-22.243-24.283%200-5.378%201.94-9.778%205.014-13.2-.485-1.222-2.184-6.275.486-13.038%200%200%204.125-1.304%2013.426%205.052a46.97%2046.97%200%200%201%2012.214-1.63c4.125%200%208.33.571%2012.213%201.63%209.302-6.356%2013.427-5.052%2013.427-5.052%202.67%206.763.97%2011.816.485%2013.038%203.155%203.422%205.015%207.822%205.015%2013.2%200%2018.905-11.404%2023.06-22.324%2024.283%201.78%201.548%203.316%204.481%203.316%209.126%200%206.6-.08%2011.897-.08%2013.526%200%201.304.89%202.853%203.316%202.364%2019.412-6.52%2033.405-24.935%2033.405-46.691C97.707%2022%2075.788%200%2048.854%200z'%20fill='%2324292f'/%3e%3c/svg%3e) ![GitHub Logo](data:image/svg+xml,%3csvg%20width='98'%20height='96'%20xmlns='http://www.w3.org/2000/svg'%3e%3cpath%20fill-rule='evenodd'%20clip-rule='evenodd'%20d='M48.854%200C21.839%200%200%2022%200%2049.217c0%2021.756%2013.993%2040.172%2033.405%2046.69%202.427.49%203.316-1.059%203.316-2.362%200-1.141-.08-5.052-.08-9.127-13.59%202.934-16.42-5.867-16.42-5.867-2.184-5.704-5.42-7.17-5.42-7.17-4.448-3.015.324-3.015.324-3.015%204.934.326%207.523%205.052%207.523%205.052%204.367%207.496%2011.404%205.378%2014.235%204.074.404-3.178%201.699-5.378%203.074-6.6-10.839-1.141-22.243-5.378-22.243-24.283%200-5.378%201.94-9.778%205.014-13.2-.485-1.222-2.184-6.275.486-13.038%200%200%204.125-1.304%2013.426%205.052a46.97%2046.97%200%200%201%2012.214-1.63c4.125%200%208.33.571%2012.213%201.63%209.302-6.356%2013.427-5.052%2013.427-5.052%202.67%206.763.97%2011.816.485%2013.038%203.155%203.422%205.015%207.822%205.015%2013.2%200%2018.905-11.404%2023.06-22.324%2024.283%201.78%201.548%203.316%204.481%203.316%209.126%200%206.6-.08%2011.897-.08%2013.526%200%201.304.89%202.853%203.316%202.364%2019.412-6.52%2033.405-24.935%2033.405-46.691C97.707%2022%2075.788%200%2048.854%200z'%20fill='%23fff'/%3e%3c/svg%3e)

# LLMs.txt

> How to get tools like Cursor, GitHub Copilot, ChatGPT, and Claude to understand Aptos documentation.

## What is LLMs.txt?

[Section titled “What is LLMs.txt?”](#what-is-llmstxt)

We support [LLMs.txt](https://llmstxt.org/) files for making the Aptos documentation available to large language models (LLMs). This feature helps AI tools better understand the Aptos blockchain, its Move language, SDKs, and development patterns.

## Available Routes

[Section titled “Available Routes”](#available-routes)

We provide the following LLMs.txt routes to help AI tools access our documentation:

* [llms.txt](/llms.txt) - Contains a structured overview of Aptos LLMs.txt files
* [llms-small.txt](/llms-small.txt) - Provides a condensed version of the documentation, optimized for smaller context windows
* [llms-full.txt](/llms-full.txt) - Provides the full comprehensive documentation for all Aptos concepts

## Usage with AI Tools

[Section titled “Usage with AI Tools”](#usage-with-ai-tools)

### Cursor

[Section titled “Cursor”](#cursor)

Use the `@Docs` feature in Cursor to include the LLMs.txt files in your project. This helps Cursor provide more accurate code suggestions and documentation for Aptos development.

[Read more about @Docs in Cursor](https://docs.cursor.com/context/@-symbols/@-docs)

### GitHub Copilot

[Section titled “GitHub Copilot”](#github-copilot)

GitHub Copilot can leverage the information in these LLMs.txt files to provide better assistance when developing Aptos applications. You can reference these files in your GitHub Copilot Chat by using the following URLs:

```plaintext
https://aptos.dev/llms.txt
https://aptos.dev/llms-small.txt
https://aptos.dev/llms-full.txt
```

### Windsurf

[Section titled “Windsurf”](#windsurf)

Reference the LLMs.txt files using `@` or in your `.windsurfrules` files to enhance Windsurf’s understanding of Aptos development.

[Read more about Windsurf Memories](https://docs.codeium.com/windsurf/memories#memories-and-rules)

### Other AI Tools

[Section titled “Other AI Tools”](#other-ai-tools)

Any AI tool that supports LLMs.txt can use these routes to better understand Aptos. Simply point your tool to any of the routes above.

# Blockchain

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.

# Accounts

An account on the Aptos blockchain represents access control over a set of assets including on-chain currency and NFTs. In Aptos, these assets are represented by a Move language primitive known as a **resource** that emphasizes both access control and scarcity.

Each account on the Aptos blockchain is identified by a 32-byte account address. You can employ the Aptos Name Service at [www.aptosnames.com](https://www.aptosnames.com/) to secure .apt domains for key accounts to make them memorable and unique.

Different from other blockchains where accounts and addresses are implicit, accounts on Aptos are explicit and need to be created before they can execute transactions. The account can be created explicitly or implicitly by transferring Aptos tokens (APT) there. See the [Creating an account](#creating-an-account) section for more details. In a way, this is similar to other chains where an address needs to be sent funds for gas before it can send transactions.

Explicit accounts allow first-class features that are not available on other networks such as:

* Rotating authentication key. The account’s authentication key can be changed to be controlled via a different private key. This is similar to changing passwords in the web2 world.
* Native multisig support. Accounts on Aptos support k-of-n multisig using both Ed25519 and Secp256k1 ECDSA signature schemes when constructing the authentication key.

There are three types of accounts on Aptos:

* *Standard account* - This is a typical account corresponding to an address with a corresponding pair of public/private keys.
* [*Resource account*](/build/smart-contracts/resource-accounts) - An autonomous account without a corresponding private key used by developers to store resources or publish modules on-chain.
* [*Object*](/build/smart-contracts/objects) - A complex set of resources stored within a single address representing a single entity.

Note

Account addresses are 32-bytes. They are usually shown as 64 hex characters, with each hex character a nibble. Sometimes the address is prefixed with a 0x. See the [Your First Transaction](/build/guides/first-transaction) for an example of how an address appears, reproduced below:

```text
Alice: 0xeeff357ea5c1a4e7bc11b2b17ff2dc2dcca69750bfef1e1ebcaccf8c8018175b
Bob: 0x19aadeca9388e009d136245b9a67423f3eee242b03142849eb4f81a4a409e59c
```

## Account address

[Section titled “Account address”](#account-address)

Currently, Aptos supports only a single, unified identifier for an account. Accounts on Aptos are universally represented as a 32-byte hex string. A hex string shorter than 32-bytes is also valid; in those scenarios, the hex string can be padded with leading zeroes, e.g., `0x1` => `0x0000000000000...01`. While Aptos standards indicate leading zeroes may be removed from an Address, most applications attempt to eschew that legacy behavior and only support the removal of 0s for special addresses ranging from `0x0` to `0xa`.

## Creating an account

[Section titled “Creating an account”](#creating-an-account)

When a user requests to create an account, for example by using the [Aptos SDK](/build/sdks/ts-sdk/account), the following steps are executed:

* Select the authentication scheme for managing the user’s account, e.g., Ed25519 or Secp256k1 ECDSA.
* Generate a new private key, public key pair.
* Combine the public key with the public key’s authentication scheme to generate a 32-byte authentication key and the account address.

The user should use the private key for signing the transactions associated with this account.

## Account sequence number

[Section titled “Account sequence number”](#account-sequence-number)

The sequence number for an account indicates the number of transactions that have been submitted and committed on-chain from that account. Committed transactions either execute with the resulting state changes committed to the blockchain or abort wherein state changes are discarded and only the transaction is stored.

Every transaction submitted must contain a unique sequence number for the given sender’s account. When the Aptos blockchain processes the transaction, it looks at the sequence number in the transaction and compares it with the sequence number in the on-chain account. The transaction is processed only if the sequence number is equal to or larger than the current sequence number. Transactions are only forwarded to other mempools or executed if there is a contiguous series of transactions from the current sequence number. Execution rejects out of order sequence numbers preventing replay attacks of older transactions and guarantees ordering of future transactions.

## Authentication key

[Section titled “Authentication key”](#authentication-key)

The initial account address is set to the authentication key derived during account creation. However, the authentication key may subsequently change, for example when you generate a new public-private key pair, public keys to rotate the keys. An account address never changes.

The Aptos blockchain supports the following authentication schemes:

1. [Ed25519](https://ed25519.cr.yp.to/)
2. [Secp256k1 ECDSA](https://github.com/aptos-foundation/AIPs/blob/main/aips/aip-49.md)
3. [K-of-N multi-signatures](https://github.com/aptos-foundation/AIPs/blob/main/aips/aip-55.md)
4. A dedicated, now legacy, MultiEd25519 scheme

Note

The Aptos blockchain defaults to Ed25519 signature transactions.

### Ed25519 authentication

[Section titled “Ed25519 authentication”](#ed25519-authentication)

To generate an authentication key and the account address for an Ed25519 signature:

1. **Generate a key-pair**: Generate a fresh key-pair (`privkey_A`, `pubkey_A`). The Aptos blockchain uses the PureEdDSA scheme over the Ed25519 curve, as defined in RFC 8032.

2. **Derive a 32-byte authentication key**: Derive a 32-byte authentication key from the `pubkey_A`:

```text
   auth_key = sha3-256(pubkey_A | 0x00)
   ```

where `|` denotes concatenation. The `0x00` is the 1-byte single-signature scheme identifier.

3. Use this initial authentication key as the permanent account address.

### MultiEd25519 authentication

[Section titled “MultiEd25519 authentication”](#multied25519-authentication)

With K-of-N multisig authentication, there are a total of N signers for the account, and at least K of those N signatures must be used to authenticate a transaction.

To generate a K-of-N multisig account’s authentication key and the account address:

1. **Generate key-pairs**: Generate `N` ed25519 public keys `p_1`, …, `p_n`.

2. Decide on the value of `K`, the threshold number of signatures needed for authenticating the transaction.

3. **Derive a 32-byte authentication key**: Compute the authentication key as described below:

```text
   auth_key = sha3-256(p_1 | . . . | p_n | K | 0x01)
   ```

The `0x01` is the 1-byte multisig scheme identifier.

4. Use this initial authentication key as the permanent account address.

### Generalized authentication

[Section titled “Generalized authentication”](#generalized-authentication)

Generalized authentication supports both Ed25519 and Secp256k1 ECDSA. Like the previous authentication schemes, these schemes contain a scheme value, `0x02` and `0x03` for single and multikey respectively, but also each key contains a prefix value to indicate its key type:

| Key type                          | Prefix byte |
| --------------------------------- | ----------- |
| Ed25519 generalized scheme        | `0x00`      |
| Secp256k1Ecdsa generalized scheme | `0x01`      |
| Secp256r1Ecdsa WebAuthn scheme    | `0x02`      |
| Keyless                           | `0x03`      |

For a single key Secp256k1 ECDSA account, using public key `pubkey`, the authentication key would be derived as follows:

```text
auth_key = sha3-256(0x01 | pubkey | 0x02)
```

Where

* the first entry, `0x01`, represents the use of a Secp256k1 ECDSA key;
* the last entry, `0x02`, represents the authentication scheme.

For a 1-of-2 multi-key account containing, a single Secp256k1 ECDSA public key, `pubkey_0`, and a single Ed25519 public key, `pubkey_1`, where one signature suffices, the authentication key would be derived as follows:

```text
auth_key = sha3-256(0x02 | 0x01 | pubkey_0 | 0x00 | pubkey_1 | 0x01 | 0x03)
```

Where

* the first entry, `0x02`, represents the total number of keys as a single byte;
* the second to last entry, `0x01`, represents the required number of signatures as a single byte;
* the last entry, `0x03`, represents the authentication scheme.

## Rotating the keys

[Section titled “Rotating the keys”](#rotating-the-keys)

An Account on Aptos has the ability to rotate keys so that potentially compromised keys cannot be used to access the accounts. Keys can be rotated via the `account::rotate_authentication_key` function.

Refreshing the keys is generally regarded as good hygiene in the security field. However, this presents a challenge for system integrators who are used to using a mnemonic to represent both a private key and its associated account. To simplify this for the system integrators, Aptos provides an on-chain mapping via aptos account lookup-address. The on-chain data maps an effective account address as defined by the current mnemonic to the actual account address.

For more information, see [`account.move`](https://github.com/aptos-labs/aptos-core/blob/a676c1494e246c31c5e96d3363d99e2422e30f49/aptos-move/framework/aptos-framework/sources/account.move#L274).

## State of an account

[Section titled “State of an account”](#state-of-an-account)

The state of each account comprises both the code (Move modules) and the data (Move resources). An account may contain an arbitrary number of Move modules and Move resources:

* **Move modules**: Move modules contain code, for example, type and procedure declarations; but they do not contain data. A Move module encodes the rules for updating the Aptos blockchain’s global state.
* **Move resources**: Move resources contain data but no code. Every resource value has a type that is declared in a module published on the Aptos blockchain.

## Access control with signers

[Section titled “Access control with signers”](#access-control-with-signers)

The sender of a transaction is represented by a signer. When a function in a Move module takes `signer` as an argument, the Aptos Move VM translates the identity of the account that signed the transaction into a signer in a Move module entry point. See the below Move example code with `signer` in the `initialize` and `withdraw` functions. When a `signer` is not specified in a function, for example, the below `deposit` function, then no signer-based access controls will be provided for this function:

```move
module Test::Coin {
  struct Coin has key { amount: u64 }

public fun initialize(account: &signer) {
    move_to(account, Coin { amount: 1000 });
  }

public fun withdraw(account: &signer, amount: u64): Coin acquires Coin {
    let balance = &mut borrow_global_mut<Coin>(Signer::address_of(account)).amount;
    *balance = *balance - amount;
    Coin { amount }
  }

public fun deposit(account: address, coin: Coin) acquires Coin {
      let balance = &mut borrow_global_mut<Coin>(account).amount;
      *balance = *balance + coin.amount;
      Coin { amount: _ } = coin;
  }
}
```

# Aptos White Paper

## Full PDF Versions

[Section titled “Full PDF Versions”](#full-pdf-versions)

[🇺🇸 English (en-US) ↗ ](https://aptosfoundation.org/whitepaper/aptos-whitepaper_en.pdf)Original Aptos White Paper PDF in English

[🇰🇷 한국어 Korean (ko-KR) ↗ ](https://aptosfoundation.org/whitepaper/aptos-whitepaper_ko.pdf)Aptos White Paper PDF translated to Korean

[🇯🇵 日本語 Japanese (ja-JP) ↗ ](https://aptosfoundation.org/whitepaper/aptos-whitepaper_ja.pdf)Aptos White Paper PDF translated to Japanese

[🇪🇸 Español Spanish (es-ES) ↗ ](https://aptosfoundation.org/whitepaper/aptos-whitepaper_es.pdf)Aptos White Paper PDF translated to Spanish

## Abstract

[Section titled “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

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

[Section titled “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

[Section titled “No-operation”](#no-operation)

| Parameter | Meaning        |
| --------- | -------------- |
| `nop`     | A no-operation |

### Control flow

[Section titled “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

[Section titled “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

[Section titled “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

[Section titled “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

[Section titled “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

[Section titled “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

[Section titled “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

[Section titled “Arithmetic”](#arithmetic)

| Parameter | Meaning  |
| --------- | -------- |
| `add`     | Add      |
| `sub`     | Subtract |
| `mul`     | Multiply |
| `mod_`    | Modulo   |
| `div`     | Divide   |

### Bitwise

[Section titled “Bitwise”](#bitwise)

| Parameter | Meaning           |
| --------- | ----------------- |
| `bit_or`  | `OR`: `\|`        |
| `bit_and` | `AND`: `&`        |
| `xor`     | `XOR`: `^`        |
| `shl`     | Shift left: `<<`  |
| `shr`     | Shift right: `>>` |

### Boolean

[Section titled “Boolean”](#boolean)

| Parameter | Meaning      |
| --------- | ------------ |
| `or`      | `OR`: `\|\|` |
| `and`     | `AND`: `&&`  |
| `not`     | `NOT`: `!`   |

### Comparison

[Section titled “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

[Section titled “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

[Section titled “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

[Section titled “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

[Section titled “Vectors”](#vectors-1)

Byte-wise fees are similarly assessed on vectors, which consume ∑\_i=0n−1e\_i+b(n) bytes, where:

* n is the number of elements in the vector
* e\_i is the size of element i
* b(n) is a “base size” which is a function of n

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=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

[Section titled “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

[Section titled “Optimization principles”](#optimization-principles)

### Unit and pricing constants

[Section titled “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

[Section titled “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

[Section titled “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=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

[Section titled “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

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

[Section titled “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

[Section titled “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.

```mermaid
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[3\nMempool]
        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| 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

[Section titled “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

[Section titled “Accepting the transaction”](#accepting-the-transaction)

### Sharing the transaction with other validator nodes

[Section titled “Sharing the transaction with other validator nodes”](#sharing-the-transaction-with-other-validator-nodes)

### Proposing the block

[Section titled “Proposing the block”](#proposing-the-block)

### Executing the block and reaching consensus

[Section titled “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

[Section titled “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

[Section titled “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

[Section titled “REST Service”](#rest-service)

```mermaid
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

[Section titled “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

[Section titled “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

[Section titled “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

[Section titled “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)

[Section titled “Virtual Machine (VM)”](#virtual-machine-vm)

```mermaid
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

[Section titled “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

[Section titled “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

[Section titled “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

[Section titled “Mempool”](#mempool)

```mermaid
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

[Section titled “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

[Section titled “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

[Section titled “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

[Section titled “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

[Section titled “Consensus”](#consensus)

```mermaid
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

[Section titled “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

[Section titled “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

[Section titled “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

[Section titled “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

[Section titled “Execution”](#execution)

```mermaid
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

[Section titled “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

[Section titled “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

[Section titled “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

[Section titled “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

[Section titled “Storage”](#storage)

```mermaid
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

[Section titled “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

[Section titled “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

[Section titled “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

[Section titled “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

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

[Section titled “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

[Section titled “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

## Delegated Staking on the Aptos Blockchain

[Section titled “Delegated Staking on the Aptos Blockchain”](#delegated-staking-on-the-aptos-blockchain)

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)

![image](https://user-images.githubusercontent.com/120680608/234953723-ae6cc89e-76d8-4014-89f3-ec8799c7b281.png)

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

[Section titled “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

[Section titled “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

[Section titled “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

[Section titled “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

[Section titled “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

[Section titled “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

[Section titled “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

[Section titled “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

[Section titled “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

[Section titled “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

[Section titled “Resetting the lockup”](#resetting-the-lockup)

Lockup cannot be reset.

## Rewards

[Section titled “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

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

[Section titled “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,

```move
/// 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:

```move
// 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 "Module event example")

## Access in Tests

[Section titled “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:

```move
/// 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

[Section titled “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)

[Section titled “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

```json
[
  {
    "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

[Section titled “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

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?

[Section titled “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

[Section titled “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

[Section titled “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

[Section titled “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

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

[Section titled “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

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

[Section titled “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

[Section titled “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`.

```move
#[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

[Section titled “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

[Section titled “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:

```text
  (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

[Section titled “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

[Section titled “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

[Section titled “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

[Section titled “Examples”](#examples)

### Example 1: Account balance vs transaction fee

[Section titled “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

[Section titled “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

[Section titled “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

[Section titled “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.

# Governance

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

[Section titled “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

[Section titled “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

[Section titled “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

[Section titled “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)

[Section titled “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

[Section titled “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

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?

[Section titled “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

[Section titled “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

[Section titled “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

[Section titled “More Resources”](#more-resources)

Developers can begin their journey in Move by heading over to our [Move developer page](/network/blockchain/move).

# Node Networks and Sync

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)

## Node types

[Section titled “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

[Section titled “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

[Section titled “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

[Section titled “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).

# Resources

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

[Section titled “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:

```move
/// 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:

```move
struct CustomCoinBox<phantom CoinType> has key {
    coin: Coin<CoinType>,
}
```

## Define resources and objects

[Section titled “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:

```move
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

[Section titled “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

[Section titled “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

[Section titled “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

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

[Section titled “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

[Section titled “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

[Section titled “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

[Section titled “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

[Section titled “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

[Section titled “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

[Section titled “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

[Section titled “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

[Section titled “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

[Section titled “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

[Section titled “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

[Section titled “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

[Section titled “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

[Section titled “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

[Section titled “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

[Section titled “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

[Section titled “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

[Section titled “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

[Section titled “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

[Section titled “Rewards formula”](#rewards-formula)

See below the formula used to calculate rewards to the validator:

```text
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

[Section titled “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

[Section titled “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

[Section titled “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

[Section titled “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

[Section titled “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)

# Transactions and States

The Aptos blockchain stores three types of data:

* **Transactions**: Transactions represent an intended operation being performed by an account on the blockchain (e.g., transferring assets).
* **States**: The (blockchain ledger) state represents the accumulation of the output of execution of transactions, the values stored within all [resources](/network/blockchain/resources).
* [**Events**](/network/blockchain/events): Ancillary data published by the execution of a transaction.

Note

Only transactions can change the ledger state.

## Transactions

[Section titled “Transactions”](#transactions)

Aptos transactions contain information such as the sender’s account address, authentication from the sender, the desired operation to be performed on the Aptos blockchain, and the amount of gas the sender is willing to pay to execute the transaction.

### Transaction states

[Section titled “Transaction states”](#transaction-states)

A transaction may end in one of the following states:

* Committed on the blockchain and executed. This is considered as a successful transaction.
* Committed on the blockchain and aborted. The abort code indicates why the transaction failed to execute.
* Discarded during transaction submission due to a validation check such as insufficient gas, invalid transaction format, or incorrect key.
* Discarded after transaction submission but before attempted execution. This could be caused by timeouts or insufficient gas due to other transactions affecting the account.

The sender’s account will be charged gas for any committed transactions.

During transaction submission, the submitter is notified of successful submission or a reason for failing validations otherwise.

A transaction that is successfully submitted but ultimately discarded may have no visible state in any accessible Aptos node or within the Aptos network. A user can attempt to resubmit the same transaction to re-validate the transaction. If the submitting node believes that this transaction is still valid, it will return an error stating that an identical transaction has been submitted.

The submitter can try to increase the gas cost by a trivial amount to help make progress and adjust for whatever may have been causing the discarding of the transaction further downstream.

Note

See [Aptos Blockchain Deep Dive](/network/blockchain/blockchain-deep-dive) for a comprehensive description of the Aptos transaction lifecycle.

### Contents of a Transaction

[Section titled “Contents of a Transaction”](#contents-of-a-transaction)

A signed transaction on the blockchain contains the following information:

* **Signature**: The sender uses a digital signature to verify that they signed the transaction (i.e., authentication).
* **Sender address**: The sender’s [account address](/network/blockchain/accounts#account-address).
* **Sender public key**: The public authentication key that corresponds to the private authentication key used to sign the transaction.
* **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](/network/blockchain/gas-txn-fee#specifying-gas-fees-within-a-transaction) in APT the sender 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 as [Octas](/network/glossary#octa).
* **Gas price** (in specified gas units): This is the amount the sender is willing to pay per unit of [gas](/network/blockchain/gas-txn-fee) to execute the transaction. [Gas](/network/blockchain/gas-txn-fee) is a way to pay for computation and storage. A gas unit is an abstract measurement of computation with no inherent real-world value.
* **Sequence number**: This is an unsigned integer that must be equal to the sender’s account [sequence number](/network/blockchain/accounts#account-sequence-number) at the time of execution.
* **Expiration time**: A timestamp after which the transaction ceases to be valid (i.e., expires).

### Types of transaction payloads

[Section titled “Types of transaction payloads”](#types-of-transaction-payloads)

Within a given transaction, the two most common types of payloads include:

* An entry point
* [A script (payload)](/build/smart-contracts/scripts)

Currently, the SDKs [Python](/build/sdks/python-sdk) and [Typescript](/build/sdks/ts-sdk) support both. This guide points out many of those entry points, such as `coin::transfer` and `aptos_account::create_account`.

All operations on the Aptos blockchain should be available via entry point calls. While one could submit multiple transactions calling entry points in series, many such operations may benefit from being called atomically from a single transaction. A script payload transaction can call any entry point or public function defined within any module.

Note

See the tutorial on [Your First Transaction](/build/guides/first-transaction) for generating valid transactions.

Note

The Aptos REST API supports generating BCS-encoded transactions from JSON. This is useful for rapid prototyping, but be cautious using it in Mainnet as this places a lot of trust on the fullnode generating the transaction.

## States

[Section titled “States”](#states)

The Aptos blockchain’s ledger state, or global state, represents the state of all accounts in the Aptos blockchain. Each validator node in the blockchain must know the latest version of the global state to execute any transaction.

Anyone can submit a transaction to the Aptos blockchain to modify the ledger state. Upon execution of a transaction, a transaction output is generated. A transaction output contains zero or more operations to manipulate the ledger state called **write sets** emitting a vector of resulting events, the amount of gas consumed, and the executed transaction status.

### Proofs

[Section titled “Proofs”](#proofs)

The Aptos blockchain uses proof to verify the authenticity and correctness of the blockchain data.

Data within the Aptos blockchain is replicated across the network. Each validator and fullnode’s [storage](/network/blockchain/validator-nodes#storage) is responsible for persisting the agreed upon blocks of transactions and their execution results to the database.

The blockchain is represented as an ever-growing [Merkle tree](/network/glossary#merkle-trees), where each leaf appended to the tree represents a single transaction executed by the blockchain.

All operations executed by the blockchain and all account states can be verified cryptographically. These cryptographic proofs ensure that:

* The validator nodes agree on the state.
* The client does not need to trust the entity from which it is receiving data. For example, if a client fetches the last **n** transactions from an account, a proof can attest that no transactions were added, omitted or modified in the response. The client may also query for the state of an account, ask whether a specific transaction was processed, and so on.

### Versioned database

[Section titled “Versioned database”](#versioned-database)

The ledger state is versioned using an unsigned 64-bit integer corresponding to the number of transactions the system has executed. This versioned database allows the validator nodes to:

* Execute a transaction against the ledger state at the latest version.
* Respond to client queries about ledger history at both current and previous versions.

## Transactions change ledger state

[Section titled “Transactions change ledger state”](#transactions-change-ledger-state)

![Signed Transaction Flow](/_astro/transactions-and-state.DnHxozEu.svg) ![Signed Transaction Flow](/_astro/transactions-and-state-dark.ffwcWBtN.svg)

The above figure shows how executing transaction T*i* changes the state of the Aptos blockchain from S*i-1* to S*i*.

In the figure:

* Accounts **A** and **B**: Represent Alice’s and Bob’s accounts on the Aptos blockchain.
* **S*i-1*** : Represents the (*i-1*)-the state of the blockchain. In this state, Alice’s account **A** has a balance of 110 APT (Aptos coins), and Bob’s account **B** has a balance of 52 APT.
* **T*i*** : This is the *i*-th transaction executed on the blockchain. In this example, it represents Alice sending 10 APT to Bob.
* **Apply()**: This is a deterministic function that always returns the same final state for a specific initial state and a specific transaction. If the current state of the blockchain is **S*i-1***, and transaction **T*i*** is executed on the state **S*i-1***, then the new state of the blockchain is always **S*i***. The Aptos blockchain uses the [Move language](/build/smart-contracts/book/SUMMARY) to implement the deterministic execution function **Apply()**.
* **S*i*** : This is the *i*-the state of the blockchain. When the transaction **T*i*** is applied to the blockchain, it generates the new state **S*i*** (an outcome of applying **Apply(S*i-1*, T*i*)** to **S*i-1*** and **T*i***). This causes Alice’s account balance to be reduced by 10 to 100 APT and Bob’s account balance to be increased by 10 to 62 APT. The new state **S*i*** shows these updated balances.

## Size limits

[Section titled “Size limits”](#size-limits)

As part of the gas schedule, there are on-chain configurable limits for the sizes of [the transaction itself](https://github.com/aptos-labs/aptos-core/blob/8074588b5c9c4424fa247c2c9ec5572981ee31cd/aptos-move/aptos-gas-schedule/src/gas_schedule/transaction.rs#L71-L81) and [its outputs](https://github.com/aptos-labs/aptos-core/blob/8074588b5c9c4424fa247c2c9ec5572981ee31cd/aptos-move/aptos-gas-schedule/src/gas_schedule/transaction.rs#L152-L177).

| Limit Type             | Current Per Transaction Limit |
| ---------------------- | ----------------------------- |
| transaction            | 64KB                          |
| governance transaction | 1MB                           |
| a single write op      | 1MB                           |
| all write ops combined | 10MB                          |
| number of write ops    | 8192                          |
| a single event         | 1MB                           |
| all events combined    | 10MB                          |

# Validator Nodes Overview

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.

## Overview

[Section titled “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

[Section titled “Validator node components”](#validator-node-components)

![](/_astro/validator.Cw82vyRD.svg)

### Mempool

[Section titled “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

[Section titled “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

[Section titled “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)

[Section titled “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

[Section titled “Storage”](#storage)

The storage component is used to persist agreed upon blocks of transactions and their execution results to the local database.

### State synchronizer

[Section titled “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.

# Faucet

Content for network/faucet could not be fully rendered due to component compatibility issues.

# Aptos Glossary

## A

[Section titled “A”](#a)

### Accumulator Root Hash

[Section titled “Accumulator Root Hash”](#accumulator-root-hash)

* An **accumulator root hash** is the root hash of a [Merkle accumulator](https://eprint.iacr.org/2009/625.pdf).

### Account

[Section titled “Account”](#account)

* An **account** in the Aptos blockchain is a container for an arbitrary number of [Move modules](#move-module) and [Move resources](#move-resources).
* The state of each account is composed of both code and data.
* The account is identified by [account address](#account-address).

See [Accounts](/network/blockchain/accounts) for more information.

### Account Address

[Section titled “Account Address”](#account-address)

* An **account address** is the address of an Aptos account.
* Account address refers to a specific destination on the Aptos network. The address dictates the destination and source of a specific amount of assets exchanged by two parties on the blockchain.
* Aptos addresses are 64-character hex string (32 bytes). Often times these strings are prefixed with `0x` and for first 16 addresses, the leading 0s are excluded (ex. `0x1`)

See [Accounts](/network/blockchain/accounts) for more information.

### API

[Section titled “API”](#api)

* An **Application Programming Interface (API)** is a set of protocols and tools that allow users to interact with Aptos blockchain nodes and client networks via external applications. Aptos offers a REST API to communicate with our nodes.
* See [documentation](/build/apis) for more details.

### APT

[Section titled “APT”](#apt)

**Aptos token (APT)** is the Aptos blockchain native token used for paying network and transaction fees.

### Aptos

[Section titled “Aptos”](#aptos)

**Aptos** is a Layer 1 blockchain for everyone. It uses the Move programming language and launched its mainnet on 2022-10-17 to redefine the web3 user experience. The Aptos blockchain is dedicated to creating better user experiences through increased speed, security, scalability, reliability and usability with low transaction costs. The word “Aptos” means “The People” in the Ohlone language. Learn more about the Aptos blockchain on the [official Aptos website](https://aptosfoundation.org).

### AptosBFT

[Section titled “AptosBFT”](#aptosbft)

* **AptosBFT** is the Aptos protocol’s BFT consensus algorithm.
* AptosBFT is based on Jolteon.

### Aptos Blockchain

[Section titled “Aptos Blockchain”](#aptos-blockchain)

* The **Aptos blockchain** is a ledger of immutable transactions agreed upon by the validators on the Aptos network (the network of validators).

### Aptos Name Service (ANS)

[Section titled “Aptos Name Service (ANS)”](#aptos-name-service-ans)

* The **Aptos Name Service (ANS)** is a decentralized naming address service for the Aptos blockchain. An Aptos name is a human-readable *.apt* domain name that is used in place of a public key, for example *love.apt*.
* This service also allows users to register subdomain names in addition to the registered domain. Find out more at: [Aptosnames.com](https://www.aptosnames.com/)

### Aptos Core

[Section titled “Aptos Core”](#aptos-core)

**Aptos-core** is the [open-source repository](https://github.com/aptos-labs/aptos-core/) containing the code for Aptos Network software. Aptos-core contains software for

* the Aptos blockchain itself, which generates and stores the immutable ledger of confirmed transactions and
* the validation process, which implements the consensus algorithm to validate transactions and add them to the Aptos blockchain immutable ledger.

### Aptos Ecosystem

[Section titled “Aptos Ecosystem”](#aptos-ecosystem)

* **Aptos ecosystem** refers to various components of the Aptos blockchain network and their interactions. The Aptos ecosystem includes the community, [community-driven projects](https://aptosfoundation.org/ecosystem/projects/all), and [events](https://aptosfoundation.org/events).

### Aptos Explorer

[Section titled “Aptos Explorer”](#aptos-explorer)

* The **[Aptos Explorer](https://explorer.aptoslabs.com/)** is an interface that helps users examine details of the Aptos blockchain, including account information, validators, and transactions.
* The Aptos Explorer help users validate their work in Aptos wallets and other tools in the blockchain.

### Aptos Framework

[Section titled “Aptos Framework”](#aptos-framework)

The **Aptos Framework** defines the public API for blockchain updates and the structure of on-chain data. It defines the business logic and access control for the three key pillars of Aptos functionality: payments, treasury, and on-chain governance. It is implemented as a set of modules written in the Move programming language and stored on-chain as Move bytecode.

### Aptos Node

[Section titled “Aptos Node”](#aptos-node)

An **Aptos node** is a peer entity of the Aptos network that tracks the state of the Aptos blockchain. There are two types of Aptos nodes, [validators](#validator) and [fullnodes](#fullnodes).

### Aptos Protocol

[Section titled “Aptos Protocol”](#aptos-protocol)

* **Aptos protocol** is the specification of how transactions are submitted, ordered, executed, and recorded within the Aptos network.

### AptosAccount

[Section titled “AptosAccount”](#aptosaccount)

* A **`AptosAccount`** is a Move resource that holds all the administrative data associated with an account, such as sequence number, balance, and authentication key.
* A **`AptosAccount`** is the only resource that every account is guaranteed to contain.

### AptosAccount module

[Section titled “AptosAccount module”](#aptosaccount-module)

* **The AptosAccount module** is a Move module that contains the code for manipulating the administrative data held in a particular `AptosAccount.T` resource.
* Code for checking or incrementing sequence numbers, withdrawing or depositing currency, and extracting gas deposits is included in the AptosAccount module.

### Aptos Devnet

[Section titled “Aptos Devnet”](#aptos-devnet)

* See [devnet](#devnet).

## B

[Section titled “B”](#b)

### Blocks

[Section titled “Blocks”](#blocks)

* On Aptos, blocks are a batch of [transactions](#transaction) committed at the same time.
* Block number is analogous to “block height” in blockchain literature.
* Transactions are referenced by ledger version rather than by block.

### BlockSTM

[Section titled “BlockSTM”](#blockstm)

* **BlockSTM** is the state-of-the-art dynamic parallelism execution engine developed by the Aptos Labs team.
* Dynamic parallelism allows developers to flexibly write applications without facing design constraints of statically declaring write sets of transactions.
* It has been adopted across the industry by multiple blockchains.
* More details can be found in [the blog post](https://medium.com/aptoslabs/block-stm-how-we-execute-over-160k-transactions-per-second-on-the-aptos-blockchain-3b003657e4ba) and [presentation at a16z crypto](https://www.youtube.com/watch?v=2SE5tqPzhyw)

### Byzantine (Validator)

[Section titled “Byzantine (Validator)”](#byzantine-validator)

* A **validator** that does not follow the specification of the consensus protocol, and wishes to compromise the correct execution of the protocol.
* BFT algorithms traditionally support up to one-third of the algorithm’s voting power being held by Byzantine validators.

### Byzantine Fault Tolerance (BFT)

[Section titled “Byzantine Fault Tolerance (BFT)”](#byzantine-fault-tolerance-bft)

* **Byzantine Fault Tolerance** (BFT) is the ability of a distributed system to provide safety and liveness guarantees in the presence of faulty, or “[Byzantine](https://en.wikipedia.org/wiki/Byzantine_fault),” validators below a certain threshold.
* The Aptos blockchain uses AptosBFT, a consensus protocol based on [Jolteon](#jolteon).
* BFT algorithms typically operate with a number of entities, collectively holding N votes (which are called “validators” in the Aptos network’s application of the system).
* N is chosen to withstand some number of validators holding f votes, which might be malicious.
* In this configuration, N is typically set to 3f+1. Validators holding up to f votes will be allowed to be faulty — offline, malicious, slow, etc. As long as 2f+1 votes are held by [honest](#honest-validator) validators, they will be able to reach consensus on consistent decisions.
* This implies that BFT consensus protocols can function correctly, even if up to one-third of the voting power is held by validators that are compromised or fail.

## C

[Section titled “C”](#c)

### CLI

[Section titled “CLI”](#cli)

* **Command line interface** refers to the Aptos CLI used for developing on the Aptos blockchain, operating nodes, and debugging issues. Find out more at [the Aptos CLI page](/build/cli).

### Client

[Section titled “Client”](#client)

* **Client** is software that receives information from the blockchain and manages transactions. Clients interact with the blockchain through the Aptos nodes.

### Code Labs

[Section titled “Code Labs”](#code-labs)

* **Code labs and tutorials** depict various workflows - such as the use of the Aptos CLI in minting non-fungible tokens (NFTs) - in order for users to understand how the process works and employ related functions in their code. If users have the necessary funds in their accounts, they can follow the same code lab and tutorial steps used in devnet, testnet and mainnet networks.

### Consensus

[Section titled “Consensus”](#consensus)

* **Consensus** is a component of a validator.
* The consensus component is responsible for coordination and agreement amongst all validators on the block of transactions to be executed, their order, and the execution results.
* The Aptos blockchain is formed with these agreed-upon transactions and their corresponding execution results.
* The consensus component is accountable for achieving security, trust, and agreement among all validators on the Aptos blockchain.

### Consensus Protocol

[Section titled “Consensus Protocol”](#consensus-protocol)

* A **consensus protocol** is collectively executed by n validators to accept or reject a transaction and to agree on the ordering of transactions and execution results.
* See [BFT](#byzantine-fault-tolerance-bft).

## D

[Section titled “D”](#d)

### Dapps

[Section titled “Dapps”](#dapps)

* **Decentralized applications (dapps)** are programs or digital applications that run on the Aptos blockchain autonomously. Smart contracts are commonly used to achieve this function.

### Devnet

[Section titled “Devnet”](#devnet)

* The **Aptos devnet** is a publicly deployed instance of the Aptos network that runs using a set of validator test nodes.
* The devnet is a demonstration of the Aptos network that is built for experimenting with new ideas
* The devnet simulates a digital payment system and the coins on the devnet have *no real world value*.
* The devnet is the network by which developers are given the opportunity to test given protocols. It is similar to testnet as it operates independently of the mainnet yet is reset weekly.

## E

[Section titled “E”](#e)

### Ed25519

[Section titled “Ed25519”](#ed25519)

* **Ed25519** is our supported digital signature scheme.
* More specifically, the Aptos network uses the PureEdDSA scheme over the Ed25519 curve, as defined in RFC 8032.

### Epoch

[Section titled “Epoch”](#epoch)

* An **epoch** is the period of time between reconfigurations of the validator set and other administrative actions by the blockchain. On Aptos mainnet currently, it is every 2 hours.

### Event

[Section titled “Event”](#event)

* An **event** is the user-facing representation of the effects of executing a transaction.
* A transaction may be designed to emit any number of events as a list. For example, a `Coin<AptosCoin>` transfer emits a `WithdrawEvent` for the sender account and a `DepositEvent` for the recipient account.
* In the Aptos protocol, events provide evidence that the successful execution of a transaction resulted in a specific effect. The `DepositEvent` (in the above example) allows the recipient to confirm that a payment was received into their account.
* Events are persisted on the blockchain and are used to answer queries by [clients](#client).

### Execution

[Section titled “Execution”](#execution)

* **Execution** in the Aptos blockchain is an Aptos node component that manages the block of transactions. The execution component stores successful transactions.

### Expiration Time

[Section titled “Expiration Time”](#expiration-time)

A transaction ceases to be valid after its **expiration time**. If it is assumed that:

* Time\_C is the current time that is agreed upon between validators (Time\_C is not the local time of the client);
* Time\_E is the expiration time of a transaction T\_N; and
* Time\_C>Time\_E and transaction T\_N has not been included in the blockchain, then there is a guarantee that T\_N will never be included in the blockchain.

## F

[Section titled “F”](#f)

### Faucet

[Section titled “Faucet”](#faucet)

* The **faucet** is a service that mints APT on devnet. For testnet see the [mint page](/network/faucet).
* APT on devnet and testnet has no real world value, it is only for development purposes.
* To use a faucet, see [Faucet API](/build/apis/faucet-api).

### Fullnodes

[Section titled “Fullnodes”](#fullnodes)

* **Fullnodes** are clients that ensure data are stored up-to-date on the network. They replicate blockchain state and transactions from other fullnodes and validator nodes.

### Fungible Asset

[Section titled “Fungible Asset”](#fungible-asset)

* A **fungible asset** is an asset, such as a currency, share, in-game resource, etc., that is interchangeable with another identical asset without any loss in its value. For example, APT is a fungible asset because you can exchange one APT for another.
* Follow the [Asset Standards](/build/smart-contracts/aptos-standards#asset-standards) to create fungible assets on the Aptos blockchain.
* Next generation of the Coin standard that addresses shortcomings of `aptos_framework::coin` such as lack of guaranteed enforcement of freeze and burn and advanced functionalities such as programmable transfers, e.g., approve in ERC-20.

### Fungible Token

[Section titled “Fungible Token”](#fungible-token)

* For the legacy Aptos Token Standard (aptos\_token::token), a **fungible token** is a token that is interchangeable with other identical tokens (i.e., tokens that share the same `TokenId`). This means the tokens have the same `creator address`, `collection name`, `token name`, and `property version`.
* For the Aptos Digital Asset Standard (aptos\_token\_objects::token), a \* *fungible token*\* is a fungible asset with metadata object that includes a Digital Asset resource.

### Fungible Unit

[Section titled “Fungible Unit”](#fungible-unit)

* A **fungible unit** is an individual unit of a fungible asset. These units are identical and interchangeable without any loss in value. For example, each [Octa](#octa) (the smallest unit of APT) is a fungible unit.

## G

[Section titled “G”](#g)

### Gas

[Section titled “Gas”](#gas)

* **Gas** is a way to pay for computation and storage on a blockchain network. All transactions on the Aptos network cost a certain amount of gas.
* The gas required for a transaction depends on the size of the transaction, the computational cost of executing the transaction, and the amount of additional global state created by the transaction (e.g., if new accounts are created).
* The purpose of gas is regulating demand for the limited computational and storage resources of the validators, including preventing denial of service ( DoS) attacks.

See [Gas and Storage Fees](/network/blockchain/gas-txn-fee) for more information.

### Gas Unit Price

[Section titled “Gas Unit Price”](#gas-unit-price)

* Each transaction specifies the **gas unit price** the sender is willing to pay per unit of gas.
* The price of gas required for a transaction depends on the current demand for usage of the network.
* Gas price is expressed in [Octas](#octa).

See [Gas and Storage Fees](/network/blockchain/gas-txn-fee) for more information.

## H

[Section titled “H”](#h)

### Honest (Validator)

[Section titled “Honest (Validator)”](#honest-validator)

* **Honesty** means a validator that faithfully executes the consensus protocol and is not Byzantine.

## I

[Section titled “I”](#i)

### Indexer

[Section titled “Indexer”](#indexer)

* **[Indexer](/build/indexer)** is the component of Aptos that retrieves, processes, and efficiently stores raw data in the database to provide speedy access to the Aptos blockchain state.
* At a high level, indexer gets data from a gRPC stream and runs processors to transform raw blockchain data and serve transformed data via GraphQL endpoint.

## J

[Section titled “J”](#j)

### Jolteon

[Section titled “Jolteon”](#jolteon)

* **Jolteon** is a recent proposal for a [BFT](#byzantine-fault-tolerance-bft) consensus protocol.
* AptosBFT, the Aptos network’s consensus algorithm, is based on Jolteon.
* It simplifies the reasoning about safety, and it addresses some performance limitations of previous consensus protocols. In particular, it reduces latency by 33% compared to HotStuff.

## L

[Section titled “L”](#l)

### Leader

[Section titled “Leader”](#leader)

* A **leader** is a validator that proposes a block of transactions for the consensus protocol.
* In leader-based protocols, nodes must agree on a leader to make progress.
* Leaders are selected by a function that takes the current [round number](#round-number) as input.

## M

[Section titled “M”](#m)

### Mainnet

[Section titled “Mainnet”](#mainnet)

* **Mainnet** refers to a working, fully-operational blockchain. A mainnet network has been fully deployed and performs the functionality of transferring digital currency from a sender to a recipient.

### Maximum Gas Amount

[Section titled “Maximum Gas Amount”](#maximum-gas-amount)

* The **Maximum Gas Amount** of a transaction is the maximum gas amount in gas units that the sender is ready to pay for the transaction.
* The transaction can be successfully executed only if the gas used does not exceed the maximum gas amount.
* The gas charged is equal to the gas price multiplied by units of gas required to process this transaction.
* If the transaction runs out of gas while it is being executed or the account runs out of balance during execution, then the sender will be charged for gas used and the transaction will fail.

See [Gas and Storage Fees](/network/blockchain/gas-txn-fee) for more information.

### Mempool

[Section titled “Mempool”](#mempool)

* **Mempool** is one of the components of the validator. It holds an in-memory buffer of transactions that have been submitted but not yet agreed upon and executed. Mempool receives transactions from other [full nodes](#fullnodes).
* Transactions in the mempool of a validator are added from the JSON-RPC Service of the current node and from the mempool of other Aptos nodes.
* When the current validator is the leader, its consensus component pulls the transactions from its mempool and proposes the order of the transactions that form a block. The validator quorum then votes on the proposal.

### Merkle Trees

[Section titled “Merkle Trees”](#merkle-trees)

* **Merkle tree** is a type of authenticated data structure that allows for efficient verification of data integrity and updates.

* The Aptos network treats the entire blockchain as a single data structure that records the history of transactions and states over time.

* The [Merkle tree](https://en.wikipedia.org/wiki/Merkle_tree) implementation simplifies the work of apps accessing the blockchain. It allows apps to:

* Read any data from any point in time.
  * Verify the integrity of the data using a unified framework.

### Merkle Accumulator

[Section titled “Merkle Accumulator”](#merkle-accumulator)

* The **[Merkle Accumulator](https://www.usenix.org/legacy/event/sec09/tech/full_papers/crosby.pdf)** is an *append-only* Merkle tree that the Aptos blockchain uses to store the ledger.
* A Merkle accumulator can provide proofs that a transaction was included in the chain (“proof of inclusion”).
* They are also called “history trees” in literature.

### Module

[Section titled “Module”](#module)

* A **module** in the Move programming language may either be a program or library that can create, transfer, or store assets.

### Move

[Section titled “Move”](#move)

* **Move** is a new programming language that implements all the transactions on the Aptos blockchain.
* It has two different kinds of code — [Move scripts](#move-script) and [Move modules](#move-module).
* Move is a safe and secure programming language for web3 that emphasizes access control and scarcity. It is the programming language used to build the Aptos blockchain. You can read more about it in [Move on Aptos](/network/blockchain/move).

### Move Bytecode

[Section titled “Move Bytecode”](#move-bytecode)

* Move programs are compiled into **Move bytecode**.
* Move bytecode is used to express Move scripts and Move modules.

### Move Module

[Section titled “Move Module”](#move-module)

* A **Move module** defines the rules for updating the global state of the Aptos blockchain.
* In the Aptos protocol, a Move module is a **smart contract**.
* Each user-submitted transaction includes a Move script. The Move script invokes procedures of one or more Move modules to update the global state of the blockchain according to the rules.

### Move Resources

[Section titled “Move Resources”](#move-resources)

* **Move resources** contain data that can be accessed according to the \* *procedures*\* declared in a Move **module.**
* Move resources can never be copied, reused, or lost. This protects Move programmers from accidentally or intentionally losing track of a resource.

### Move Script

[Section titled “Move Script”](#move-script)

* Each transaction submitted by a user includes a **Move script**.
* These transactions, also known as Move scripts, represent the operations a client submits to a validator.
* The operation could be a request to move coins from user A to user B, or it could involve interactions with published [Move modules](#move-module) (smart contracts).
* The Move script is an arbitrary program that interacts with resources published in the global storage of the Aptos blockchain by calling the procedures of a module. It encodes the logic for a transaction.
* A single Move script can send funds to multiple recipients and invoke procedures from several different modules.
* A Move script **is not** stored in the global state and cannot be invoked by other Move scripts. It is a single-use program.

To see example uses of Move scripts, follow [Move scripts](/build/smart-contracts/scripts/script-tutorial).

### Move Virtual Machine (MVM)

[Section titled “Move Virtual Machine (MVM)”](#move-virtual-machine-mvm)

* The **Move virtual machine** executes Move scripts written in [Move bytecode](#move-bytecode) to produce an execution result. This result is used to update the blockchain **state**.
* The virtual machine is part of a [validator](#validator).
* The Move virtual machine (MoveVM) processes each validator node that translates transactions along with the current blockchain ledger state to produce a changeset as input or storage delta as output.

## N

[Section titled “N”](#n)

### Node

[Section titled “Node”](#node)

* A **node** is a peer entity of the Aptos network that tracks the state of the Aptos blockchain.
* An Aptos node consists of logical components. [Mempool](#mempool), [consensus](#consensus), and the [Move virtual machine](#move-virtual-machine-mvm) are examples of node components.

### Nonce

[Section titled “Nonce”](#nonce)

* **Nonce** is a number only used once, a random or semi-random number that is generated for a specific use for authentication protocols and cryptographic hash functions.

## O

[Section titled “O”](#o)

### Octa

[Section titled “Octa”](#octa)

* An **Octa** is the smallest unit of [APT](#apt). 1 APT = 108 Octas.

### Open-Source Community

[Section titled “Open-Source Community”](#open-source-community)

* **Open-source community** is a term used for a group of developers who work on open-source software. If you’re reading this glossary, then you are part of the Aptos project’s developer community.

## P

[Section titled “P”](#p)

### Proof

[Section titled “Proof”](#proof)

* A **proof** is a way to verify the accuracy of data in the blockchain.
* Every operation in the Aptos blockchain can be verified cryptographically that it is indeed correct and that data has not been omitted.
* For example, if a user queries the information within a particular executed transaction, they will be provided with a cryptographic proof that the data returned to them is correct.

### Proof-of-Stake (PoS)

[Section titled “Proof-of-Stake (PoS)”](#proof-of-stake-pos)

**Proof-of-Stake (PoS)** is a security mechanism that serves in confirming the uniqueness and legitimacy of blockchain transactions. The PoS consensus mechanism is leveraged by the Aptos blockchain powered by a network of validators, which in turn update the system and process transactions.

## Q

[Section titled “Q”](#q)

### Quorum Store

[Section titled “Quorum Store”](#quorum-store)

* **Quorum Store** is the component that disseminates transactions (in batches) within the validator set.
* It significantly improves consensus throughput by removing the leader bottleneck.
* It decouples data dissemination from metadata ordering, allowing validators to disseminate data asynchronously in parallel.
* More details can be found in the [blog post](https://medium.com/aptoslabs/quorum-store-how-consensus-horizontally-scales-on-the-aptos-blockchain-988866f6d5b0)

## R

[Section titled “R”](#r)

### Randapp

[Section titled “Randapp”](#randapp)

* A [dapp](#dapps) that uses randomness for its functionality.

### Resource Account

[Section titled “Resource Account”](#resource-account)

* A **resource account** is used to manage resources independent of an account managed by a user. For example, a developer may use a resource account to manage an account for module publishing, say managing a contract.

* The contract itself does not require a signer post initialization. A resource account gives you the means for the module to provide a signer to other modules and sign transactions on behalf of the module.

See [Resource accounts](/build/smart-contracts/resource-accounts) for instructions on use.

### REST API Service

[Section titled “REST API Service”](#rest-api-service)

* The **REST API Service** component is the external interface of an Aptos node. Any incoming client request, such as submitted transactions or queries, must first go through the REST Service. A client needs to go through the REST Service component to access storage or any other component in the system. This filters requests and protects the system.
* Whenever a client submits a new transaction, the REST Service passes it to [mempool](#mempool).

### Round

[Section titled “Round”](#round)

* A **round** consists of achieving consensus on a block of transactions and their execution results.

### Round Number

[Section titled “Round Number”](#round-number)

* A **round number** is a shared counter used to select leaders during an [epoch](#epoch) of the consensus protocol.

## S

[Section titled “S”](#s)

### SDKs

[Section titled “SDKs”](#sdks)

* Aptos **software development kits (SDKs)** are sets of tools that enable a developer to quickly create a custom app on the Aptos platform. Find out more at [Use the Aptos SDKs](/build/sdks).

### Sequence Number

[Section titled “Sequence Number”](#sequence-number)

* The **sequence number** for an account indicates the number of transactions that have been submitted and committed on chain from that account. It is incremented every time a transaction sent from that account is executed or aborted and stored in the blockchain.
* A transaction is executed only if it matches the current sequence number for the sender account. This helps sequence multiple transactions from the same sender and prevents replay attacks.
* If the current sequence number of an account A is X, then a transaction T on account A will only be executed if T’s sequence number is X.
* These transactions will be held in mempool until they are the next sequence number for that account (or until they expire).
* When the transaction is applied, the sequence number of the account will become X+1. The account has a strictly increasing sequence number.

### Sender

[Section titled “Sender”](#sender)

* *Alternate name*: Sender address.
* **Sender** is the address that originates the transaction. A transaction must be signed by the sender but can have more than one signer.

### Shoal

[Section titled “Shoal”](#shoal)

* Method for decreasing latency for BFT protocols. See the [Shoal paper](https://arxiv.org/pdf/2306.03058.pdf)

### Smart Contract

[Section titled “Smart Contract”](#smart-contract)

* **Smart contract** refers to a computer program that automatically and directly carries out the contract’s terms.
* See [Move Module](#move-module) for related details.

### State

[Section titled “State”](#state)

* A **state** in the Aptos protocol is a snapshot of the distributed database.
* A transaction modifies the database and produces a new and updated state.

### State Root Hash

[Section titled “State Root Hash”](#state-root-hash)

* **State root hash** is a [Merkle hash](https://en.wikipedia.org/wiki/Merkle_tree) over all keys and values the state of the Aptos blockchain at a given version.

## T

[Section titled “T”](#t)

### Table

[Section titled “Table”](#table)

* A [**table**](https://github.com/aptos-labs/aptos-core/blob/main/aptos-move/framework/aptos-stdlib/doc/table.md) implements the Table type and in Aptos is used to store information as key-value data within an account at large scale.

See [`table.move`](https://github.com/aptos-labs/aptos-core/blob/main/aptos-move/framework/aptos-stdlib/sources/table.move) for the associated Aptos source file.

### Testnet

[Section titled “Testnet”](#testnet)

* **Testnet** describes the Aptos network that is not fully functional yet more stable than devnet; it is an alternative network to mainnet to be used for testing.

### Tokens

[Section titled “Tokens”](#tokens)

* **Tokens** are digital units of value issued on a blockchain. They can be redeemed for assets or value held. Tokens can be of the types: Fungible Token (FT), Non-Fungible Token (NFT), and Semi-Fungible Token (SFT).

### Transaction

[Section titled “Transaction”](#transaction)

* A raw **transaction** contains the following fields:

* [Sender (account address)](#account-address)
  * [Move script](#move-script)
  * [Gas price](#gas-unit-price)
  * [Maximum gas amount](#maximum-gas-amount)
  * [Sequence number](#sequence-number)
  * [Expiration time](#expiration-time)

* A signed transaction is a raw transaction with the digital signature.

* An executed transaction changes the state of the Aptos blockchain.

### Transaction Script

[Section titled “Transaction Script”](#transaction-script)

* See [Move script](#move-script)

## V

[Section titled “V”](#v)

### Validator

[Section titled “Validator”](#validator)

* *Alternate name*: Validators.
* A **validator** is an entity of the Aptos ecosystem that validates on the Aptos blockchain. It receives requests from clients and runs consensus, execution, and storage.
* A validator maintains the history of all the transactions on the blockchain.
* Internally, a validator needs to keep the current state, to execute transactions, and to calculate the next state.
* Aptos validators are in charge of verifying transactions.

### Validator Nodes

[Section titled “Validator Nodes”](#validator-nodes)

* **Validator nodes** are a unique class of fullnodes that take part in consensus, specifically a Byzantine Fault Tolerance (BFT) consensus protocol in Aptos. Validators agree upon transactions to be added to the Aptos blockchain as well as the order in which they are added.

### Version

[Section titled “Version”](#version)

* A **version** is a sequentially increasing number that increments for every [transaction](#transaction).
* On aptos, transactions are globally ordered and every transaction has a version (often called “height” in blockchain literature.)
* Transaction version 0 is the first transaction (genesis transaction), and a transaction version 100 is the 101st transaction in the blockchain.

## W

[Section titled “W”](#w)

### Well-Formed Transaction

[Section titled “Well-Formed Transaction”](#well-formed-transaction)

An Aptos transaction is **well-formed** if each of the following conditions are true for the transaction:

* The transaction has a valid signature.
* An account exists at the sender address.
* It includes a public key, and the hash of the public key matches the sender account’s authentication key.
* The sequence number of the transaction matches the sender account’s sequence number.
* The sender account’s balance is greater than the [maximum gas amount](#maximum-gas-amount).
* The expiration time of the transaction has not passed.

# Learn about Nodes

The Aptos network consists of three node types: validator nodes, validator fullnodes (VFNs), and public fullnodes (PFNs). To participate in consensus, you are required to run a validator node and stake the minimum amount of utility coins. VFNs and PFNs are not required to participate in consensus, but they are necessary to distribute blockchain data and enable ecosystem services, e.g., indexing, querying, and RESTful API services (see [Aptos APIs](/build/apis)). VFNs can only be run by validator operators, while PFNs can be run by anyone. You can learn more about the different types of nodes in the [Blockchain Deep Dive](/network/blockchain) section.

This section provides detailed, step-by-step instructions on how to deploy and operate Aptos nodes in different environments. It also describes everything you need to stake and participate in consensus and governance.

## Quick Links

[Section titled “Quick Links”](#quick-links)

### Validation on Aptos

[Section titled “Validation on Aptos”](#validation-on-aptos)

Everything you need to know about how validation, staking and governance works on Aptos.

[How validation works ](/network/blockchain/staking#validation-on-the-aptos-blockchain)Validator-leader proposes and earns rewards on success.

[Validator states ](/network/blockchain/staking#validator-state-and-stake-state)Learn how a validator gets into a validator set.

### Staking

[Section titled “Staking”](#staking)

[Staking on Aptos ](/network/blockchain/staking)A comprehensive guide to how staking works on Aptos.

[Governance ](/network/blockchain/governance)Who can propose, who can vote, and how an AIP is resolved.

[Owner ](/network/nodes/validator-node/connect-nodes/staking-pool-operations)Describes the owner operations performed for staking.

[Voter ](/network/nodes/validator-node/connect-nodes/staking-pool-voter)Describes the voter operations performed for staking.

### Validators and VFNs

[Section titled “Validators and VFNs”](#validators-and-vfns)

A comprehensive guide to deploying nodes, staking operations and participate in consensus.

[Node requirements ](/network/nodes/validator-node/node-requirements)Details the compute and storage resources you need. Read this first before anything.

[Running validator node ](/network/nodes/validator-node/deploy-nodes)In the cloud or on-premises, Docker or source, you will read step-by-step instructions here.

[Node health ](/network/nodes/validator-node/verify-nodes/node-liveness-criteria)You can verify your node health using several options.

[Connecting to Aptos network ](/network/nodes/validator-node/connect-nodes/connect-to-aptos-network)Steps to connect your nodes to an Aptos network.

[Staking pool operations ](/network/nodes/validator-node/connect-nodes/staking-pool-operations)Step-by-step guide for how to perform staking pool operations.

[Shutting down nodes ](/network/nodes/validator-node/modify-nodes/shutting-down-nodes)Leave the validator set first, and then shut down your node.

### Public Fullnodes (PFNs)

[Section titled “Public Fullnodes (PFNs)”](#public-fullnodes-pfns)

A section with detailed, step-by-step instructions on everything related to Aptos PFNs.

[Deploy a PFN ](/network/nodes/full-node/deployments)Follow this section to deploy a PFN.

[Indexer PFN ](/build/indexer/legacy/indexer-fullnode)Describes how to run an indexer PFN on the Aptos network.

### Common Operations

[Section titled “Common Operations”](#common-operations)

[Develop with localnet ](/network/nodes/localnet/local-development-network)Run a localnet for development (including validator nodes).

[Upgrade your PFN ](/network/nodes/full-node/modify/update-fullnode-with-new-releases)Upgrade your node with new releases.

[Bootstrap from a snapshot ](/network/nodes/bootstrap-fullnode/bootstrap-fullnode)Use a snapshot to bootstrap a new node.

[Bootstrap from a backup ](/network/nodes/bootstrap-fullnode/aptos-db-restore)Use data restore to bootstrap a new node.

# Bootstrap a Node

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)
  [Section titled “Bootstrap from a Snapshot”](#bootstrap-from-a-snapshot)
* ### [Bootstrap from a Backup](/network/nodes/bootstrap-fullnode/aptos-db-restore)
  [Section titled “Bootstrap from a Backup”](#bootstrap-from-a-backup)

# Bootstrap from a Backup

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

[Section titled “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> |
| 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/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)

## Restore an Aptos DB

[Section titled “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

[Section titled “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:

```shellscript
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

[Section titled “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:

```shellscript
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

[Section titled “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:

```shellscript
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

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

[Section titled “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

[Section titled “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

[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

[Section titled “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

[Section titled “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.

```shellscript
   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:

```shellscript
   cd aptos-core
   ```

### (Optional) Check out release branch

[Section titled “(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

```shellscript
  git checkout --track origin/devnet
  ```

* Testnet

```shellscript
  git checkout --track origin/testnet
  ```

* Mainnet

```shellscript
  git checkout --track origin/mainnet
  ```

## Set up build dependencies

[Section titled “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/>
2. Run the dev setup script to prepare your environment:

```shellscript
./scripts/dev_setup.sh
```

3. Update your current shell environment:

```shellscript
source ~/.cargo/env
```

Note

You can see the available options for the script by running

```shellscript
./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:

```shellscript
./scripts/dev_setup.sh
```

2. Update your current shell environment:

```shellscript
source ~/.cargo/env
```

Note

You can see the available options for the script by running

```shellscript
./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
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

[Section titled “Additional Tools”](#additional-tools)

If you used `scripts/dev_setup.sh` for macOS or Linux setup, additional tools are optionally available.

## Building Aptos

[Section titled “Building Aptos”](#building-aptos)

The simplest check that you have a working environment is to build everything and run the tests.

```shellscript
cargo build
cargo 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

[Section titled “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

This section contains tutorials for understanding and configuring Aptos node internals. These include:

* ### [Consensus Observer](/network/nodes/configure/consensus-observer)
  [Section titled “Consensus Observer”](#consensus-observer)
* ### [State Synchronization](/network/nodes/configure/state-sync)
  [Section titled “State Synchronization”](#state-synchronization)
* ### [Data Pruning](/network/nodes/configure/data-pruning)
  [Section titled “Data Pruning”](#data-pruning)
* ### [Telemetry](/network/nodes/configure/telemetry)
  [Section titled “Telemetry”](#telemetry)
* ### [Locating Node Files](/network/nodes/configure/node-files-all-networks)
  [Section titled “Locating Node Files”](#locating-node-files)

# Consensus Observer

Caution

**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.

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).

## Configure consensus observer

[Section titled “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

[Section titled “Enable consensus observer”](#enable-consensus-observer)

To enable consensus observer on your PFN, add the following to your node configuration file (e.g., `fullnode.yaml`):

```yaml
consensus:
  enable_pre_commit: false

consensus_observer:
  observer_enabled: true
  publisher_enabled: true
```

### Disable consensus observer

[Section titled “Disable consensus observer”](#disable-consensus-observer)

To disable consensus observer on your PFN, add the following to your node configuration file (e.g., `fullnode.yaml`):

```yaml
consensus:
  enable_pre_commit: true

consensus_observer:
  observer_enabled: false
  publisher_enabled: false
```

# Data Pruning

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.

Caution

**Default pruning window**\
The default configuration of the ledger pruner is to keep only the most recent 150 million transactions. This roughly corresponds to around \~200G of disk space, depending on transaction types and outputs. Almost all Aptos nodes in testnet and mainnet use the default configuration. If you instead wish to run an archival node, follow the instructions, [here](/network/nodes/configure/state-sync#archival-pfns).

## Disable the ledger pruner

[Section titled “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 the node configuration file, e.g., `fullnode.yaml` or `validator.yaml`.

```yaml
storage:
  storage_pruner_config:
    ledger_pruner_config:
      enable: false
```

Caution

**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.

## Configure the ledger pruner

[Section titled “Configure the ledger pruner”](#configure-the-ledger-pruner)

If you wish, you can configure the size of the ledger pruning window (i.e., the number of the most recent transactions to retain in storage). To do this, add the following to the node configuration file, e.g., `fullnode.yaml` or `validator.yaml`.

```yaml
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

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)
  [Section titled “Files For Mainnet”](#files-for-mainnet)
* ### [Files For Testnet](/network/nodes/configure/node-files-all-networks/node-files-testnet)
  [Section titled “Files For Testnet”](#files-for-testnet)
* ### [Files For Devnet](/network/nodes/configure/node-files-all-networks/node-files-devnet)
  [Section titled “Files For Devnet”](#files-for-devnet)

# Files For 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

[Section titled “Validator Files”](#validator-files)

All the files listed below are for validator nodes.

### docker-compose.yaml

[Section titled “docker-compose.yaml”](#docker-composeyaml)

* **Git repo:** `aptos-core`

* **Git branch:** `devnet` on <https://github.com/aptos-labs/aptos-core>

* **Command to download:**

```shellscript
  wget -O docker-compose.yaml https://raw.githubusercontent.com/aptos-labs/aptos-core/devnet/docker/compose/aptos-node/docker-compose.yaml
  ```

### validator.yaml

[Section titled “validator.yaml”](#validatoryaml)

* **Git repo:** `aptos-core`

* **Git branch:** `devnet` on <https://github.com/aptos-labs/aptos-core>

* **Command to download:**

```shellscript
  wget -O validator.yaml https://raw.githubusercontent.com/aptos-labs/aptos-core/devnet/docker/compose/aptos-node/validator.yaml
  ```

### genesis.blob

[Section titled “genesis.blob”](#genesisblob)

* **Git repo:** `aptos-networks`

* **Git branch:** `main` on <https://github.com/aptos-labs/aptos-networks>

* **Command to download:**

```shellscript
  wget -O genesis.blob https://raw.githubusercontent.com/aptos-labs/aptos-networks/main/devnet/genesis.blob
  ```

### waypoint.txt

[Section titled “waypoint.txt”](#waypointtxt)

* **Git repo:** `aptos-networks`

* **Git branch:** `main` on <https://github.com/aptos-labs/aptos-networks>

* **Command to download:**

```shellscript
  wget -O waypoint.txt https://raw.githubusercontent.com/aptos-labs/aptos-networks/main/devnet/waypoint.txt
  ```

### docker-compose-src.yaml

[Section titled “docker-compose-src.yaml”](#docker-compose-srcyaml)

* **Git repo:** `aptos-core`

* **Git branch:** `devnet` on <https://github.com/aptos-labs/aptos-core>

* **Command to download:**

```shellscript
  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

[Section titled “haproxy.cfg”](#haproxycfg)

* **Git repo:** `aptos-core`

* **Git branch:** `devnet` on <https://github.com/aptos-labs/aptos-core>

* **Command to download:**

```shellscript
  wget -O haproxy.cfg https://raw.githubusercontent.com/aptos-labs/aptos-core/devnet/docker/compose/aptos-node/haproxy.cfg
  ```

### blocked.ips

[Section titled “blocked.ips”](#blockedips)

* **Git repo:** `aptos-core`

* **Git branch:** `devnet` on <https://github.com/aptos-labs/aptos-core>

* **Command to download:**

```shellscript
  wget -O blocked.ips https://raw.githubusercontent.com/aptos-labs/aptos-core/devnet/docker/compose/aptos-node/blocked.ips
  ```

## VFN or PFN files

[Section titled “VFN or PFN files”](#vfn-or-pfn-files)

The files listed below are for VFNs or PFNs.

### docker-compose-fullnode.yaml

[Section titled “docker-compose-fullnode.yaml”](#docker-compose-fullnodeyaml)

* **Git repo:** `aptos-core`

* **Git branch:** `devnet` on <https://github.com/aptos-labs/aptos-core>

* **Command to download:**

```shellscript
  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

[Section titled “fullnode.yaml”](#fullnodeyaml)

* **Git repo:** `aptos-core`

* **Git branch:** `devnet` on <https://github.com/aptos-labs/aptos-core>

* **Command to download:**

```shellscript
  wget -O fullnode.yaml https://raw.githubusercontent.com/aptos-labs/aptos-core/devnet/docker/compose/aptos-node/fullnode.yaml
  ```

### haproxy-fullnode.cfg

[Section titled “haproxy-fullnode.cfg”](#haproxy-fullnodecfg)

* **Git repo:** `aptos-core`

* **Git branch:** `devnet` on <https://github.com/aptos-labs/aptos-core>

* **Command to download:**

```shellscript
  wget -O haproxy-fullnode.cfg https://raw.githubusercontent.com/aptos-labs/aptos-core/devnet/docker/compose/aptos-node/haproxy-fullnode.cfg
  ```

# Files For 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

[Section titled “Validator Files”](#validator-files)

All the files listed below are for validator nodes.

### docker-compose.yaml

[Section titled “docker-compose.yaml”](#docker-composeyaml)

* **Git repo:** `aptos-core`

* **Git branch:** `mainnet` on <https://github.com/aptos-labs/aptos-core>

* **Command to download:**

```shellscript
  wget -O docker-compose.yaml https://raw.githubusercontent.com/aptos-labs/aptos-core/mainnet/docker/compose/aptos-node/docker-compose.yaml
  ```

### validator.yaml

[Section titled “validator.yaml”](#validatoryaml)

* **Git repo:** `aptos-core`

* **Git branch:** `mainnet` on <https://github.com/aptos-labs/aptos-core>

* **Command to download:**

```shellscript
  wget -O validator.yaml https://raw.githubusercontent.com/aptos-labs/aptos-core/mainnet/docker/compose/aptos-node/validator.yaml
  ```

### genesis.blob

[Section titled “genesis.blob”](#genesisblob)

* **Git repo:** `aptos-networks`

* **Git branch:** `main` on <https://github.com/aptos-labs/aptos-networks>

* **Command to download:**

```shellscript
  wget -O genesis.blob https://raw.githubusercontent.com/aptos-labs/aptos-networks/main/mainnet/genesis.blob
  ```

### waypoint.txt

[Section titled “waypoint.txt”](#waypointtxt)

* **Git repo:** `aptos-networks`

* **Git branch:** `main` on <https://github.com/aptos-labs/aptos-networks>

* **Command to download:**

```shellscript
  wget -O waypoint.txt https://raw.githubusercontent.com/aptos-labs/aptos-networks/main/mainnet/waypoint.txt
  ```

### docker-compose-src.yaml

[Section titled “docker-compose-src.yaml”](#docker-compose-srcyaml)

* **Git repo:** `aptos-core`

* **Git branch:** `mainnet` on <https://github.com/aptos-labs/aptos-core>

* **Command to download:**

```shellscript
  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

[Section titled “haproxy.cfg”](#haproxycfg)

* **Git repo:** `aptos-core`

* **Git branch:** `mainnet` on <https://github.com/aptos-labs/aptos-core>

* **Command to download:**

```shellscript
  wget -O haproxy.cfg https://raw.githubusercontent.com/aptos-labs/aptos-core/mainnet/docker/compose/aptos-node/haproxy.cfg
  ```

### blocked.ips

[Section titled “blocked.ips”](#blockedips)

* **Git repo:** `aptos-core`

* **Git branch:** `mainnet` on <https://github.com/aptos-labs/aptos-core>

* **Command to download:**

```shellscript
  wget -O blocked.ips https://raw.githubusercontent.com/aptos-labs/aptos-core/mainnet/docker/compose/aptos-node/blocked.ips
  ```

***

## VFN or PFN files

[Section titled “VFN or PFN files”](#vfn-or-pfn-files)

The files listed below are for VFNs or PFNs.

### docker-compose-fullnode.yaml

[Section titled “docker-compose-fullnode.yaml”](#docker-compose-fullnodeyaml)

* **Git repo:** `aptos-core`

* **Git branch:** `mainnet` on <https://github.com/aptos-labs/aptos-core>

* **Command to download:**

```shellscript
  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

[Section titled “fullnode.yaml”](#fullnodeyaml)

* **Git repo:** `aptos-core`

* **Git branch:** `mainnet` on <https://github.com/aptos-labs/aptos-core>

* **Command to download:**

```shellscript
  wget -O fullnode.yaml https://raw.githubusercontent.com/aptos-labs/aptos-core/mainnet/docker/compose/aptos-node/fullnode.yaml
  ```

### haproxy-fullnode.cfg

[Section titled “haproxy-fullnode.cfg”](#haproxy-fullnodecfg)

* **Git repo:** `aptos-core`

* **Git branch:** `mainnet` on <https://github.com/aptos-labs/aptos-core>

* **Command to download:**

```shellscript
  wget -O haproxy-fullnode.cfg https://raw.githubusercontent.com/aptos-labs/aptos-core/mainnet/docker/compose/aptos-node/haproxy-fullnode.cfg
  ```

# Files For 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

[Section titled “Validator Files”](#validator-files)

All the files listed below are for validator nodes.

### docker-compose.yaml

[Section titled “docker-compose.yaml”](#docker-composeyaml)

* **Git repo:** `aptos-core`

* **Git branch:** `testnet` on <https://github.com/aptos-labs/aptos-core>

* **Command to download:**

```shellscript
  wget -O docker-compose.yaml https://raw.githubusercontent.com/aptos-labs/aptos-core/testnet/docker/compose/aptos-node/docker-compose.yaml
  ```

### validator.yaml

[Section titled “validator.yaml”](#validatoryaml)

* **Git repo:** `aptos-core`

* **Git branch:** `testnet` on <https://github.com/aptos-labs/aptos-core>

* **Command to download:**

```shellscript
  wget -O validator.yaml https://raw.githubusercontent.com/aptos-labs/aptos-core/testnet/docker/compose/aptos-node/validator.yaml
  ```

### genesis.blob

[Section titled “genesis.blob”](#genesisblob)

* **Git repo:** `aptos-networks`

* **Git branch:** `main` on <https://github.com/aptos-labs/aptos-networks>

* **Command to download:**

```shellscript
  wget -O genesis.blob https://raw.githubusercontent.com/aptos-labs/aptos-networks/main/testnet/genesis.blob
  ```

### waypoint.txt

[Section titled “waypoint.txt”](#waypointtxt)

* **Git repo:** `aptos-networks`

* **Git branch:** `main` on <https://github.com/aptos-labs/aptos-networks>

* **Command to download:**

```shellscript
  wget -O waypoint.txt https://raw.githubusercontent.com/aptos-labs/aptos-networks/main/testnet/waypoint.txt
  ```

### docker-compose-src.yaml

[Section titled “docker-compose-src.yaml”](#docker-compose-srcyaml)

* **Git repo:** `aptos-core`

* **Git branch:** `testnet` on <https://github.com/aptos-labs/aptos-core>

* **Command to download:**

```shellscript
  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

[Section titled “haproxy.cfg”](#haproxycfg)

* **Git repo:** `aptos-core`

* **Git branch:** `testnet` on <https://github.com/aptos-labs/aptos-core>

* **Command to download:**

```shellscript
  wget -O haproxy.cfg https://raw.githubusercontent.com/aptos-labs/aptos-core/testnet/docker/compose/aptos-node/haproxy.cfg
  ```

### blocked.ips

[Section titled “blocked.ips”](#blockedips)

* **Git repo:** `aptos-core`

* **Git branch:** `testnet` on <https://github.com/aptos-labs/aptos-core>

* **Command to download:**

```shellscript
  wget -O blocked.ips https://raw.githubusercontent.com/aptos-labs/aptos-core/testnet/docker/compose/aptos-node/blocked.ips
  ```

## VFN or PFN files

[Section titled “VFN or PFN files”](#vfn-or-pfn-files)

The files listed below are for VFNs or PFNs.

## docker-compose-fullnode.yaml

[Section titled “docker-compose-fullnode.yaml”](#docker-compose-fullnodeyaml)

* **Git repo:** `aptos-core`

* **Git branch:** `testnet` on <https://github.com/aptos-labs/aptos-core>

* **Command to download:**

```shellscript
  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

[Section titled “fullnode.yaml”](#fullnodeyaml)

* **Git repo:** `aptos-core`

* **Git branch:** `testnet` on <https://github.com/aptos-labs/aptos-core>

* **Command to download:**

```shellscript
  wget -O fullnode.yaml https://raw.githubusercontent.com/aptos-labs/aptos-core/testnet/docker/compose/aptos-node/fullnode.yaml
  ```

## haproxy-fullnode.cfg

[Section titled “haproxy-fullnode.cfg”](#haproxy-fullnodecfg)

* **Git repo:** `aptos-core`

* **Git branch:** `testnet` on <https://github.com/aptos-labs/aptos-core>

* **Command to download:**

```shellscript
  wget -O haproxy-fullnode.cfg https://raw.githubusercontent.com/aptos-labs/aptos-core/testnet/docker/compose/aptos-node/haproxy-fullnode.cfg
  ```

# State Synchronization

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 the peers, validates the data and persists it to local storage. This document explains how state sync works and how to configure it.

Caution

**Manual configuration**\
Most users should not need to configure state sync. State sync will automatically select the best configuration for your node. You should only manually configure state sync if you have a specific use case that requires it. Selecting the wrong configuration will lead to slower syncing times and degraded performance.

## State sync

[Section titled “State sync”](#state-sync)

At a high-level, state sync operates in two phases. First, all nodes will bootstrap on startup (in the **bootstrapping phase**). This allows the node to catch up to the latest state in the Aptos blockchain. Next, the node will stay up-to-date with the blockchain by continuously syncing (in the **continuous syncing phase**). Each of these phases has different modes of operation.

Note

Need to start a node quickly? If you need to start a node quickly, here’s what we recommend by network and use case:

* **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).
* **Testnet**: To sync the entire blockchain history, restore from a [backup](/network/nodes/bootstrap-fullnode/aptos-db-restore). Otherwise, download [a snapshot](/network/nodes/bootstrap-fullnode/bootstrap-fullnode) or use [fast sync](/network/nodes/configure/state-sync#fast-syncing).
* **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).

### Bootstrapping phase

[Section titled “Bootstrapping phase”](#bootstrapping-phase)

When the node starts, state sync will perform bootstrapping by using the configured bootstrapping mode. There are several bootstrapping modes:

* **Execute all the transactions since genesis**. In this mode, the node will retrieve from the Aptos network all the transactions since genesis, i.e., since the start of the blockchain’s history, and re-execute those transactions. Naturally, this mode takes the longest amount of time because it must process all transactions since the network began.
* **Apply transaction outputs since genesis**. In this mode, the node will retrieve all the transactions since genesis, but it will skip transaction re-execution and instead apply the outputs of the transactions that were previously produced by validator execution. This mode reduces the amount of CPU time required, but still processes all transactions since the network began.
* **Intelligent syncing since genesis**. In this mode, the node will retrieve all the transactions since genesis 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. This mode is the default mode for devnet and other testing environments.
* **Fast syncing**. In this mode, the node will skip the transaction history in the blockchain and will download only the latest blockchain state directly. As a result, the node will not have the historical transaction data, but it will be able to catch up to the Aptos network much more rapidly. This mode is the default mode for testnet and mainnet.

Note

**Bootstrapping defaults?**\
The default bootstrapping mode depends on the network type:

* **Testnet and Mainnet**: The default bootstrapping mode is fast sync, because these networks are long-lived and have a large amount of historical data.
* **Devnet and other networks**: The default bootstrapping mode is intelligent syncing, because these networks are typically short-lived and have a small amount of historical data.

### Continuous syncing phase

[Section titled “Continuous syncing phase”](#continuous-syncing-phase)

After the node has bootstrapped and caught up to the Aptos network initially, state sync will then move into the continuous syncing phase to stay up-to-date with the blockchain. There are several continuous syncing modes:

* **Executing transactions**. This mode will keep the node up-to-date by executing new 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. This is the default mode for all environments.

Note

**Continuous syncing defaults?**\
The default continuous syncing mode is always intelligent syncing, because this mode is the most performant.

## Configuring state sync

[Section titled “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`.

Caution

**Manual configuration**\
You should only manually configure state sync if you have a specific use case that requires it. Selecting the wrong configuration will lead to slower syncing times and degraded performance.

### Executing all transactions

[Section titled “Executing all transactions”](#executing-all-transactions)

To execute all the transactions since genesis and continue to execute new transactions as they are committed, add the following to your node configuration file (for example, `fullnode.yaml` or `validator.yaml`):

```yaml
state_sync:
  state_sync_driver:
    bootstrapping_mode: ExecuteTransactionsFromGenesis
    continuous_syncing_mode: ExecuteTransactions
```

Caution

**Verify node syncing**\
While your node is syncing, you’ll be able to see the [`aptos_state_sync_version{type="synced"}`](/network/nodes/full-node/verify-pfn) metric gradually increase.

### Applying all transaction outputs

[Section titled “Applying all transaction outputs”](#applying-all-transaction-outputs)

To apply all transaction outputs since genesis and continue to apply new transaction outputs as transactions are committed, add the following to your node configuration file:

```yaml
state_sync:
  state_sync_driver:
    bootstrapping_mode: ApplyTransactionOutputsFromGenesis
    continuous_syncing_mode: ApplyTransactionOutputs
```

Note

**Verify node syncing**\
While your node is syncing, you’ll be able to see the [`aptos_state_sync_version{type="synced"}`](/network/nodes/full-node/verify-pfn) metric gradually increase.

### Intelligent syncing

[Section titled “Intelligent syncing”](#intelligent-syncing)

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:

```yaml
state_sync:
  state_sync_driver:
    bootstrapping_mode: ExecuteOrApplyFromGenesis
    continuous_syncing_mode: ExecuteTransactionsOrApplyOutputs
```

Note

**Verify node syncing**\
While your node is syncing, you’ll be able to see the [`aptos_state_sync_version{type="synced"}`](/network/nodes/full-node/verify-pfn) metric gradually increase.

### Fast syncing

[Section titled “Fast syncing”](#fast-syncing)

Caution

**Proceed with caution**\
Fast sync should only be used as a last resort for validators and VFNs. This is because fast sync skips the blockchain history, and: (i) reduces data availability in the network (as the blockchain history is truncated on the fast synced nodes); and (ii) hinders validator consensus performance (if too much data has been skipped). Validators that fast sync may require additional running time before they are eligible to participate in consensus.

To download the latest blockchain state and continue to process new transactions as they are committed, add the following to your node configuration file:

```yaml
state_sync:
  state_sync_driver:
    bootstrapping_mode: DownloadLatestStates
    continuous_syncing_mode: ExecuteTransactionsOrApplyOutputs
```

Caution

**Verify node syncing**\
While your node is syncing, you’ll be able to see the `aptos_state_sync_version{type="synced_states"}` metric gradually increase. However, `aptos_state_sync_version{type="synced"}` will only increase once the node has bootstrapped. This may take several hours depending on the amount of data, network bandwidth and node resources available.

**Note:** If `aptos_state_sync_version{type="synced_states"}` does not increase then do the following:

1. Double-check the node configuration file has correctly been updated.
2. Make sure that the node is starting up with an empty storage database (i.e., that it has not synced any state previously).

## Archival PFNs

[Section titled “Archival PFNs”](#archival-pfns)

To operate an archival PFN (which is a PFN that contains all blockchain data since the start of the network, i.e., genesis), you should:

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

**Archival nodes are deprecated**\
Running and maintaining archival nodes is expensive and slow, as the amount of data being stored on the node will grow endlessly. 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).

## Security implications and data integrity

[Section titled “Security implications and data integrity”](#security-implications-and-data-integrity)

Each of the different state sync syncing modes perform data integrity verifications to ensure that the data being synced to the node has been correctly produced and signed by the validators. This occurs slightly differently for each syncing mode:

1. **Executing transactions**: 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 correctly executed by the validators. All resulting blockchain state will thus be re-verified by the syncing node.
2. **Applying transaction outputs**: Applying transaction outputs from genesis is faster than executing all transactions, but it requires that the syncing node trusts 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 the state hashes are still verified.
3. **Intelligent syncing**: Intelligent syncing will either execute or apply the transaction outputs depending on whichever is faster, per data chunk. Thus, the security implications of using this mode are identical to those of applying transaction outputs.
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 trust that all transactions were correctly executed by the validators. However, all other blockchain state 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

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.

Note

**No personal information is collected**\
The Aptos node binary does **not** collect any personal information, such as usernames or email addresses. It only collects relevant node telemetry, such as software version, node metrics, operating system information and the IP address of your node. This data is used to enhance the decentralization and performance of the network.

## Node telemetry

[Section titled “Node telemetry”](#node-telemetry)

The list below shows the categories of information collected by Aptos node telemetry:

* **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

[Section titled “CLI telemetry”](#cli-telemetry)

The Aptos CLI tool also collects telemetry data. The list below shows the categories of information collected by CLI telemetry:

* **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

[Section titled “Disabling telemetry”](#disabling-telemetry)

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`:

```shellscript
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:

```shellscript
echo "export APTOS_DISABLE_TELEMETRY=true" >> ~/.profile
source ~/.profile
```

## Configuring telemetry

[Section titled “Configuring telemetry”](#configuring-telemetry)

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

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>.

# Deploy a PFN

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 [Aptos Build](https://build.aptoslabs.com/) 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)
  [Section titled “Using Source Code”](#using-source-code)
* ### [Using Docker](/network/nodes/full-node/deployments/using-docker)
  [Section titled “Using Docker”](#using-docker)
* ### [Using GCP](/network/nodes/full-node/deployments/using-gcp)
  [Section titled “Using GCP”](#using-gcp)

# Using Docker

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>

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:

```shellscript
mkdir mainnet && cd mainnet
mkdir 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>. 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):

```yaml
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:

```shellscript
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>

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

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

[Section titled “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>
* Kubernetes CLI: <https://kubernetes.io/docs/tasks/tools/>
* Google Cloud CLI: <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):

```shellscript
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

[Section titled “GCP setup”](#gcp-setup)

#### Sign up for the 90-day free trial

[Section titled “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

[Section titled “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

[Section titled “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

[Section titled “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

[Section titled “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.

```shellscript
   export WORKSPACE=devnet
   ```

* Create a directory for the workspace

```shellscript
   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).

```shellscript
gsutil mb gs://BUCKET_NAME
# for example
gsutil mb gs://<project-name>-aptos-terraform-dev
```

3. Create Terraform file called `main.tf` in your working directory:

```shellscript
cd ~/$WORKSPACE
touch 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
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:

```shellscript
terraform init
```

This will download all the Terraform dependencies into the `.terraform` folder.

6. Create a new Terraform workspace to isolate your environments:

```shellscript
terraform workspace new $WORKSPACE
# This command will list all workspaces
terraform workspace list
```

7. Apply the configuration:

```shellscript
terraform apply
```

This might take a while to finish (10 - 20 minutes), Terraform will create all the resources on your cloud account.

## Validation

[Section titled “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:

```shellscript
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):

```shellscript
kubectl get pods -n aptos
```

You should see this:

```shellscript
NAME                       READY   STATUS    RESTARTS   AGE
devnet0-aptos-fullnode-0   1/1     Running   0          56s
```

3. Get your PFN IP:

```shellscript
kubectl get svc -o custom-columns=IP:status.loadBalancer.ingress -n aptos
```

You should see something like this:

```plaintext
[map[ip:104.198.36.142]]
```

4. Check the REST API, make sure that the ledger version is increasing:

```shellscript
curl http://<IP>/v1
# Example command syntax: curl http://104.198.36.142/v1
```

You should see this something like this:

```json
{
  "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:

```shellscript
     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:

```shellscript
     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

[Section titled “PFN identity and seed peers”](#pfn-identity-and-seed-peers)

### Static identity

[Section titled “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:

```terraform
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     = "devnet"       # Specify the docker image tag to use

fullnode_helm_values = {
    chain = {
      name = "devnet"
    }
    # create fullnode from this identity config, so it will always have same peer id and address
    fullnode_identity = {
      type = "from_config"
      key = "B8BD811A91D8E6E0C6DAC991009F189337378760B55F3AD05580235325615C74"
      peer_id = "ca3579457555c80fc7bb39964eb298c414fd60f81a2f8eedb0244ec07a26e575"
    }
  }
}
```

3. Apply Terraform changes:

```shellscript
terraform apply
```

### Seed peers

[Section titled “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:

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:

```shellscript
terraform apply
```

## Check logging

[Section titled “Check logging”](#check-logging)

To check the logs of the pod, use the following commands:

```shellscript
# Get a list of the pods
kubectl get pods -n aptos

# Get logs of the pod
kubectl 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 "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 "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 "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 "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 "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

[Section titled “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 "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 "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

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):

```shellscript
     curl -O https://raw.githubusercontent.com/aptos-labs/aptos-networks/main/mainnet/genesis.blob
     ```

* Run this command to download the waypoint file (for mainnet):

```shellscript
     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>. 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:

```shellscript
   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.

```yaml
      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:

```yaml
      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:

```yaml
      base:
        data_dir: "</path/to/my/homedir/my-full-node/data>"
      ```

6. Start your local public fullnode by running the below command:

```shellscript
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

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)
  [Section titled “Upgrade your PFN”](#upgrade-your-pfn)
* ### [Generate a PFN Identity](/network/nodes/full-node/modify/network-identity-fullnode)
  [Section titled “Generate a PFN Identity”](#generate-a-pfn-identity)
* ### [Customize PFN Networks](/network/nodes/full-node/modify/fullnode-network-connections)
  [Section titled “Customize PFN Networks”](#customize-pfn-networks)

# Customize PFN Networks

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

[Section titled “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`:

```yaml
<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:

```yaml
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

[Section titled “Connecting to seed peers”](#connecting-to-seed-peers)

Caution

**Seeds are not required**\
Seed peers are not required for your PFN to connect to any Aptos network. All networks (e.g., devnet, testnet and mainnet) are automatically discoverable. Adding seed peers should only be done if you wish to connect to a specific peer (or set of peers), and are confident that the peers are high quality.

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:

```yaml
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

[Section titled “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:

```yaml
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:

```yaml
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

[Section titled “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:

```yaml
...
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

Caution

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 on demand. As such, generating an identity using this guide **should only be done for PFNs**, and not for validators or VFNs.

## Ephemeral vs. Static Identities

[Section titled “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.

### Ephemeral Identity

[Section titled “Ephemeral Identity”](#ephemeral-identity)

* Automatically generated on startup. The same ephemeral identity is used across restarts if the identity key file already exists.
* Stored at `/opt/aptos/data/db/ephemeral_identity_key`.

### Static Identity

[Section titled “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.

Caution

Before you proceed, make sure that you already know how to start your local PFN. See [Run a PFN](/network/nodes/full-node) for detailed documentation.

## Generate a static identity

[Section titled “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

[Section titled “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:

```shellscript
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:

```shellscript
cat ~/private-key.txt
C83110913CBE4583F820FABEB7514293624E46862FAE1FD339B923F0CACC647D%

cat ~/private-key.txt.pub
B881EA2C174D8211C123E5A91D86227DB116A44BB345A6E66874F83D8993F813%
```

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):

```shellscript
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:

```json
{
  "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:

```yaml
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:

```yaml
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

[Section titled “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:

```shellscript
cd ~/my-full-node
docker 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:

```shellscript
aptos key generate \
    --key-type x25519 \
    --output-file /path/to/private-key.txt
```

3. **Retrieve the peer identity**

```shellscript
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**

```yaml
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.

# Upgrade your PFN

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

[Section titled “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):

```shellscript
   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:

```shellscript
   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:

```shellscript
   cargo run -p aptos-node --release -- -f ./fullnode.yaml
   ```

### (Devnet) Data Wipe and Reset

[Section titled “(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

[Section titled “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:

```shellscript
   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:

```shellscript
   docker compose up -d
   ```

## GCP deployment

[Section titled “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)

[Section titled “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):

```shellscript
terraform get -update
```

4. Apply the Terraform changes:

```shellscript
terraform apply
```

### Upgrade without data wipe

[Section titled “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):

```shellscript
terraform get -update
```

3. Apply the Terraform changes:

```shellscript
terraform apply

# If you didn't update the image tag, terraform will show nothing to change, in this case, force a helm update
terraform apply -var force_helm_update=true
```

# PFN Requirements

To ensure that your public fullnode (PFN) operates smoothly, it should meet the requirements specified in this document.

## Hardware requirements

[Section titled “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

[Section titled “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

[Section titled “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:

[Section titled “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

[Section titled “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

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

[Section titled “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:

```shellscript
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:

```shellscript
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:

```shellscript
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

[Section titled “(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:

```shellscript
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:

```shellscript
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

[Section titled “(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`:

```shellscript
# 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

## Recommended

[Section titled “Recommended”](#recommended)

Most developers should use the CLI to run a local development network. It is simpler and more fully featured than just a single node localnet + faucet. If you want a local stack that works just like a production network ([Node API](/build/apis) + [Transaction Stream](/build/indexer/txn-stream) + [Indexer API](/build/indexer) + Faucet), this is the option for you.

* ### [Run a Local Development Network](/network/nodes/localnet/local-development-network)
  [Section titled “Run a Local Development Network”](#run-a-local-development-network)

## Specialized

[Section titled “Specialized”](#specialized)

If you’re developing the core Aptos node software itself or have complex testing needs, consider this guide.

* ### [Run a Localnet with Validator](/network/nodes/localnet/run-a-localnet)
  [Section titled “Run a Localnet with Validator”](#run-a-localnet-with-validator)

# Running a Local Network via Aptos CLI

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

[Section titled “Starting A Local Network”](#starting-a-local-network)

1. Ensure you have the installed.

You can verify if the Aptos CLI is installed by running `aptos --version`.

2. Ensure you have 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:

```shellscript
   aptos node run-local-testnet --with-indexer-api
   ```

Caution

Note: Despite the name (`local-testnet`), this has nothing to do with the Aptos testnet, it will run a network entirely local to your machine.

You should expect to see an output similar to this:

```shellscript
   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_testnet
   Transaction stream is ready. Endpoint: http://0.0.0.0:50051/
   Indexer API is ready. Endpoint: http://127.0.0.1:8090/
   Faucet 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

[Section titled “Address Already In Use”](#address-already-in-use)

```shellscript
   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

[Section titled “Too many open files error”](#too-many-open-files-error)

```shellscript
   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`:

```shellscript
   ulimit -n 1048576
   ```

### Docker is not available

[Section titled “Docker is not available”](#docker-is-not-available)

```shellscript
   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](/network/nodes/aptos-api-spec): 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:

```shellscript
   aptos node run-local-testnet --help
   ```

## Using The Local Network

[Section titled “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:

```shellscript
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:

```shellscript
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

[Section titled “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`):

```tsx
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

[Section titled “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:

```shellscript
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.

```shellscript
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:

```shellscript
aptos node run-local-testnet --force-restart --assume-yes
```

## Running in a container

[Section titled “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:

```shellscript
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.

# Run a Localnet with Validator

Note

**Using the CLI to run a local development network**\
Running a localnet with the Aptos CLI is simpler and more fully featured. Learn how by following this guide: [Run a Local Development Network with the CLI](/network/nodes/localnet/local-development-network).

You can run a localnet of the Aptos blockchain. This localnet will not be connected to the Aptos devnet. It will run on your local machine, independent of other Aptos networks. You can use this localnet for testing and development purposes.

You can run a localnet using the Aptos-core source code. This approach is useful for testing modifications to the Aptos-core codebase or to the Aptos Framework.

The rest of this document describes:

* How to start your localnet with a single validator node, and
* How to start a Faucet service and attach it to your localnet.

## Using the Aptos-core source code

[Section titled “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, now you can start your localnet. Before you proceed, make a note of the following:

Note

**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:

```shellscript
   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.

```shellscript
   ...
   ...
   ...

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/7180
   Aptos is running, press ctrl-c to exit
   ```

**NOTE**: 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:

```shellscript
cargo run -p aptos-node -- --test --config <config-path>
```

### Attaching a Faucet to your localnet

[Section titled “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:

```shellscript
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

[Section titled “Interacting with the localnet”](#interacting-with-the-localnet)

After starting your localnet, you will see the following:

```shellscript
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

[Section titled “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)

# Monitor your 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)
  [Section titled “Node Inspection Service”](#node-inspection-service)
* ### [Important Node Metrics](/network/nodes/measure/important-metrics)
  [Section titled “Important Node Metrics”](#important-node-metrics)
* ### [Node Health Checker](/network/nodes/measure/node-health-checker)
  [Section titled “Node Health Checker”](#node-health-checker)

# Important Node Metrics

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

[Section titled “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

[Section titled “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

[Section titled “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

[Section titled “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

[Section titled “REST API”](#rest-api)

The following [REST API](/build/apis) 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

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

[Section titled “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:

```shellscript
   mkdir /tmp/nhc
   cd /tmp/nhc
   wget 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:

```shellscript
   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`:

```shellscript
   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:

```json
   {
     "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

[Section titled “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

[Section titled “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:

```shellscript
curl 'http://nhc.aptoslabs.com/check?node_url=http://myfullnode.mysite.com&baseline_configuration_id=devnet_fullnode'
```

### Getting baseline configurations ready

[Section titled “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

[Section titled “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:

```shellscript
mkdir /tmp/nhc
cd /tmp/nhc
configs=(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

[Section titled “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

[Section titled “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:

```shellscript
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

[Section titled “Running NHC: Source”](#running-nhc-source)

First, check out the source:

```shellscript
git clone git@github.com:aptos-labs/aptos-core.git
cd 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:

```shellscript
cargo run -p aptos-node-checker --release -- server run --baseline-config-paths /tmp/nhc/devnet_fullnode.yaml
```

## Generating the OpenAPI specs

[Section titled “Generating the OpenAPI specs”](#generating-the-openapi-specs)

To generate the OpenAPI specs, run the following commands from `ecosystem/node-checker`:

```shellscript
cargo run -- server generate-openapi -f yaml > doc/spec.yaml
cargo 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

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?

[Section titled “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:

```shellscript
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

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.

You can configure various aspects of the node inspection service. This document describes how to expose and see the metrics locally, on the respective node. You may also view these metrics remotely by making the port accessible via firewall rules.

Caution

If you do make the inspection service port publicly accessible on your node, we recommend disabling access when not in use (to prevent unauthorized access and abuse).

## Examining node metrics

[Section titled “Examining node metrics”](#examining-node-metrics)

If you’d like to examine the metrics of your node, start running a node and review the inspection service locally by loading this URL in your browser:

```shellscript
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:

```shellscript
http://localhost:9101/json_metrics
```

Note

Inspection service configuration See additional configuration details below.

## Change inspection service port

[Section titled “Change inspection service port”](#change-inspection-service-port)

The inspection service should run on all nodes 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:

```yaml
inspection_service:
  port: 1000
```

## Expose system configuration

[Section titled “Expose system configuration”](#expose-system-configuration)

The inspection service also provides a way to examine the configuration of your node at runtime (i.e., the configuration settings that your node started with).

Caution

**Proceed with caution**\
By default, the configuration endpoint is disabled as it may expose potentially sensitive information about the configuration of 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:

```yaml
inspection_service:
  expose_configuration: true
```

And visit the configuration URL:

```shellscript
http://localhost:9101/configuration
```

## Expose system information

[Section titled “Expose system information”](#expose-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:

```shellscript
http://localhost:9101/system_information
```

If you’d like to disable this endpoint, add the following to your node configuration file:

```yaml
inspection_service:
  expose_system_information: false
```

Note

**System information accuracy**\
The system information displayed here is not guaranteed to be 100% accurate due to limitations in the way this information is collected. As a result, we recommend not worrying about any inaccuracies and treating the information as an estimate.

# Networks

## Network Overview

[Section titled “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

[Section titled “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

[Section titled “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://aptosfoundation.org/currents/aptos-tokenomics-overview).

# Run a Validator and VFN

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 Nodes

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

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

[Section titled “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

[Section titled “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

[Section titled “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

[Section titled “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

[Section titled “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:

```terraform
   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:

```shellscript
   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:

```shellscript
${WORKSPACE}-aptos-node-0-genesis-e3
```

```shellscript
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

[Section titled “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

[Section titled “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:

```shellscript
aptos init --profile mainnet-operator \
   --network mainnet \
   --private-key <operator_account_private_key> \
   --skip-faucet
```

### 2. Check your account balance

[Section titled “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:

```shellscript
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:

```json
"coin": {
   "value": "5000"
}
```

### 3. Update on-chain network addresses

[Section titled “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.

```shellscript
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.

```shellscript
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

[Section titled “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).

```shellscript
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

[Section titled “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:

```shellscript
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

[Section titled “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.

```shellscript
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:

```shellscript
aptos node show-validator-set --profile mainnet-operator | jq -r '.Result.active_validators' | grep <pool_address>
```

## Bootstrap your nodes

[Section titled “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

[Section titled “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

> 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

[Section titled “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

[Section titled “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:

```shellscript
  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:

```shellscript
  aptos account derive-resource-account-address
  ```

1. Run the command below, substitute in the profile you previously configured during initialization:

```shellscript
   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

[Section titled “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:

```shellscript
  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:

```shellscript
  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:

```shellscript
  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:

```shellscript
  aptos move run --profile delegator \
    --function-id 0x1::delegation_pool::withdraw \
    --args address:<pool_address> u64:<amount>
  ```

## Perform pool owner operations

[Section titled “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:

```shellscript
  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):

```shellscript
  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

[Section titled “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:

```shellscript
  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:

```shellscript
  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

[Section titled “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:

```typescript
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.

```shellscript
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

[Section titled “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

[Section titled “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:

```shellscript
  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:

```shellscript
  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:

```shellscript
  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:

```shellscript
  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:

```shellscript
  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:

```shellscript
  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`:

```shellscript
  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:

```shellscript
  aptos move view --url <REST API for the network> \
    --function-id 0x1::delegation_pool::get_delegators_allowlist \
    --args address:<pool>
  ```

# Staking Pool Operations

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

[Section titled “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.

```shellscript
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:

```shellscript
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

[Section titled “Perform pool owner operations”](#perform-pool-owner-operations)

### Transfer coin between accounts

[Section titled “Transfer coin between accounts”](#transfer-coin-between-accounts)

```shellscript
aptos account transfer \
  --account <operator-address> \
  --amount <amount> \
  --profile mainnet-owner
```

### Switch operator

[Section titled “Switch operator”](#switch-operator)

```shellscript
aptos stake set-operator \
  --operator-address <new-operator-address> \
  --profile mainnet-owner
```

### Switch voter

[Section titled “Switch voter”](#switch-voter)

```shellscript
aptos stake set-delegated-voter \
  --voter-address <new-voter-address> \
  --profile mainnet-owner
```

### Add stake

[Section titled “Add stake”](#add-stake)

```shellscript
aptos stake add-stake \
  --amount <amount> \
  --profile mainnet-owner
```

### Increase stake lockup

[Section titled “Increase stake lockup”](#increase-stake-lockup)

```shellscript
aptos stake increase-lockup --profile mainnet-owner
```

### Unlock stake

[Section titled “Unlock stake”](#unlock-stake)

```shellscript
aptos stake unlock-stake \
  --amount <amount> \
  --profile mainnet-owner
```

### Withdraw stake

[Section titled “Withdraw stake”](#withdraw-stake)

```shellscript
aptos stake withdraw-stake \
  --amount <amount> \
  --profile mainnet-owner
```

### Update commission

[Section titled “Update commission”](#update-commission)

```shellscript
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

[Section titled “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:

```shellscript
  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:

```shellscript
  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

[Section titled “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).

```shellscript
aptos node get-stake-pool \
  --owner-address e7be097a90c18f6bdd53efe0e74bf34393cac2f0ae941523ea196a47b6859edb \
  --profile mainnet-operator
```

Example output:

```json
{
  "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

[Section titled “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

[Section titled “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:

```shellscript
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

[Section titled “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.

```shellscript
aptos node get-performance \
  --pool-address <pool address> \
  --profile mainnet-operator
```

Example output:

```json
{
  "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

[Section titled “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

[Section titled “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:

```shellscript
aptos node analyze-validator-performance \
  --analyze-mode detailed-epoch-table \
  --profile mainnet-operator \
  --start-epoch 0 | grep <pool address>
```

## Tracking rewards

[Section titled “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`.

# Staking Pool Voter

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

[Section titled “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

[Section titled “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

[Section titled “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

[Section titled “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

[Section titled “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 Nodes

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

[Section titled “Deployment methods”](#deployment-methods)

Select a deployment method for your nodes:

* ### [Using Source Code](/network/nodes/validator-node/deploy-nodes/using-source-code)
  [Section titled “Using Source Code”](#using-source-code)
* ### [Using Docker](/network/nodes/validator-node/deploy-nodes/using-docker)
  [Section titled “Using Docker”](#using-docker)
* ### [Using AWS](/network/nodes/validator-node/deploy-nodes/using-aws)
  [Section titled “Using AWS”](#using-aws)
* ### [Using Azure](/network/nodes/validator-node/deploy-nodes/using-azure)
  [Section titled “Using Azure”](#using-azure)
* ### [Using GCP](/network/nodes/validator-node/deploy-nodes/using-gcp)
  [Section titled “Using GCP”](#using-gcp)

# Using AWS

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

[Section titled “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.,

```shellscript
   export WORKSPACE=mainnet
   export USERNAME=alice
   mkdir ~/$WORKSPACE
   cd ~/$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:

```shellscript
   aws s3 mb s3://<bucket name> --region <region name>
   ```

3. Create a Terraform file called `main.tf` in your working directory:

```shellscript
   cd ~/$WORKSPACE
   vi main.tf
   ```

4. Modify the `main.tf` file to configure Terraform and create the Terraform module. See the example below:

```terraform
   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>
   * The Helm values: <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.

```shellscript
   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.

```shellscript
   terraform workspace new $WORKSPACE

# This command will list all workspaces
   terraform workspace list
   ```

7. Apply the Terraform configuration.

```shellscript
   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:

```shellscript
   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:

```shellscript
    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:

```shellscript
    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`

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:

```shellscript
    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:

```shellscript
    kubectl get pods

# Example output
    NAME                                        READY   STATUS    RESTARTS   AGE
    node1-aptos-node-0-fullnode-e9-0              1/1     Running   0          4h31m
    node1-aptos-node-0-haproxy-7cc4c5f74c-l4l6n   1/1     Running   0          4h40m
    node1-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

[Section titled “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

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

[Section titled “Deployment steps”](#deployment-steps)

Note

1. Create a working directory for your Aptos nodes, and pick a username for your nodes, e.g.,

```shellscript
   export WORKSPACE=mainnet
   export USERNAME=alice
   mkdir ~/$WORKSPACE
   cd ~/$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:

```shellscript
   az group create -l <azure region> -n aptos-$WORKSPACE
   az storage account create -n <storage account name> -g aptos-$WORKSPACE -l <azure region> --sku Standard_LRS
   az 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:

```shellscript
   cd ~/$WORKSPACE
   vi main.tf
   ```

4. Modify the `main.tf` file to configure Terraform and create the Terraform module. See the example below:

```terraform
   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>
   * The Helm values: <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.

```shellscript
   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.

```shellscript
   terraform workspace new $WORKSPACE

# This command will list all workspaces
   terraform workspace list
   ```

7. Apply the Terraform configuration.

```shellscript
   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:

```shellscript
   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:

```shellscript
    aptos genesis generate-keys --output-dir ~/$WORKSPACE/keys
    ```

This will create 4 key files under `~/$WORKSPACE/keys` directory:

Caution

* `genesis.blob`
    * `waypoint.txt`

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:

* `$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:

```shellscript
    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.

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:

```shellscript
    kubectl get pods

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

[Section titled “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

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

[Section titled “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.,

```shellscript
   export WORKSPACE=mainnet
   export USERNAME=alice
   mkdir ~/$WORKSPACE
   cd ~/$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:

```shellscript
   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:

```shellscript
   # Replace <validator node IP / DNS address> and <Full Node IP / DNS address> below,
   # with the appropriate IP or DNS address for your nodes.

cd ~/$WORKSPACE
   aptos 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
   ```

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. 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.

6. To start the validator node, run the following command in your working directory:

```shellscript
   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.

7. 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:

```yaml
   ---
   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:

```yaml
   ---
   addresses:
     - "/dns/example.com/tcp/6181/noise-ik/..." # Set the DNS Address of the validator
   ```

8. 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:

```shellscript
   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

[Section titled “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

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

[Section titled “Deployment steps”](#deployment-steps)

1. Create a working directory for your Aptos nodes, and pick a username for your nodes, e.g.,

```shellscript
   export WORKSPACE=mainnet
   export USERNAME=alice
   mkdir ~/$WORKSPACE
   cd ~/$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:

```shellscript
   gsutil mb gs://BUCKET_NAME

# Here's an example of creating a bucket
   gsutil mb gs://<project-name>-aptos-terraform-dev
   ```

3. Create a Terraform file called `main.tf` in your working directory:

```shellscript
   cd ~/$WORKSPACE
   vi main.tf
   ```

4. Modify the `main.tf` file to configure Terraform and create the Terraform module. See the example below:

```terraform
   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>
   * The Helm values: <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.

```shellscript
   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.

```shellscript
   terraform workspace new $WORKSPACE

# This command will list all workspaces
   terraform workspace list
   ```

7. Apply the Terraform configuration.

```shellscript
   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:

```shellscript
   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:

```shellscript
    aptos genesis generate-keys --output-dir ~/$WORKSPACE/keys
    ```

This will create 4 key files under `~/$WORKSPACE/keys` directory:

Caution

* `genesis.blob`
    * `waypoint.txt`

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:

* `$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:

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.

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:

```shellscript
    kubectl get pods

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

[Section titled “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

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

[Section titled “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.,

```shellscript
   export WORKSPACE=mainnet
   export USERNAME=alice
   mkdir ~/$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:

```shellscript
   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:

```shellscript
   # Replace <validator node IP / DNS address> and <Full Node IP / DNS address> below,
   # with the appropriate IP or DNS address for your nodes.

# For example, if you are using IP addresses:

# 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
   ```

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. 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:

```shellscript
   mkdir ~/$WORKSPACE/config
   cp validator.yaml ~/$WORKSPACE/config/validator.yaml
   cp fullnode.yaml ~/$WORKSPACE/config/fullnode.yaml
   ```

These will be the primary configuration files for your validator and VFN, respectively.

8. 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:

```yaml
     ---
     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:

```yaml
     ---
     addresses:
       - "/dns/example.com/tcp/6181/noise-ik/..." # Set the DNS Address of the validator
     ```

9. 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.

10. 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:

```shellscript
    cargo clean
    cargo build -p aptos-node --release
    sudo mv target/release/aptos-node /usr/local/bin
    aptos-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:

```shellscript
    cargo clean
    cargo build -p aptos-node --release
    sudo mv target/release/aptos-node /usr/local/bin
    aptos-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

[Section titled “(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.

```shellscript
[Unit]
Description=Aptos Node Service

[Service]
User=nodeuser
Group=nodeuser

LimitNOFILE=500000

#Environment="RUST_LOG=error"
WorkingDirectory=/home/nodeuser/aptos-core
ExecStart=/usr/local/bin/aptos-node -f /home/nodeuser/aptos-mainnet/config/validator.yaml

Restart=on-failure
RestartSec=3s

StandardOutput=journal
StandardError=journal
SyslogIdentifier=aptos-node

[Install]
WantedBy=multi-user.target
```

## Connecting to the Aptos Network

[Section titled “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.

# Modify Nodes

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)
  [Section titled “Upgrade Nodes”](#upgrade-nodes)
* ### [Shutdown Nodes](/network/nodes/validator-node/modify-nodes/shutting-down-nodes)
  [Section titled “Shutdown Nodes”](#shutdown-nodes)
* ### [Rotate Consensus Key](/network/nodes/validator-node/modify-nodes/rotate-consensus-key)
  [Section titled “Rotate Consensus Key”](#rotate-consensus-key)

# Rotate consensus key

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

[Section titled “New key generation”](#new-key-generation)

Using the following [Aptos CLI](https://aptos.dev/en/build/cli) command to generate a new consensus identity. In this example, identity files are saved to directory `/new/key/root`.

```shellscript
aptos genesis generate-keys --output-dir /new/key/root
```

## Add new private key to node

[Section titled “Add new private key to node”](#add-new-private-key-to-node)

Edit the node config yaml as described below.

```yaml
# ...
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

[Section titled “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.

```shellscript
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.

```shellscript
aptos move run \
    --profile profile1 \
    --function-id 0x1::stake::rotate_consensus_key \
    --args \
        address:0x1eb42885d7d5232269229e56bb80d0959584e14485097ebf9ab619cf4fda5c02 \
        hex:0xacb7859468ca85cf9935e64ebb2b9b3fa8187de42d541acebaf732365a0131eaa994098f9d0d7e6b8ddea8ef11e16c55 \
        hex:0x8e27fd9300433191b1123217928a6f5190a6ec344ea8623555712a850029b34f5c4bab68df7568b48bcced408cde5174064284407ee760df5dbf12d1c6090589ea1a692997018aca740e91d2182e5715c7745565fe99361e279ccfcfa10ae1f7
```

## Wait for the next epoch

[Section titled “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

[Section titled “(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`.

```js
{
    // ...
    "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).

# Shutdown Nodes

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

[Section titled “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.

```shellscript
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

[Section titled “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

[Section titled “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

[Section titled “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

[Section titled “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`

# Upgrade Nodes

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

[Section titled “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

[Section titled “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

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

[Section titled “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

[Section titled “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

[Section titled “Reference specs”](#reference-specs)

**Specifications for Running an Aptos Validator and VFN on Mainnet**

| Component            | Specification                                                     |
| -------------------- | ----------------------------------------------------------------- |
| CPU                  | 32 cores, 2.8GHz or faster, AMD Milan EPYC or Intel Xeon Platinum |
| Memory               | 64GB RAM                                                          |
| Storage              | 3.0 TB SSD with at least 60K IOPS and 200MiB/s bandwidth          |
| Networking Bandwidth | 1Gbps                                                             |

**Example Machine Types on Various Clouds**

| Cloud Provider | Machine Type                      | Notes                |
| -------------- | --------------------------------- | -------------------- |
| AWS            | c6id.16xlarge                     | If using a local SSD |
| AWS            | c6i.16xlarge + io2 EBS volume     | With 60K IOPS        |
| GCP            | t2d-standard-60 + pd-ssd          | With 60K IOPS        |
| Azure          | Standard\_D64\_v5                 | With 64K IOPS        |
| Latitude.sh    | m4.large, rs4.large or rs4.xlarge | With 64K IOPS        |

### Performance benchmarking

[Section titled “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:

```shellscript
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

[Section titled “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

[Section titled “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

[Section titled “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

[Section titled “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:

[Section titled “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:

[Section titled “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

[Section titled “Software Requirements”](#software-requirements)

### Time Service

[Section titled “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

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

[Section titled “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

[Section titled “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

[Section titled “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

[Section titled “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).

# Verify Nodes

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)
  [Section titled “Node Health”](#node-health)
* ### [Validator Leaderboard](/network/nodes/validator-node/verify-nodes/leaderboard-metrics)
  [Section titled “Validator Leaderboard”](#validator-leaderboard)

# Validator Leaderboard

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).

## Calculating validator rewards

[Section titled “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

[Section titled “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

[Section titled “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

[Section titled “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

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

[Section titled “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:

```shellscript
   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.

```shellscript
   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:

```shellscript
   aptos_connections{direction="inbound",network_id="Validator",peer_id="f326fd30",role_type="validator"} 5
   aptos_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.

```shellscript
   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

[Section titled “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-reference).

* **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>).
  * 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>).

## Telemetry

[Section titled “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

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

[Section titled “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

[Section titled “Subscribe to Release Announcements”](#subscribe-to-release-announcements)

### Subscribe via GitHub

[Section titled “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)

[Section titled “Subscribe via Aptos Discord”](#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)

[Section titled “Subscribe via Aptos Twitter”](#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

[Section titled “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).

# 404

> Page not found. Check the URL or try using the search bar.

404.move

```move
/// A playful 404 module that uses Aptos blockchain concepts
module 0x404::lost_transaction {
    use aptos_framework::account;
    use aptos_framework::coin::{Self, AptosCoin};
    use std::error;
    use std::signer;

/// Custom errors for our lost transaction saga
    const E_TRANSACTION_NOT_FOUND: u64 = 404;
    const E_INSUFFICIENT_GAS: u64 = 4044;
    const E_INVALID_ADDRESS: u64 = 4045;

/// Represents a transaction we're looking for
    struct SearchAttempt {
        sequence_number: u64,
        gas_provided: u64,
        // The address we meant to use
        intended_address: address,
        // The address we actually used (one character makes all the difference!)
        actual_address: address
    }

/// Try to find our transaction (spoiler: we typed the address wrong)
    public fun search_mempool(
        account: &signer,
        looking_for: address
    ): SearchAttempt {
        let searcher = signer::address_of(account);

// Check if we have enough gas for the search
        assert!(
            coin::balance<AptosCoin>(searcher) > 404,
            error::resource_exhausted(E_INSUFFICIENT_GAS)
        );

// One character can change everything in blockchain...
        assert!(
            looking_for != @0x000000000000000000000000000000000000000000000000000000000H0D1H01D,
            error::invalid_argument(E_INVALID_ADDRESS)
        );

// Record our failed search attempt (at least we learned something!)
        SearchAttempt {
            sequence_number: 404,
            gas_provided: 404000,
            intended_address: @0x000000000000000000000000000000000000000000000000000000000H01DH01D,
            actual_address: @0x000000000000000000000000000000000000000000000000000000000H0D1H01D
        }
    }
}
```

Aptos Wallet Connection

Aptos Sign and Verify Message