InterchainJS

A single, universal signing interface for any network. Birthed from the interchain ecosystem for builders. Create adapters for any Web3 network.

install

npm install interchainjs

Table of Contents

• InterchainJS
• Install
• Introduction
• Overview
• Tutorials & Documentation
  • RPC Clients
  • Tree Shakable Helpers
  • Module-Specific Helpers
• Connecting with Wallets and Signing Messages
  • Initializing the Signing Client
  • Creating Signers
  • Broadcasting Messages
  • All In One Example
• Amino Helpers
• Auth
• Crypto Helpers
• Encoding Helpers
• Math Helpers
• Pubkey Helpers
• Supported Networks
  • Cosmos Network
  • Injective Network
  • Ethereum Network
• Developing
  • Codegen
• Interchain JavaScript Stack ⚛️
• Credits
• Disclaimer

InterchainJS: Universal Signing for Web3

InterchainJS is a universal signing interface designed for seamless interoperability across blockchain networks. It is one of the core libraries of the Interchain JavaScript Stack, a modular framework that brings Web3 development to millions of JavaScript developers.

At its core, InterchainJS provides a flexible adapter pattern that abstracts away blockchain signing complexities, making it easy to integrate new networks, manage accounts, and support diverse authentication protocols and signing algorithms—all in a unified, extensible framework.

Overview

InterchainJS sits at the foundation of the Interchain JavaScript Stack, a set of tools that work together like nested building blocks:

• InterchainJS → Powers signing across Cosmos, Ethereum (EIP-712), and beyond.
• Interchain Kit → Wallet adapters that connect dApps to multiple blockchain networks.
• Interchain UI → A flexible UI component library for seamless app design.
• Create Interchain App → A developer-friendly starter kit for cross-chain applications.

This modular architecture ensures compatibility, extensibility, and ease of use, allowing developers to compose powerful blockchain applications without deep protocol-specific knowledge.

Visualizing InterchainJS Components

The diagram below illustrates how InterchainJS connects different signer types to various network classes, showcasing its adaptability for a wide range of blockchain environments.

graph LR
    signers --> cosmos_signer["Cosmos Network"]
    signers --> injective_signer["Injective Network"]
    signers --> ethereum_signer["Ethereum Network"]
    signers --> implement_signer["ANY Network"]

    cosmos_signer --> cosmos_amino["Amino Signer"]
    cosmos_signer --> cosmos_direct["Direct Signer"]

    ethereum_signer --> ethereum_eip712["EIP712 Signer"]

    injective_signer --> injective_amino["Amino Signer"]
    injective_signer --> injective_direct["Direct Signer"]

    implement_signer --> any_signer["Any Signer"]

    style signers fill:#f9f,stroke:#333,stroke-width:2px

graph LR
    encoders[Encoders] --> auth["@interchainjs/auth"]
    encoders --> utils["@interchainjs/utils"]
    encoders --> cosmos_types["@interchainjs/cosmos-types"]

    auth --> secp256k1_auth["Secp256k1 Auth"]
    auth --> ethSecp256k1_auth["EthSecp256k1 Auth"]

    utils --> signer_utils["Signer Utilities"]
    utils --> crypto_utils["Crypto Utilities"]

    style encoders fill:#f9f,stroke:#333,stroke-width:2px
    style auth fill:#ccf,stroke:#333,stroke-width:2px
    style utils fill:#ccf,stroke:#333,stroke-width:2px

Tutorials & Documentation

The following resources provide comprehensive guidance for developers working with InterchainJS. Whether you're setting up a new application, implementing custom signers, or exploring advanced features, these tutorials and documentation will help you leverage the full power of InterchainJS across various blockchain networks.

RPC Clients

RPC (Remote Procedure Call) clients enable communication between your application and blockchain networks. InterchainJS provides a flexible and type-safe way to create these clients, allowing you to query blockchain data with minimal configuration. The following example demonstrates how to create and use an RPC client to query data from a Cosmos-based blockchain.

import { getAllBalances } from "@interchainjs/cosmos/bank/v1beta1/query.rpc.func";

{ getRpcEndpoint } = useChain("cosmoshub");

const endpoint = await getRpcEndpoint();

