Guides
Start typing to search…

zkVerify

@stakefish/sdk-zkverify

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

Table of Contents

Installation

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

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

Type Imports

The SDK exports TypeScript types for all transaction objects:

import { ZkVerify } from '@stakefish/sdk-zkverify';
import type {
  ZkVerifyConfig,
  ZkVerifyPrepareDelegate,
  ZkVerifyPrepareUndelegate,
  ZkVerifyPrepareRedelegate,
  ZkVerifyPreparePause,
  ZkVerifyPrepareWithdraw,
  ZkVerifySign,
  ZkVerifyBroadcast,
  ZkVerifyUnsignedTransaction,
  ZkVerifySignedTransaction,
  ZkVerifyTransactionBroadcastResult,
} from '@stakefish/sdk-zkverify';

API Reference

Constructor

import type { ZkVerifyConfig } from '@stakefish/sdk-zkverify';

new ZkVerify({ rpcUrl: 'https://rpc.zkverify.io', memo: 'Stake with stake.fish' }: ZkVerifyConfig)
  • rpcUrl (required): zkVerify RPC endpoint URL
  • memo (required): A memo to include in the transaction. This should be a unique string approved by stake.fish for your account.

Delegation

import type { ZkVerifyPrepareDelegate, ZkVerifyUnsignedTransaction } from '@stakefish/sdk-zkverify';

delegate({ delegatorAddress: 'zk1abc123...', amount: '1000000000000000000' }: ZkVerifyPrepareDelegate): Promise<ZkVerifyUnsignedTransaction>

Creates an unsigned transaction for delegating a specified amount of VFY tokens (in base units, 18 decimals) from the delegator's address to the stake.fish validator.

Parameters:

  • delegatorAddress: The zkVerify address of the delegator (SS58 prefix 8741)
  • amount: The amount to delegate in base units (1 VFY = 1,000,000,000,000,000,000 base units)

Undelegation

import type { ZkVerifyPrepareUndelegate, ZkVerifyUnsignedTransaction } from '@stakefish/sdk-zkverify';

undelegate({ delegatorAddress: 'zk1abc123...', amount: '500000000000000000' }: ZkVerifyPrepareUndelegate): Promise<ZkVerifyUnsignedTransaction>

Creates an unsigned transaction for undelegating from the stake.fish validator. If amount is not specified, unbonds all staked tokens.

Parameters:

  • delegatorAddress: The zkVerify address of the delegator
  • amount (optional): The amount to undelegate in base units (1 VFY = 1,000,000,000,000,000,000 base units). If not provided, unbonds all staked tokens.

Redelegation

import type { ZkVerifyPrepareRedelegate, ZkVerifyUnsignedTransaction } from '@stakefish/sdk-zkverify';

redelegate({ delegatorAddress: 'zk1abc123...' }: ZkVerifyPrepareRedelegate): Promise<ZkVerifyUnsignedTransaction>

Creates an unsigned transaction for redelegating to the stake.fish validator. This changes the delegation target while keeping the bonded amount.

Parameters:

  • delegatorAddress: The zkVerify address of the delegator

Pause Staking

import type { ZkVerifyPreparePause, ZkVerifyUnsignedTransaction } from '@stakefish/sdk-zkverify';

pause({ delegatorAddress: 'zk1abc123...' }: ZkVerifyPreparePause): Promise<ZkVerifyUnsignedTransaction>

Creates an unsigned transaction for pausing staking (chilling). This stops earning rewards while keeping tokens bonded.

Parameters:

  • delegatorAddress: The zkVerify address of the delegator

Withdraw Unbonded

import type { ZkVerifyPrepareWithdraw, ZkVerifyUnsignedTransaction } from '@stakefish/sdk-zkverify';

withdraw({ delegatorAddress: 'zk1abc123...' }: ZkVerifyPrepareWithdraw): Promise<ZkVerifyUnsignedTransaction>

Creates an unsigned transaction for withdrawing all unbonded VFY tokens that have completed the unbonding period.

Parameters:

  • delegatorAddress: The zkVerify address of the delegator

Signing

import type { ZkVerifySign, ZkVerifySignedTransaction } from '@stakefish/sdk-zkverify';

sign({ privateKey: 'word1 word2 word3 ...', unsignedTx }: ZkVerifySign): Promise<ZkVerifySignedTransaction>

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

Parameters:

  • privateKey: The private key as a mnemonic phrase (12, 15, 18, 21, or 24 words)
  • unsignedTx: The unsigned transaction object from delegate(), undelegate(), redelegate(), pause(), or withdraw()

Broadcasting

import type { ZkVerifyBroadcast, ZkVerifyTransactionBroadcastResult } from '@stakefish/sdk-zkverify';

broadcast({ signedTransaction, checkInclusion: true, timeoutMs: 60000 }: ZkVerifyBroadcast): Promise<ZkVerifyTransactionBroadcastResult>

Broadcasts the signed transaction to the zkVerify network.

Parameters:

  • signedTransaction: The signed transaction object from sign()
  • checkInclusion (optional): Whether to wait for block inclusion (default: false)
  • timeoutMs (optional): Timeout in milliseconds when waiting for inclusion (default: 60000)

Returns: ZkVerifyTransactionBroadcastResult object containing:

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

Examples

Full delegation example

import { ZkVerify } from '@stakefish/sdk-zkverify';
import type { ZkVerifyUnsignedTransaction, ZkVerifySignedTransaction } from '@stakefish/sdk-zkverify';
// or: const { ZkVerify } = require('@stakefish/sdk-zkverify');

const delegator = process.env.ZKVERIFY_DELEGATOR_ADDRESS;
const privateKey = process.env.ZKVERIFY_PRIVATE_KEY;

async function main() {
  const zkverify = new ZkVerify({
    rpcUrl: 'https://rpc.zkverify.io',
    memo: 'Stake with stake.fish',
  });

  // Delegation (1 VFY = 1,000,000,000,000,000,000 base units)
  const unsignedTx: ZkVerifyUnsignedTransaction = await zkverify.delegate({
    delegatorAddress: delegator,
    amount: '1000000000000000000',
  });

  // Sign
  const signedTx: ZkVerifySignedTransaction = await zkverify.sign({ privateKey, unsignedTx });

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

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

Undelegation

// Full undelegation (unbonds all staked tokens)
const tx = await zkverify.undelegate({
  delegatorAddress: delegator,
});

// Partial undelegation (unbonds specified amount)
const tx = await zkverify.undelegate({
  delegatorAddress: delegator,
  amount: '500000000000000000',
});

Redelegation

const tx = await zkverify.redelegate({
  delegatorAddress: delegator,
});

Pause Staking

const tx = await zkverify.pause({
  delegatorAddress: delegator,
});

Withdraw Unbonded

const tx = await zkverify.withdraw({
  delegatorAddress: delegator,
});

Configuration

The SDK uses default stake.fish validator address. You can configure custom endpoints during instantiation:

const zkverify = new ZkVerify({
  rpcUrl: 'https://custom-rpc.zkverify.io',
  memo: 'Stake with stake.fish',
});

Notes

  • All amounts in the SDK are specified in base units (18 decimals), the smallest unit of VFY (1 VFY = 1,000,000,000,000,000,000 base units)
  • The SDK automatically handles transaction fees and fee estimation
  • Private keys should be kept secure and never committed to version control
  • zkVerify uses Substrate-based addresses (SS58 format with prefix 8741)
  • Key derivation follows BIP-39 standard for mnemonic phrases

Updated 1 day ago