Secure Wallet Management on Kaia Chain: A Developer's Cookbook
Introduction
Who This Cookbook Is For
Welcome to the Kaia Secure Wallet Cookbook. This guide is written for developers, engineers, and teams building on the Kaia blockchain. Whether you are creating your first decentralized application (dApp), deploying automated services, or managing a treasury, this cookbook provides the essential recipes for handling cryptographic keys and wallets with a security-first mindset.
How to Use This Cookbook
This cookbook follows a progressive learning path:
- Part 1 establishes the security fundamentals you need to understand.
- Part 2 provides hands-on recipes from basic to advanced scenarios.
Each recipe builds on concepts from previous sections. New to Web3 security? Start with Chapter 1. Experienced developer? Jump to the recipes that match your use case
Core Philosophy: Security First
In Web3, the phrase not your keys, not your crypto is a fundamental truth. For developers, this extends to every part of the software development lifecycle. A single compromised key can lead to catastrophic losses for users and projects alike. The core philosophy of this guide is Security First. Every recipe and recommendation is designed to help you build robust, secure systems by default, minimizing attack surfaces and protecting assets from day one.
Prerequisites
To get the most out of this cookbook, you should have a basic understanding of blockchain concepts (e.g., public/private keys, transactions, gas fees) and be comfortable working with a command-line interface.
Part 1: Foundational Concepts & Security Principles
This part focuses on the why behind secure wallet management. It establishes the core knowledge needed before writing any code.
Chapter 1: The Principles of Private Key Security
1.1. Understanding Key Pairs: The Heart of Your Account
On Kaia, as with other EVM-compatible chains, your account is not a username and password. It is a cryptographic key pair: a public key and a private key. The public key derives your public address, which is like your bank account number—it's safe to share. The private key is the secret that authorizes all actions from your account, like signing transactions or messages. It is the single most critical piece of information to protect. Anyone who possesses your private key has complete and irreversible control over your account and its assets.
1.2. Secure Key Generation: Best Practices for Kaia
A secure key is a randomly generated one. The security of your account relies on the mathematical impossibility of someone guessing your private key. Always use well-vetted, standard cryptographic libraries to generate keys, such as those embedded within ethers-ext
or the tools discussed in this guide. Never attempt to create your own "clever" or "human-readable" private keys, as this dramatically reduces their randomness and makes them vulnerable to being guessed.
1.3. Secure Key Storage: From Local Keystores to Production Vaults
How you store your private key is as important as how you generate it. Storing a private key in a plaintext file is the digital equivalent of writing your bank password on a sticky note and leaving it on your monitor.
WARNING: Never store private keys in plaintext .env
files. While convenient for development, .env files are frequently committed to version control by mistake, exposing keys publicly and leading to immediate theft of funds.
The standard for secure local storage is an encrypted keystore file (sometimes called a JSON keystore). This file contains your private key, but it is encrypted with a strong password that you choose. To use the key, you must provide the keystore file and the password to decrypt it in memory. For production systems, the best practice is to use dedicated secret managers like AWS KMS or Google Cloud KMS, which ensure keys are never exposed directly to the application code.
1.4. Handling Keys in Memory: Minimizing Exposure During Runtime
Even when loaded from a secure source, a private key must exist in your application's memory to sign a transaction. It's crucial to minimize this exposure. Good application design ensures that the key is held in memory for the shortest possible duration and is cleared immediately after use. The libraries and recipes in this cookbook are designed to follow this principle.
Chapter 2: Navigating the Kaia Wallet Ecosystem
2.1. Kaia Wallet
Kaia Wallet is the native browser extension wallet for the Kaia ecosystem. While it shares many features with MetaMask, it is optimized for Kaia by supporting unique transaction types, fee-delegated transactions, and the account system specific to the network and offers a seamless user experience on the network. For developers, understanding its specific behaviors and APIs is key to building smooth dApp integrations.
2.2. Cold Storage: An Overview of Hardware Wallets
Cold storage refers to keeping private keys on a device that is not connected to the internet. A hardware wallet is a physical device built for this purpose. It signs transactions internally without ever exposing the private key to the connected computer. This makes them the gold standard for securing high-value assets. This guide will focus on the officially supported DCENT and SafePal hardware wallets.
2.3. Multi-Signature Wallets: An Introduction to Kaia Safe
A multi-signature (or "multi-sig") wallet is a smart contract that requires multiple private keys to approve a transaction before it can be executed. For example, a 2-of-3 multi-sig requires approval from two out of three designated owners. This is the standard for managing team funds, treasuries, and critical smart contract administration, as it prevents a single point of failure. Kaia Safe is the primary multi-sig solution on the Kaia network.
Part 2: Practical Recipes for Wallet Management
Now that you understand the foundational security principles from Part 1, it's time to put them into practice. This section provides step-by-step guides for real-world scenarios, starting with individual development setups and progressing to production-grade solutions.
What You'll Build:
- Secure development environments for Foundry and Hardhat
- Multi-signature treasury setups for team collaboration
- dApp integrations with various wallet types
Chapter 3: Setups for Individual Developers & dApps
This chapter provides hands-on guides for setting up and managing wallets during the development process, emphasizing security from the very first line of code.
3.1. Recipe: Your First Kaia Development Wallet
If you are new to Kaia or setting up your Kaia Wallet for the first time, we recommend referring to the Getting Started with Wallets section. It covers essential steps such as installing a wallet, creating and backing up your account securely, adding additional accounts, and funding your wallet.
3.2. Recipe: Securely Managing Accounts in a Foundry Project
With Foundry, you can import encrypted wallets through the cast wallet CLI. While encrypting other values such as RPC URLs is not currently available, combining encrypted keys with environment variables still provides a secure setup.
Step 1: Install and Initialize Foundry
Run the command below in your terminal if you haven’t installed foundry:
curl -L https://foundry.paradigm.xyz | bash
Then, initialize a Foundry project by running the following command:
foundryupforge init foundry-encryptedcd foundry-encrypted
Now you should have a folder with foundry’s default template.
Step 2: Import Your Wallet
You can import a wallet using the cast wallet CLI. Simply replace your-wallet-name with the desired name of your wallet and execute the following command:
cast wallet import your-wallet-name --interactive
After entering your private key, you will be prompted to set a password for encryption. The encrypted key is saved in your local keystore at the default path ~/.foundry/keystore.
The - - interactive flag is used to prevent the private key from being saved in the terminal history
Step 3: Create and Source an Environment File
After encrypting your wallet, you will need to store your RPC endpoint securely. Foundry does not yet offer encryption for values like RPC URLs, so using a .env file is a common and safer choice for this type of secret value.
Create a .env
file in the root directory of your project and add your KAIROS_RPC_URL
:
KAIROS_RPC_URL=https://responsive-green-emerald.kaia-kairos.quiknode.pro
And load it before running your script:
source .env
Step 4: Run Your Script
We completed the wallet import and added the RPC endpoint to our configuration. Now we are ready to run the script and deploy the contract.
The default Foundry template includes a sample script that deploys the Counter contract. You should modify this script to use your own wallet name and RPC endpoint.
When you run your script using either of forge create or forge script,
- the terminal will prompt you to enter your password that was used to encrypt your private key.
- foundry will run your script and deploy your contract once you've entered the password.
Using forge create
forge create --rpc-url $KAIROS_RPC_URL src/Counter.sol:Counter --broadcast --account your-wallet-name
Using forge script
forge script script/Counter.s.sol:CounterScript --rpc-url $KAIROS_RPC_URL --account your-wallet-name --broadcast
Congratulations. You have successfully configured encrypted secrets in Foundry and used them in your deployment scripts.
3.3. Recipe: Securely Managing Accounts in a Hardhat Project
Hardhat 3 (currently in alpha) introduces encrypted secrets via a built-in secrets manager. This feature supports securely storing any sensitive string-based secret like private keys or RPC URLs, with API keys that shouldn’t be committed to version control.
Hardhat 3 is in alpha and may not be fully stable. Use it with care until a stable version is officially released
Step 1: Create a New Hardhat Project
Run the following commands in your terminal to create a new Hardhat project.
mkdir hardhat-encrypted && cd hardhat-encryptednpm init -ynpx hardhat@next --init
Adding @next to the npx command fetches the most recent tagged pre-release of Hardhat, which is 3.0.0-next.20
at the time of writing.
Accept default answers to the prompts. Then run the Hardhat version to verify the project version:
npx hardhat --version
Step 2: Set Encrypted Secrets
To store your RPC URL, run the following command:
npx hardhat keystore set KAIROS_RPC_URL
To store your PRIVATE KEY in an encrypted manner, run the following command:
npx hardhat keystore set PRIVATE_KEY
Step 3: Verify Encrypted Secrets
To verify that your secrets are encrypted, run the following command:
npx hardhat keystore list
You should see your KAIROS_RPC_URL
and PRIVATE_KEY
in the list of encrypted secrets.
To retrieve the secret value again, run the command below. You will be prompted to enter the master key to decrypt it.
npx hardhat keystore get KAIROS_RPC_URL
Once your secrets are set, update your configuration file to securely reference them in your project.
Step 4: Reference Secrets in Config
Open hardhat.config.ts
and update the networks section to reference your encrypted secrets. If your secret names differ, adjust the entries accordingly.
import { configVariable } from "hardhat/config";module.exports = { networks: { kairos: { url: configVariable("KAIROS_RPC_URL"), accounts: [configVariable("PRIVATE_KEY")], }, },};
Now you can use your encrypted secrets in your deployment scripts, without ever exposing them as plaintext.
Step 5: Use Encrypted Secrets in Deployment Scripts
Use the command below to deploy your contract via the Counter.ts
module in ignition/modules. This module deploys Counter.sol
and calls the incBy
function with the value 5.
npx hardhat ignition deploy --network kairos ignition/modules/Counter.ts
Running the command will trigger a prompt from Hardhat asking for the password you created earlier.
This is needed because the kairos network is configured with a keystore. You will only be prompted if your task or script relies on encrypted secrets. Once the password is entered, Hardhat proceeds to deploy your contract and execute the incBy
function with a value of 5.
Congratulations. You've successfully configured encrypted secrets in Hardhat and used them in your deployment scripts.
3.4. Recipe: Connecting a Hardware Wallet (SafePal) to a dApp
In this section, you will learn how to connect your SafePal S1 hardware wallet to a third party decentralized application (DApp) and request a signature for a transaction.
Step 1: Set up Safepal S1 wallet
Before connecting to any DApp, ensure your SafePal S1 device is properly set up. Follow this setup guide if you have not done so already.
If your device is already configured, you can skip this step.
Step 2: Pair the S1 device with the SafePal App
The SafePal S1 is a fully offline hardware wallet, which means it cannot directly connect to the internet or communicate with blockchain networks. To interact with dApps or sign transactions, the device must be paired with the SafePal App.
The SafePal App acts as an intermediary — fetching blockchain data, broadcasting transactions, and relaying dApp interactions – while ensuring your private key remains safely stored on the offline S1 device.
To complete the pairing process, follow this pairing guide.
Step 3: Connect to a dApp.
In this step, you will connect your SafePal S1 hardware wallet to a decentralized application (dApp) using WalletConnect.
For this guide, we will use DragonSwap, Kaia’s leading decentralized exchange (DEX), as our example dApp. The connection will be made through your browser using WalletConnect.
- Launch the DragonSwap dApp by entering the dApp URL in your browser, then click the Connect Wallet button at the right upper corner of the website.
- Among all the connection options, click Wallet Connect. There will be a QR code shown on the screen.
- Scan the QR code with your SafePal App. You can enter the scan process by clicking the scan button at the top right of the App main page.
- After scanning successfully, confirm the connection to the dApp in the App, and click Agree.
- Then you have successfully connected the wallet to the DragonSwap dApp in your browser! Your wallet address should now show in the DragonSwap connect component.