// now you can query the cosmos modules
const balance = await getAllBalances(endpoint,{
  address: "cosmos1addresshere",
});

Tree Shakable Helpers

InterchainJS provides tree shakable helper functions to optimize your application's bundle size. These helpers follow a factory pattern that allows modern JavaScript bundlers to eliminate unused code through tree shaking. These helpers improve modularity and optimize performance by allowing you to import only the functionality you need. Tree shakable tutorial video: https://youtu.be/3dRm9HEklMo

How Tree Shakable Helpers Work

Each helper function is individually exported (e.g., getAllBalances). This pattern enables:

1. Bundle Size Optimization: Only the functions you import and use are included in your final bundle
2. Lazy Initialization: Helper functions are only constructed when explicitly called
3. Customizable Configuration: Each helper can be configured with specific parameters

For example, query helpers are functions that return other functions, constructed with specific parameters:

// Import only what you need
import { getAllBalances } from "@interchainjs/cosmos/bank/v1beta1/query.rpc.func";

// Now you can query the blockchain
const balance = await getAllBalances(endpoint, {
  address: "cosmos1addresshere",
});

Available Helper Types

InterchainJS provides two main types of tree shakable helpers:

1. Query Helpers: For retrieving data from the blockchain

   import { getValidator } from "@interchainjs/cosmos/staking/v1beta1/query.rpc.func";

2. Transaction Helpers: For broadcasting transactions

   import { createDelegate } from "@interchainjs/cosmos/staking/v1beta1/tx.rpc.func";

Example: Combining Query and Transaction Helpers

Here's how you might use both types together in a staking scenario:

// Import helpers
import { getValidator } from "@interchainjs/cosmos/staking/v1beta1/query.rpc.func";
import { delegate } from "@interchainjs/cosmos/staking/v1beta1/tx.rpc.func";

// Query validator info
const { validator } = await getValidator(endpoint, {
  validatorAddr: "cosmosvaloper1...",
});

// Execute delegation
const result = await delegate(
  signingClient,
  signerAddress,
  {
    delegatorAddress: signerAddress,
    validatorAddress: validator.operatorAddress,
    amount: { denom: "uatom", amount: "1000000" },
  },
  fee,
  "Delegation via InterchainJS"
);

By importing only the specific helpers you need, you ensure that your application bundle remains as small and efficient as possible.

Framework Integration

These tree shakable helpers can be used with framework-specific implementations:

• React: Available as hooks in @interchainjs/react

  import { useGetAllBalances } from "@interchainjs/react/cosmos/bank/v1beta1/query.rpc.react";

• Vue: Available as composables in @interchainjs/vue

  import { useGetAllBalances } from "@interchainjs/vue/cosmos/bank/v1beta1/query.rpc.vue";

Examples and Documentation

For detailed usage examples and implementation patterns, refer to the test suite in the starship/tests directory.

Module-Specific Helpers

The following sections provide import examples for various Cosmos SDK modules.

Authz

// query helpers
import {
  getGrants,
  getGranterGrants,
  getGranteeGrants,
} from "@interchainjs/cosmos/authz/v1beta1/query.rpc.func";

// tx helpers
import {
  grant,
  revoke,
  exec,
} from "@interchainjs/cosmos/authz/v1beta1/tx.rpc.func";

Bank

// query helpers
import {
  getAllBalances,
  getDenomMetadata,
  getSupply,
  getParams,
} from "@interchainjs/cosmos/bank/v1beta1/query.rpc.func";

// tx helpers
import {
  send,
  multiSend,
} from "@interchainjs/cosmos/bank/v1beta1/tx.rpc.func";

Circuit

// query helpers
import {
  getAccount,
  getAccounts,
  getDisabledList,
} from "@interchainjs/cosmos/circuit/v1/query.rpc.func";

// tx helpers
import {
  authorizeCircuitBreaker,
  tripCircuitBreaker,
  resetCircuitBreaker,
} from "@interchainjs/cosmos/circuit/v1/tx.rpc.func";

Consensus

// query helpers
import { getParams } from "@interchainjs/cosmos/consensus/v1/query.rpc.func";

