@nezavis/sdk

TypeScript SDK for the Nezavis Solana escrow program — a marketplace payment system with escrow, disputes, and seller earning vaults.

Installation

npm install @nezavis/sdk
# or
yarn add @nezavis/sdk

Peer dependencies

npm install @coral-xyz/anchor @solana/web3.js @solana/spl-token

Quick Start

import { Connection, clusterApiUrl } from "@solana/web3.js";
import { BN } from "@coral-xyz/anchor";
import { NezavisClient, DisputeWinnerBuyer, DisputeWinnerSeller } from "@nezavis/sdk";

// Create a client (wallet = Anchor Wallet interface)
const connection = new Connection(clusterApiUrl("devnet"));
const client = new NezavisClient(connection, wallet);

// Fetch the global config
const config = await client.fetchConfig();
console.log("Platform fee:", config?.platformFeeBps.toString(), "bps");

// Fetch a payment by UUID
const payment = await client.fetchPaymentByUuid(
  "550e8400-e29b-41d4-a716-446655440000",
  "6ba7b810-9dad-11d1-80b4-00c04fd430c8"
);

API Reference

NezavisClient

Constructor

new NezavisClient(connection, wallet, options?)

| Param | Type | Description | |-------|------|-------------| | connection | Connection | Solana RPC connection | | wallet | Wallet | Anchor wallet (signing adapter) | | options.programId | PublicKey | Override program ID (default: G86p8ACuDxwKzAiFdUgbR5c6JZxFmyLBNBxsRKUm34r3) | | options.confirmOptions | ConfirmOptions | Transaction confirm options |

Account Fetchers

| Method | Returns | Description | |--------|---------|-------------| | fetchConfig() | NezavisConfig \| null | Fetch the global config PDA | | fetchPayment(orderId, productId) | Payment \| null | Fetch a payment by raw byte IDs | | fetchPaymentByUuid(orderUuid, productUuid) | Payment \| null | Fetch a payment by UUID strings | | fetchEarningVault(seller) | EarningVault \| null | Fetch a seller's earning vault | | fetchAllPayments() | Payment[] | Fetch all payment accounts | | fetchPaymentsByBuyer(buyer) | Payment[] | Filter payments by buyer | | fetchPaymentsBySeller(seller) | Payment[] | Filter payments by seller |

Instruction Builders

Low-level builders that return a TransactionInstruction. Use these when you need to compose custom transactions.

| Method | Signer | Description | |--------|--------|-------------| | buildInitializeConfig(params) | Admin | Initialize the global config + escrow PDA | | buildUpdateConfig(params) | Admin | Update config settings | | buildMakePayment({ purchaseInfo, oracleSignature, tokenMint }) | Buyer | Create payment + transfer to escrow | | buildRaiseDispute(orderId, productId) | Buyer | Flag a payment as disputed | | buildResolveDispute(orderId, productId, winner) | Admin | Resolve dispute (Buyer or Seller wins) | | buildClaimDisputedAmount(orderId, productId, tokenMint) | Buyer | Claim tokens back after winning dispute | | buildClaimPayment(orderId, productId, tokenMint, revenueVault) | Seller | Claim payment (after buffer time) | | buildWithdrawEarning(tokenMint, amount) | Seller | Withdraw from earning vault |

Send & Confirm Wrappers

Convenience methods that build, send, and confirm in one call. Return the transaction signature.

await client.initializeConfig(params);
await client.updateConfig(params);
await client.raiseDispute(orderId, productId);
await client.resolveDispute(orderId, productId, DisputeWinnerBuyer);
await client.claimDisputedAmount(orderId, productId, tokenMint);
await client.claimPayment(orderId, productId, tokenMint, revenueVault);
await client.withdrawEarning(tokenMint, new BN(1_000_000));

Static Utilities

// Build Ed25519 pre-instruction for oracle signature verification
const ed25519Ix = NezavisClient.buildEd25519Instruction(
  oraclePublicKey,
  message,
  oracleSignature
);

// Serialize purchase info for oracle signing
const message = NezavisClient.serializePurchaseInfoForSigning(purchaseInfo);

// Convert UUID to bytes
const orderId = NezavisClient.uuidToBytes("550e8400-e29b-41d4-a716-446655440000");

PDA Helpers

Standalone functions (also available as instance methods on the client):

import {
  findConfigPda,
  findEscrowPda,
  findPaymentPda,
  findEarningVaultPda,
} from "@nezavis/sdk";

const [configPda] = findConfigPda();
const [escrowPda] = findEscrowPda();
const [paymentPda] = findPaymentPda(orderId, productId);
const [earningVaultPda] = findEarningVaultPda(sellerPublicKey);

Error Handling

import { parseNezavisError, NEZAVIS_ERRORS } from "@nezavis/sdk";

try {
  await client.claimPayment(orderId, productId, tokenMint, revenueVault);
} catch (err) {
  const nezErr = parseNezavisError(err);
  if (nezErr) {
    console.error(nezErr.code, nezErr.errorName, nezErr.message);
  }
}

Payment Flow

Buyer: makePayment ──► Escrow holds tokens
                           │
         ┌─────────────────┼─────────────────┐
         ▼                 ▼                  ▼
    No dispute        raiseDispute        (buffer time passes)
         │                 │                  │
         │           resolveDispute           │
         │            ┌────┴────┐             │
         │            ▼         ▼             ▼
         │      Buyer wins  Seller wins   claimPayment
         │            │         │          (seller)
         │    claimDisputedAmount  claimPayment
         │      (buyer)          (seller)
         ▼
   claimPayment ──► Earning Vault ──► withdrawEarning
     (seller)        (- platform fee)     (seller)

Building

npm run build    # Outputs CJS + ESM + type declarations

License

MIT