Skip to content

sdk-overview.md

Latest commit

 

History

History
255 lines (190 loc) · 7.6 KB

sdk-overview.md

File metadata and controls

255 lines (190 loc) · 7.6 KB
Raw
id sdk-overview
title SDK Overview
sidebar_position 3

SDK Overview

Detailed overview of the Mass Payout SDK architecture and available operations.

What the SDK Does

The Mass Payout SDK is a TypeScript library for interacting with the LifeCycle Cash Flow smart contract on Hedera. It provides two core functionalities:

  1. Contract Interaction: Create and execute transactions with the LifeCycle Cash Flow contract
  2. Transaction Signing: Sign transactions using custodial wallet providers (DFNS)

Transaction Signing with Custodial Wallets

The SDK uses the Hedera Custodians Library for secure transaction signing. Instead of managing private keys directly, transactions are signed remotely by DFNS.

How Transaction Signing Works

Your Application
       │
       ▼
SDK creates unsigned transaction
       │
       ▼
Transaction sent to DFNS API
       │
       ▼
DFNS signs with secure private key
       │
       ▼
Signed transaction submitted to Hedera
       │
       ▼
Transaction receipt returned

Benefits:

  • Private keys never leave the custodial provider's infrastructure
  • Enterprise-grade audit trails and access controls
  • Compliance with regulatory requirements

Available Operations

Commands (Write Operations)

Commands modify blockchain state and require transaction signing:

  • DeployCommand - Deploy new LifeCycle Cash Flow contract
  • ExecuteDistributionCommand - Execute payment distribution (paginated)
  • ExecuteDistributionByAddressesCommand - Execute distribution for specific addresses
  • ExecuteAmountSnapshotCommand - Create fixed-amount snapshot (paginated)
  • ExecuteAmountSnapshotByAddressesCommand - Create fixed-amount snapshot for specific addresses
  • ExecutePercentageSnapshotCommand - Create percentage-based snapshot (paginated)
  • ExecutePercentageSnapshotByAddressesCommand - Create percentage snapshot for specific addresses
  • ExecuteBondCashOutCommand - Execute bond maturity cash-out (paginated)
  • ExecuteBondCashOutByAddressesCommand - Execute bond cash-out for specific addresses
  • PauseCommand - Pause contract (emergency stop)
  • UnpauseCommand - Resume contract operations

Queries (Read Operations)

Queries read contract state without transactions:

  • GetPaymentTokenQuery - Get payment token address
  • GetPaymentTokenDecimalsQuery - Get payment token decimals
  • IsPausedQuery - Check if contract is paused

Usage Examples

Deploy a Contract

import { DeployCommand } from "@hashgraph/mass-payout-sdk";

const command = new DeployCommand({
  tokenAddress: "0.0.789012", // Asset token address
  paymentTokenAddress: "0.0.429274", // Payment token (e.g., USDC)
});

const result = await commandBus.execute(command);
console.log("Contract deployed at:", result.contractId);

Execute a Distribution

import { ExecuteDistributionCommand } from "@hashgraph/mass-payout-sdk";

const command = new ExecuteDistributionCommand({
  contractId: "0.0.123456",
  holderAddresses: ["0xabc...", "0xdef...", "0xghi..."],
  amounts: ["100", "200", "150"], // In smallest unit (e.g., cents for USDC)
  startIndex: 0,
  endIndex: 100, // For pagination with large holder lists
});

const receipt = await commandBus.execute(command);
console.log("Distribution executed:", receipt.transactionId);

Create a Snapshot (Fixed Amount)

import { ExecuteAmountSnapshotCommand } from "@hashgraph/mass-payout-sdk";

const command = new ExecuteAmountSnapshotCommand({
  contractId: "0.0.123456",
  holderAddresses: ["0xabc...", "0xdef..."],
  amounts: ["100", "100"], // Same amount for all holders
  startIndex: 0,
  endIndex: 50,
});

await commandBus.execute(command);

Create a Snapshot (Percentage-based)

import { ExecutePercentageSnapshotCommand } from "@hashgraph/mass-payout-sdk";

const command = new ExecutePercentageSnapshotCommand({
  contractId: "0.0.123456",
  holderAddresses: ["0xabc...", "0xdef..."],
  balances: ["1000", "2000"], // Token balances for each holder
  totalAmount: "300", // Total amount to distribute proportionally
  startIndex: 0,
  endIndex: 50,
});

await commandBus.execute(command);

Execute Bond Cash-Out

import { ExecuteBondCashOutCommand } from "@hashgraph/mass-payout-sdk";

const command = new ExecuteBondCashOutCommand({
  contractId: "0.0.123456",
  holderAddresses: ["0xabc...", "0xdef..."],
  amounts: ["1000", "2000"], // Maturity amounts
  startIndex: 0,
  endIndex: 100,
});

await commandBus.execute(command);

Query Contract State

import { GetPaymentTokenQuery, IsPausedQuery } from "@hashgraph/mass-payout-sdk";

// Get payment token
const paymentToken = await queryBus.execute(new GetPaymentTokenQuery({ contractId: "0.0.123456" }));

// Check if paused
const isPaused = await queryBus.execute(new IsPausedQuery({ contractId: "0.0.123456" }));

Pause/Unpause Contract

import { PauseCommand, UnpauseCommand } from "@hashgraph/mass-payout-sdk";

// Emergency pause
await commandBus.execute(new PauseCommand({ contractId: "0.0.123456" }));

// Resume operations
await commandBus.execute(new UnpauseCommand({ contractId: "0.0.123456" }));

Pagination for Large Distributions

When distributing to many holders, use startIndex and endIndex to paginate:

// Distribute to first 100 holders
await commandBus.execute(
  new ExecuteDistributionCommand({
    contractId: "0.0.123456",
    holderAddresses: allHolders,
    amounts: allAmounts,
    startIndex: 0,
    endIndex: 100,
  }),
);

// Distribute to next 100 holders
await commandBus.execute(
  new ExecuteDistributionCommand({
    contractId: "0.0.123456",
    holderAddresses: allHolders,
    amounts: allAmounts,
    startIndex: 100,
    endIndex: 200,
  }),
);

For small lists, use the ByAddresses variants which don't require pagination.

Error Handling

import { CommandError } from "@hashgraph/mass-payout-sdk";

try {
  await commandBus.execute(command);
} catch (error) {
  if (error instanceof CommandError) {
    console.error("Command failed:", error.message);
    console.error("Details:", error.details);
  }
  throw error;
}

Architecture

The SDK uses a clean architecture pattern:

  • Commands/Queries: High-level operations for contract interaction
  • Adapters: Pluggable implementations for transaction signing (DFNS, future providers)
  • Services: Network management, contract handling, events

This design allows swapping custodial providers without changing your application code.

Best Practices

  1. Never hardcode private keys - Always use custodial wallets in production
  2. Use pagination - For distributions with >100 holders, use startIndex/endIndex
  3. Test on testnet first - Validate all operations before mainnet deployment
  4. Handle errors properly - Implement retry logic for transient failures
  5. Monitor gas costs - Each transaction costs HBAR (~$0.0001 per transaction)

Additional Resources

Related Guides