@zebec-network/admin-sdk

Admin SDK for managing Zebec smart contract operations across Solana, EVM-compatible chains, and Sui.

Provides typed service classes for configuring payment streams, staking/lockup programs, and card payment infrastructure — covering initialization, fee management, token whitelisting, vault setup, and on-chain data reads.

Table of Contents

• Installation
• Quick Start
• Usage
  • Solana — Stream Admin
  • Solana — Staking Admin
  • Solana — Card Admin
  • Solana — Partner Card Admin
  • EVM — Card Admin
  • Sui — Card Admin
• API Reference
  • ZebecStreamAdminService
  • ZebecStakeAdminService
  • ZebecSolanaCardV2AdminService
  • ZebecSolanaPartnerAdminCardService
  • ZebecCardService (EVM)
  • SuiCardAdminService
  • ProxyStreamAdminService
• Supported Networks
• Types
• Utilities
• Environment Setup
• Folder Structure
• Scripts

Installation

npm install @zebec-network/admin-sdk
# or
yarn add @zebec-network/admin-sdk

Peer dependencies vary by which chains you use:

| Chain | Required peer dep | | -------- | --------------------------------------------------- | | Solana | @coral-xyz/anchor, @solana/web3.js | | EVM | ethers@^6 | | Sui | @mysten/sui |

Quick Start

Solana Quick Start

import { Connection, Keypair } from "@solana/web3.js";
import { AnchorProvider, Wallet } from "@coral-xyz/anchor";
import { ZebecStreamAdminService } from "@zebec-network/admin-sdk";

const connection = new Connection(process.env.RPC_URL!);
const keypair = Keypair.fromSecretKey(/* your key */);
const provider = new AnchorProvider(connection, new Wallet(keypair), {});

const service = ZebecStreamAdminService.create("my-config", provider, "mainnet-beta");

const tx = await service.initializeStreamConfig({
  feePercentage: 1, // 100 in basis points
  feeVault: keypair.publicKey,
  // ...other params
});
console.log(tx.signature);

EVM Quick Start

import { ethers } from "ethers";
import { ZebecCardService, SupportedChain } from "@zebec-network/admin-sdk";

const provider = new ethers.JsonRpcProvider(process.env.EVM_RPC_URL!);
const signer = new ethers.Wallet(process.env.EVM_PRIVATE_KEY!, provider);

const cardService = new ZebecCardService(signer, SupportedChain.Base);
await cardService.setNativeFee({ feeInPercent: "1" }); // 100 bps

Sui Quick Start

import { SuiClient } from "@mysten/sui/client";
import { Ed25519Keypair } from "@mysten/sui/keypairs/ed25519";
import {
  SuiCardAdminService,
  SuiSilverCardPackageInfo,
  createSuiSignTransactionMethodFromSigner,
} from "@zebec-network/admin-sdk";

const suiClient = new SuiClient({ url: "https://fullnode.mainnet.sui.io" });
const keypair = Ed25519Keypair.fromSecretKey(/* your key */);

const wallet = {
  address: keypair.toSuiAddress(),
  signTransaction: createSuiSignTransactionMethodFromSigner(keypair),
};

const packageInfo = new SuiSilverCardPackageInfo("mainnet");
const adminService = await SuiCardAdminService.create(packageInfo, suiClient, wallet);

const payload = await adminService.setCardVault({ vaultAddress: "0x..." });
const result = await payload.execute();

Usage

Solana — Stream Admin

import { ZebecStreamAdminService } from "@zebec-network/admin-sdk";

const service = ZebecStreamAdminService.create("config-name", provider, "mainnet-beta");

// Initialize a new stream config
const initTx = await service.initializeStreamConfig({
  feePercentage: 1,
  feeVault: adminPublicKey,
  feeTiers: [{ minAmount: 1, maxAmount: 1000, feePercent: 5 }],
});

// Update an existing stream config
const updateTx = await service.updateStreamConfig({
  feePercentage: 8,
  feeVault: adminPublicKey,
});

// Whitelist tokens for streaming
const whitelistTx = await service.whiteListTokens({
  tokens: [usdcMint, usdtMint],
});

// Read on-chain data
const config = await service.getStreamConfigInfo("config-name");
const tokens = await service.getWhitelistedTokens("config-name");
const metadata = await service.getStreamMetadataInfo(streamMetadataAddress);

Solana — Staking Admin

import { ZebecStakeAdminService } from "@zebec-network/admin-sdk";

