@stakefish/sdk-cardano

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

Table of Contents

• Installation
• API Reference
  • Constructor
  • Delegation
  • Undelegation
  • Withdraw Rewards
  • Key Derivation
  • Signing
  • Broadcasting
• Examples
• Notes

Installation

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

npm install @stakefish/sdk-cardano

yarn add @stakefish/sdk-cardano

API Reference

Constructor

interface CardanoConfig {
  blockfrostProjectId: string;
  blockfrostUrl?: string;
  memo: string;
}

export class Cardano {
  constructor(config: CardanoConfig)
...

• blockfrostProjectId (required): Your Blockfrost project ID for API access
• blockfrostUrl (optional): Blockfrost API endpoint URL (default: mainnet)
• memo (required): Memo to include in transactions. This should be a unique string approved by stake.fish for your account.

Delegation

delegate(delegatorAddress: string): Promise<CardanoUnsignedTransaction>

Creates an unsigned transaction for delegating to the stake.fish validator pool. The transaction automatically handles the stake registration if needed and delegates the entire stake account to the validator.

Parameters:

• delegatorAddress: The Cardano address of the delegator (e.g., 'addr1...')

Undelegation

undelegate(delegatorAddress: string): Promise<CardanoUnsignedTransaction>

Creates an unsigned transaction for undelegating from the stake.fish validator pool. This deregisters the stake key, effectively undelegating all staked ADA.

Parameters:

• delegatorAddress: The Cardano address of the delegator

Withdraw Rewards

withdraw(delegatorAddress: string): Promise<CardanoUnsignedTransaction>

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

Set DRep

setDrep(delegatorAddress: string): Promise<CardanoUnsignedTransaction>

Creates an unsigned transaction for setting DRep to always-abstain.

Parameters:

• delegatorAddress: The Cardano address of the delegator

Key Derivation

deriveKeysFromMnemonic(mnemonic: string, accountIndex: number): CardanoKeys

Derives Cardano cryptographic keys from a BIP-39 mnemonic phrase following the CIP-1852 standard. This is a helper method to obtain the necessary keys for signing transactions.

Parameters:

• mnemonic: A valid BIP-39 mnemonic phrase (12, 15, 18, 21, or 24 words)
• accountIndex: The account index to derive (typically 0 for the first account)

Returns: CardanoKeys object containing:

• stakePrivateKey: Private key for stake operations
• paymentPrivateKey: Private key for payment operations
• stakePublicKey: Public key for stake operations
• paymentPublicKey: Public key for payment operations

Signing

sign(keys: CardanoKeys, unsignedTx: CardanoUnsignedTransaction): Promise<CardanoSignedTransaction>

Signs the unsigned transaction using the provided Cardano keys. This operation works completely offline and does not require network connectivity. Both stake and payment keys are used to sign the transaction.

Parameters:

• keys: CardanoKeys object containing stake and payment private/public key pairs
• unsignedTx: The unsigned transaction object from delegate(), undelegate(), or withdraw()

Broadcasting

broadcast(signedTransaction: CardanoSignedTransaction, checkInclusion?: boolean, timeoutMs?: number, pollIntervalMs?: number): Promise<CardanoTransactionBroadcastResult>

Broadcasts the signed transaction to the Cardano 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: CardanoTransactionBroadcastResult object containing:

• txId: The transaction hash
• blockHash: The block hash if included (optional)
• blockHeight: The block height if included (optional)

Examples

Full delegation example

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

const delegatorAddress = process.env.CARDANO_ADDRESS;
const mnemonic = process.env.CARDANO_MNEMONIC;
const blockfrostProjectId = process.env.CARDANO_BLOCK_FROST_PROJECT_ID;

async function main() {
  const cardano = new Cardano({
    blockfrostProjectId,
    memo: '@stakefish/sdk-cardano test',
  });

  // Delegation
  const tx = await cardano.delegate(delegatorAddress);

  // Derive keys from mnemonic
  const keys = cardano.deriveKeysFromMnemonic(mnemonic, 0);

  // Sign
  const signedTx = await cardano.sign(keys, tx);

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

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

Undelegation

const tx = await cardano.undelegate(delegatorAddress);

Withdraw Rewards

const tx = await cardano.withdraw(delegatorAddress);

Set DRep

const tx = await cardano.setDrep(delegatorAddress);

Configuration

The SDK requires configuration during instantiation with Blockfrost API credentials:

const cardano = new Cardano({
  blockfrostProjectId: 'your-blockfrost-project-id',
  blockfrostUrl: 'https://cardano-mainnet.blockfrost.io/api/v0',
  memo: 'stakefishUniqueString',
});

Notes

• All amounts in Cardano are specified in lovelace, the smallest unit of ADA (1 ADA = 1,000,000 lovelace)
• The SDK automatically handles transaction fees and UTxO management
• Cardano delegation does not require specifying amounts - the entire stake account is delegated
• Private keys and mnemonics should be kept secure and never committed to version control
• The SDK uses the Blockfrost API for network interactions
• Key derivation follows the CIP-1852 standard for Cardano HD wallets
• Both stake and payment keys are required to sign transactions