Ownables SDK

Ownables are CosmWasm smart contracts that define ownership. In addition to running on a Cosmos blockchain, Ownables can run directly in a wallet and integrate with Base.

The SDK contains examples and tools for developing Ownables.

Quickstart

yarn install
yarn rustup
yarn ownables:build
yarn start

Once that is done, navigate to http://localhost:3000/ and you should see an empty wallet that is ready to import Ownable packages.

In the wallet, click the ＋ icon at the bottom right. This will open an action menu in which we can choose to import a new Ownable from a file and select a zipped package. The packages are located in the ownables folder.

Please read the documentation to learn more about Ownables.

SDK Wallet

The wallet is a React application that can be used to test Ownables.

Available Scripts

In the project directory, you can run:

yarn start

Runs the app in the development mode. Open http://localhost:3000 to view it in the browser. The page will reload if you make edits. You will also see any lint errors in the console.

yarn test:e2e

Runs all Cucumber-based end-to-end tests against the shared local E2E stack. Start that stack in a separate terminal first:

yarn test:e2e:setup

The setup command starts Anvil, deploys and configures the test contracts, starts a PostgreSQL-backed Hub, and starts Vite. All scenarios use this same environment. Scenarios tagged @broken are skipped by the Cucumber config.

yarn verify:main-list-discovery

Runs the accepted Vitest/jsdom verifier for Hub-backed main-list discovery, strict Hub import origin guards, per-account dismiss persistence, and the combined imported-plus-available list behavior, including wallet/account switching while the next discovery fetch is in flight.

yarn build

Builds the app for production to the build folder. It correctly bundles React in production mode and optimizes the build for the best performance.

The build is minified and the filenames include the hashes. Your app is ready to be deployed!

See the section about deployment for more information.

Note: Due to compartibility and version related issues it is preferable to use Node version 20.

Ownables

Prerequisites

Rustup, so that you can set up the wasm32 target:

curl https://sh.rustup.rs -sSf | sh
curl https://rustwasm.github.io/wasm-pack/installer/init.sh -sSf | sh

rustup default stable
cargo version

rustup update stable

rustup target list --installed
rustup target add wasm32-unknown-unknown

Alternatively run yarn rustup.

Build

Build a single package:

yarn ownables:build car

Build all packages:

yarn ownables:build

Examples

Car

A static Ownable, with a widget that shows an MP4 loop of a car.

Potion

An basic stateful Ownable. The potion gets a random color when instantiated. You can drink a portion of the potion, until it's empty.

Robot

An Ownable to showcase Consumables. The robot will change as it consumes an upgrade.

Consumables are Ownables with a consume method. The following Consumables are available for the robot:

Paint

A Consumable with a random color. Consume it to change the color of the robot.

Antenna

Adds an antenna to the robot. Only one antenna can be added.

Speakers

Adds speakers to the robot. Only one set of speakers can be added.

Armor

Adds armor to the robot. Only one shield can be added.

Environment variables

Create a .env file in the project root (or use your existing one) and ensure the following variables are set:

• VITE_E2E
• VITE_E2E_MNEMONIC
• VITE_E2E_ACCOUNT_INDEX
• VITE_E2E_RPC_URL
• VITE_HUB
• VITE_RELAY
• VITE_LOCAL
• VITE_OWNABLE_EXAMPLES_URL
• VITE_BUILDER
• VITE_BUILDER_SERVER_WALLETS_ENDPOINT (optional, default: /api/v1/ServerWalletAddresses)
• VITE_BUILDER_NETWORK_PARAM (optional, default: networkId)
• VITE_WALLETCONNECT_PROJECT_ID

RainbowKit requires a WalletConnect Cloud Project ID to enable WalletConnect and to display the full list of popular wallets in the connect modal (MetaMask, Coinbase, Ledger, etc.).

1. Go to https://cloud.walletconnect.com/ and create a project.
2. Copy the Project ID and set it in your .env:

VITE_WALLETCONNECT_PROJECT_ID=your-project-id-here

Notes:

• This project uses Vite. Environment variables must be prefixed with VITE_ to be available in the browser.
• VITE_HUB is required for active Hub upload, download, delivery-status, available-ownables discovery, and Hub import flows. Hub download URLs are rejected unless their origin matches new URL(VITE_HUB).origin.
• VITE_RELAY and VITE_LOCAL remain legacy-only compatibility knobs and are no longer part of the active Hub receive path.
• On localhost, when VITE_HUB is configured, the SDK looks for available ownables at GET /ownables/available?owner=<caip10-account> and renders them directly in the main list with import and dismiss actions.
• The accepted manual localhost wallet-A-to-wallet-B smoke for this receive path is documented in DEVELOPMENT.md.
• If you change .env while the dev server is running, you may need to restart yarn start to pick up the changes.