const stakeService = ZebecStakeAdminService.create(provider, "mainnet-beta");

// Initialize a lockup program
const lockupTx = await stakeService.initLockup({
  stakeToken: usdcMint,
  rewardToken: zbcMint,
  name: "my-lockup",
  fee: 5,
  feeVault: adminPublicKey,
  rewardSchemes: [
    { lockupDurationDays: 30, rewardRate: 5 },
    { lockupDurationDays: 90, rewardRate: 12 },
  ],
  minimumStake: "1",
});

// Update an existing lockup
const updateTx = await stakeService.updateLockup({
  lockupName: "my-lockup",
  fee: 7.5,
  feeVault: adminPublicKey,
  rewardSchemes: [],
  minimumStake: "2",
});

// Read on-chain data
const lockupInfo = await stakeService.getLockupInfo(lockupAddress);
const stakeCount = await stakeService.getAllStakesCount(lockupAddress);
const allStakes = await stakeService.getAllStakesInfo(lockupAddress);

Solana — Card Admin

import { ZebecSolanaCardV2AdminService } from "@zebec-network/admin-sdk";

const cardService = ZebecSolanaCardV2AdminService.create(provider, "mainnet-beta");

// Initialize card configuration
await cardService.initCardConfig({
  nativeFee: 1,
  nonNativeFee: 1.5,
  revenueFee: 0.5,
  cardVault: vaultPublicKey,
  revenueVault: revenuePublicKey,
  minCardAmount: "10",
  maxCardAmount: "1500",
  dailyLimit: "10000",
});

// Update card config
await cardService.setCardConfig({
  nativeFee: 1.2,
  nonNativeFee: 1.6,
  revenueFee: 0.6,
  cardVault: vaultPublicKey,
  revenueVault: revenuePublicKey,
  minCardAmount: "10",
  maxCardAmount: "1500",
  dailyLimit: "10000",
});

// Manage custom token fees
await cardService.setCustomFees({ token: usdcMint, fee: 80 });
await cardService.deleteCustomFees({ token: usdcMint });

// Read on-chain data
const config = await cardService.getCardConfigInfo();
const purchase = await cardService.getCardPurchaseInfo(purchasePda);
const userRecord = await cardService.getUserPurchaseRecord(userRecordPda);
const customFees = await cardService.getCustomTokenFees();

Solana — Partner Card Admin

import { ZebecSolanaPartnerAdminCardService } from "@zebec-network/admin-sdk";

const partnerService = ZebecSolanaPartnerAdminCardService.create(
  "my-partner",
  provider,
  "mainnet-beta"
);

await partnerService.initPartnerCardConfig({ /* params */ });
await partnerService.setPartnerCardConfig({ /* params */ });
await partnerService.setPartnerCustomFees({ token: usdcMint, fee: 0.8 });
await partnerService.deletePartnerCustomFees({ token: usdcMint });

const partnerConfig = await partnerService.getPartnerCardConfigInfo();
const partnerFees = await partnerService.getPartnerCustomTokenFees();

EVM — Card Admin

import { ZebecCardService, SupportedChain } from "@zebec-network/admin-sdk";

const cardService = new ZebecCardService(signer, SupportedChain.Base);

// Fee configuration
await cardService.setNativeFee({ feeInPercent: "1" });       // 1%
await cardService.setNonNativeFee({ feeInPercent: "1.50" });    // 1.5%
await cardService.setRevenueFee({ feeInPercent: "0.5" });       // 0.5%

// Card limits
await cardService.setMinCardLimit({ amount: "10" });
await cardService.setMaxCardLimit({ amount: "1500" });
await cardService.setDailyLimit({ amount: "10000" });

// Vault addresses
await cardService.setCardVault({ vault: "0xYourVaultAddress" });
await cardService.setRevenueVault({ vault: "0xYourRevenueVault" });

// Read config
const config = await cardService.getCardConfig();
console.log(config.nativeFee, config.cardVault);

Sui — Card Admin

All Sui operations return a SuiTransactionPayload that must be explicitly executed:

import {
  SuiCardAdminService,
  SuiSilverCardPackageInfo,
  createSuiSignTransactionMethodFromSigner,
} from "@zebec-network/admin-sdk";

const packageInfo = new SuiSilverCardPackageInfo("mainnet");
const adminService = await SuiCardAdminService.create(packageInfo, suiClient, wallet);

