A JavaScript SDK for building applications on the Juicebox protocol.
Juice SDK is split across the following npm packages:
juice-sdk-core
: Core utilities and helpers for building client and server-side applications.juice-sdk-react
: Wagmi hooks for Juicebox. Useful data contexts and helpers for building React applications.
Choose the package that best serves your needs.
The Juicebox contracts use fixed-point representations of data extensively. To make this data easier to work with, Juice SDK uses fpnum
for common Juicebox datatypes. These include Reserved Percent, Redemption Rate, Weight, Decay Percent and so on. See utils/data.ts
for a full reference to all available data types.
Juice SDK is based on Yarn workspaces. Each package in the packages/
directory is published seperately.
Note:
juice-sdk-react
depends onjuice-sdk-core
.
-
Populate the
.env
file based on the.env.example
. -
Install dependencies for both packages.
# in the root directory yarn install
-
Change directory into the package you're working on.
-
Consult the package's README for specific setup steps.
Both packages use Wagmi CLI to generate foundational code. Further utilities and helpers are included in each package.
The build process for each package is roughly as follows:
- Compile a list of contract addresses to use for codegen (see Add or update contract addresses).
- Generate viem/wagmi code using Wagmi CLI and the list of contract addresses from Step 1. Each package has a
wagmi.config.ts
file that defines Wagmi CLI behavior. - Compile and build the package for publishing.
To build each package, run yarn build
from the root directory.
Out-of-the-box Wagmi CLI is inadequate for our needs. We apply a patch to the package (using patch-package) that changes the following:
Patch | Why |
---|---|
Accept optional address arg in contract read/write functions and hooks |
Not all Juicebox projects use the same contract addresses. Juicebox contracts store references to other Juicebox contracts, and it's common to need to call a function on a specific contract address instead of the 'default' address given in the Forge deployment manifest. For example, two projects might use different payment terminal contracts. This patch lets developers pass a 'custom' address to read/write functions. |
Add Optimism Sepolia as a possible codegen target | Juicebox contracts are deployed on Optimism Sepolia (chain ID 11155420 ). This patch means Wagmi CLI will generate Optimism Sepolia-compatible code. |
The scripts/generateAddresses.ts
script produces an addresses.json
which contains the contract addresses Wagmi CLI will use for codegen.
To add new contract addresses, modify the generateAddresses
script to fetch and parse the desired Forge deployment manifest, and include the result in the script output.
To update existing contract addresses, just run the script; it will pull the latest contract addresses from GitHub.
To add support for a new chain, add its chain ID to juice.config.ts
and run yarn build
.
In local development, linking juice-sdk to another local project or app requires some extra setup.
Both juice-sdk and the local project need to depend on the same wagmi
on the filesystem.
The following describes how to link a local juice-sdk to another local project:
- Run
yarn link
in bothpackages/juice-sdk-react
andpackages/juice-sdk-core
- In
packages/juice-sdk-react
, runyarn link "juice-sdk-core"
. - In 2 separate processes, run
yarn dev
in bothpackages/juice-sdk-react
andpackages/juice-sdk-core
.
In your local project:
-
Clear any build files
rm -Rf .next
-
Manually remove the project's
wagmi
dependencyrm -Rf node_modules/wagmi
-
Symlink juice-sdk's
wagmi
dependency to the project's node_modulesln -s /absolute/path/to/juice-sdk/node_modules/wagmi node_modules
-
Run or build the project.