1. If you haven't already, download an install Keplr wallet in your browser

2. Open Keplr, click the hamburgetr menu, and select "Add more chains" at the bottom (alternatively, you can browse to https://chains.keplr.app)

3. Connect your Keplr wallet

4. Filter to "Kima" and add Kima Mainnet (and Testnet) - this adds the 2 blockchains to your wallet

5. In your Keplr wallet, click the hamburger menu, select "Manage Chain Visibility" and make one, or both blockchains visible

6. If you have any tokens on any of the blockchains, they will now become visible

Here's a video demonstrating the full process:

Supported Assets

Kima supports a variety of EVM-compatible Layer 1 and Layer 2 chains, and will ultimately allow the swift and secure transfer of value between the following blockchains:

The short names are used in various API queries and are the same when using testnet.

Testnet support

Kima is currently available on the following testnets, which can be used for development and/or testing in the Kima Demo App:

• Arbitrum Sepolia

• Avalanche Fuji

• Base Sepolia

• Binance Smart Chain Testnet (aka BNB Testnet)

• Berachain Testnet (bArtio)

• Ethereum Sepolia

• Optimism Sepolia

• Polygon Amoy

• Solana Devnet

• Tron Nile Testnet

Querying for Supported Chains

For an up to date list of support chains query the following endpoint:

GET https://api.sardis.kima.network/kima-finance/kima-blockchain/chains/get_available_chains/{originChain}

Params

• originChain (string): the starting chain short name (see above)

Reponse

• Chains: string[]: the list of chain short names which can be bridged to from the origin chain

{
  "Chains": [
    "ETH",
    "AVX",
    "SOL",
    "BSC",
    "BASE",
    "BERA",
    "ARB",
    "OPT",
    "TRX",
  ]
}

Supported Tokens

Mainnet:

• USDC

• USDT

• HONEY (Berachain)

• WBTC

Testnet (faucet)

• USDK: the Kima testnet stablecoin

• KEUR: Kima EUR testnet stablecoin

The Kima Demo is a reference implementation to help people understand how Kima works.

You will need to have a wallet installed and to have some USDK (Kima's US dollar stablecoin) in your wallet on the testnet you want to use. This page explains how to do this. Remember that you will also need a small amount of the native token for the testnet you are sending funds from so you can pay for gas (for example, you will need Sepolia ETH if you want to send from Etherum's Sepolia testnet).

The demo showcases the following scenario:

• bridge between different chains (transfer to the same or a different address on different chains). Example: a user has funds on Avalanche but wants to add liquidity to a liquidity pool on Ethereum.

Bridging

This demo allows us to send funds to our own or a different wallet address on a network of our choice. Here we are sending USDK from Arbitrum's Sepolia testnet to Avalanche's Fuji testnet.

First, we connect our wallet, ensuring we are on the network from which we wish to send funds.

The widget pre-fills the target address field with the same wallet address we are sending from (if both network addresses are the same type), but this can be changed to a different address if desired.

We approve the transaction in our wallet...

... and then in the next step submit it.

We can follow the transaction status in the next screen, and check completion in each network explorer by selecting the corresponding transaction hashes.

If we wish, we can also retrieve the proper transaction id to follow the status of the transaction later.

Once the transaction is found, the status will be displayed with its corresponding state and transfers.

@ -1,35 +0,0 @@

The Kima Light Demo App

The Kima Light Demo is a reference implementation to help people understand how Kima works.

You can experience Kima's functionality directly in your browser, without needing to install or connect a wallet because the Light Demo App has been pre-configured to send funds between two accounts under the control of the Kima team.

The demo showcases two different scenarios:

• payment between different users on different chains. Example: a user has funds on Ethereum but wants to buy an item from an eCommerce store that accepts payments only on Polygon

• bridge between different chains (transfer to the same address on different chains). Example: a user has funds on Avalanche but wants to add liquidity to a liquidity pool on Ethereum.

Try the payment demo

By default the payment demo will "pay" 100 USDK from one address to another, you can choose which payee and payer are involved in the transaction.

After clicking the Pay button, you can watch the transaction complete in real-time. Clicking the transaction (TX) IDs shows the transaction details in the relevant block explorer.

In the last screenshot,you can see that the transaction is finalised.

Try the bridge demo

Similarly, the bridging demo (named Transfer in the Light Demo App) moves value between a subset of addresses on different networks. You can configure the number of USDK to be sent between addresses and choose which accounts are used.

Once you have submitted the transaction, you can watch it complete in real-time by clicking the transaction links to the block explorers that are involved.

The Kima demo app serves two purposes:

• to showcase payments and bridging using Kima

• to illustrate the look and feel of the Kima front-end widget

The Kima Demo supports the following testnets:

• Ethereum Sepolia

• Polygon Mumbai

• Avalanche Fuji

• Tron Nile Testnet

• Optimism (Sepolia)

• Arbitrum (Sepolia)

• Binance Smart Chain Testnet (aka BNB Testnet)

• Base Sepolia

• Bera bArtio

• Solana Devnet

To enable a smooth experience and a 360-degree overview of what is happening, we also provide a faucet and a block explorer.

Kima is the world’s first infrastructure-agnostic money transfer protocol. The Kima platform is comprised of a blockchain and a toolkit that allows the seamless transfer of assets between different protocols and platforms.

Challenges in Blockchain Interoperability

Blockchains are siloed. Web3 apps built within those ecosystems are constrained by their on-chain liquidity. Many solutions developed for these challenges, known as bridges, suffer from flaws and vulnerabilities: security, user experience, complexity, and poor capital efficiency.

How Kima Solves These Challenges

Kima addresses these challenges in a unique way, by creating a Web3 settlement layer which enables interchain transactions. This approach allows liquidity to be transferred between chains in a safe, secure, and cost-effective manner, enabling a reliable omnichain solution.

Key Concepts of Kima

Security: Kima achieves unique security by eliminating all known attack vectors (no smart contracts, no oracles, no external relayers) and adding multiple layers of security (e.g., using a Trusted Execution Environment with Intel SGX and decoupled validation). The protocol uses game theory and financial incentives to maintain liquidity equilibrium and maximize capital efficiency.

Infrastructure: Kima simplifies and accelerates the creation of secure Omnichain applications, tackling interoperability problems without causing additional liquidity fragmentation. It provides a mechanism for users to perform cross-chain atomic swaps without token-wrapping.

Kima's Blockchain Architecture

The Kima blockchain, built using the Cosmos SDK, employs a committee-based consensus. "Wardens" in a rotating committee ensure asset pool synchronization and authorize withdrawals based on corresponding deposits. This structure uses Threshold Signature Schemes (TSS) and operates within a Trusted Execution Environment for enhanced security.

Liquidity Management

Kima maintains liquidity pools on each integrated layer-1 blockchain (e.g., Ethereum, Polygon, Solana) and synchronizes assets across these platforms without creating synthetic ("wrapped") tokens.

Permission Layers

Permissioned Layer: Includes validators known for reliability (e.g., funds, banks, organizations). Permissionless Layer: Allows anyone with sufficient stake to become a block producer and warden, facilitating regular changes in the warden set.

Consensus and Goals

The two-layer consensus mechanism ensures stability, security, and decentralization, with four main goals:

• Manage and update the warden set.

• Execute platform governance (e.g., selecting blockchains and tokens, setting fees).

• Create an auditable record for accountability. -Enable cross-chain messaging for interacting with contracts across blockchains.

Cross-Chain Transfers

When users request cross-chain transfers, the warden committee is responsible for:

• Recording the request and monitoring the deposit on the source chain.

• Completing a threshold signature to release funds on the destination chain.

• Recording the finalized process, providing an auditable record of validator actions.

This architecture, proven in other Cosmos SDK-built systems, ensures a secure, decentralized, and efficient cross-chain transfer system.

To read a more detailed account of Kima's architecture and approach, read the White Paper.

How can you participate?

This documentation shows how to:

• Use Kima as an end user

• Become a validator for the Kima blockchain

• Leverage Kima's SDK to effortlessly integrate all Kima's functionality into your application

The Kima blockchain relies on a network of validator nodes for its security and consensus. KIMA tokens are distributed to validators as an incentive for their participation in the network.

You can read more about both Kima's incentive model and its innovative security architecture in the White Paper

Two areas of Kima's security architecture stand out:

• Threshold signature schemes (TSSs) allow a group of participants (“cosigners”) to securely generate and control the secret signing key for a digital signature scheme, such that a certain threshold (e.g. 2-out-of-3 or 7-out-of-10) cosigners must participate in, and agree upon, the signing protocol in order to generate a signature.

• To further complement security, Kima wardens run the threshold signature scheme inside an SGX enclave, thus the TSS key-shares are not directly accessible to the wardens or their system administrators.

For this reason, would-be validators need to ensure that they either have access to a machine that is compliant with the relevant SGX requirements, either by:

• Owning the relevant hardware

• Running their node on Azure

• Other enclave technologies such as AMD SEV-SNP may be supported in the future. Please contact us if you are interested in other enclave architectures.

Read the validator requirements page for more details.

If you have questions about setup, or would prefer to be guided through the process, get in touch here.

Kima Faucets

Kima has two testnet faucets: one for the native KIMA token and one for the Kima stablecoin, USDK.

You will need KIMA tokens for development purposes.

You will need testnet USDK to interact with the Kima platform on whatever testnets you are developing on, and also if you would like to use the Kima Advanced Demo App.

The faucet will give out 100 USDK daily per wallet address.

Note that these are testnet tokens only and have no financial value or benefit

Instructions for USDK faucet - EVM chains

1. You will first need to have an EVM-compatible wallet installed in your browser, such as MetaMask or Rainbow, if you do not already have one installed. Note that Kima does not endorse, recommend or guarantee any specific wallet. Follow the installation instructions and ensure that you keep your seed phrase safe.

2. Visit the faucet site.

3. Select the network you want to send funds from, whether this is for payment or bridging.

1. Connect your wallet by clicking the Connect button.

2. Your screen should now look like the screenshot below. Go ahead and click the Get Free 100 USDK button.

Note that in order to send funds from a particular network, you will also need a small amount of that network's native token in order to pay for gas costs.

So, for example, to bridge or pay from Ethereum's Sepolia network, you will need a small amount of Sepolia ETH, which can be acquired from any Sepolia faucet.

Instructions for USDK faucet - Solana and Tron

To acquire testnet USDK on Solana or Tron, the process is broadly the same but you will need to use a wallet that is compatibile with these chains.

While we at Kima do not endorse or guarantee any particular wallet, we note that Phantom is a popular choice for interacting with Solana and TronLink is a popular choice for Tron, so we will demo the use of these two wallets in obtaining testnet USDK.

USDK faucet - Solana

You will need to manually switch your Phantom wallet to use Solana's Devnet. In Phantom, you do this by clicking the Menu icon at the top left and then the Settings gearbox icon at the bottom left.

Within the settings menu you will see a submenu for Developer Settings, and this is where you can switch networks. You will see a banner advising that you are connected to a test network, as shown in the image below.

Solana faucet

From here, you can connect your wallet and request tokens as described in steps 4 to 6 above.

USDK faucet - Tron

Again, you will need to manually switch your network in your TronLink wallet to use the Nile testnet. You can do this by clicking on the down arrow in the middle of the top navigation bar where the current network is displayed, as shown in the image below.

Tron faucet

From here, you can connect your wallet and request tokens as described in steps 4 to 6 above.

Instructions for KIMA faucet

1. You will first need to have a wallet installed that is designed to interact with the Cosmos ecosystem, such as Keplr.

2. Visit the faucet site.

3. Connect your wallet by clicking the Connect button.

4. Go ahead and click the Get Free 100 KIMA button.

5. Your wallet will ask you to confirm the transaction, and you will soon see the tokens arrive in your wallet, as shown below.

How to configure access to blockchain networks with a managed service

To quickly connect to the Kima testnet, you can use managed services like Infura, Alchemy, QuickNode, or Ankr. These services simplify blockchain infrastructure by providing RPC endpoints you can access with API keys.

Here’s how to create API keys for each service:

Infura

Alchemy

Sign up at Alchemy's website. Navigate to the dashboard and select Apps in the left-hand menu. Create a new App, selecting the network(s) you need. Once saved, your API key will be displayed at the top right of the page.

QuickNode

Ankr

Kima's block explorer, currently available for the Kima Devnet, is an essential dashboard showing all the key facts about the state of the network, including transaction history.

If you are developing on Kima, this is where you will be able to monitor your transactions.

Must be an Intel XEON E-series or any other XEON supporting SGX-SPS (Server Platform Services). The motherboard must also support SGX.

• CPU: 4vCPU (8vCPU recommended)

• RAM: 16GB (32GB recommended)

• Storage: 512GB HDD (1TB recommended)

• Operating System: Ubuntu 22.04

SGX requirements

Must be an Intel XEON E-series or any other XEON supporting SGX-SPS (Server Platform Services). The motherboard must also support SGX. The below list of supported SGX-compliant CPUs List is current for the second half of 2024

Compliant servers

• Intel XEON E-2174G

• Intel XEON E-2176G

• Intel XEON E-2178G

• Intel XEON E-2186G

• Intel XEON E-2188G

• Intel XEON E-2274G

• Intel XEON E-2276G

• Intel XEON E-2278G

• Intel XEON E-2286G

• Intel XEON E-2288G

• Intel XEON E-2334G

• Intel XEON E-2386G

• Intel XEON E-2388G

Compliant servers

Prerequisites

Programs and applications

curl: Required for fetching external IPs and interacting with web services. Ensure it is installed and configured on your system. git: Needed for cloning repositories and managing code changes. Install it and ensure familiarity with basic commands. text editor: Use any editor (e.g., Vim, Nano) to update configuration files as needed

Currently, validators are selected manually and require access to private GitHub repositories. These repositories will be made open-source in the near future.

To gain access and prepare your environment, you must: 1. Set up an SSH key

• Generate an SSH key.

• Add the SSH key to your GitHub account. 2. Accept the repository invitation

• Once your SSH key is linked to your GitHub account, you will receive an invitation to access the necessary repositories. 3. Ensure required permissions and tools You will need sudo access on your machine to manage installations and configurations.

Ensure the git command is installed and configured, as it is required to clone the Kima repositories. Note: For assistance with setting up an SSH key or linking it to GitHub, refer to GitHub's SSH setup guide.

Proper SSH configuration and access permissions ensure secure and seamless repository access.

Network

Public static IP

Open Ports:

• 22: SSH (Secure Shell) protocol

• 26656: Cosmos app CometBFT gossiping port for consensus

• 26657: Cosmos app CometBFT RPC port

• 9090: Cosmos app gRPC port

• 5051: TSS-ECDSA P2P port 5052: TSS-EDDSA P2P port

• 5053: TSS app EDDSA (Solana chain signer) gossiping port

• 8081: TSS-ECDSA info address 8082: TSS-ECDSA info address

• 7070: Cosmos validator management on genesis node port

Initial setup:

Download scripts from the Github repository to your server using any convenient method.

git clone git@github.com:kima-finance/kima-external-validator.git

Prepare the scripts:

Make the files executable with:

sudo chmod +x setup-validator.sh
sudo chmod +x update-config.sh
sudo chmod +x run-validator.sh

Prepare the environment:

Navigate to the validator directory:

	cd $HOME

Create an empty .env file:

touch .env

Copy the template file to .env:

⚠️ Note: This will overwrite any existing .env file. Ensure you want to proceed.

cp .env.template .env

Add the blockchain networks configuration

In the same .env file, add the RPC and WSS endpoints for the blockchain networks you will connect to:

ETH_RPC_HOST="https://mainnet.infura.io/v3/<YOUR_INFURA_API_KEY>"
ETH_WSS_HOST="wss://sepolia.infura.io/ws/v3/<YOUR_INFURA_API_KEY>"

⚠️ Important: Use a high-performance RPC endpoint. Free or basic paid plans may not suffice. Replace <YOUR_INFURA_API_KEY> with your actual API key. Update the URLs and details for other networks as needed.

Suggestions for Testnet API Keys: Services like Alchemy, QuickNode, or Ankr support various chains, including Ethereum, Polygon, AVAX, BSC, and more. Refer to their documentation for API key acquisition and configuration.

📝 Tip: Check each blockchain's official documentation for the latest public testnet endpoints or additional API services.

Execute the first script:

Execute the following script to install necessary components and start the installation:

	./1-setup-validator.sh <validator-node-name>

Upon successful installation, your node will begin synchronizing with the blockchain network. To monitor progress:

watch -n 1 'kimad status | jq .SyncInfo'

You will see synchronization details like this:

{  
  "latest_block_height": "12345",  
  "catching_up": true  
}

Wait for catching_up to turn false; indicating the sync is complete.

Execute the second script:

Complete the setup by executing the following:

./1-run-validator.sh

Once this script completes, your node will be fully operational, and you will become a validator on the Kima Network blockchain.

Delegating your $KIMA tokens has multiple benefits. Most of these are related to enhancing network security, reducing operation complexity and increasing participation.

Enhanced Security

Delegation allows for a wider distribution of decision-making power and staking responsibilities, thus reducing centralization.

Reduced operation complexity

A delegator who may not have the required technical expertise or resources to run a validator node can still participate in staking. Additionally, the amount required to run a validator often exceeds the funds a typical user might hold.

Delegation also allows delegators to diversify their portfolios by designating some tokens for delegation while keeping others for active trading or investment.

Increased participation

Delegators can participate in network decisions without having to manage the technical aspects of voting or governance. They can rely on validators to handle these aspects while still staking their tokens to influence network decisions.

Delegation is a process that facilitates efficient governance, consensus and operational management in a blockchain.

A participant in the network - a delegator - assigns their voting rights, governance power, and/or staking responsibilities to another participant, referred to as the delegate. This is often a validator of the network.

Why choose to delegate?

This process allows every token holder to participate in the staking process without running their own validator. The validator receives yields from the staking process for validating transactions directly. Then the validator shares a portion of the corresponding rewards with each delegator while taking a percentage of the rewards for being the delegate. Each validator can adjust the commission percentage to incentivize more participants to become delegators.

In Kima, delegation locks the tokens for a period of time. This prevents misuse of the delegation and instant withdrawals after receiving rewards or participating in network decisions.

Welcome to the Delegation documentation section. This guide covers everything you need to know about delegating to a validator, including the benefits, technical workings, and step-by-step instructions.

In this guide, you will learn how to set up a wallet and add funds to it. This process can vary depending on whether you're using the mainnet or testnet. We'll cover the following scenarios:

• Setting up a wallet

• Using a faucet (testnet only)

Set up a wallet

Choose a wallet

Some wallet options are Keplr (recommended), Station and Leap.

Install the wallet

Then select your preferred browser/device. This guide shows the installation process using Google Chrome.

Add the wallet as a Chrome extension. To minimize risk, always verify that the team behind the extension corresponds with the Keplr app.

Click the Add to Chrome button and wait for the extension to open a new tab with the setup steps. Click the Create a new wallet button to begin the setup.

This will prompt you to choose a wallet creation method.

Read the security concerns about creating a new wallet using a recovery phrase carefully, and click 'I understood. Show my phrase.' Store that phrase in a secure place where only you can access it.

Now enter the words requested from your recovery phrase, add a name and a password to your wallet, then click Next.

Select the default networks and the setup will be completed.

Adding funds to your wallet

Using a faucet

Note that this step applies to the testnet only.

Kima has available faucets for both its native token ($KIMA) and the USDK stablecoin. To delegate on the testnet, you need to have $KIMA to execute the transaction and send the delegated amount.

For further reference, please visit the Kima Faucets documentation.)