// Fee settings
await (await adminService.setNativeFee({ feePercent: 1 })).execute();
await (await adminService.setNonNativeFee({ feePercent: 1.5 })).execute();
await (await adminService.setRevenueFee({ feePercent: 0.5 })).execute();

// Vault addresses
await (await adminService.setCardVault({ vaultAddress: "0x..." })).execute();
await (await adminService.setRevenueVault({ vaultAddress: "0x..." })).execute();

// Card limits
await (await adminService.setMinCardAmount({ minCardAmount: "10" })).execute();
await (await adminService.setMaxCardAmount({ maxCardAmount: "1500" })).execute();
await (await adminService.setDailyLimit({ dailyLimit: "10000" })).execute();

// Token address
await (await adminService.setUsdcAddress({ usdcAddress: "0x..." })).execute();

// Fee tiers
await (await adminService.addFeeTier({ minAmount: "0", maxAmount: "1000", fee: 100 })).execute();
await (await adminService.updateFeeTier({ minAmount: "0", maxAmount: "1000", fee: 120 })).execute();
await (await adminService.removeFeeTier({ minAmount: "0", maxAmount: "1000" })).execute();

// Swap fees per token type
await (await adminService.addSwapFee({ tokenType: "0x2::sui::SUI", fee: 200 })).execute();
await (await adminService.updateSwapFee({ tokenType: "0x2::sui::SUI", fee: 180 })).execute();
await (await adminService.removeSwapFee({ tokenType: "0x2::sui::SUI" })).execute();

// Read on-chain data (no execution needed)
const config = await adminService.getCardConfig();
const feeTiers = await adminService.getFeeTierList();
const swapFees = await adminService.getSwapFeeList();

API Reference

ZebecStreamAdminService

Manages payment stream configurations on Solana.

static create(
  streamConfigName: string,
  provider: Provider,
  network: RpcNetwork
): ZebecStreamAdminService

| Method | Description | | ------ | ----------- | | initializeStreamConfig(params) | Creates a new stream configuration on-chain | | updateStreamConfig(params) | Updates fee or vault settings on an existing stream config | | whiteListTokens(params) | Adds tokens to the stream whitelist | | getStreamConfigInfo(configName, commitment?) | Fetches stream config account data | | getWhitelistedTokens(configName, commitment?) | Returns all whitelisted token metadata | | getStreamMetadataInfo(streamMetadata, commitment?) | Fetches stream payment metadata |

ZebecStakeAdminService

Manages staking/lockup programs on Solana.

static create(provider: Provider, network: RpcNetwork): ZebecStakeAdminService

| Method | Description | | ------ | ----------- | | initLockup(params) | Creates a new lockup program with reward schemes | | updateLockup(params) | Updates lockup fee, vault, or reward settings | | getLockupInfo(lockupAddress) | Fetches lockup account data | | getAllStakesCount(lockupAddress, commitment?) | Returns the total number of stakes | | getAllStakesInfo(lockupAddress) | Returns all individual stake records | | getStakeSignatureForStake(stakeInfo) | Returns the creation transaction signature for a stake |

ZebecSolanaCardV2AdminService

Manages card configuration and fees on Solana.

static create(provider: Provider, network: "mainnet-beta" | "devnet"): ZebecSolanaCardV2AdminService

| Method | Description | | ------ | ----------- | | initCardConfig(params) | Initializes card config on-chain | | setCardConfig(params) | Updates card configuration | | setCustomFees(params) | Sets a custom fee for a specific token | | deleteCustomFees(params) | Removes a custom fee for a token | | getCardConfigInfo() | Fetches card configuration | | getCardPurchaseInfo(cardPurchasePda) | Fetches a specific card purchase record | | getUserPurchaseRecord(userPurchaseRecordPda) | Fetches a user's purchase history record | | getCustomTokenFees() | Returns all custom token fee records |

ZebecSolanaPartnerAdminCardService

Manages partner-specific card configuration on Solana.

static create(
  partnershipName: string,
  provider: Provider,
  network: "mainnet-beta" | "devnet"
): ZebecSolanaPartnerAdminCardService

Exposes the same surface area as ZebecSolanaCardV2AdminService prefixed with partner: initPartnerCardConfig, setPartnerCardConfig, setPartnerCustomFees, deletePartnerCustomFees, getPartnerCardConfigInfo, getPartnerCustomTokenFees, getCardPurchaseInfo, getPartnerUserPurchaseRecord.

ZebecCardService (EVM)

Manages card configuration on EVM-compatible chains.

