loam-cli

Build smart contracts authored with Loam SDK, manage smart contract dependencies from a frontend, initialize new loam projects.

Loam CLI comes with three main commands:

• loam init - Generates a Loam frontend that includes an environments.toml file describing the network settings, accounts, and contracts for each environment your team builds against.
• loam build - Two build processes in one:
  • Build smart contracts. Essentially, this is a wrapper around soroban build that can be used to build any Soroban project's contracts. Like soroban build, this will build contracts using suggested settings, meaning that it functions as a shorthand for something like cargo build --target wasm32-unknown-unknown. But on top of that, loam build will also find all Loam dependencies, resolve interdependencies, and build them all in the correct order.
  • Build frontend clients. If the project contains an environments.toml file, loam build will match the environment specified by the LOAM_ENV environment variable (for loam build, the default is production) to a predictable starting state. It will turn the contracts you depend on (contract dependencies) into frontend packages (NPM dependencies), getting your frontend app to the point where it is ready to build or run with its own dev server. This is done in as low-intrusive a way as possible (for example, if contracts are already deployed, are they using the correct Wasm hash? Do they need to have their TTL extended? It will update these things, rather than re-deploy every time.)
• loam dev - Monitors contracts/* and environments.toml for changes and re-runs loam build as needed. It also defaults to LOAM_ENV=development, rather than production.

Getting started with loam init

1. Install loam cli: cargo install loam-cli
2. To create a loam project, run loam init <PROJECT_PATH>. This will create a Loam frontend project at the provided <PROJECT_PATH>.
3. In your project directory run the following commands to get up and running with a loam project with two example contracts:

• cp .env.example .env
• npm install
• npm run dev

loam dev and loam build in Depth

loam dev and loam build essentially work the same, except that one is for testing and another for production.

loam build

loam dev is the contract-dependencies-to-NPM-dependencies toolchain. It turns the contracts you depend on (contract dependencies) into frontend packages (NPM dependencies), getting your app to the point where it is ready to build or run with its own dev server, such as astro dev. (This template uses Astro, but loam-cli itself is agnostic to how you run your JavaScript frontend. It would work equally well with next dev, or with Svelte or Vue or any other JavaScript frontend tool.)

Here's a full list of everything loam build will do:

1. Default to production environment. This environment setting can be changed with either the --env flag or with the LOAM_ENV environment variable.

2. Inspect the environments.toml file and get things to the specified predictable starting state:

   flowchart TD
     A[loam dev] -->|network| B(run-locally?)
     B -->|yes| C[start]
     B -->|no| D[check]
     A -->|accounts| E(mainnet?)
     E -->|yes| F[check]
     E -->|no| G[create & fund]
     A -->|contracts| H(local?)
     H -->|yes| I(workspace = true?)
     I -->|yes| J[build, deploy, init]
     I -->|no| K[spoon]
     H -->|no| L[check]
     J --> M[bind & import]
     K --> M
     L --> M
   

   • connect to the specified network, or run it with soroban network start
   • create and/or fund accounts → on mainnet, will instead check that accounts exist and are funded
   • For specified contracts:
     • For an environment which uses a local network:
       • For contracts which have workspace = true:
         • build & deploy the contracts, saving the IDs so that on subsequent runs it can instead verify contracts are deployed and update them if needed.
         • initialize the contracts: runs any specified init commands (see environments.toml below)
       • [Beyond the scope of initial grant]: For contracts which instead specify an environment, address, and at-ledger-sequence:
         • spoon the specified contract's state, at time of specified ledger sequence, into the current environment's network.
     • For an environment which uses futurenet, testnet, mainnet or some other live network:
       • check that the contracts exist on that network. Note: Loam does not yet have plans to help with deploying the contracts. It only checks that you have successfully done so yourself.
     • For all environments:
       • bind the contracts
         • run soroban contract bindings typescript for each
         • save each generated library to gitignored packages/*, part of the NPM workspace, using the name specified in environments.toml
         • modify networks export for each, to include all networks specified in environments.toml
       • import the contracts for use in the frontend. That is, create gitignored src/contracts/* files for each, which import the Contract class and networks object and export an instantiated version for the current environment's network.

loam dev

loam dev is a wrapper around loam build, but will:

1. Default to development environment
2. Automatically watch contracts/* and environments.toml for changes, and re-run loam build when things change

loam build Suggestions

We suggest that each frontend have separate contract dependencies, deployed on separate networks.

So, you should build one version of your frontend for mainnet and host it at the root domain, say, example.com. Then build a separate version for testnet and host it at a separate domain, maybe staging.example.com.