Aptos Fundable Token storage

The project aims to show Aptos features and highlight important security points

• Aptos Fundable Token storage
  • Aptos CLI
    • Instalation
    • Account commands
    • Move commands
  • Common used options and errors
    • Options
    • Errors
  • Architecture
    • Repo structure
    • Move.toml
    • Module structure
  • Objective
    • Abstract
    • Solution
    • Hack example
  • Getting started
    • Setup
    • Develop
    • Deploy & Interact
  • Functional requirements
    • Deposit
    • Withdraw
    • Balance

Aptos CLI

Aptos CLI is the primary tool needed for development on the Aptos blockchain

It manages accounts, compiles and publishes blockchain modules, resolves transactions, etc.

Instalation

Download the binary file from github release and put it to any directory defined in $PATH

Use aptos config set-global-config --config-type VALUE to choose where profiles info will be stored:

• Workspace - in a local directory of each project
• Global - in the HOME dir

Account commands

• aptos init - create a new on-chain account profile

  Common used option is PROFILE

• aptos account fund-with-faucet --account PROFILE - fund specified account from a faucet

  Common known error is 411_LENGTH_REQUIRED

Move commands

• aptos move compile - compile the module depending on Move.toml config

  Common used option is NAMED_ADDRESSES

• aptos move publish - publish the module to blockchain

  Common used options are NAMED_ADDRESSES and PROFILE

  Common known error is RESOURCE_NOT_FOUND

• aptos move run - run entry function of the specified module

  Common used options are FUNCTION_ID, TYPE_ARGS, ARGS and PROFILE

  Common known errors are RESOURCE_NOT_FOUND and MAX_GAS_UNITS_BELOW_MIN_TRANSACTION_GAS_UNITS

• aptos move test - run tests for the module

  Common used option is NAMED_ADDRESSES

Common used options and errors

Options

• Option<PROFILE> - is needed for defining the profile which is used for a context of the command

  --profile NAME

• Option<NAMED_ADDRESSES> - is needed for defining addresses that are described in Move.toml as _ (for example, address where a module will be published)

  --named-addresses NAME=ADDRESS

• Option<FUNCTION_ID> - is needed for defining which exactly FUNCTION in which MODULE at which ADDRESS should be called

  --function-id 'ADDRESS::MODULE::FUNCTION'

• Option<TYPE_ARGS> - is needed for defining generic RESOURCE type located in specified MODULE at the ADDRESS, it may be used by the function if it process different data types depending on resource (for example, functions processing different coin types)

  --type-args 'ADDRESS::MODULE::RESOURCE'

• Option<FUNCTION_ID> - is needed for defining function parameters of TYPE containing VALUE, look help command for a list of all supported types

  --args 'TYPE:VALUE'

Errors

• Error<RESOURCE_NOT_FOUND> - it may appear in case if not enough APT is presented on the account: use a faucet to get more APT Coin

  "Error": "API error: API error Error(ResourceNotFound): Resource not found by Address(ADDRESS), Struct tag(TAG) and Ledger version(VERSION)"

• Error<MAX_GAS_UNITS_BELOW_MIN_TRANSACTION_GAS_UNITS> - it may appear in case if the amount of APT presented on the account is enough for the transaction but is lower than minimum Gas units attached to the transaction: use a faucet to get more APT Coin

  "Error": "Simulation failed with status: Transaction Executed and Committed with Error MAX_GAS_UNITS_BELOW_MIN_TRANSACTION_GAS_UNITS"

• Error<411_LENGTH_REQUIRED> - it may happen if you use an outdated Aptos CLI version, it was fixed on v0.3.7

  "Error": "API error: Faucet issue: 411 Length Required"

• Error<502_BAD_GATEWAY> - it happens sometimes, try again

  "Error": "API error: 502 Bad Gateway"

Architecture

Repo structure

build/ - dir contains module artifacts

sources/ - dir contains move modules

Move.toml - configuration file

Move.toml

[package] section contains

• name identifier - is used when adding the repo as a dependency of another project
• version - simple semver identifier
• upgrade_policy - may be
  • immutable - no code updates allowed
  • compatible (is default) - new resources and functions may be added but old ones should be kept

[addresses] section contains named addresses that may be used in code

• Common used aptos_std = "0x1" or just std = "0x1"
• Named address that should be provided as parameter during compilation NAME = "_"

[dependencies] section may contain local and global deps

• Common used devnet version of aptos-framework

  AptosFramework = { git = "https://github.com/aptos-labs/aptos-core.git", subdir = "aptos-move/framework/aptos-framework/", rev = "devnet" }

• Or just import a local package (may be useful in case of huge project with a lot of modules interacting each other)

  LOCAL_PACK = { local = "LOCAL_PATH" }

Module structure

Module definition is module ADDRESS::MODULE_NAME { ... }

In module there are:

• Imports:

  Imports are defined by the use ADDRESS::MODULE pattern and the imported modules/functions/structs may be used through the code

