Skip to main content

Create a Move Package

Once you have installed IOTA, you are ready to create your first IOTA Move package. In IOTA, packages are the way to organize the modules that make up your smart contract program. When you publish a package to any IOTA network, it will be assigned an address you can use to interact with the package by issuing transactions.

Use the following command to create a standard package:

iota move new first_package

The command will create and populate the first_package directory with a skeleton for an IOTA Move project, consisting of the following files and directories:

Move.toml​

The Move.toml file is the package's manifest. It describes the package and its dependencies.

Comments in .toml files

In .toml files, use the hash mark (#) to denote a comment.

[package]
name = "first_package"
edition = "2024.beta" # edition = "legacy" to use legacy (pre-2024) Move
# license = ""           # e.g., "MIT", "GPL", "Apache 2.0"
# authors = ["..."]      # e.g., ["Joe Smith ([email protected])", "John Snow ([email protected])"]

[dependencies]
Iota = { git = "https://github.com/iotaledger/iota.git", subdir = "crates/iota-framework/packages/iota-framework", rev = "framework/testnet" }

# For remote import, use the `{ git = "...", subdir = "...", rev = "..." }`.
# Revision can be a branch, a tag, and a commit hash.
# MyRemotePackage = { git = "https://some.remote/host.git", subdir = "remote/path", rev = "main" }

# For local dependencies use `local = path`. Path is relative to the package root
# Local = { local = "../path/to" }

# To resolve a version conflict and force a specific version for dependency
# override use `override = true`
# Override = { local = "../conflicting/version", override = true }

[addresses]
first_package = "0x0"

# Named addresses will be accessible in Move as `@name`. They're also exported:
# for example, `std = "0x1"` is exported by the Standard Library.
# alice = "0xA11CE"

[dev-dependencies]
# The dev-dependencies section allows overriding dependencies for `--test` and
# `--dev` modes. You can introduce test-only dependencies here.
# Local = { local = "../path/to/dev-build" }

[dev-addresses]
# The dev-addresses section allows overwriting named addresses for the `--test`
# and `--dev` modes.
# alice = "0xB0B"
Using a local version of IOTA

For local testnet development and testing it is recommended to use the local dependency of the Iota framework for faster and more reliable builds. See the commented line in the example above as an example pointing towards your local checkout of the iota repository.

Package​

The [package] section describes the package. By default, the iota move new command populates only the name value of the metadata.

  • name: The package name when it is imported.
  • version: The package version. It can be used in release management.
  • edition: The edition of the Move language; currently, the only valid value is 2024.

Dependencies​

The [dependencies] section specifies the dependencies of the project. The dependency specification can be a git repository URL or a path to the local directory.

# For remote import, use the `{ git = "...", subdir = "...", rev = "..." }`.
# Revision can be a branch, a tag, and a commit hash.
# MyRemotePackage = { git = "https://some.remote/host.git", subdir = "remote/path", rev = "main" }

# For local dependencies use `local = path`. Path is relative to the package root
# Local = { local = "../path/to" }

Packages also import addresses from other packages. For example, the Iota dependency adds the std and iota addresses to the project. These addresses can be used in the code as aliases for the addresses.

Resolving Version Conflicts with override​

If you have two dependencies that use different versions of the same package, you can override the dependency in the [dependencies] section. To do so, add the override field to the dependency. The version specified in the [dependencies] section will be used instead of the one specified in the dependency itself.

# To resolve a version conflict and force a specific version for dependency
# override use `override = true`
# Override = { local = "../conflicting/version", override = true }

Dev-dependencies​

You can also add a [dev-dependencies] section to the manifest to override dependencies in the dev and test modes. For example, if you want to use a different version of the IOTA package in dev mode, you can add a custom dependency specification to the [dev-dependencies] section.

Addresses​

The [addresses] section is used to add aliases for the addresses you use in your package. You can add any address in this section, and then use its alias in the code instead of the actual address. For example, if you add alice = "0xA11CE" to this section, you can use alice as 0xA11CE in the code.

If you created your package with the iota client new command, this section includes a 0x0 address for your package. You do not need to update this as package addresses are automatically managed.

Dev-addresses​

Much like the [dev-dependencies] section, you can also define [dev-addresses] to override the addresses you defined in the [addresses] section for test and dev modes.

Override Only

You cannot introduce new aliases in this section, only override the ones you defined in [addresses].

TOML Styles​

The TOML format supports two styles for tables: inline and multiline. The examples above use the inline style, but it is also possible to use the multiline style. You wouldn't want to use it for the [package] section, but it can be useful for the dependencies.

[dependencies]
iota = { override = true, git = "", subdir = "crates/iota-framework/packages/iota-framework", rev = "framework/testnet" }
MyPackage = { local = "../my-package" }