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
Coinobject that you obtained from the Testnet faucet. - Forge: The
Forgecreated when you published this package. Theinitfunction was executed during the publishing process, creating theForgeand assigning it to you (the sender). - UpgradeCap: An
UpgradeCapassociated 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.