Skip to main content

Generate Bindings

Let's turn our attention to how we'll interact with the deployed smart contract. This is where the TypeScript bindings come in! But, I hear you ask: What are TypeScript bindings?

These bindings are a feature of the Stellar CLI that will generate and produce a fully typed NPM package ready for integration into your frontend. This means you can import and invoke a smart contract as if it were any other nodejs package! You get typed functions for each of your contract's functions, and those will result in a built, simulated, signable, and submittable assembled transaction!

tip

This can be done with ANY contract that's live on the network! Or, you can use it on contracts you've only compiled locally, too.

We'll be generating our contract bindings, and keeping them in the same repository as our frontend code. However, you could do this in a lot of different ways:

  • Your frontend can instantiate a contract.Client instance using the fromWasmHash function of the JavaScript SDK. This can generate bindings on-the-fly as your users browse your application.
  • Your deploy process might include a step that builds/deploys/binds a contract package at deploy-time.
  • You could even generate and publish a bindings package all by itself. Then pnpm install <bindings_package_name> can be done in any dapp that you (or somebody else) might need to interact with that contract.

The manual method​

Before you skip ahead! Take a look at this (brief) section. It's really useful to have a full understanding of what steps we're going through in the automated section. This will help you adapt and/or troubleshoot this tutorial for your specific purposes.

Install the compiled contract​

The smart contract code needs to be installed to the network first. This uploads the compiled, binary Wasm file to the blockchain to be instantiated into a contract later on. From inside your project directory:

stellar contract upload \
    --source-account <identity or secret key> \
    --network testnet \
    --wasm ./target/wasm32v1-none/release/ye_olde_guestbook.wasm

Deploy a contract instance​

This will return a hexadecimal hash corresponding to the uploaded Wasm executable (it's just the Sha256 hash of the executable file, fyi). This hash can then be used in the deploy command to create a new contract instance. Our __constructor function takes an admin address, and the title and text of the first guestbook message, so we supply those arguments after the -- separator:

stellar contract deploy \
    --source-account <identity or secret key> \
    --network testnet \
    --wasm-hash <wasm_hash_from_install_step> \
    -- \
    --admin <admin address> \
    --title "Welcome!" \
    --text "Thanks for visiting. Please sign my guestbook!"

Generate bindings for the deployed contract​

Now we can (again) use the Stellar CLI to generate bindings from the contract we've just deployed. You can also generate these bindings from your local Wasm file using the --wasm-hash parameter. The --overwrite parameter is used to tell the CLI that it should output the generated bindings package, even if it finds the directory is not empty (i.e., we're re-binding a contract because we've modified the code and redeployed it).

stellar contract bindings typescript \
    --network testnet \
    --id <contract_address_from_deploy_step> \
    --output-dir ./packages/ye_olde_guestbook \
    --overwrite

The guestbook keeps its bindings packages in a pnpm workspace, so packages/* is already claimed by the workspace glob and our freshly generated package is picked up automatically:

pnpm-workspace.yaml
packages:
  - "packages/*"

That leaves two bits of housekeeping. The CLI writes a standalone package, so it ships its own pnpm-lock.yaml, which you don't want inside a workspace (the root lockfile is the only one that matters). And the generated package.json only defines a build script, so we'll add a prepare script, which lets pnpm compile the bindings on every workspace install. That last one is nicer than it sounds: it means the built dist/ directory never has to be committed.

rm -f packages/ye_olde_guestbook/pnpm-lock.yaml
pnpm --filter ye_olde_guestbook pkg set scripts.prepare=tsc
Customize your bindings

You could take this opportunity to customize your generated bindings before you build them. By default, generated bindings will re-export the entirety of @stellar/stellar-sdk for your frontend application. If this behavior isn't desired, you can remove it. These packages are your own to modify as you see fit.

Import the bindings package as a project dependency​

With our bindings generated, we can add it to our frontend project. Because it's a workspace package, we don't point at a file path. We let pnpm resolve it from the workspace instead, running this from the root of the project:

pnpm add -D ye_olde_guestbook --workspace

That records "ye_olde_guestbook": "workspace:*" in your root package.json, and pnpm links the package out of packages/ rather than copying it. So when you re-generate the bindings after changing your contract, your frontend picks up the new version with no re-install.

This is also the moment the bindings actually get compiled. Adding the dependency runs an install, the install runs the prepare script we just added, and prepare runs tsc. You'll see pnpm report it as it goes.

note

Earlier versions of this tutorial used pnpm add file:./packages/ye_olde_guestbook here. That still resolves, but with a workspace declared the --workspace form is the right idiom, and it's what the guestbook's own package.json records.

Import the bindings client into the SvelteKit project​

info

We're straying just a bit into the Svelte-ish side of things here. The main goal of this step is to get the contract client (which is the "bindings package" we've just generated) into our frontend in a way that makes it usable anywhere we need it. In SvelteKit, we're putting it into src/lib/contracts because that means we can easily access the client by importing from $lib/contracts/ye_olde_guestbook whenever and wherever we need it.

Now, we'll define the contract client in a way we can easily access it through the rest of our app.

src/lib/contracts/ye_olde_guestbook.ts
import { Client, networks } from "ye_olde_guestbook";
import { PUBLIC_STELLAR_RPC_URL } from "$env/static/public";

// `networks.testnet` contains the contract address and network passphrase
// baked in at bindings-generation time.
export default new Client({
  ...networks.testnet,
  rpcUrl: PUBLIC_STELLAR_RPC_URL,
});

The automated way​

That was a lot of steps and a lot of work wasn't it!?

The good news is that our starter template (remember that?) comes with an initialize.js script that will perform all of those actions for you! This script will go through all the following steps for you:

  • Create and fund a keypair in the CLI
  • Compile, install, and deploy all contracts in the /contracts directory
  • Generate bindings from the deployed contracts, and settle each package into the workspace: add the prepare script, gitignore the compiled dist/ directory, and delete the standalone lockfile the CLI writes
  • Create a $lib/contracts/<contract_alias>.ts file for easy import into your frontend code

You can always customize this script to suit your needs. Check out the source code here (which has been documented with comments). Or, you can see the officially maintained script in the soroban-template-astro repository, as well.

Run the initialization script like so:

node initialize.js
info

For a more comprehensive overview of the process of creating, customizing, and using initialization scripts like this, check out the frontend template guide.

We've also added a command to the package.json scripts, so you can run this initialize script simply by running (from your project's root directory):

pnpm run setup

Right, so we've now cloned the starter project, written a guestbook smart contract, and generated an NPM package that will help us interact with that contract on the network. Amazing!

Next up, let's set up the one prerequisite our passkey-powered smart wallets need: an OpenZeppelin Relayer API key.