If you are planning to undelegate for the purpose of switching validators, unstaking funds to use elsewhere, or just taking a break, follow the steps below. When you undelegate your tokens on the Kima network, they enter an Unbonding period of 21 days, which means they are locked until the period ends before being transferred back to your wallet. This ensures commitment to the KIMA network and prevent abuse and misuse of the delegation process.

This guide assumes you have previously delegated tokens on Kima.

Connect your wallet

Go to the KIMA explorer and click the Connect Keplr button.

Testnet explorer Mainnet explorer

Approve the prompts.

In the explorer, click the Overview tab in the left sidebar of the home screen.

Scroll down until you can see the Delegations section. There, you should be able to see a summary of your delegated stake among the available validators.

Look for the delegated stake that you plan to undelegate and click on the Undelegate button.

Enter the amount of $KIMA you want to undelegate and click on Submit.

You will be prompted to approve the transaction. To confirm, click on Approve.

In the Delegations section, you should see that you no longer have any delegated stake. Your undelegated tokens will be in the Unbonding period.

After this period, you will be able to view your tokens in your wallet.

In this guide, you will learn how to delegate tokens to a validator using the Kima explorer.

Connect your wallet

From the left sidebar, select Validators.

Connect your wallet by clicking the Connect Keplr button on the top right corner.

