@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
• API Reference
  • Constructor
  • Delegation
  • Undelegation
  • Redelegation
  • Pause Staking
  • Withdraw Unbonded
  • Signing
  • Broadcasting
• Examples
• Notes

Installation

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

npm install @stakefish/sdk-zkverify

yarn add @stakefish/sdk-zkverify

API Reference

Constructor

interface ZkVerifyConfig {
  rpcUrl: string;
  memo: string;
}

export class ZkVerify {
  constructor(config: 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

delegate(params: { delegatorAddress: string; amount: string }): 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:

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

Undelegation

undelegate(params: { delegatorAddress: string; amount?: string }): Promise<ZkVerifyUnsignedTransaction>

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

Parameters:

• params.delegatorAddress: The zkVerify address of the delegator
• params.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

redelegate(params: { delegatorAddress: string }): Promise<ZkVerifyUnsignedTransaction>

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

Parameters:

• params.delegatorAddress: The zkVerify address of the delegator

Pause Staking

pause(params: { delegatorAddress: string }): Promise<ZkVerifyUnsignedTransaction>

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

Parameters:

• params.delegatorAddress: The zkVerify address of the delegator

Withdraw Unbonded

withdraw(params: { delegatorAddress: string }): Promise<ZkVerifyUnsignedTransaction>

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

Parameters:

• params.delegatorAddress: The zkVerify address of the delegator

Signing

sign(privateKey: string, unsignedTx: ZkVerifyUnsignedTransaction): 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

broadcast(signedTransaction: ZkVerifySignedTransaction): Promise<ZkVerifyTransactionBroadcastResult>

Broadcasts the signed transaction to the zkVerify network.

Parameters:

• signedTransaction: The signed transaction object from sign()

Returns: ZkVerifyTransactionBroadcastResult object containing:

• txId: The transaction hash
• success: Boolean indicating if the transaction was successful

Examples

Full delegation example

import { ZkVerify } 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.fish',
  });

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

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

  // Broadcast
  const result = await zkverify.broadcast(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',
  stakefishValidator: 'ZKUPAmjpPz7SMkzZuTfsobVEcWetdzFuRqBKZGiY6hWrkx1JK', // optional custom validator
});

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