// tx helpers
import { updateParams } from "@interchainjs/cosmos/consensus/v1/tx.rpc.func";

Crisis

// tx helpers
import {
  verifyInvariant,
  updateParams,
} from "@interchainjs/cosmos/crisis/v1beta1/tx.rpc.func";

Distribution

// query helpers
import {
  getParams,
  getValidatorDistributionInfo,
  getValidatorOutstandingRewards,
  getValidatorCommission,
  getValidatorSlashes,
  getDelegationRewards,
  getDelegationTotalRewards,
} from "@interchainjs/cosmos/distribution/v1beta1/query.rpc.func";

// tx helpers
import {
  setWithdrawAddress,
  withdrawDelegatorReward,
  withdrawValidatorCommission,
  fundCommunityPool,
  communityPoolSpend,
  updateParams,
} from "@interchainjs/cosmos/distribution/v1beta1/tx.rpc.func";

Evidence

// query helpers
import {
  getEvidence,
  getAllEvidence,
} from "@interchainjs/cosmos/evidence/v1beta1/query.rpc.func";

// tx helpers
import { submitEvidence } from "@interchainjs/cosmos/evidence/v1beta1/tx.rpc.func";

Feegrant

// query helpers
import {
  getAllowance,
  getAllowances,
  getAllowancesByGranter,
} from "@interchainjs/cosmos/feegrant/v1beta1/query.rpc.func";

// tx helpers
import {
  grantAllowance,
  revokeAllowance,
  pruneAllowances,
} from "@interchainjs/cosmos/feegrant/v1beta1/tx.rpc.func";

Gov

// query helpers
import {
  getProposal,
  getProposals,
  getVote,
  getVotes,
  getParams,
  getDeposit,
  getDeposits,
  getTallyResult,
} from "@interchainjs/cosmos/gov/v1beta1/query.rpc.func";

// tx helpers
import {
  submitProposal,
  deposit,
  vote,
  voteWeighted,
} from "@interchainjs/cosmos/gov/v1beta1/tx.rpc.func";

Group

// query helpers
import {
  getGroupInfo,
  getGroupPolicyInfo,
  getGroupMembers,
  getGroupsByAdmin,
  getGroupPoliciesByGroup,
  getGroupPoliciesByAdmin,
} from "@interchainjs/cosmos/group/v1/query.rpc.func";

// tx helpers
import {
  createGroup,
  updateGroupMetadata,
  updateGroupMembers,
  updateGroupAdmin,
  updateGroupPolicyMetadata,
  submitProposal,
  vote,
  exec,
} from "@interchainjs/cosmos/group/v1/tx.rpc.func";

Mint

// query helpers
import {
  getParams,
  getInflation,
  getAnnualProvisions,
} from "@interchainjs/cosmos/mint/v1beta1/query.rpc.func";

// tx helpers
import { updateParams } from "@interchainjs/cosmos/mint/v1beta1/tx.rpc.func";

Nft

// query helpers
import {
  getBalance,
  getOwner,
  getClass,
  getClasses,
  getNFTs,
  getNFT,
} from "@interchainjs/cosmos/nft/v1/query.rpc.func";

// tx helpers
import { send } from "@interchainjs/cosmos/nft/v1/tx.rpc.func";

Staking

// query helpers
import {
  getValidators,
  getValidator,
  getValidatorDelegations,
  getValidatorUnbondingDelegations,
  getDelegation,
  getUnbondingDelegation,
} from "@interchainjs/cosmos/staking/v1beta1/query.rpc.func";

// tx helpers
import {
  createValidator,
  editValidator,
  delegate,
  undelegate,
  redelegate,
} from "@interchainjs/cosmos/staking/v1beta1/tx.rpc.func";

Vesting

// tx helpers
import {
  createVestingAccount,
  createPermanentLockedAccount,
  createPeriodicVestingAccount,
} from "@interchainjs/cosmos/vesting/v1beta1/tx.rpc.func";

CosmWasm

// query helpers
import {
  getContractInfo,
  getContractHistory,
  getContractsByCode,
  getAllContractState,
  getRawContractState,
  getSmartContractState,
  getCode,
  getCodes,
} from "@interchainjs/cosmwasm/wasm/v1/query.rpc.func";