Keplr will now prompt you to add the Kima network (mainnet or testnet) to your wallet's chain registry. To complete the operation, click the Approve button.

You should now see your Kima address instead of Connect Keplr in the top right corner.

View your KIMA tokens in Keplr

Keplr requires an extra step to display the KIMA network so you can view your tokens. From the extensions panel in Chrome, click on the Keplr extension and select the hamburger icon in the top left corner.

In the menu, select Settings.

On the next screen, select General.

Next, scroll down until you reach the Manage Chain Visibility button and click it.

This will open a new tab. In the search box, type kima for mainnet or kima-testnet for the testnet. and it should show the relevant network, along with your $KIMA tokens. Select it by clicking the checkbox and click Save.

You should now be able to see your $KIMA balance in your wallet.

Delegate your $KIMA

Select one of the available validators in the Kima explorer and click on the Delegate button.

Enter the amount of $KIMA that you want to delegate. Ensure that you have sufficient balance for both the delegation amount and the fees for sending the transaction to the network. To confirm the delegation, click Submit.

You will now be prompted to approve the transaction. You will see the following information (numbers are examples):

• Method to execute: Stake

• Amount of tokens: 10 $KIMA

• Transaction fees: 0.05 $KIMA

Check all details, then click Approve and wait for the transaction to complete.

You should now see a success message, along with the transaction hash of the delegation.

To see further transaction details, you can click on the transaction hash, which will take you to the transaction details within the explorer.

There you can view details such as:

• Minimum period 30 days

• Minimum delegation >0

• Unbonding lockup period 7 days

• Commission fee X%

• Estimated APY minimum guarantee + rewards

• Exit before period ends - no commission paid

• Add KIMA to delegation will reset the period timer

Finally you can see your delegated stake in the overview page of the explorer.

Troubleshooting and tips

Check network atatus

Ensure that the Kima network is operational and that there are no ongoing issues or outages.

Verify validator information

Double-check the validator’s details before delegating to avoid any mistakes.

Ensure sufficient funds

Make sure you have enough tokens to cover both the delegation amount and any associated network fees.

Overview

This guide will help you learn how to provide liquidity for the Kima protocol.

Getting Started

• Understand the Benefits: Start by reviewing the Benefits of becoming a Liquidity Provider section to learn about the incentives, rewards, and advantages of providing liquidity for Kima.

• Review Supported Assets and Networks: Before proceeding, familiarize yourself with the Supported assets and networks section to understand which assets and networks are currently supported by Kima.

• Set Up Your Environment: Follow the Prepare to provide liquidity section to set up your wallets and networks to interact with Kima.

• Deposit Liquidity: Once set up, head to the Deposit assets in Kima pools section to start adding liquidity, and earning rewards.

• Monitor and Withdraw: Manage and withdraw your liquidity by following the steps in the Withdraw assets from Kima section.

Please ensure you read the disclaimer.

Kima offers significant incentives for liquidity providers, whether they participate passively or actively. By joining our liquidity pool system, providers can maximize their returns and help secure cross chain liquidity, benefiting from Kima’s efficient and secure network.

Earn Network Fees

Liquidity providers earn a portion of the network transaction fees. For every transaction processed through the liquidity pool, a small fee (0.05% of the transaction amount) is distributed to liquidity providers. Example: For every $1 million in daily transaction volume, liquidity providers earn $500 in network fees per day, or $182,500 annually. Passive liquidity providers, in this case, would receive half of that amount ($91,250/year).

Capital Efficiency

Kima is designed to achieve high capital efficiency, meaning liquidity providers can earn more returns with less liquidity.

Cross-chain Liquidity

Kima’s liquidity pools span multiple blockchain networks, offering liquidity providers access to a broad range of opportunities. By providing liquidity across Ethereum, Polygon, Optimism, and other networks, providers can participate in various ecosystems while enjoying the benefits of Kima’s seamless cross-chain infrastructure.

Security

Kima Finance leverages Trusted Execution Environments (TEEs) and a Threshold Signature Scheme (TSS) to ensure that all liquidity provider operations are secure and private. These advanced security mechanisms protect liquidity providers' assets while enabling the system to function at optimal performance.

Conclusion

Kima Finance’s liquidity pool system is designed to be efficient, secure, and flexible. Liquidity providers can benefit from participating in cross-chain pools, earning rewards through network fees and bounties. For more information on becoming a liquidity provider, refer to the Deposit assets in Kima pools section.

During the initial release period of Kima, the only supported assets will be USDC and USDT on EVM, Tron and Solana. More assets and blockchains will be added in later releases. Assets marked “optional” will be added on demand.

Before you can start providing liquidity to Kima Finance pools, you will need to set up wallets for interacting with the Kima protocol, and the supported target blockchains.

Interacting with Kima

Kima is a Cosmos based blockchain. To interact with Kima, you need to:

• Install a Cosmos wallet such as Keplr.

• Download your wallet

Follow the instructions to create a new wallet. Secure your seed phrase!

Add the Kima blockchain to the wallet.

Go to the Explorer page:

Browse to the Liquidity panel

Click the button in the upper right to connect your Keplr wallet

Accept all the parameters that will add Kima Mainnet chain to your wallet

You will need Kima tokens to pay gas for the provisioning operations.

Supported Networks and Wallets

Kima offers broad support for multiple blockchain networks, allowing you to connect using a variety of wallets compatible with WalletConnect. You are not limited to specific wallets; instead, you can choose from options such as:

• EVM-compatible blockchains: To provide liquidity on any EVM-compatible blockchain (Ethereum, Arbitrum, BNB, etc.) use any EVM-compatible wallet such as MetaMask.

• Solana: To provide liquidity on Solana, use Solflare, Phantom, or any other Solana-compatible wallet.

• Tron: We have provided instructions for TronLink.

• Bitcoin: We have provided instructions for XVerse.

Below are the setup instructions for each wallet option:

EVM-compatible blockchains

For EVM-compatible blockchains, such as Ethereum, Polygon, or Optimism, you may use a wallet such as MetaMask.

Install MetaMask: Download MetaMask as a browser extension or mobile app from the MetaMask website.

Create a wallet: Follow the prompts to create a wallet. Secure your seed phrase!

Add blockchains: Add the blockchains you’d like to provide liquidity on to your MetaMask wallet.

The easiest way is to browse to Chainlist.org and add the desired blockchains.

Kima supports the following blockchains:

Solana

For interacting with Kima's liquidity pools on Solana, you may use Solflare or a similar wallet that supports Solana.

Install Solflare: Download the Solflare wallet from the Solflare website.

Create a Wallet: Set up your Solflare wallet. Secure your seed phrase!

Tron

For interacting with Kima's liquidity pools on Tron, you may use TronLink or a similar wallet that supports Tron.

Install TronLink: Download TronLink from the TronLink website.

Create a Wallet: Follow the instructions to create your Tron wallet. Secure your seed phrase!

Bitcoin

To provide liquidity to the Kima Finance Bitcoin pool, you may use XVerse wallet, a recommended wallet for interacting with Bitcoin.

How to Set Up XVerse Wallet:

Install XVerse: Download the XVerse wallet from the XVerse website.

Create a Wallet: Follow the prompts to set up your XVerse wallet. Secure your seed phrase!

You are now ready to start providing liquidity to Kima pools across various networks. If you encounter any issues during setup, refer to the official documentation of each wallet or reach out to the Kimae community for support.

Instructions for using these wallets do not represent an endorsement by Kima of any of the wallets mentioned.

Below is a step by-step guide on how to deposit assets:

Step 0: Check you have enough funds

Before depositing liquidity, make sure:

• You have assets available for deposit.

• The assets are on the supported assets list.

• You have at least 0.2 Kima tokens in your Keplr wallet.

• You have enough funds for gas on your desired network (e.g., ETH for Ethereum, MATIC for Polygon, etc).

Step 1: Connect your wallets

Browse to the Kima Explorer.

Browse to the Liquidity panel

Click the button in the upper right to connect your Keplr wallet

Your existing positions are now visible.

Step 2: Select the blockchain, the asset and balance

Select the blockchain you’d like to provide liquidity on.

Choose the amount you would like to deposit.

Select the asset you’d like to provide.

Click Deposit.

Step 3: Confirm transaction in the new transfer window

Upon clicking Deposit, a New Transfer window will appear. In this window:

Connect your blockchain wallet if you haven't already.

Review the transaction details, including the source network, wallet address, and deposit amount. Click Next.

Step 4: Approve the transaction

After reviewing the transaction details, click Submit.

Approve all the transactions your wallets ask you to approve.

Step 5: Sign approval requests in Keplr

For all Kima Network transactions, you will be asked to make two approvals through your Keplr wallet.

Important: You may have to wait a few seconds for the second approval request to appear. If the Keplr wallet does not automatically launch, open it manually to see the pending approval requests.

Once you’ve signed and approved both requests, the transaction process will begin.

Step 6: Verify your deposit

Once the transaction reaches 100% completion, your asset’s liquidity is deposited in the pool.

You can now view your balance, or withdraw it.

To withdraw an asset on any blockchain in the Kima Finance protocol,follow these steps:

Step 0: Ensure Liquidity Balance

Before withdrawing liquidity, make sure:

• You have assets available for withdrawal.

• You have at least 0.2 Kima tokens in your Keplr wallet.

Step 1: Select the amount and network

Choose the amount you would like to withdraw.

Select the network from which you want to withdraw.

Step 2: Initiate the withdrawal process

Once you have set the amount and network, click Withdraw to remove liquidity from the chosen pool.

Step 3: Confirm Transaction in the New Transfer Window

Upon clicking Withdraw, a New Transfer window will appear. In this window:

Connect your wallet if it is not already connected.

Review the transaction details, including the source network, wallet address, and withdrawal amount.

Step 4: Approve the transaction

After reviewing the transaction details, click Next to move to the confirmation step.

In this step, you'll need to approve the transaction, which allows the transfer of the liquidity from the pool you selected to your wallet.

