Skip to main content

​
Get started in three steps

This quickstart will help you set up and use the Katana Development Starter Kit for building applications on Katana and its testnets, Tatara and Bokuto. You’ll learn how to:
  • Set up your development environment with the Katana toolchain
  • Run a local fork of Katana mainnet for testing without spending real tokens
  • Explore Katana’s “primitives” - composable financial building blocks
Note: Tatara will eventually be deprecated. It is recommended to use Bokuto as the testnet, or to use a local fork of Katana’s mainnet, as will be described in the content below.

​
Before you begin

Before you start building on Katana, make sure you have the required tools and access:
  • Bun: Install for a fast JavaScript runtime and package manager
  • Foundry: Install toolkit for Ethereum application development
  • Git: Version control system
  • MetaMask or compatible wallet: For connecting to networks

​
Step 1: Clone the kit

1

Clone the Katana Starter Kit

Get the official Katana development repository:
git clone https://github.com/katana-network/specialk
cd specialk
The “specialk” repository contains the complete Katana Development Starter Kit with interfaces, examples, and tooling.

​
Step 2: Configure your environment

1

Set up environment variables

Create your environment configuration:
cp .env.example .env
Edit .env to add your RPC endpoints, if desired (optional for local development).
For local fork development, you don’t need to configure any RPC endpoints as you’ll be using a local Anvil fork.
2

Install dependencies

Install all project dependencies:
bun install
Dependencies installed successfully when you see no error messages

​
Step 3: Run local development setup

To develop locally without spending real tokens, you can run a local fork of the testnets or the mainnet. This will make a local copy of the chain in a few seconds, running the real state but also providing you with infinite ETH on any of the open test-addresses provided by Foundry’s Anvil. This is the recommended approach to develop on Katana - it keeps state local and prevents RPC rate limits, while letting you play with the real state of Katana’s live mainnet.
1

Start Anvil fork (Terminal 1)

Run a local fork of Katana mainnet:
bun run start:anvil katana
This command starts a local fork of Katana mainnet using Anvil. Keep this terminal running during development.
Anvil fork running
2

Verify the fork (Terminal 2)

In a new terminal, verify your local fork is working:
bun run verify:anvil
If verification passes, your local Katana fork is ready for development
Anvil fork verified
3

Connect your wallet

Add the local network to MetaMask or your preferred wallet:
Network Configuration
{
  "networkName": "Katana Local Fork",
  "rpcUrl": "http://localhost:8545",
  "chainId": 747474,
  "currencySymbol": "ETH"
}
You can now interact with Katana contracts locally without spending real tokens. You’ll have access to infinite ETH on Foundry’s test addresses.

​
Explore the starter kit

1

Build the example app

Compile the starter kit application:
bun run build:all
This command will:
  • Compile your TypeScript code into dist
  • Copy static assets like HTML, CSS, and images
  • Build the ABIs, the MCP server, and more utilities to bootstrap your environment
For subsequent builds, you can use bun run build to rebuild only the app
2

Serve the application

Make sure your local fork is running (Terminal 1) and serve the compiled web app:
bun run dev
Open your browser to the provided localhost URL to see the Katana starter app running
Demo app running in terminalLocal dapp running
3

Explore the Katana primitives

Browse the comprehensive interfaces for Katana’s financial building blocks:
  • Local Files
  • Contract Directory UI
Browse the contracts directory in your cloned repository to see all available contracts and their descriptions.

​
What’s next?

You now have a complete Katana development environment! Here’s how to continue building with DeFi Katana primitives.

Explore example code

Study how the starter app interacts with Katana’s financial primitives

Browse Katana primitives

Discover available contracts and composable financial building blocks

Awesome Katana

Find tutorials, examples, and inspiration for building on Katana

Technical reference

Deep dive into chain configuration and advanced development

​
Troubleshooting

Common solutions:
  • Check that port 8545 isn’t already in use by another application
  • Ensure Foundry is properly installed and anvil is in your PATH
  • Verify your RPC URL in .env is correct
  • If the script isn’t executable, run chmod +x scripts/start_anvil.sh
Check these items:
  • Ensure Bun is properly installed: bun --version
  • Try clearing Bun cache: bun install --force
  • Check internet connection and repository access
  • Verify you’re in the correct specialk directory
Verification steps:
  • Check the RPC URL format in your .env file
  • Verify network configuration matches Chain ID
  • Try the local fork first to test your setup
Debug checklist:
  • Run bun run build:all for first-time builds
  • Check for TypeScript compilation errors
  • Ensure all dependencies installed successfully
  • Verify static assets are in the correct directories

​
Need help?

Report issues

Found a problem with the starter kit? Report it on GitHub
 Additional Resources: Happy building on Katana! 🚀
⌘I