Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
52 changes: 30 additions & 22 deletions docs/build/apps/guestbook/bindings.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -19,37 +19,37 @@ We'll be generating our contract bindings, and keeping them in the same reposito
- 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
## 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
### 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:

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

#### Deploy a contract instance
### Deploy a contract instance

This will return a hexadecimal hash corresponding to the uploaded Wasm executable. This hash can then be used in the deploy command to create a new 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:

```shell
```sh
stellar contract deploy \
--source-account <identity or secret key> \
--network testnet \
--wasm-hash <wasm_hash_from_install_step>
```

#### Generate bindings for the deployed contract
### 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).

```shell
```sh
stellar contract bindings typescript \
--network testnet \
--id <contract_address_from_deploy_step> \
Expand All @@ -59,68 +59,76 @@ stellar contract bindings typescript \

We'll need to build the bindings package, since (in its initial state) the package is mostly TypeScript types and stubs for the various contract functions.

```shell
```sh
cd packages/ye_olde_guestbook
pnpm install
pnpm run build
cd ../..
```

#### Import the bindings package as a project dependency
:::tip[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. Run this from the root of your project:

```shell
```sh
pnpm add file:./packages/ye_olde_guestbook
```

#### Import the bindings client into the SvelteKit project
### 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 put 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.
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.

```js title="src/lib/contracts/ye_olde_guestbook.ts"
import * as Client from "ye_olde_guestbook"; // import the package we just added as a dependency
import { Client, networks } from "ye_olde_guestbook"; // import from the package we just added as a dependency
import { PUBLIC_STELLAR_RPC_URL } from "$env/static/public"; // import the RPC url from the .env file

// instantiate and export the Client class from the bindings package
export default new Client.Client({
...Client.networks.testnet, // this includes the contract address and network passphrase
export default new Client({
...networks.testnet, // this includes the contract address and network passphrase
rpcUrl: PUBLIC_STELLAR_RPC_URL, // this is required to invoke the contract through RPC calls
});
```

### The automated way
## The automated way

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

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:
The good news is that our starter template (remember [that](./overview.mdx#start-from-the-stellar-template-repository)?) 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
- Install and deploy **all contracts** in the `/contracts` directory
- Generate bindings from the deployed contracts
- 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](https://github.com/ElliotFriend/soroban-template-sveltekit-passkeys/blob/main/initialize.js) (which has been documented with comments). Or, you can see the [officially maintained script](https://github.com/stellar/soroban-template-astro/blob/main/initialize.js) in the [`soroban-template-astro` repository](https://github.com/stellar/soroban-template-astro), as well.
You can always customize this script to suit your needs. Check out the [source code here](https://github.com/ElliotFriend/stellar-template-sveltekit-passkeys/blob/main/initialize.js) (which has been documented with comments). Or, you can see the [officially maintained script](https://github.com/stellar/soroban-template-astro/blob/main/initialize.js) in the [`soroban-template-astro` repository](https://github.com/stellar/soroban-template-astro), as well.

Run the initialization script like so:

```shell
```sh
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](https://developers.stellar.org/docs/build/guides/dapps/soroban-contract-init-template).
For a more comprehensive overview of the process of creating, customizing, and using initialization scripts like this, check out the [frontend template guide](../../guides/dapps/soroban-contract-init-template.mdx).

:::

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):

```shell
```sh
pnpm run setup
```

Expand Down
Loading
Loading