Click Approve to proceed with the transaction.

Step 5: Sign approval requests in Keplr

For all transactions on the Kima Finance network, you will be asked to make two approvals through your Keplr wallet.

Important: You may have to wait a few seconds for the second approval request to appear. If the Keplr wallet does not automatically launch, open it manually to see the pending approval requests.

Once you’ve signed and approved both requests, the transaction process will begin.

Step 6: Verify the Withdrawal

Once the transaction reaches 100% completion, your asset’s liquidity will be withdrawn from the pool to your wallet.

You can verify your current liquidity assets still deposited with Kima.

Drafting and submitting a proposal is a process that takes time, attention, and involves risk.

In an ideal world, a proposal should only fail to pass in a situation where engaged and aware make an informed decision to vote down the proposal.

If you are considering drafting a proposal, you should first review the general background on drafting and submission:

• How the voting process and governance mechanism works

• How to draft your proposal and engage with the Kima community about it

• How to format proposals

• How to submit your proposal

You should also review details specific to each kind of proposal, listed in this section.

Text (Signaling)

What are signaling proposals currently used for?​

Signaling proposals are used to make an on-chain record of support or agreement on a certain topic or ideas. Text proposals do not contain any code. In other words, they do not directly cause any changes to the Hub if they are passed.

Past signaling proposals have been used for a variety of reasons:

• Agreement to adopt (or not adopt) a feature in a future release

• A high-signal alert to validators

• On-chain record of community opinion

• Ratification of a social norm

Why make a signaling proposal?​

Signaling proposals are a great way to take an official public poll of community sentiment before investing more resources into a project. The most common use of text proposals is to confirm that the community is actually interested in what the proposer wants to develop, without asking for money to fund development that might not be concrete enough to have a budget yet.

Because the results of signaling proposals remain on-chain and are easily accessible to anyone, they are also a good way to formalize community opinions. Information contained in documentation or GitHub repos can be hard to find for new community members but signaling proposals in a block explorer or wallet is very accessible.

You might make a signaling proposal to gather opinions for work you want to do for the Hub, or because you think it is important to have a record of some perspective held by the community at large.

What happens when a signaling proposal passes?​

Technically, nothing happens on-chain. No code executes, and this 'unenforceable' property of text proposals is one of the biggest criticisms of the format. Regardless of whether the results of a signaling proposal are enforced by code, there can still be value from having a proposal on-chain and subject to discussion. Whether a proposal passes or fails, we all get information from it having been considered.

• The community might have had a thorough, thoughtful discussion about a topic that they otherwise would not have had.

• A development team interested in a feature might have a better idea of how their work will be received by the community.

• The community might be more informed about a topic.

• The community might feel confident that we are aligned on a particular definition or social norm.

Submitting a text proposal​

Follow the instructions below to create a text proposal and submit it to the network.

Community Pool Spend

Unlocks the potential for token-holders to vote to approve spending from the Community Pool.

Learn About the Community Pool​

How is the Community Pool funded?​

2% of all staking rewards generated (via block rewards & transaction fees) are continually transferred to and accrue within the Community Pool. For example, from December 19, 2019 until January 20, 2020 (32 days), 28,726 ATOM were generated and added to the pool.

How can funding for the Community Pool change?​

Though the rate of funding is currently fixed at 2% of staking rewards, the effective rate is dependent upon Kima staking rewards, which can change with inflation and block times. The current parameter Community Tax parameter of 2% may be modified with a governance proposal and enacted immediately after the proposal passes.

How much money is in the Community Pool?​

You may directly query Kima for the balance of the Community Pool:

Alternatively, the Kima Explorer will display the ongoing Community Pool balance.

How can funds from the Community Pool be spent?​

Funds from the Kima Community Pool may be spent via a successful governance proposal.

How should funds from the Community Pool be spent?​

We don't know 🤷

The prevailing assumption is that funds should be spent in a way that brings value to Kima. However, there is debate about how to keep the fund sustainable. There is also some debate about who should receive funding. For example, part of the community believes that the funds should only be used for those who need funding most. Other topics of concern include:

• Retroactive grants

• Price negotiation

• Fund disbursal (eg. payments in stages; payments pegged to reduce volatility)

• Radical overhaul of how the community-spend mechanism functions

We can expect this to take shape as proposals are discussed, accepted, and rejected by the Kima community.

How are funds disbursed after a community-spend proposal is passed?​

If a community-spend proposal passes successfully, the number of $KIMA encoded in the proposal will be transferred from the community pool to the address encoded in the proposal, and this will happen immediately after the voting period ends.

Why create a proposal to use Community Pool funds?​

As a strategy: funding is fast. Besides the time it takes to push your proposal on-chain, the only other limiting factor is a fixed 14-day voting period. As soon as the proposal passes, your account will be credited the full amount of your proposal request.

To build rapport. Engaging publicly with the community is the opportunity to develop relationships with stakeholders and to educate them about the importance of your work. Unforeseen partnerships could arise, and overall the community may value your work more if they are involved as stakeholders.

To be more independent. The Interchain Foundation (ICF) may not always be able to fund work. Having a more consistently funded source and having a report with its stakeholders means you can use your rapport to have confidence in your ability to secure funding without having to be dependent upon the ICF alone

Parameter change

Drafting and submitting a parameter-change governance proposal involves two kinds of risk: losing proposal deposit amounts and the potential to alter the function of the Kima network in an undesirable way.

What parameters can be changed?​

The complete parameters of the Kima network are split up into different modules, each of which has its own set of parameters. Most parameters can be updated by submitting a governance proposal.

List of modules whose parameters can be changed via governance:

What are the current parameter values?​

There are ways to query the current settings for each module's parameter(s). Some can be queried with the command line program gaiad. You can begin by using the command gaiad q [module] -h to get help about the subcommands for the module you want to query. For example, gaiad q staking params returns the settings of relevant parameters:

bond_denom: uKIMA max_entries: 7 max_validators: 180 unbonding_time: 1814400s

If a parameter change proposal is successful, the change takes effect immediately upon completion of the voting period.

Note: You cannot currently query the bank module's parameter, which is sendenabled. You also cannot query the crisis module's parameters.

Why create a parameter change proposal?​

Parameters govern many aspects of Kima's behaviour. As circumstances and attitudes change, sometimes you might want to change a parameter to bring the chain's behaviour in line with community opinion. For example, the Cosmos Hub launched with 100 active validators and there have been 4 proposals to date that have increased the MaxValidators parameter. At the time of writing, the active set contains 180 validators.

The Cosmos Hub has been viewed as a slow-moving, highly secure chain and that is reflected in some of its other parameters, such as a 21 day unbonding period and 14 day voting period. These are quite long compared to other chains in the Cosmos Ecosystem

Risks in parameter change proposals​

Because parameters dictate some of the ways in which the chain operates, changing them can have an impact beyond what is immediately obvious.

For example, reducing the unbonding period might seem like the only effect is in how quickly delegators can liquidate their assets. It might also have a much greater impact on the overall security of the network that would be hard to realize at first glance.

This is one of the reasons that having a thorough discussion before going on-chain is so important - talking through the impacts of a proposal is a great way to avoid unintended effects.

Software Upgrade

Use the draft-proposal command to create a draft proposal and populate it with required information.

The Kima Network has an on-chain governance mechanism for signaling (text proposals), changing parameters and allocating funds from the community pool.

Community​

Governance parameters​

The following are parameters that are currently present in the governance process:

• Minimum deposit: 10,000 KIMA

• Maximum deposit period: 14 days

• Voting period: 7 days

• Quorum: 33.40% of participating voting power

• Pass threshold: 50% of participating voting power

• Veto threshold: 33.40% of participating voting power

Deposit period​

The deposit period lasts 14 days.

Before a governance proposal enters the voting period (i.e., for the proposal to be voted upon), there must be at least a minimum number of KIMA deposited (10,000). Anyone may contribute to this deposit, though it is usually filled by the proposal maker. Deposits of passed and failed proposals are returned to the contributors.

Burned deposits​

Deposits are burned only when proposals are vetoed. Deposits are not burned for failing to meet quorum or for being rejected.

Voting period​

The voting period is currently a fixed 7 day period. During the voting period, participants may select a vote of either 'Yes', 'No', 'Abstain', or 'NoWithVeto'. Voters may change their vote at any time before the voting period ends.

What do the voting options mean?​

• Abstain: The voter wishes to contribute to quorum without voting for or against a proposal.

• Yes: Approval of the proposal in its current form.

• No: Disapproval of the proposal in its current form.

• NoWithVeto: NoWithVeto is a mechanism that allows voters to indicate that they strongly disagree with a proposal or if a proposal is identified to be spam. If more than 1/3 of voters cast a NoWithVeto vote, the proposal is rejected.

Voting 'NoWithVeto' has no immediate additional financial cost to the voter - you do not directly risk your KIMA by using this option.

What determines whether or not a governance proposal passes?​

There are four criteria:

1. Deposit is filled: A minimum deposit of 10,000 KIMA is required for the proposal to enter the voting period

• anyone may contribute to this deposit

• the deposit must be reached within 14 days (this is the deposit period)

1. Quorum is reached: A minimum of 33.40% of the network's total voting power (staked KIMA) is required to participate

2. Simple majority of 'Yes' votes: Greater than 50% of the participating voting power must back the 'Yes' vote by the end of the 7 day voting period

3. Not vetoed: Less than 33.4% of participating voting power must have backed 'NoWithVeto' by the end of the 7 day voting period

Currently, the criteria for submitting and passing/failing all proposal types is the same.

Because the Kima blockchain is a public network, you can interact with it however you see fit. You can choose to become a validator, if you want - see Becoming a Validator for more details - or you can build a variety of applications on top of it.

To make developing on top of Kima simpler, we have created a toolkit - the Kima Software Development Kit (SDK).

We provide:

• a standalone server that you can run locally and use as middleware that sits between the front end of your dApp and the Kima blockchain, submitting requests and returning the response to the front end

• a front-end widget with different configuration options that you can easily integrate into your dApp

Of course, the open ethos of Web3 means that you can develop your own solutions from scratch, but we strongly recommend building with both front end and back end components of our SDK so you can leverage the efforts our development team have made on your behalf.

Troubleshooting

There is an extra step that needs to happen if you are using Kima's tools to transfer to or from Solana wallets. The recipient wallet first needs to be "primed" by sending a small amount of USDK to the wallet before transfers or payments via Kima can take place.

