Packages, Move.toml & Named Addresses

5.1 Package layout

A package is the unit of publishing. All modules in a package are published together at one address.

my_pkg/
├── Move.toml          # manifest
├── Move.lock          # resolved dependencies (generated)
├── sources/           # modules (.move)
│   └── counter.move
├── tests/             # test-only modules (optional)
│   └── counter_tests.move
├── scripts/           # Aptos/Diem scripts (optional)
└── build/             # compiler output (generated)

5.2 Sui Move.toml

On Sui, the package address is assigned when you publish (it is derived from the transaction), so you leave it as 0x0. After publishing, the CLI records the published address (in Move.lock or, with the newer package-management system, in a published-addresses file per environment) so dependents can link against it.

[package]
name = "my_pkg"
edition = "2024"            # Move 2024 edition (older code: "2024.beta" or legacy)

[dependencies]
# Recent Sui CLIs add Sui, MoveStdlib, Bridge, and SuiSystem implicitly.
# Explicit form (older projects):
# Sui = { git = "https://github.com/MystenLabs/sui.git", subdir = "crates/sui-framework/packages/sui-framework", rev = "framework/testnet" }

[addresses]
my_pkg = "0x0"              # 0x0 = "not yet published"; replaced at publish time

5.3 Aptos Move.toml

On Aptos, a package is published under an account address (or an object address via aptos move create-object-and-publish-package), so the address is known in advance.

[package]
name = "my_pkg"
version = "1.0.0"
upgrade_policy = "compatible"   # or "immutable"

[addresses]
my_addr = "_"                   # placeholder; supplied with --named-addresses

[dev-addresses]
my_addr = "0xCAFE"              # used for tests

[dependencies.AptosFramework]
git = "https://github.com/aptos-labs/aptos-framework.git"
rev = "mainnet"
subdir = "aptos-framework"

5.4 Named addresses

A named address is a compile-time alias for a numeric address:

Well-known addresses:

Move standard library (both chains) Aptos standard extensions (tables, math) Aptos Digital Asset standard Sui system (staking, validators) Sui Clock object Sui Random object Shared randomness beacon

module my_addr::counter { /* ... */ }     // module declared at named address my_addr
const ADMIN: address = @my_addr;          // @ turns a named address into a value

5.5 Dependencies

Git dependencies (git, rev, subdir), local dependencies (local = "../other_pkg"), and on Sui the Move Registry (MVR) for resolving packages by name.

Dev dependencies ([dev-dependencies]) are used only for tests.

Pin dependency revisions for reproducible builds; framework versions must match the network you deploy to.