The Kima Transaction Back End

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 [e-mail] with your public address- it will start with kima1. This is a temporary measure to combat spammers.

You can find your Kima address in the Kepler wallet by

• Clicking the "Copy Address" button

• Find "Kima" in the list of chains

• Click the "Copy Address" button

If you have not yet added the Kima Network to Kepler, you can enter "Kima" in the "Search for a chain" field when copying the address.

Get Kima Address from Kepler wallet

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://fcs.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
PAYMENT_PARTNER_ID=Kima

Testnet

KIMA_BACKEND_FEE_URL=https://fcs.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
PAYMENT_PARTNER_ID=KimaTest

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 "";
};

Chain Filtering

Chain filtering is an optional feature that can be enabled by setting the KIMA_CHAIN_FILTER environment variable. This will:

• Filter the chains returned by the /chains endpoint and therefore the options listed in the React component

• Restricts the allowed chains for the /submit endpoint causing a 400 error if the chain is not allowed

It supports two modes:

• whitelist: Only chains in the whitelist will be returned.

• blacklist: Only chains not in the blacklist will be returned.

This is a JSON object with the following structure:

• origin: Filter for the origin chain

  • mode: The mode to use. Can be whitelist or blacklist

  • chains: An array of chain short names to filter

• target: Filter for the target chain

  • mode: The mode to use. Can be whitelist or blacklist

  • chains: An array of chain short names to filter

Example: only ARB and OPT chains are allowed for the origin and all chains except TRX are allowed for the target:

{
  "origin": {
    "mode": "whitelist",
    "chains": ["ARB", "OPT"]
  },
  "target": {
    "mode": "blacklist",
    "chains": ["TRX"]
  }
}

Example filerting out only the "Credit Card" network:

{
  "origin": {
    "mode": "blacklist",
    "chains": ["CC"]
  },
  "target": {
    "mode": "blacklist",
    "chains": ["CC"]
  }
}

The stringified version:

KIMA_CHAIN_FILTER='{"origin":{"mode":"blacklist","chains":["CC"]},"target":{"mode":"blacklist","chains":["CC"]}}'

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.