This applies to the testnet only and will not be the case once Kima's mainnet goes live.

Once a proposal is on-chain, it cannot be changed to reflect feedback or new information. It is very important to give a proposal time off-chain to receive feedback, input, and edits before going on-chain and asking for votes.

The process of passing a proposal starts long before it goes on-chain!

There are currently several types of proposals supported by Kima:

• Text: Proposal to agree to a certain strategy, plan, commitment, future upgrade or other statement. Text proposals do not directly cause any changes, but they can be used to take a record of the community's opinion or commitment to a future idea.

• Community Pool Spend: Proposal to spend funds from the community pool on a project

• Parameter Change: Proposal to change a core on-chain parameter.

• Software Upgrade: Proposal to upgrade the chain version.

You will first want to determine which kind of proposal you are making. Be sure to review all details of your specific proposal type.

Engage directly with the voting community and seek feedback​

Engagement is likely to be critical to the success of a proposal. The degree to which you engage with the Kima community should be relative to the potential impact that your proposal may have on the stakeholders. This guide does not cover all ways of engaging but here are some suggestions:

• Post your idea to the Cosmos Hub Forum

• Mention the idea in a community call (often hosted on X/Twitter)

• Host an AMA on Reddit

• We encourage you to experiment and use your strengths to introduce proposal ideas and gather feedback.

There are many different ways to engage. One strategy involves a few stages of engagement before and after submitting a proposal on chain.

Why do it in stages? It's a more conservative approach to save resources. The idea is to check in with key stakeholders at each stage before investing more resources into developing your proposal.

In the first stage of this strategy, you should engage people (ideally experts) informally about your idea. You'll want to start with the minimal, critical components (name, value to Kima, timeline, any funding needs) and check:

• Does it make sense?

• Are there critical flaws?

• How will this affect other projects or properties of the Hub?

You should be engaging with key stakeholders (e.g., a large validator operator) with a few short sentences to measure their support. Here is an example:

"We are considering a proposal for funding to work on project. We think it will help the Hub to outcome. Timeline is x, and we're asking for y amount. Do you think that this is a proposal that large validator may support?"

Why a large validator? They tend to be the de facto decision-makers on Kima, since their delegators also delegate their voting power. If you can establish a base layer of off-chain support, you can be more confident that it's worth proceeding to the next stage.

Note: Many validators will likely hesitate to commit support, and that's okay. It will be important to reassure these stakeholders that this isn't a binding commitment. You're just canvasing the community to get a feel for whether it's worthwhile to proceed. It's also an opportunity to connect with new people and to answer their questions about what it is you're working on. It will be important for them to clearly understand why you think what you're proposing will be valuable Kima, and if possible, why it will be valuable to them as long-term stakeholders.

If you're already confident about your idea, skip to Stage 2.

Stage 1: Your Idea​

Not yet confident about your idea?​

Great! Governance proposals potentially impact many stakeholders. Introduce your idea with known members of the community before investing resources into drafting a proposal. Don't let negative feedback dissuade you from exploring your idea if you think that it's still important.

If you know people who are very involved with Kima, send them a private message with a concise overview of what you think will result from your idea or proposed changes. Wait for them to ask questions before providing details. Do the same in semi-private channels where people tend to be respectful (and hopefully supportive).

Confident with your idea?​

Great! However, remember that governance proposals potentially impact many stakeholders, which can happen in unexpected ways. Introduce your idea with members of the community before investing resources into drafting a proposal. At this point you should seek out and carefully consider critical feedback in order to protect yourself from confirmation bias. This is the ideal time to see a critical flaw, because submitting a flawed proposal on-chain will waste resources and have reputational costs.

Posting your idea to the Cosmos Hub Forum is a great way to get broad feedback and perspective even if you don't have personal connections to any stakeholders or involved parties.

Are you ready to draft a governance proposal?​

There will likely be differences of opinion about the value of what you're proposing to do and the strategy by which you're planning to do it. If you've considered feedback from broad perspectives and think that what you're doing is valuable and that your strategy should work, and you believe that others feel this way as well, it's likely worth drafting a proposal. However, remember that the largest KIMA stakers have the biggest vote, so a vocal minority isn't necessarily representative or predictive of the outcome of an on-chain vote.

You could choose to take a conservative approach and wait until you have some confidence that you roughly have initial support from a majority of the voting power before proceeding to drafting the details of your proposal. Or you could propose the idea, or define the problem statement and let the community participate freely in drafting competing solutions to solve the issue.

Stage 2: Your Draft Proposal​

The next major section outlines and describes some potential elements of drafting a proposal. Ensure that you have considered your proposal and anticipated questions that the community will likely ask. Once your proposal is on-chain, you will not be able to change it.

Proposal Elements​

It will be important to balance two things: being detailed and being concise. You'll want to be concise so that people can assess your proposal quickly. You'll want to be detailed so that voters will have a clear, meaningful understanding of what the changes are and how they are likely to be impacted.

Each major proposal type has a rough template available on the forum: Text, community pool spend, parameter change, software upgrade.

Each proposal should contain a summary with key details about what the proposal hopes to change. If you were viewing only the summary with no other context, it should be a good start to being able to make a decision.

Assume that many people will stop reading at this point. However it is important to provide in-depth information. The on-chain proposal text should also include a link to an un-editable version of the text, such as an IPFS pin, and a link to where discussion about the idea is happening.

A few more pointers for Parameter Change and Community Spend proposals are below.

Parameter Change​

An example of a successful parameter change proposal is Proposal #66. Note that this proposal went on-chain without the recommended IPFS pin.

• Problem/Value: The problem or value that's motivating the parameter change(s).

• Solution: How changing the parameter(s) will address the problem or improve the network.

• Risks & Benefits: How making this/these change(s) may expose stakeholders to new benefits and/or risks.

  • The beneficiaries of the change(s) (ie. who will these changes impact and how?)

  • Voters should understand the importance of the change(s) in a simple way

• Supplementary materials: Optional materials eg. models, graphs, tables, research, signed petition, etc

Community-Spend Proposal​

An example of a successful community spend proposal is Proposal #63.

Applicant(s) - The profile of the person(s)/entity making the proposal. Who you are and your involvement in Kima and/or other blockchain networks. An overview of team members involved and their relevant experience. Problem - What you're solving and/or opportunity you're addressing. Past, present (and possibly a prediction of the future without this work being done). Solution - How you're proposing to deliver the solution. Your plan to fix the problem or deliver value. The beneficiaries of this plan (ie. who will your plan impact and how?). Your reasons for selecting this plan. Your motivation for delivering this solution/value. Funding - amount and denomination proposed eg. 5000 KIMA. The entity controlling the account receiving the funding. Consider an itemized breakdown of funding per major deliverable. Note that the 'budget' of a spend proposal is generally the easiest thing to criticize. If your budget is vague, consider explaining the reasons you're unable to give a detailed breakdown and be clear about what happens if you do not meet your budget. Deliverables and timeline - the specifics of what you're delivering and how, and what to expect. What are the specific deliverables? (be detailed). When will each of these be delivered? How will each of these be delivered? What will happen if you do not deliver on time? Do you have a plan to return the funds if you're under-budget or the project fails? How will you be accountable to the KIMA stakeholders? How will you communicate updates and how often? How can the community observe your progress? How can the community provide feedback? How should the quality of deliverables be assessed? eg. metrics. Relationships and disclosures. Have you received or applied for grants or funding? for similar work? eg. from the Interchain Foundation. How will you and/or your organization benefit? Do you see this work continuing in the future and is there a plan? What are the risks involved with this work? Do you have conflicts of interest to declare? Begin with a well-considered draft proposal​

Ideally, a proposal is first sent to the forum in Markdown format so that it can be further edited and available for comments. A changelog is a great tool so that people can see how the idea has developed over time and in response to feedback.

This Markdown-formatted post can eventually become the description text in a proposal sent on-chain.

Engage the community with your draft proposal​

Post a draft of your proposal as a topic in the appropriate category of the forum. Hub Proposals is a catch-all if you are not sure where to post, but there are categories for all types of proposals. Directly engage key members of the community for feedback. These could be large contributors, those likely to be most impacted by the proposal, and entities with high stake-backing (eg. high-ranked validators; large stakers). Alert the entire community to the draft proposal on other platforms such as Twitter, tagging accounts such as the Cosmos Hub account, the Cosmos Governance account, and other governance-focused groups.

Submit your proposal to the testnet​

Before going to mainnet, you can test your proposal on the testnet.

This is a great way to make sure your proposal looks the way you want and refine it before heading to mainnet.

Stage 3: Your On-Chain Proposal​

A majority of the voting community should probably be aware of the proposal and have considered it before the proposal goes live on-chain. If you're taking a conservative approach, you should have reasonable confidence that your proposal will pass before risking deposit contributions. Make revisions to your draft proposal after each stage of engagement.

See the submitting guide for more on submitting proposals.

The deposit period​

The deposit period currently lasts 14 days. If you submitted your transaction with the minimum deposit (10,000 KIMA), your proposal will immediately enter the voting period. If you did not submit the minimum deposit amount, then this may be an opportunity for others to show their support by contributing (and risking) their KIMA as a bond for your proposal. You can request contributions openly and also contact stakeholders directly (particularly stakeholders who are enthusiastic about your proposal). Remember that each contributor is risking their funds, and you can read more about the conditions for burning deposits here.

This is a stage where proposals may begin to get broader attention. Some block explorers display proposals in the deposit period, while others don't show them until they hit the voting period.

A large cross-section of the blockchain/cryptocurrency community exists on Twitter/X. Having your proposal in the deposit period is a good time to engage the so-called 'crypto Twitter' Kima community to prepare validators to vote (eg. tag @cosmosvalidator) and KIMA-holders that are staking (eg. tag @cosmoshub, @CosmosGov).

The voting period​

At this point you will want to track which validator has voted and which has not. You'll want to re-engage directly with top stake-holders, ie. the highest-ranking validator operators, to ensure that:

• They are aware of your proposal

• They can ask you any questions about your proposal; and

• They are prepared to vote.

Remember that any voter may change their vote at any time before the voting period ends. That historically doesn't happen often, but there may be an opportunity to convince a voter to change their vote. The biggest risk is that stakeholders won't vote at all (for a number of reasons). Validator operators tend to need multiple reminders to vote.

