program JS

JS library for interacting with Soroban smart contract program via Soroban RPC.

This library was automatically generated by Soroban CLI using a command similar to:

soroban contract bindings ts \
  --rpc-url INSERT_RPC_URL_HERE \
  --network-passphrase "INSERT_NETWORK_PASSPHRASE_HERE" \
  --contract-id INSERT_CONTRACT_ID_HERE \
  --output-dir ./path/to/program

The network passphrase is exported from index.ts in the networks constant. Unlike singleton contracts (e.g. registry, record), the program package does not carry a deployed contract ID because every programme is a separate instantiated contract rather than a singleton. Consumers must provide the specific contract ID of the programme they wish to interact with at runtime.

Versions of this package precisely match the release tag of the Milepost smart contracts. Stale bindings will fail at runtime if the on-chain contract interface changes, so always ensure the npm package version matches the deployed contract version you are interacting with.

To publish or not to publish

This library is suitable for publishing to NPM. You can publish it to NPM using the npm publish command.

But you don't need to publish this library to NPM to use it. You can add it to your project's package.json using a file path:

"dependencies": {
  "program": "./path/to/this/folder"
}

However, we've actually encountered frustration using local libraries with NPM in this way. Though it seems a bit messy, we suggest generating the library directly to your node_modules folder automatically after each install by using a postinstall script. We've had the least trouble with this approach. NPM will automatically remove what it sees as erroneous directories during the install step, and then regenerate them when it gets to your postinstall step, which will keep the library up-to-date with your contract.

"scripts": {
  "postinstall": "soroban contract bindings ts --rpc-url INSERT_RPC_URL_HERE --network-passphrase \"INSERT_NETWORK_PASSPHRASE_HERE\" --id INSERT_CONTRACT_ID_HERE --name program"
}

Obviously you need to adjust the above command based on the actual command you used to generate the library.

Use it

Now that you have your library up-to-date and added to your project, you can import it in a file and see inline documentation for all of its exported methods:

import { Contract, networks } from "program"

const contract = new Contract({
  ...networks.futurenet, // for example; check which networks this library exports
  rpcUrl: '...', // use your own, or find one for testing at https://soroban.stellar.org/docs/reference/rpc#public-rpc-providers
})

contract.|

As long as your editor is configured to show JavaScript/TypeScript documentation, you can pause your typing at that | to get a list of all exports and inline-documentation for each. It exports a separate async function for each method in the smart contract, with documentation for each generated from the comments the contract's author included in the original source code.