Guides
Start typing to search…

Starknet

@stakefish/sdk-starknet

The @stakefish/sdk-starknet is a JavaScript/TypeScript library that provides a unified interface for STRK staking operations on Starknet with stake.fish. It supports preparing stake, unstake, withdraw, and claim rewards transactions, signing with starknet.js, and checking transaction status.

Table of Contents

Installation

npm install @stakefish/sdk-starknet
yarn add @stakefish/sdk-starknet

Type Imports

import { Starknet } from '@stakefish/sdk-starknet';
import type {
  StarknetConfig,
  StarknetPrepareStake,
  StarknetPrepareUnstake,
  StarknetPrepareWithdraw,
  StarknetPrepareClaimRewards,
  StarknetSign,
  StarknetBroadcast,
  StarknetGetTransactionStatus,
  StarknetUnsignedTransaction,
  StarknetSignedTransaction,
  StarknetBroadcastResult,
  StarknetTransactionStatus,
} from '@stakefish/sdk-starknet';

Configuration

import { Starknet } from '@stakefish/sdk-starknet';
import type { StarknetConfig } from '@stakefish/sdk-starknet';

new Starknet({ rpcUrl: 'https://starknet-mainnet.public.blastapi.io' }: StarknetConfig)

The SDK is pre-configured for Starknet mainnet (SN_MAIN) and the stake.fish STRK delegation pool.

API Reference

stake

import type { StarknetPrepareStake, StarknetUnsignedTransaction } from '@stakefish/sdk-starknet';

stake({ delegatorAddress: '0x049d36...', amount: '100000000000000000000' }: StarknetPrepareStake): Promise<StarknetUnsignedTransaction>

Prepares a stake transaction (approve + enter/add_to_delegation_pool). Amount is in wei (1 STRK = 10^18 wei).

Parameters:

  • delegatorAddress: Starknet address of the delegator (0x + hex)
  • amount: Amount to stake in wei (1 STRK = 10^18 wei)

unstake

import type { StarknetPrepareUnstake, StarknetUnsignedTransaction } from '@stakefish/sdk-starknet';

unstake({ delegatorAddress: '0x049d36...', amount: '50000000000000000000' }: StarknetPrepareUnstake): Promise<StarknetUnsignedTransaction>

Prepares an unstake intent (exit_delegation_pool_intent). This starts the 21-day unbonding period.

Parameters:

  • delegatorAddress: Starknet address of the delegator (0x + hex)
  • amount: Amount to unstake in wei (1 STRK = 10^18 wei)

withdraw

import type { StarknetPrepareWithdraw, StarknetUnsignedTransaction } from '@stakefish/sdk-starknet';

withdraw({ delegatorAddress: '0x049d36...' }: StarknetPrepareWithdraw): Promise<StarknetUnsignedTransaction>

Prepares a withdraw transaction (exit_delegation_pool_action). Call this after the unbonding period completes to claim your unstaked STRK.

Parameters:

  • delegatorAddress: Starknet address of the delegator (0x + hex)

claimRewards

import type { StarknetPrepareClaimRewards, StarknetUnsignedTransaction } from '@stakefish/sdk-starknet';

claimRewards({ delegatorAddress: '0x049d36...' }: StarknetPrepareClaimRewards): Promise<StarknetUnsignedTransaction>

Prepares a claim rewards transaction.

Parameters:

  • delegatorAddress: Starknet address of the delegator (0x + hex)

sign

import type { StarknetSign, StarknetSignedTransaction } from '@stakefish/sdk-starknet';

sign({ privateKey: '0xabc123...', unsignedTx }: StarknetSign): Promise<StarknetSignedTransaction>

Signs and submits the transaction using starknet.js Account.execute(). Requires network access (for nonce). Returns a payload containing the transaction hash as { signedTransaction: string } (JSON with transaction_hash).

Parameters:

  • privateKey: Hex string (with or without 0x)
  • unsignedTx: The unsigned transaction returned by a prepare method

broadcast

import type { StarknetBroadcast, StarknetBroadcastResult } from '@stakefish/sdk-starknet';

broadcast({ signedTx, checkInclusion: true, timeoutMs: 60000, pollIntervalMs: 2000 }: StarknetBroadcast): Promise<StarknetBroadcastResult>