How you choose to contact validator operators, how often, and what you say is up to you--remember that no validator is obligated to vote, and that operators are likely occupied by competing demands for their attention. Take care not to stress any potential relationship with validator operators.

The Kima Transaction Widget is a ready made React component that allows users to transfer like assets between chains using the Kima protocol. Combined with the Kima Transaction Backend, it is the quickest way to integrate Kima into your dApp.

Modes

The Kima Transaction Widget supports 3 modes:

1. Payment

2. Bridge

3. Status

Payment

I.e. Pay 12.34 USDC from Polygon or Solana

Bridge

I.e. Send 12.34 USDT on BSC and receive USDC on Arbitrum

Status

Genesis File Governance Parameters

"gov": {
      "starting_proposal_id": "1",
      "deposits": [],
      "votes": [],
      "proposals": [],
      "deposit_params": {
        "min_deposit": [
          {
            "denom": "uKIMA",
            "amount": "100000000000"
          }
        ]
      },
      "voting_params": null,
      "tally_params": null,
      "params": {
        "min_deposit": [
          {
            "denom": "uKIMA",
            "amount": "10000000"
          }
        ],
        "max_deposit_period": "300s",
        "voting_period": "200s",
        "quorum": "0.334000000000000000",
        "threshold": "0.500000000000000000",
        "veto_threshold": "0.334000000000000000",
        "min_initial_deposit_ratio": "0.000000000000000000",
        "burn_vote_quorum": false,
        "burn_proposal_deposit_prevote": false,
        "burn_vote_veto": true
      }
    },

Kima Use Cases for Developers

As a developer, what can you build with Kima? In order to onboard more users to Web3, we need to simplify the user experience, which means helping them avoid complicated procedures on bridging applications that may or may not be safe to use.

Integrating with Kima's SDK or front-end widget removes the need for your users to leave your dApp and enables them to effortlessly switch funds between networks with the click of a button.

You could think about using Kima for:

Decentralized Exchanges (DEX)

eCommerce and Gaming

In-game payments can slow down the user experience and add unwanted friction. If your users also have to bridge their funds between chains, this can introduce frustration and boredom that may lead to them abandoning your game completely. Kima's smooth, intuitive transactions will mean your users barely notice them.

Similarly, buyers on eCommerce sites are more likely to proceed through the sales funnel if their experience is not impeded by having to visit a separate bridging application.

NFT Marketplace

NFT collectors are no longer limited to one or two chains, and some of the coolest up-and-coming collections can be found on minority chains where fees are cheaper and transactions are faster. Make your marketplace effortlessly multi-chain by integrating Kima.

Wallet

Wallet developers looking for an easy, intuitive way for their users to swap assets in-wallet need to look no further than Kima.

Essentially, as the number of networks within the thriving Web3 ecosystem expands, the need for sending value securely and quickly from one chain to another has become a pressing need.

Add the widget to your React project using npm or your favorite javascript package manager.

npm install @kimafinance/kima-transaction-widget redux react-redux pino-pretty

You'll need to add the following:

• The <KimaProvider> component in App.tsx

• The <KimaTransactionWidget> which interacts with Kima

• A link to the Kima Transaction Backend (or build your own)

• A WalletConnect project id

For the purposes of this example, we'll just add the widget to App.tsx, but it can go anywhere it makes sense for your project.

Open App.tsx, wrap your existing componts with the <KimaProvider> and add the <KimaTransactionWidget> component.

If you don't have one already, you'll need to get a (free) WallectConnect project ID from Reown Cloud and add it to the <KimaProvider> component.

import React from 'react'

import {
  KimaTransactionWidget,
  KimaProvider,
  ModeOptions,
  NetworkOptions,
  ColorModeOptions
} from '@kimafinance/kima-transaction-widget'
import '@kimafinance/kima-transaction-widget/index.css'

const App = () => {
  return (
    <KimaProvider
      walletConnectProjectId='your-project-id'
      networkOption={NetworkOptions.testnet}
    >
      <KimaTransactionWidget
        theme={{ colorMode: ColorModeOptions.light }}
        mode={ModeOptions.bridge}
        kimaBackendUrl='http://localhost:3001'
      />
    </KimaProvider>
  )
}

export default App

In the following sections, we'll go through the framework specific configuration for Vinalla React and NextJS.

This is a web server that works as middleware between the Kima Transaction Widget and Kima Chain. Once it receives a transaction request from the widget, it will submit a transaction to Kima Chain signed by a local wallet.

The server is an Express application and requires minimal setup. Here are the instructions:

Create a wallet for development purposes

We recommend Keplr, which is a widely used wallet for blockchains within the Cosmos ecosystem.

Install it from here and make sure you back it up by saving the seed phrase.

You will need to record the mnemonic seed phrase rather than the private key, as the seed phrase is used as an environment variable.

⚠️ In order to connect to the Kima chain (both Mainnet and Sardis Testnet), you will need to get your Kima address whitelisted. Please contact us at dev@kima.finance with your public address- it will start with kima1. This is a temporary measure to combat spammers.

Get some KIMA tokens to use for transaction fees

If you are developing on the KIMA testnet, you can acquire test KIMA tokens from our faucet site. For mainnet, there is a list of exhanges where you can buy KIMA tokens here.

Follow the instructions here if you have not used a faucet before.

Clone the repo at:

https://github.com/kima-finance/kima-transaction-backend

Set your environment variables

If you are using Docker, create the following files, copy the appropriate sections of the .env.sample, and fill in the missing values:

• /env/dev.env

• /env/prod.env

For local development, create a .env file in the root directory. These files will be ignored by git, but the .env.sample is not so do NOT accidently fill in the sample values!

A few notes about these environment variables:

KIMA_BACKEND_MNEMONIC is the seed phrase from the wallet you installed. Never share this with anyone. Never commit this to a code repository. Use a secret manager service like Google Secret Manager or AWS Secrets Manager to store your seed phrase instead of putting it in the .env file.

KIMA_ENVIRONMENT is separate from the NODE_ENV variable and determines wether information endpoints like /chains will return testnet or mainnet values.

DOMAIN is a comma separated list of urls that the server will accept requests from. All other domains will be blocked (except in the dev environment). Put the url of your frontend here.

COMPLIANCE_URL (OPTIONAL) If your app needs to block non-compliant addresses contact us for more information and the url to use here.

Mainnet

Here are the mainnet specific environment variables. See the .env.sample for the most up to date list of ENV variables and default values. The other vars you will need to fill in with your specific values.

KIMA_BACKEND_FEE_URL=https://fee.kima.network
KIMA_BACKEND_NODE_PROVIDER=https://rpc.kima.network
KIMA_BACKEND_NODE_PROVIDER_GRAPHQL=https://graphql.kima.network/v1/graphql
KIMA_BACKEND_NODE_PROVIDER_QUERY=https://api.kima.network
KIMA_ENVIRONMENT=mainnet
KIMA_EXPLORER=https://explorer.kima.network

Testnet

KIMA_BACKEND_FEE_URL=https://fee.sardis.kima.network
KIMA_BACKEND_NODE_PROVIDER=https://rpc-testnet.kima.finance
KIMA_BACKEND_NODE_PROVIDER_GRAPHQL=https://graphql.sardis.kima.network/v1/graphql
KIMA_BACKEND_NODE_PROVIDER_QUERY=https://api.sardis.kima.network
KIMA_ENVIRONMENT=testnet
KIMA_EXPLORER=https://explorer.sardis.kima.network

Install and start

You can run:

npm install

then

npm run dev

Or use Docker. Use docker-compose.yml for dev, and docker-compose-prod.yml for prod.

Start the server with:

docker compose up

Test the installation

In your terminal, run the following command:

Copy

curl -i -H "Accept: application/json" -H "Content-Type: application/json" -X POST http://localhost:3001/auth

The server should respond with "ok".

Available routes

See OpenAPI documentation at /docs for more details (only available when NODE_ENV is development). The following is an overview of how the routes are used together.