constructor(signer: ethers.Signer, chainId: number)

| Method | Description | | ------ | ----------- | | setNativeFee(params) | Sets the native token fee percentage | | setNonNativeFee(params) | Sets the non-native token fee percentage | | setRevenueFee(params) | Sets the revenue fee percentage | | setMaxCardLimit(params) | Sets the maximum card purchase amount | | setMinCardLimit(params) | Sets the minimum card purchase amount | | setDailyLimit(params) | Sets the daily purchase limit | | setCardVault(params) | Sets the card vault address | | setRevenueVault(params) | Sets the revenue vault address | | getCardConfig() | Fetches current card configuration |

SuiCardAdminService

Manages card configuration on Sui.

static async create(
  packageInfo: SuiSilverCardPackageInfo,
  suiClient: ClientWithCoreApi,
  wallet: WalletInterface
): Promise<SuiCardAdminService>

All mutation methods return Promise<SuiTransactionPayload> which exposes an execute() method.

| Method | Description | | ------ | ----------- | | getCardConfig() | Fetches card configuration object | | getFeeTierList() | Fetches all fee tiers | | getSwapFeeList() | Fetches all swap fees | | setNativeFee(params) | Sets native token fee percent | | setNonNativeFee(params) | Sets non-native token fee percent | | setRevenueFee(params) | Sets revenue fee percent | | setCardVault(params) | Sets card vault address | | setRevenueVault(params) | Sets revenue vault address | | setMinCardAmount(params) | Sets minimum card amount | | setMaxCardAmount(params) | Sets maximum card amount | | setDailyLimit(params) | Sets daily transaction limit | | setUsdcAddress(params) | Sets USDC token address | | addFeeTier(params) | Adds a new fee tier range | | updateFeeTier(params) | Updates an existing fee tier | | removeFeeTier(params) | Removes a fee tier | | addSwapFee(params) | Adds a swap fee for a token type | | updateSwapFee(params) | Updates a swap fee | | removeSwapFee(params) | Removes a swap fee |

ProxyStreamAdminService

Manages proxy stream configurations on Solana.

static create(provider: Provider, network: RpcNetwork): ProxyStreamAdminService

Supported Networks

Solana

| Network | RpcNetwork value | | ------- | ----------------- | | Mainnet Beta | "mainnet-beta" | | Devnet | "devnet" |

EVM (SupportedChain enum)

| Chain | Chain ID | | ----- | -------- | | Ethereum Mainnet | 1 | | Sepolia Testnet | 11155111 | | Base | 8453 | | BSC | 56 | | BSC Testnet | 97 | | Polygon | 137 | | Polygon Amoy | 80002 | | Odyssey | 153153 | | Odyssey Testnet | 131313 |

Sui

| Network | SuiNetwork value | | ------- | ----------------- | | Mainnet | "mainnet" | | Devnet | "devnet" | | Testnet | "testnet" |

Types

Key types exported from the package:

// Network
type RpcNetwork = "mainnet-beta" | "devnet";
type SuiNetwork = "mainnet" | "devnet" | "testnet";

// Solana stream
type StreamConfigInfo
type StreamMetadataInfo
type TokenMetadata
type StreamFeeTier
type InitializeStreamConfigParams
type UpdateStreamConfigParams
type WhiteListTokensParams

// Solana staking
type LockupInfo
type StakeInfo
type RewardScheme
type InitLockupInstructionData
type UpdateLockupInstructionData

// Solana card
type CardConfigInfo
type PartnerCardConfigInfo
type CardPurchaseInfo
type UserPurchaseRecordInfo
type TokenFeeRecord
type CardFeeTier
type InitCardConfigParams
type SetCardConfigParams
type SetCustomFeesParams
type DeleteCustomFeesParams

// EVM card
type EvmCardConfig
type CardPurchaseOfDay

// Sui card
type SuiCardConfig
type SuiFeeTier
type SuiFeeTierList
type SuiSwapFee
type SuiSwapFeeList
type WalletInterface
type SuiSignTransactionMethod
type SuiTransactionPayload

// Shared
type Numeric = string | number
type Address          // blockchain address string
type DecimalString    // decimal value as string
type Percent          // percentage value

Utilities

createSuiSignTransactionMethodFromSigner

Creates a SuiSignTransactionMethod compatible wallet adapter from a Sui keypair or signer.

import { createSuiSignTransactionMethodFromSigner } from "@zebec-network/admin-sdk";
import { Ed25519Keypair } from "@mysten/sui/keypairs/ed25519";