// tx helpers
import {
  storeCode,
  instantiateContract,
  migrateContract,
  updateAdmin,
  clearAdmin,
} from "@interchainjs/cosmwasm/wasm/v1/tx.rpc.func";

IBC

// query helpers
import {
  getParams,
  getDenomHash,
  getEscrowAddress,
  getTotalEscrowForDenom,
} from "@interchainjs/ibc/applications/transfer/v1/query.rpc.func";

// tx helpers
import {
  transfer,
  updateParams,
} from "@interchainjs/ibc/applications/transfer/v1/tx.rpc.func";

Connecting with Wallets and Signing Messages

⚡️ For web interfaces, we recommend using interchain-kit. Continue below to see how to manually construct signers and clients.

Here are the docs on creating signers in interchain-kit that can be used with Keplr and other wallets.

Initializing the Signing Client

Use SigningClient.connectWithSigner to get your SigningClient:

import { SigningClient } from "@interchainjs/cosmos/signing-client";

const signingClient = await SigningClient.connectWithSigner(
  await getRpcEndpoint(),
  new AminoGenericOfflineSigner(aminoOfflineSigner)
);

Creating Signers

To broadcast messages, you can create signers with a variety of options:

• interchain-kit (recommended)
• keplr

Broadcasting Messages

When you have your signing client, you can broadcast messages:

const msg = {
  typeUrl: MsgSend.typeUrl,
  value: MsgSend.fromPartial({
    amount: [
      {
        denom: "uatom",
        amount: "1000",
      },
    ],
    toAddress: address,
    fromAddress: address,
  }),
};

const fee: StdFee = {
  amount: [
    {
      denom: "uatom",
      amount: "1000",
    },
  ],
  gas: "86364",
};
const response = await signingClient.signAndBroadcast(address, [msg], fee);

All In One Example

For a comprehensive example of how to use InterchainJS to send messages, please see the example here. This example demonstrates how to:

• Initialize the client.
• Create and sign messages.
• Broadcast transactions.
• Handle responses and errors.

The example provides a complete walkthrough of setting up the client, creating a message for sending txs, and broadcasting the transaction to the chain.

Amino Helpers

The @interchainjs/amino package provides utilities for working with Amino messages and types. It includes functions for encoding and decoding messages, as well as for creating and manipulating Amino types.

Auth

The authentication module is universally applied across different networks.

Crypto Helpers

The @interchainjs/crypto package provides utilities for working with cryptographic primitives. It includes functions for encoding and decoding messages, as well as for creating and manipulating Amino types.

Encoding Helpers

The @interchainjs/encoding package provides utilities for working with encoding. It includes functions for encoding and decoding messages, as well as for creating and manipulating encoding types.

Math Helpers

The @interchainjs/math package provides utilities for working with math. It includes functions for encoding and decoding messages, as well as for creating and manipulating math types.

Pubkey Helpers

The @interchainjs/pubkey package provides utilities for working with pubkeys. It includes functions for encoding and decoding messages, as well as for creating and manipulating pubkey types.

Supported Networks

Cosmos Network

Injective Network

Ethereum Network

Developing

When first cloning the repo:

yarn
yarn build:dev

Codegen

Contract schemas live in ./contracts, and protos in ./proto. Look inside of scripts/interchainjs.telescope.json and configure the settings for bundling your SDK and contracts into interchainjs:

yarn codegen

Interchain JavaScript Stack ⚛️

A unified toolkit for building applications and smart contracts in the Interchain ecosystem

Credits

🛠 Built by Hyperweb (formerly Cosmology) — if you like our tools, please checkout and contribute to our github ⚛️

Disclaimer

AS DESCRIBED IN THE LICENSES, THE SOFTWARE IS PROVIDED "AS IS", AT YOUR OWN RISK, AND WITHOUT WARRANTIES OF ANY KIND.

No developer or entity involved in creating this software will be liable for any claims or damages whatsoever associated with your use, inability to use, or your interaction with other users of the code, including any direct, indirect, incidental, special, exemplary, punitive or consequential damages, or loss of profits, cryptocurrencies, tokens, or anything else of value.