Developer Guide

SDK Helper

Integration Overview

The zkLogin Paymaster Kit provides reusable TypeScript types and helpers for integrating sponsored transactions into any Sui dApp. Import from zklogin-paymaster-kit/sdk.

Prerequisites:
  • Sui Testnet RPC endpoint
  • Paymaster account with SUI balance for gas sponsorship
  • Google OAuth client ID (for real zkLogin)
  • zkProof generation service or circuit

1. Sponsor Request Payload

// Sponsor request payload
interface SponsorRequest {
  sender: string       // zkLogin user's Sui address
  txKind: string       // base64-encoded transaction kind
  label?: string       // optional label for tracking
  email?: string       // optional email for quota
}

// Create a request
import { createSponsorRequest } from 'zklogin-paymaster-kit/sdk'

const req = createSponsorRequest(
  '0xuser_address',
  'base64_encoded_tx_kind',
  { label: 'mint_nft', email: 'user@example.com' }
)

2. Sponsor Response

// Sponsor response
interface SponsorResponse {
  sponsored: boolean     // whether the tx was sponsored
  txDigest?: string      // Sui transaction digest
  receiptId?: string     // unique receipt identifier
  error?: string         // error message if rejected
  quotaRemaining?: number // remaining daily quota
}

3. Validation

// Validate a sponsor request
import { validateSponsorRequest } from 'zklogin-paymaster-kit/sdk'

const { valid, errors } = validateSponsorRequest(req)
if (!valid) {
  console.error('Invalid request:', errors)
  return
}

4. Mock Sponsor (for testing)

// Test with mock sponsor (no real gas cost)
import { mockSponsorTransaction } from 'zklogin-paymaster-kit/sdk'

const response = await mockSponsorTransaction({
  sender: '0xuser_address',
  txKind: 'base64_encoded_tx_kind',
  email: 'user@example.com',
})

if (response.sponsored) {
  console.log('Tx digest:', response.txDigest)
  console.log('Receipt:', response.receiptId)
}

5. Explorer URL Builder

// Build SuiVision explorer URL
import { buildExplorerUrl } from 'zklogin-paymaster-kit/sdk'

const url = buildExplorerUrl(txDigest)
// -> https://testnet.suivision.xyz/txblock/0x...

Production Notes

  • Replace mock sponsor with Sui SDK sponsored transaction API: use sui.signAndExecuteTransaction() with a sponsor wallet.
  • Store quota data in a persistent database (PostgreSQL, SQLite, or Walrus).
  • Implement rate limiting and IP allowlist for the sponsor endpoint.
  • Use zkLogin real flow: Google OAuth redirect + zk proof generation via a trusted service or browser-side circuit.
  • Monitor sponsor wallet balance and set up auto-top-up alerts.