• Structs and Resources:

  • Structs are defined by keyword struct and may have typed fields

    Structs may be copyable and droppable like simple variables

    Struct may be generated based on generic type struct NAME<phantom GENERIC>{ ... }

  • Resources are undroppable and uncopyable structs

    Resources should be moved to storage or destroyed according to module policy before the transaction ends

    It is considered storing resources on user accounts (not in module storage)

• Friends:

  Friends are modules whitelisted to run public(friend) functions

  friend ADDRESS::MODULE

• Functions

  Functions could be

  • entry - callable by user outside from blockchain
  • public - callable by any other modules
  • public(friend) - callable by friend modules
  • no modifier - are internal only accessible in the module

  Functions could have generic type argument

  fun FUNCTION<GENERIC>(ARGS: TYPES): RETURN_TYPE { CODE_DEPENDS_ON<GENERIC> }

Structs, friends and functions may be marked by #[test_only]

This means the code is applied only for tests and is not accessible on-chain

Objective

Abstract

According to the current implementation of the aptos_std::coin it is possible for anyone who has access to the signer object to withdraw any coins stored in the account. In EVM systems, it is called authorization through tx.origin and is considered to be a critical issue as any contract (module) which user calls may be confused with the user.

However, it is the expected behavior in the Aptos network, and when a user starts a transaction, the called module gets the signer object which is the only thing that could be checked for auth.

In such a way, it is important to check contracts (or contract audits at least) before calling them. It needs to be mentioned that contracts may be updated, so the current version should be checked. Generally, a Front-Running attack may be used: contract owner sees a rich user calls the contract and adds harmful code making gas cost extremely higher.

Moreover, all the module dependencies should be checked as the signer object is transmitted to most of the dependencies.

In EVM systems, upgrades are also vulnerable but only attached (allowed) deposit may be stolen, whether all funds may be withdrawn in the Aptos network.

Solution

Storing funds wrapped by a module like this one is safe because only the owner itself can withdraw funds from there. The withdraw function of the module is marked public(friends) entry, and there are no friends specified in the module, so only the owner is able to call the function outside of the network. The contract upgrade policy is defined as immutable in the Move.toml config, so it is not possible for the contract maintainer to change the contract code and steal any funds.

Hack example

• Remove upgrade_policy = "immutable" line from Move.toml file and deploy the module.
• Currently it is be possible to udgrade the module, so uncomment lines in the sources/coin_storage.move file located between //==> hack and //==< hack.
• Update module.
• Now, all the user coins on the deposit function call will be transferred to your account!

Getting started

Setup

Clone the repo from GitHub

git clone git@github.com:SteMak/aptos_coin_storage.git

Create accounts and fund it

aptos init
aptos init --profile coin_storage

aptos account fund-with-faucet --account default
aptos account fund-with-faucet --account coin_storage

Develop

Update code in coin_storage.move and tests in coin_storage_test.move files

Compile the module

aptos move compile --named-addresses coin_storage=coin_storage

Check that tests are ok

aptos move test --named-addresses coin_storage=coin_storage

Deploy & Interact

Deploy the module on-chain

aptos move publish --named-addresses coin_storage=coin_storage

Try do some deposits and withdrawals

aptos move run \
  --function-id 'default::coin_storage::deposit' \
  --type-args '0x1::aptos_coin::AptosCoin' \
  --args 'u64:100'

aptos move run \
  --function-id 'default::coin_storage::withdraw' \
  --type-args '0x1::aptos_coin::AptosCoin' \
  --args 'u64:77'

Check your account resources in explorer

Deploy MoonCoin according the tutorial and check interactions

aptos move run \
  --function-id 'default::coin_storage::deposit' \
  --type-args 'moon_coin_address::moon_coin::MoonCoin' \
  --args 'u64:30'

Functional requirements

Module CoinStorage should be have

• immutable upgrade policy
• deployable on any address

It should be implemented a mechanism of depositing/withdrawing of any standard coin

It should be possible for anyone who manages user's signer object to deposit coins

It should not be possible for anyone except of the user directly to withdraw user funds

Deposit

Accepts user deposit, creates wrapper resource moving it to caller account

Signature:

• <CoinType>: resource - resource of coin which will be deposited
• account: &signer - link to caller signer object
• amount: u64 - amount of coins to deposit

Fail conditions:

• NotFound(ECOIN_STORE_NOT_PUBLISHED) - user is not registred in the coin module
• PermissionDenied(EFROZEN) - user coin account is frozen
• InvalidArgument(EINSUFFICIENT_BALANCE) - user don't have enough funds

Return: void

Withdraw

Transfer user deposit back, is callable only by user itself

Signature:

• <CoinType>: resource - resource of coin which will be withdrawn
• account: &signer - link to caller signer object
• amount: u64 - amount of coins to withdraw

Fail conditions:

• NotFound(E_USER_IS_NOT_FOUND) - user is not registred in the storage
• InvalidArgument(E_USER_INSUFFICIENT_BALANCE) - user deposit is too small
• PermissionDenied(EFROZEN) - user coin account is frozen

Return: void

Balance

Return current user balance

Signature:

• <CoinType>: resource - resource of coin which will be checked
• account_addr: address - address of user checked

Fail conditions: void

Return: u64 - stored balance