Waits for transaction confirmation. The transaction is submitted during sign(). Use this to wait until it is accepted on L2/L1. Returns { txHash: string; status: 'pending' | 'confirmed' }.

Parameters:

  • signedTx: The signed transaction returned by sign()
  • checkInclusion: Whether to wait for confirmation (default: true)
  • timeoutMs: Maximum time to wait in milliseconds (default: 60000)
  • pollIntervalMs: Polling interval in milliseconds (default: 2000)

getTransactionStatus

import type { StarknetGetTransactionStatus, StarknetTransactionStatus } from '@stakefish/sdk-starknet';

getTransactionStatus({ txHash: '0x...' }: StarknetGetTransactionStatus): Promise<StarknetTransactionStatus>

Fetches transaction status by hash.

Parameters:

  • txHash: The transaction hash to check

Examples

Stake STRK

import { Starknet } from '@stakefish/sdk-starknet';
import type {
  StarknetUnsignedTransaction,
  StarknetSignedTransaction,
  StarknetBroadcastResult,
} from '@stakefish/sdk-starknet';

const starknet = new Starknet({
  rpcUrl: process.env.STARKNET_RPC_URL!,
});

const delegatorAddress = '0x049d36570d4e46f48e99674bd3fcc84644ddd6b96f7c741b1562b82f9e004dc7';
const privateKey = process.env.STARKNET_PRIVATE_KEY!;

// 100 STRK in wei
const amount = '100000000000000000000';

const unsignedTx: StarknetUnsignedTransaction = await starknet.stake({ delegatorAddress, amount });
const signedTx: StarknetSignedTransaction = await starknet.sign({ privateKey, unsignedTx });
const result: StarknetBroadcastResult = await starknet.broadcast({ signedTx });
console.log('Tx hash:', result.txHash, 'Status:', result.status);

Unstake and withdraw (two-step flow)

Unstaking starts a 21-day unbonding period. After it completes, call withdraw.

import type { StarknetUnsignedTransaction, StarknetSignedTransaction } from '@stakefish/sdk-starknet';

// Step 1: Start unbonding
const unstakeTx: StarknetUnsignedTransaction = await starknet.unstake({
  delegatorAddress,
  amount: '50000000000000000000', // 50 STRK
});
const signedUnstake: StarknetSignedTransaction = await starknet.sign({ privateKey, unsignedTx: unstakeTx });
await starknet.broadcast({ signedTx: signedUnstake });

// Step 2: After 21 days, withdraw
const withdrawTx: StarknetUnsignedTransaction = await starknet.withdraw({ delegatorAddress });
const signedWithdraw: StarknetSignedTransaction = await starknet.sign({ privateKey, unsignedTx: withdrawTx });
await starknet.broadcast({ signedTx: signedWithdraw });

Claim rewards

import type { StarknetUnsignedTransaction, StarknetSignedTransaction } from '@stakefish/sdk-starknet';

const claimTx: StarknetUnsignedTransaction = await starknet.claimRewards({ delegatorAddress });
const signedClaim: StarknetSignedTransaction = await starknet.sign({ privateKey, unsignedTx: claimTx });
await starknet.broadcast({ signedTx: signedClaim });

Check transaction status

import type { StarknetTransactionStatus } from '@stakefish/sdk-starknet';

const status: StarknetTransactionStatus = await starknet.getTransactionStatus({ txHash: '0x...' });
console.log(status.status); // 'pending' | 'confirmed' | 'failed'

Important Notes

  • 21-day unbonding: Unstake (exit_delegation_pool_intent) starts a 21-day unbonding period. Tokens are only claimable via withdraw (exit_delegation_pool_action) after that period.
  • Amounts in wei: All amounts use the smallest unit (1 STRK = 10^18 wei). Minimum stake is typically 100 STRK.
  • Address format: Delegator addresses must be valid Starknet addresses (0x + hex, 1-64 chars).
  • Sign submits: sign() uses starknet.js Account.execute() and therefore signs and submits in one step. broadcast() then waits for confirmation.
  • Account abstraction: Transactions are signed by the user's wallet; the SDK uses starknet.js for signing and submission.

Updated 1 day ago