• Get various info for the frontend from /chains/* like supported chains, tokens, pool addresses, etc.

• GET /submit/fee: get the service fees and allowance amounts

  • The totalFeeUsd property is the total fees in USD and is intentially formatted as a number for display purposes.

  • Returns a ready to use allowance amount as a bigint string. Pass this value directly to the contract call. Bigints are used to avoid floating point errors.

  • The approval must be completed before submitting the transaction or the transfer will fail.

  • Use the submitAmount when calling /submit, it is already properly adjusted based on wether the fees are deducted from the amount or not.

  • Use the decimals property to convert to a number if needed eleswhere.

• POST /submit: submit will initiate the Kima Transaction and return a transaction id that can be used to monitor the status of the transaction

• GET /tx/{txId}/status: use the transaction id returned from submit to get the transaction status

Optional Features

Custom Transaction Validation

In /src/custom-transaction-validation.ts you can add your own custom validation logic. Kima does not know the requirements of your app, so it is up to you to make sure the transction makes sense. This is a convenience function, feel free to modifiy the middlware if you need lower level access.

The customTransValidation function

• Will be called in middleware after basic param validation and before the /submit route handler is called

• Should return a string with the error message or the empty string if the transaction is valid.

The following are some example of things you may want to check:

• When accepting cross chain payment for goods and services

  • Ensure the targetAddress is your app's payment address

  • Check the chains are supported by your app

const SUPPORTED_CHAINS = ["ARB", "SOL"];
const isSupportedChain = (chain: string) => SUPPORTED_CHAINS.includes(chain);

export const customTransValidation = async (
  req: SubmitTransRequest
): Promise<string> => {
  const { originChain, targetAddress, targetChain } = req.body;

  // check if the target address is your app's payment address
  if (targetAddress !== (process.env.PAYMENT_ADDRESS as string)) {
    return "invalid target address";
  }

  // check if the chains are supported by your app
  if (!isSupportedChain(originChain)) {
    return "invalid origin chain";
  }

  if (!isSupportedChain(targetChain)) {
    return "invalid target chain";
  }

  // Transaction is valid
  return "";
};

Compliance

If enabled by suppling the COMPLIANCE_URL environment variable, GET /compliant will check if an address meets compliance requirements- is not sanctioned, blocked, etc.

Use this in the frontend to check if an address is not compliant BEFORE doing the ERC20 approval. When compliance is enabled, the /submit endpoint will return status 403 (Forbidden) if an address is not compliant.

If you are interested in using compliance contact us for more information and the url to use here.

KYC

If using the KYC in the widget:

• GET /uuid will return the external identifier you need

• POST /kyc returns the KYC status for a specific uuid verification session

Again, please contact us for more information on how to implement this feature.

The procedure for adding the Kima Transaction Widget to a NextJS app is very similar to the React tutorial but you should be aware that you will need to export the widget component as a dynamic component with {ssr: false} so that the application runs the widget on the client side.

To create a new app, you can run npx create-next-app <your-app-name>. Then install the Kima Widget and its peer dependencies.

npm install @kimafinance/kima-transaction-widget redux react-redux pino-pretty

You'll need to add the following:

• The <KimaProvider> component in App.tsx

• The <KimaTransactionWidget> which interacts with Kima

• A link to the Kima Transaction Backend (or build your own)

• A WalletConnect project id

If you don't have one already, you'll need to get a (free) WallectConnect project ID from Reown Cloud and add it to the <KimaProvider walletConnectProjectId='your-project-id' /> component.

Within your app directory, create a components directory and inside that create a file named widget.jsx with the following code:

Copy

import dynamic from "next/dynamic";
import React from "react";

import {
  KimaTransactionWidget,
  KimaProvider,
  ModeOptions,
  NetworkOptions,
  ColorModeOptions,
} from "@kimafinance/kima-transaction-widget";
import "@kimafinance/kima-transaction-widget/index.css";

const App = () => {
  return (
    <KimaProvider
      walletConnectProjectId="your-project-id"
      kimaBackendUrl="http://localhost:3001"
    >
      <KimaTransactionWidget
        theme={{ colorMode: ColorModeOptions.light }}
        mode={ModeOptions.bridge}
      />
    </KimaProvider>
  );
};

const DynamicApp = dynamic(() => Promise.resolve(App), {
  ssr: false,
});

export default DynamicApp;

You can now use DynamicApp on whatever page you like. In our example, we will create an index page index.jsx in our pages directory and copy the following code:

Copy

import React from "react";
import DynamicApp from "../components/widget";

const HomePage = () => {
  return <DynamicApp />;
};

export default HomePage;

When you visit localhost:3000 you will see something like this:

See the Configuration options section for more details on setting up the widget.

Add the widget to your React project using npm or your favorite javascript package manager.

npm install @kimafinance/kima-transaction-widget redux react-redux pino-pretty

You'll need to add the following:

• The <KimaProvider> component in App.tsx

• The <KimaTransactionWidget> which interacts with Kima

• A link to the Kima Transaction Backend (or build your own)

• A WalletConnect project id

For the purposes of this example, we'll just add the widget to App.tsx, but it can go anywhere it makes sense for your project.

Open App.tsx, wrap your existing componts with the <KimaProvider> and add the <KimaTransactionWidget> component.

If you don't have one already, you'll need to get a (free) WallectConnect project ID from Reown Cloud and add it to the <KimaProvider> component.

import React from "react";

import {
  KimaTransactionWidget,
  KimaProvider,
  ModeOptions,
  NetworkOptions,
  ColorModeOptions,
} from "@kimafinance/kima-transaction-widget";
import "@kimafinance/kima-transaction-widget/index.css";

const App = () => {
  return (
    <KimaProvider
      walletConnectProjectId="your-project-id"
      kimaBackendUrl="http://localhost:3001"
    >
      <KimaTransactionWidget
        theme={{ colorMode: ColorModeOptions.light }}
        mode={ModeOptions.bridge}
      />
    </KimaProvider>
  );
};

export default App;

There are several configuration options, which will described in theConfiguration options section on setting up the widget.

Polyfills

Note that if you are using a later version of webpack (>= 5), you will need to polyfill node core modules using react-app-rewired.

This can be resolved by adding a file at the root of your project named config-overrides.js. Paste the following content into the file:

const { ProvidePlugin } = require("webpack");

module.exports = function override(config, env) {
  return {
    ...config,
    module: {
      ...config.module,
      rules: [
        ...config.module.rules,
        {
          test: /\.js$/,
          enforce: "pre",
          use: ["source-map-loader"],
        },
        {
          test: /\.cjs$/,
          type: "javascript/auto",
        },
        {
          test: /\.wasm$/,
          type: "webassembly/async",
        },
        {
          test: /\.m?js/,
          type: "javascript/auto",
        },
        {
          test: /\.m?js/,
          resolve: {
            fullySpecified: false,
          },
        },
        {
          test: /\.json$/,
          use: "json-loader",
          type: "javascript/auto", // This is important to prevent Webpack 5 from treating JSON as ESM
        },
      ],
    },
    plugins: [
      ...config.plugins,
      new ProvidePlugin({
        Buffer: ["buffer", "Buffer"],
        process: "process/browser",
      }),
    ],
    resolve: {
      ...config.resolve,
      fallback: {
        assert: "assert",
        buffer: "buffer",
        console: "console-browserify",
        constants: "constants-browserify",
        crypto: "crypto-browserify",
        domain: "domain-browser",
        events: "events",
        fs: false,
        http: "stream-http",
        https: "https-browserify",
        os: "os-browserify/browser",
        path: "path-browserify",
        punycode: "punycode",
        process: "process/browser",
        querystring: "querystring-es3",
        stream: "stream-browserify",
        _stream_duplex: "readable-stream/duplex",
        _stream_passthrough: "readable-stream/passthrough",
        _stream_readable: "readable-stream/readable",
        _stream_transform: "readable-stream/transform",
        _stream_writable: "readable-stream/writable",
        string_decoder: "string_decoder",
        sys: "util",
        timers: "timers-browserify",
        tty: "tty-browserify",
        url: "url",
        util: "util",
        vm: "vm-browserify",
        zlib: "browserify-zlib",
      },
    },
    experiments: {
      asyncWebAssembly: true,
    },
    ignoreWarnings: [/Failed to parse source map/],
  };
};

Example

The easiest way to see the widget working, including the polyfill workaround, is to check out the example in the widget repo.

mode = ModeOptions.payment

Payment mode allows your users to pay for a product or service using stablecoins from any chain supported by Kima.

• The payment details are passed into the Widget via the transactionOption prop (required)

• The user can choose to pay from any chain and token supported by Kima. The funds will be transferred to the wallet and chain specified in the transactionOption prop

• The title and subtile can be customized using the titleOption and paymentTitleOption props

import React from "react";

import {
  KimaTransactionWidget,
  KimaProvider,
  ModeOptions,
  SupportNetworks,
  ColorModeOptions,
} from "@kimafinance/kima-transaction-widget";
import "@kimafinance/kima-transaction-widget/dist/index.css";

const App = () => {
  return (
    <KimaProvider kimaBackendUrl="http://localhost:3001">
      <KimaTransactionWidget
        theme={{ colorMode: ColorModeOptions.light }}
        mode={ModeOptions.payment}
        titleOption={{
          initialTitle: "New Purchase",
        }}
        paymentTitleOption={{
          title: "Buy MyFirst NFT",
          style: {
            fontSize: "1.2em",
            fontWeight: "500",
            color: "#DDDDDD",
          },
        }}
        transactionOption={{
          targetChain: SupportNetworks.SOLANA,
          targetAddress: "5tvyUUqPMWVGaVsRXHoQWqGw6h9uifM45BHCTQgzwSdr",
          amount: 12.34,
          currency: "USDK",
        }}
      />
    </KimaProvider>
  );
};

export default App;

You should see a page that looks like this:

The payment (target) wallet and chain will show on the next step when the user approves the transfer amount.

Once the user sends the approval and submits the transaction, the user can see the transaction status in the next step.

For more details on how to get transaction status of a previous transaction, check the Widget Status Mode Section.

Configuration options

Configure the widget's look and feel

There are numerous ways to configure the Widget for your own preferences and the look and feel of your dApp, which you can do via the following props:

Theme

The Theme prop controls whether the Widget is in light or dark mode and their background colours:

• Required

• Type: ThemeOptions

  • colorMode (required): ColorModeOptions.light | ColorModeOptions.dark

  • backgroundColorLight (optional): string

  • backgroundColorDark (optional): string

Title

The Title prop enables you to give the widget whatever title you want and can be configured for each step of the widget.

• Optional

• Type: TitleOption:

  • initialTitle (optional): string

  • confirmTitle (optional): string

Payment Title

The PaymentTitle prop allows you to optionally set the title that appears on the payment screen if you are using the Payment component.

• Optional

• Type: PaymentTitleOption

  • title (optional): string

  • style (optional): object

HelpUrl

This is a string, which should be to your own help documentation or FAQ. If unset, the link will default to Kima's help documentation.

• Optional

• Type: string

mode: Configure the widget's functionality

• Required: true

• Type: ModeOptions

Used to specify the transaction flow scenario of the Widget. See the individual scenarios for more information.

TransactionOption

Sets the default chain, wallet, and amount in the Widget. Required for the Payment mode, optional for the Bridge mode.

• Payment mode: Required, Bridge mode: Optional

• Type: TransactionOption

  • targetChain (optional): SupportNetworks

  • targetAddress (optional): string

  • amount (optional): number

  • currency (optional): string

kimaBackendUrl

• Required: true

• Type: string

excludedSourceNetworks, excludedTargetNetworks

• Optional

• Type: string[]

• Default: []

Chain names to exlude from the widget. Users will not be able to select these chains in the widget. Useful for compliance reasons or to exclude chains not supported by your app.

There is currently no opton to do the opposite- i.e. explicity specify which chains to include.

Excluded target networks will have no effect in payment mode as the target chain, address, and amount are already explicity set.

txID

Used in Status mode to specify the transaction to track progress for. Only used in status mode, ignored otherwise.

• Status mode: Required, ignored otherwise

• Type: boolean

• Default: -1

Compliance

compliantOption

• Required: false

• Type: boolean

• Default: false

If your app requires compliance checks, please contact us for more information. When false (the default), compliance checks are disabled.

Configure Kima Provider

Used to provide the widget with wallet connection, custom state handlers and backend endpoint.

kimaBackendUrl

Endpoint that will be used as intermediary to communicate with the kima blockchain. It's needed to fetch network mode, chains details and submit transactions through the sdk. This is one of the few props that is mandatory to set, because there are several enpoints which the Widget expects to exist on the Backend. The examples assume the backend server is running locally at localhost:3001. Replace this with the URL of your backend.

• Required: true

• type: string

walletConnectProjectId

• Required: true

• Type: string

externalProvider

If there is already a wallet connection logic elsewhere in your app, an external provider can be passed in. Otherwise, the widget will handle the connection logic on its own.

• Required: false

• Type: ExternalProvider

errorHandler

• Optional

• Type: function

Called when an error occurs. Useful for debugging and logging.

closeHandler

• Optional

• Type: function

Called when the widget is closed.

successHandler

• Optional

• Type: function

Called when the transaction is successful.

mode = ModeOptions.bridge

Bridge mode allows your users to transfer similar assets between any chain supported by Kima. I.e. USDC on Arbitrum to USDT on Avalance.

const App = () => {
  return (
    <KimaProvider kimaBackendUrl="http://localhost:3001">
      <KimaTransactionWidget
        theme={{ colorMode: ColorModeOptions.light }}
        mode={ModeOptions.bridge}
      />
    </KimaProvider>
  );
};

On testnet it should look something like this. The test tokens are called USDK and can be obtained from the Kima faucet.

The transfer details will show on the next step, along with the fee options available. The confirmation step will also request user approval on the final transfer amount.

The transaction status will be displayed on the next step when the user approves the transfer amount and submits the transaction.

For more details on how to get transaction status of a previous transaction, check the Widget Status Mode Section.

mode = ModeOptions.status

Status mode displays the progress of a transaction that has already been submitted to Kima. This is useful if the normal flow was interrupted and the status needs to be displayed again. Usually the transaction status view will display automatically after the user approves and submits the transaction.

⚠️ txId is the transaction id returned from the /submit endpoint- not the transaction hash. I.e 22843

const App = () => {
  return (
    <KimaProvider kimaBackendUrl="http://localhost:3001">
      <KimaTransactionWidget
        theme={{ colorMode: ColorModeOptions.dark }}
        mode={ModeOptions.status}
        txId={22843}
      />
    </KimaProvider>
  );
};

You would see a page that looks like this:

If you want to allow users to get a previous transaction from the UI, you must not provide the txId prop to the KimaTransactionWidget component. This will display the transaction search form.

If the transaction id is valid, and the transaction is found, the corresponding progress of the transaction will be displayed.

Using Kima SDK without the widget

The Kima Widget serves as a reference implementation written in React. If your project uses another framework, or you want to make a custom component, it’s possible to interact with the Kima Transaction Backend directly.

Transaction Flow

1. User selects the origin and target chains and amount

2. User approves Kima to transfer origin tokens

3. The transaction details are submitted to the Kima Transaction Backend

4. The UI polls the Kima GraphQL endpoint for status updates until the transaction has completed

Reference Implementation

The React component on the Kima Github:

Selecting Chains and Amount

The frontend component will need to provide the following information. This will be used to calculate the service fee and the approval for Kima to move tokens on behalf of the user.

• Origin (from)

  • chain: this is the chain the user tokens will come from

  • token: the (stable coin) token the user will pay with (or bridge from)

  • address: the source user address- i.e. the connected user

  • amount: the amount of tokens to transfer

• Target (to)

  • Chain: the destination chain

  • Token: the (stable coin) token being delivered

    • In a payment scenario this will be the same as the origin token

  • Address: the receiving address

    • In a bridge transaction this will be same as the connected user

Supported Chains and Tokens

In order for Kima to move tokens on behalf of the user an on chain approval needs to happen. An approval has 3 components:

• Owner address: User

• Spender address: Kima Pool

• Total amount: origin token amount plus gas fees

Getting the Kima Pool Address

Using the Kima Backend

GET /chains/pool returns a list of pool addresses and balances for all supported chains.

Using the Kima API

You can also obtain the pool addresses from the TSS endpoint. Use the type in the chart above to determine which one to use.

GET https://api.sardis.kima.network/kima-finance/kima-blockchain/kima/tss_pubkey

Success Response:

• tssPubkey (array object)

  • tssPubKey: string

  • ecdsa: string

  • eddsa: string

  • reserved: string

• pagination (object)

  • nextKey: string | null

  • total: number

Note: for Tron, the hex ecdsa address must be converted to a base 58 checksum address.

Getting the Service Fee

Using theKima Backend

To calculate the total amount, the service (gas) fees are needed. The Kima Backend has an endpoint that does all the calculations for you.

/submit/fees?amount=10&originChain=TRX&targetChain=ARB&deductFee=true&originSymbol=USDK

Success Response:

• totalFee (bigint string): sum of all fees in USD

• totalFeeUsd (number): sum of all fees in USD

• allowanceAmount (bigint string): the token amount that needs to be approved. Can be passed directly to the contract call.

• decimals (number): the number of decimals for the bigint amounts

• deductFee (boolean): whether the fees are deducted from the amount or not

• submitAmount (bigint string): the amount that needs to be passed to the /submit endpoint

• breakdown: individual fees

  • amount: fee amount

  • feeType: 'gas' | 'service'

  • chain: chain short name

Chain Names

Using the Kima API

The Kima gas fee estimation endponts can also be called directly. In this case it is necessary to make 2 calls, one for the source chain and one for the target chain. Then the results can be combined to get the total fee.

The Kima API endpoint will soon be updated to perform the same calculations as the Kima Backend. We recommend using the Kima Backend for now.

GET https://fee.kima.network/fee/{chainName}

Example: https://fee.kima.network/fee/AVX

Response

• result: boolean

• fee: string: dash delimited list <Amount USD>-<Timestamp>-<Amount Crypto>

• Amount USD: the service fee amount in USD

• Timestamp: Javascript timestamp in milliseconds

• Amount Crypto: the fee amount in the native token of the given chain- i.e. AVAX

Calculating the Service Fee

To calculate the total service fee requires querying for the fees on both the source and target chains using the endpoint described above. There are a couple exceptions:

The fee is ZERO in the following cases as it is handled elsewhere:

• Source or target chain is FIAT

• Target chain is BTC

There is a constant value when the source chain is BTC:

• Source chain is BTC: 0.0004 BTC

Since the source and target chains can be different, the USD amount fee amounts should be used and added together. The user will pay the fee using the source token. Remember, even stable coins are not exactly one USD, so the USD fee amount should be converted into the source token amount using the USD price of the source token.

Code Sample

Putting it all together, the following is a typescript code example that queries the endpoint and calculates the total service fee.

Calculate the Approval Amount

Using the Kima Backend

Use the allowanceAmount property returned from the /submit/fees endpoint.

Using the Kima API

The approval amount will be different when deducting the fees or not.

• When deducting the fees, the approval should be just the amount

• Otherwise, the approval should be the amount plus the fees

Calling Approve

Once all the info has been collected it’s time to make the on chain call. The exact details of how this is done depends on the origin chain and library used.

The getClientsForChain() and getPoolAdressesForChain() would be utility functions defined elsewhere.

From the Kima Backend

Using the Kima Backend, you can get the transaction status by calling two /tx endpoints depending on the type of transaction.

For regular transactions: GET /tx/:txId/status

For liquidity pool transactions: GET /tx/lp/:txId/status

Parameters:

• txId number: the transaction id number. This is a sequential number assigned to each transaction, NOT the transaction hash (tx_id below).

Success Response:

From the Kima Subgraph

Once the transaction has been submitted to the Kima Transaction Backend, you’ll want to display the transaction progress in the frontend. There are 2 GraphQL queries on the Kima subgraph for this purpose.

• Mainnet Kima Subgraph url: https://graphql.kima.finance/v1/graphql

• Sardis Testnet url: https://graphql.sardis.kima.network/v1/graphql

Here is a code snippet for regular transactions using plain fetch. See the docs for your favorite graphql client for constructing queries.

For liquidity pool transactions:

Once the user has approved the token transfer, it’s time to construct the submit request to the Kima Transaction Backend.

Calculate the Submit Amount

Using the Kima Backend

Use the submitAmount property returned from the /submit/fees endpoint.

Using the Kima API

The submit amount should always be the amount the target addreess will receive. This means the submit amount needs to be adjusted based on whether the fees are deducted from the amount or not.

function getSubmitAmount(
  amount: bigint,
  fees: bigint,
  deductFee: boolean
): bigint {
  return deductFee ? amount - fees : amount;
}

Submitting the Transaction

POST /submit Request Body:

• originAddress (Address): sending user address

• originChain (string): sending chain

• originSymbol (string): sending token symbol

• targetAddress (Address): receiving user address

• targetChain (string): receiving chain

• targetSymbol (string): receiving token symbol

• amount (bigint string): amount of token received by the target address

• fee (bigint string): amount of token that Kima consumes to pay gas fees for pulling & releasing token transactions

• decimals (number): the number of decimals for the bigint amounts

• For Bitcoin transactions:

  • Set these to the empty string or zero for non-BTC transactions

  • htlcCreationHash (string): the tx hash locking the funds in the HTLC

  • htlcCreationVout (number): the output index of the locked funds in the HTLC creation transaction

  • htlcExpirationTimestamp (string): the timestamp when the HTLC contract expires and the user can reclaim the funds locked there

  • htclVersion (string)

  • senderPubKey (string): for bitcoin transactions this is the public key of the sender

Success Response:

• height: number

• txIndex: number

• code: number: error code; will be zero when successful

• transactionHash: string

• events: Event[]

  • type: string

  • attributes: Attribute[]

    • key: string

    • value: string

• rawLog?: string

• data?: MsgData[]

• msgResponses: Uint8Array

• gasUsed: bigint

• gasWanted: bigint

Chain Names

See the short names in the Supported Blockchains section.

Get Transaction Id

The transaction Id will be needed to get the transaction status. The following code can be used to extract the Id from the submit response.

export function getTransactionId(submitResult: any): number {
  let txId = -1;
  if (result?.code !== 0) {
    return txId;
  }

  for (const event of result.events) {
    if (event.type === "transaction_requested") {
      for (const attr of event.attributes) {
        if (attr.key === "txId") {
          txId = attr.value;
        }
      }
    }
  }

  return txId;
}

Authentication

Before calling submit a JWT token must be obtained with the body payload. The JWT will be checked against the request body and if it does not match will respond with a 500 error.

Validation

If provided, the Kima Backend will use the Explorisk url defined in the ENV var XPLORISK_URL to get the risk score for the origin and target user addresses. If the score is anything other than low it will respond with a 500 error.