const keypair = Ed25519Keypair.fromSecretKey(secretKey);
const signTransaction = createSuiSignTransactionMethodFromSigner(keypair);
// Pass signTransaction into WalletInterface

getCoinDecimals

Fetches decimal precision for a Sui coin type.

import { getCoinDecimals } from "@zebec-network/admin-sdk";

const decimals = await getCoinDecimals(suiClient, "0x2::sui::SUI");
// => 9

PDA Derivation (Solana)

Helper functions for deriving Program Derived Addresses:

import {
  deriveStreamConfigPda,
  deriveCardConfigPda,
  deriveLockupAddress,
  deriveStakeVaultAddress,
  deriveCardPurchasePda,
} from "@zebec-network/admin-sdk";

Environment Setup

Copy .env.example and fill in your credentials:

cp .env.example .env

# Solana
MAINNET_SECRET_KEYS=     # Admin keypair secret keys (mainnet)
DEVNET_SECRET_KEYS=      # Admin keypair secret keys (devnet)
RPC_URL=                 # Solana mainnet RPC endpoint
DEVNET_RPC_URL=          # Solana devnet RPC endpoint

# Sui
SUI_SECRET_KEYS=         # Sui admin keypair secret keys
HOP_API_KEY=             # Hop bridge API 

# EVM
EVM_PRIVATE_KEYS=        # Admin private keys
SEPOLIA_RPC_URL=         # Sepolia rpc url
BSC_RPC_URL=             # Bsc rpc url   
BASE_RPC_URL=            # Base rpc url
ODYSSEY_RPC_URL=         # Odyssey rpc url
BSC_TESTNET_RPC_URL=     # Bsc testnet rpc url
ONE_INCH_AUTH_TOKEN=     # 1inch auth token
ETHEREUM_RPC_URL=        # Ethereum rpc url
ODYSSEY_TESTNET_RPC_URL= # Odyssey testnet rpc url
POLYGON_AMOY_RPC_URL=    # Polygon amoy rpc url
POLYGON_RPC_URL=         # Polygon rpc url

Folder Structure

zebec-admin-sdk/
├── src/
│   ├── artifacts/              # Smart contract definitions
│   │   ├── abi/                # EVM contract ABIs (JSON)
│   │   ├── typechain-types/    # Generated TypeChain EVM types
│   │   ├── zebec_stream.ts     # Solana stream program IDL
│   │   ├── zebec_stake_v1.ts   # Solana staking program IDL
│   │   ├── zebec_instant_card.ts  # Solana card program IDL
│   │   ├── zebec_proxy_stream.ts  # Solana proxy stream IDL
│   │   └── index.ts
│   ├── services/
│   │   ├── streamServices.ts       # ZebecStreamAdminService
│   │   ├── stakingService.ts       # ZebecStakeAdminService
│   │   ├── solanaCardV2Service.ts  # Solana card services
│   │   ├── evmCardService.ts       # ZebecCardService (EVM)
│   │   ├── suiCardService.ts       # SuiCardAdminService
│   │   ├── proxyStreamService.ts   # ProxyStreamAdminService
│   │   └── index.ts
│   ├── constants.ts            # Network addresses and chain configs
│   ├── types.ts                # TypeScript type definitions
│   ├── utils.ts                # Utility functions
│   ├── pda.ts                  # Solana PDA derivation helpers
│   └── index.ts                # Public entry point
├── test/
│   ├── setup.ts                # Test keypair and client setup
│   └── sui/                    # Sui integration tests
├── .env.example
├── biome.json                  # Linter / formatter config
├── package.json
└── tsconfig.json

Scripts

| Script | Command | Description | | ------ | ------- | ----------- | | Build | yarn build | Compiles TypeScript to dist/ | | Clean | yarn clean | Removes the dist/ directory | | Test | yarn test | Runs all integration tests via Mocha | | Generate TypeChain | yarn gen:typechain | Regenerates TypeChain types from EVM ABIs in src/artifacts/abi/ |

Build

yarn build

Runs clean then tsc. Output goes to dist/ as ESM modules.

Test

yarn test

Runs ts-mocha against test/**/*.test.ts. Tests are integration tests that hit live RPC endpoints — ensure your .env is configured before running.

Generate TypeChain Types

yarn gen:typechain

Re-generates TypeScript types from ABI JSON files in src/artifacts/abi/. Run this after updating any EVM contract ABI.

License

MIT — © Zebec Network