@stakefish/sdk-cosmos

The @stakefish/sdk-cosmos is a JavaScript/TypeScript library that provides a unified interface for staking operations on the Cosmos Hub blockchain with stake.fish validators. It allows developers to easily delegate stakes, undelegate, redelegate, claim rewards, sign transactions, and broadcast them to the network.

Table of Contents

• Installation
• API Reference
  • Constructor
  • Delegation
  • Undelegation
  • Redelegation
  • Claim Rewards
  • Signing
  • Broadcasting
• Example
• Notes

Installation

To use this SDK in your project, install it via npm or yarn:

npm install @stakefish/sdk-cosmos

yarn add @stakefish/sdk-cosmos

API Reference

Constructor

interface CosmosConfig {
  rpcUrl: string;
  apiUrl: string;
  memo: string;
}

export class Cosmos {
  constructor(config: CosmosConfig)
...

• rpcUrl (required): Cosmos Hub RPC endpoint URL
• apiUrl (required): Cosmos Hub API endpoint URL
• memo (required): Memo to include in transactions. This should be a unique string approved by stake.fish for your account.

Delegation

delegate(delegatorAddress: string, amount: string): Promise<CosmosUnsignedTransaction>

Creates an unsigned transaction for delegating a specified amount of ATOM tokens (in uatom, the smallest unit) from the delegator's address to the stake.fish validator.

Parameters:

• delegatorAddress: The Cosmos address of the delegator (e.g., 'cosmos1...')
• amount: The amount to delegate in uatom (1 ATOM = 1,000,000 uatom)

Undelegation

undelegate(delegatorAddress: string, amount: string): Promise<CosmosUnsignedTransaction>

Creates an unsigned transaction for undelegating a specified amount from the stake.fish validator.

Parameters:

• delegatorAddress: The Cosmos address of the delegator
• amount: The amount to undelegate in uatom (1 ATOM = 1,000,000 uatom)

Redelegation

redelegate(delegatorAddress: string, srcValidatorAddress: string, amount: string): Promise<CosmosUnsignedTransaction>

Creates an unsigned transaction for redelegating a specified amount from a source validator to the stake.fish validator.

Parameters:

• delegatorAddress: The Cosmos address of the delegator
• srcValidatorAddress: The validator address to redelegate from (e.g., 'cosmosvaloper1...')
• amount: The amount to redelegate in uatom (1 ATOM = 1,000,000 uatom)

Claim Rewards

claimRewards(delegatorAddress: string): Promise<CosmosUnsignedTransaction>

Creates an unsigned transaction for claiming staking rewards from the stake.fish validator.

Parameters:

• delegatorAddress: The Cosmos address of the delegator

Signing

sign(privateKeyHex: string, unsignedTx: CosmosUnsignedTransaction): Promise<CosmosSignedTransaction>

Signs the unsigned transaction using the provided private key. This operation works completely offline and does not require network connectivity.

Parameters:

• privateKeyHex: The private key in hexadecimal format (with or without '0x' prefix)
• unsignedTx: The unsigned transaction object from delegate(), undelegate(), redelegate(), or claimRewards()

Broadcasting

broadcast(signedTransaction: CosmosSignedTransaction, checkInclusion?: boolean, timeoutMs?: number, pollIntervalMs?: number): Promise<CosmosTransactionBroadcastResult>

Broadcasts the signed transaction to the Cosmos network and optionally waits for inclusion confirmation.

Parameters:

• signedTransaction: The signed transaction object from sign()
• checkInclusion (optional): Whether to wait for transaction inclusion (default: true)
• timeoutMs (optional): Maximum time to wait for inclusion in milliseconds (default: 60000)
• pollIntervalMs (optional): Interval between inclusion checks in milliseconds (default: 2000)

Returns: CosmosTransactionBroadcastResult object containing:

• txId: The transaction hash
• success: Boolean indicating if the transaction was successful
• error: Error message if the transaction failed (optional)

Examples

Full delegation example

import { Cosmos } from '@stakefish/sdk-cosmos';
// or: const { Cosmos } = require('@stakefish/sdk-cosmos');

const delegator = process.env.COSMOS_ADDRESS;
const rpcUrl = process.env.COSMOS_RPC;
const privateKey = process.env.COSMOS_PRIVATE_KEY;

async function main() {
  const cosmos = new Cosmos({
    rpcUrl: rpcUrl,
    apiUrl: rpcUrl,
    memo: '@stakefish/sdk-cosmos test',
  });

  // Delegation (1 ATOM = 1,000,000 uatom)
  const tx = await cosmos.delegate(delegator, '1000000');

  // Sign
  const signedTx = await cosmos.sign(privateKey, tx);

  // Broadcast
  const result = await cosmos.broadcast(signedTx);
  console.log('Broadcast result:', JSON.stringify(result));
}

void main().catch(console.error);

Undelegation

Undelegation amount must match the full amount delegated.

const tx = await cosmos.undelegate(delegator, '1000000');

Redelegation

const tx = await cosmos.redelegate(delegator, 'cosmosvaloper1...', '1000000');

Claim Rewards

const tx = await cosmos.claimRewards(delegator);

Configuration

The SDK requires configuration during instantiation with RPC and API endpoints:

const cosmos = new Cosmos({
  rpcUrl: 'https://custom-rpc.cosmos.network',
  apiUrl: 'https://custom-api.cosmos.network',
  memo: 'stakefishUniqueString',
});

Notes

• All amounts in the SDK are specified in uatom, the smallest unit of ATOM (1 ATOM = 1,000,000 uatom)
• The SDK automatically handles gas estimation and fee calculation for transactions
• Private keys can be provided in hexadecimal format with or without the '0x' prefix
• Private keys should be kept secure and never committed to version control
• The SDK targets Cosmos Hub (cosmoshub-4) mainnet