Generate Bindings - Stellar Developer Docs

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!

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 gets the bindings compiled on a clean pnpm 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 bindingsYou 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.

Don’t lean on prepare any harder than that, because pnpm only runs lifecycle scripts when it has installing to do. Against an already up-to-date workspace it prints “Already up to date” and skips them entirely, so a dist/ that was never built (or that you cleaned) stays missing. Locally that’s a puzzling import error. On a deploy it’s worse: a warm build cache means the install has nothing to do, prepare never fires, and the build fails to resolve ye_olde_guestbook on a commit that worked perfectly well yesterday.The fix is to compile the workspace packages explicitly, as a step the other scripts depend on rather than a side effect you hope for:

package.json

{
  "scripts": {
    "bindings": "pnpm --filter \"./packages/*\" run build",
    "dev": "pnpm run bindings && vite dev",
    "build": "pnpm run bindings && vite build",
    "check": "pnpm run bindings && svelte-kit sync && svelte-check --tsconfig ./tsconfig.json"
  }
}

Now pnpm dev and pnpm build always have bindings to import, whatever pnpm decided to do about the install.

Import the bindings client into the SvelteKit project

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.js 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 "$app/env/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 src/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

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.

​The manual method

​Install the compiled contract

​Deploy a contract instance

​Generate bindings for the deployed contract

​Import the bindings package as a project dependency

​Import the bindings client into the SvelteKit project

​The automated way

The manual method

Install the compiled contract

Deploy a contract instance

Generate bindings for the deployed contract

Import the bindings package as a project dependency

Import the bindings client into the SvelteKit project

The automated way