Publish a Package
After you have successfully created and tested your package, the next step is to publish it so you can start using its functions on the IOTA network. When you publish a package, it becomes a permanent and immutable public object on the IOTA network.
Publishing Your Package
To publish your package, use the IOTA client's publish
command. Execute this command from your package's root directory, and include the --gas-budget
parameter to set the maximum gas you're willing to spend on this transaction. If the transaction requires more gas than your budget, it will fail.
iota client publish
Once the transaction succeeds, you will receive a response similar to the following, detailing the transaction data, effects, and any changes to objects and balances:
╭─────────────────────────────────────────────────────────────────────╮
│ Object Changes │
├─────────────────────────────────────────────────────────────────────┤
│ Created Objects: │
│ ... │
| |
│ Mutated Objects: │
│ ... │
| |
│ Published Objects: │
│ ┌── │
│ │ PackageID: <PACKAGE-ID> │
│ │ Version: 1 │
│ │ Digest: <DIGEST-HASH> │
│ │ Modules: first_package │
│ └── │
╰─────────────────────────────────────────────────────────────────────╯
The Object Changes section includes information about the package you just published, under Published Objects. Your actual PackageID
will appear as an address, like 0x123...ABC
.
Understanding Your Address's Object List
If this is your first time publishing a package, your active address should now hold three objects:
- Coin: A
Coin
object that you obtained from the Testnet faucet. - Forge: The
Forge
created when you published this package. Theinit
function was executed during the publishing process, creating theForge
and assigning it to you (the sender). - UpgradeCap: An
UpgradeCap
associated with the package. This object is used if you need to upgrade your package or destroy it to make the package immutable.
You can retrieve the complete list of objects associated with your address using the iota client objects
command:
iota client objects
╭───────────────────────────────────────────────────────────────────────────────────────╮
│ ╭────────────┬──────────────────────────────────────────────────────────────────────╮ │
│ │ objectId │ <OBJECT-ID> │ │
│ │ version │ 3 │ │
│ │ digest │ <DIGEST-HASH> │ │
│ │ objectType │ <PACKAGE-ID>::first_package::Forge │ │
│ ╰────────────┴──────────────────────────────────────────────────────────────────────╯ │
│ ╭────────────┬──────────────────────────────────────────────────────────────────────╮ │
│ │ objectId │ <OBJECT-ID> │ │
│ │ version │ 3 │ │
│ │ digest │ <DIGEST-HASH> │ │
│ │ objectType │ 0x0000..0002::coin::Coin │ │
│ ╰────────────┴──────────────────────────────────────────────────────────────────────╯ │
│ ╭────────────┬─────────────────────────────────────────────── ───────────────────────╮ │
│ │ objectId │ <OBJECT-ID> │ │
│ │ version │ 3 │ │
│ │ digest │ <DIGEST-HASH> │ │
│ │ objectType │ 0x0000..0002::package::UpgradeCap │ │
│ ╰────────────┴──────────────────────────────────────────────────────────────────────╯ │
╰───────────────────────────────────────────────────────────────────────────────────────╯
Accessing Your Package
After successfully publishing the package, you can use the iota client call
command to execute individual functions or create sophisticated programmable transaction blocks that group multiple commands into a single, cost-effective transaction with the iota client ptb
command.
Programmable Transaction Example
The following example demonstrates how to call the new_sword
function from your package to create a new Sword
and then transfer it to a specified address.
$ iota client ptb \
--assign forge @<FORGE-ID> \
--assign to_address @<TO-ADDRESS> \
--move-call <PACKAGE-ID>::first_package::new_sword forge 3 3 \
--assign sword \
--transfer-objects "[sword]" to_address \
--gas-budget 100000000
You can pass literal addresses and objects IDs by prefixing them with '@'. This is needed to distinguish a hexadecimal value from an address in some situations.
For addresses that are in your local wallet, you can use their alias instead (passing them without '@', for example, --transfer-objects my_alias).
Note how the command uses --assign
to define variables for <FORGE-ID>
, <TO-ADDRESS>
, and <PACKAGE-ID>
. This approach helps maintain clarity in your PTBs. Ensure you replace <FORGE-ID>
, <TO-ADDRESS>
, and <PACKAGE-ID>
with the actual objectId
of the Forge
object, the recipient's address (your address, for instance), and the packageID
, respectively.
After executing the transaction, verify the status of the Sword
object using the iota client objects
command again. If you set your address as the <TO-ADDRESS>
, you should now see a total of four objects:
╭───────────────────────────────────────────────────────────────────────────────────────╮
│ ╭────────────┬──────────────────────────────────────────────────────────────────────╮ │
│ │ objectId │ <OBJECT-ID> │ │
│ │ version │ 4 │ │
│ │ digest │ <DIGEST-HASH> │ │
│ │ objectType │ <PACKAGE-ID>::first_package::Forge │ │
│ ╰────────────┴──────────────────────────────────────────────────────────────────────╯ │
│ ╭────────────┬──────────────────────────────────────────────────────────────────────╮ │
│ │ objectId │ <OBJECT-ID> │ │
│ │ version │ 4 │ │
│ │ digest │ <DIGEST-HASH> │ │
│ │ objectType │ 0x0000..0002::coin::Coin │ │
│ ╰────────────┴─────────────────── ───────────────────────────────────────────────────╯ │
│ ╭────────────┬──────────────────────────────────────────────────────────────────────╮ │
│ │ objectId │ <OBJECT-ID> │ │
│ │ version │ 4 │ │
│ │ digest │ <DIGEST-HASH> │ │
│ │ objectType │ <PACKAGE-ID>::first_package::Sword │ │
│ ╰────────────┴──────────────────────────────────────────────────────────────────────╯ │
│ ╭────────────┬──────────────────────────────────────────────────────────────────────╮ │
│ │ objectId │ <OBJECT-ID> │ │
│ │ version │ 3 │ │
│ │ digest │ <DIGEST-HASH> │ │
│ │ objectType │ 0x0000..0002::package::UpgradeCap │ │
│ ╰────────────┴──────────────────────────────────────────────────────────────────────╯ │
╰───────────────────────────────────────────────────────────────────────────────────────╯
Congratulations! You have successfully published a package to the IOTA network and modified the blockchain state using a programmable transaction block.