STELLA Verifier SDK v2.0.1

Ultra-simplified SDK for STELLA Reward transaction submission. Get developer app IDs and submit transactions for tracking with just two core functions.

🚀 Features

• ✅ Network-per-function - Explicit testnet/mainnet selection
• ✅ Auto app ID extraction - API extracts app ID from transaction memo
• ✅ Core functionality only - Simple, focused API
• ✅ TypeScript support - Full type safety and IntelliSense
• ✅ React hooks - Easy frontend integration
• ✅ Automatic retries - Built-in error handling
• ✅ Validation utilities - Input validation helpers

📦 Installation

npm install stella-verifier-sdk

🎯 Quick Start

Basic Usage

import { StellaVerifier } from 'stella-verifier-sdk';

// Initialize SDK (no network needed in constructor)
const verifier = new StellaVerifier({
  timeout: 30000,
  retryAttempts: 3,
  debug: true
});

// Get developer's apps from testnet
const testnetApps = await verifier.getAppsByDeveloper({
  address: 'GAFTF57BRPZR23B23CMZVLOGGIJM5ND2DD7QU7P6QAHPFSGNNYIL5G2V',
  network: 'testnet'
});

console.log('Testnet apps:', testnetApps);
// Output: [{ appId: "B43A94D3B612-418E-9DF5", appName: "My DeFi Platform", owner: "GAFT...", createdAt: 1696000000 }]

// Get developer's apps from mainnet
const mainnetApps = await verifier.getAppsByDeveloper({
  address: 'GAFTF57BRPZR23B23CMZVLOGGIJM5ND2DD7QU7P6QAHPFSGNNYIL5G2V',
  network: 'mainnet'
});

// Submit a testnet transaction (app ID extracted automatically from memo)
const testnetResult = await verifier.submitTransaction({
  txHash: 'cf1bee75d4ac0a216cdd4fa826831424a6d86b345698cfee0a5e9979eb7b946a',
  network: 'testnet'
});

if (testnetResult.success) {
  console.log(`Testnet: Fee charged ${testnetResult.feeCharged} XLM for app ${testnetResult.appId}!`);
}

// Submit a mainnet transaction
const mainnetResult = await verifier.submitTransaction({
  txHash: 'cf1bee75d4ac0a216cdd4fa826831424a6d86b345698cfee0a5e9979eb7b946a',
  network: 'mainnet'
});

if (mainnetResult.success) {
  console.log(`Mainnet: Fee charged ${mainnetResult.feeCharged} XLM for app ${mainnetResult.appId}!`);
}

React Integration

import { useStellaVerifier } from 'stella-verifier-sdk/react';

function MyComponent() {
  const { 
    getAppsByDeveloper, 
    submitTransaction, 
    validateStellarAddress,
    validateTransactionHash,
    isLoading, 
    error 
  } = useStellaVerifier({
    timeout: 30000,
    debug: true
  });

  const handleGetApps = async () => {
    const apps = await getAppsByDeveloper({
      address: walletAddress,
      network: 'testnet'
    });
    
    console.log('Developer apps:', apps);
  };

  const handleSubmit = async () => {
    const result = await submitTransaction({
      txHash: transactionHash,
      network: 'testnet'
    });
    
    if (result.success) {
      alert(`Transaction submitted! Fee: ${result.feeCharged} XLM`);
    }
  };

  return (
    <div>
      <button onClick={handleGetApps} disabled={isLoading}>
        {isLoading ? 'Loading...' : 'Get My Apps'}
      </button>
      <button onClick={handleSubmit} disabled={isLoading}>
        {isLoading ? 'Submitting...' : 'Submit Transaction'}
      </button>
    </div>
  );
}

📚 API Reference

StellaVerifier Class

Constructor

new StellaVerifier(config?: StellaVerifierConfig)

Parameters:

• config.timeout? - Request timeout in ms (default: 60000)
• config.retryAttempts? - Retry attempts (default: 3)
• config.debug? - Enable debug logging (default: false)

Note: Network is specified per function call, not in constructor.

Core Methods

getAppsByDeveloper()

await verifier.getAppsByDeveloper({
  address: string,
  network: 'testnet' | 'mainnet'
}): Promise<AppInfo[]>

Get all apps created by a developer.

Parameters:

• address - Stellar address of the developer
• network - Network to query ('testnet' or 'mainnet')

Returns: Array of app information objects:

{
  appId: string;        // UUID-style App ID
  appName: string;      // Human-readable app name
  owner: string;        // Developer's Stellar address
  createdAt: number;    // Registration timestamp
}[]

submitTransaction()

await verifier.submitTransaction({
  txHash: string,
  network: 'testnet' | 'mainnet'
}): Promise<SubmissionResult>

Submit a transaction for tracking and reward processing. The API automatically extracts the app ID from the transaction memo.

Parameters:

• txHash - 64-character transaction hash
• network - Network to submit against ('testnet' or 'mainnet')

Returns:

{
  success: boolean;                    // Whether submission was successful
  transactionHash: string;             // Transaction hash that was submitted
  appId: string;                       // App ID extracted from transaction memo
  feeCharged?: string;                 // Fee charged in XLM (if successful)
  volume?: string;                     // Volume in XLM (if successful)
  feeChargedStroops?: string;          // Fee charged in stroops (if successful)
  volumeStroops?: string;              // Volume in stroops (if successful)
  message: string;                     // Success/error message
  error?: string;                      // Error details (if failed)
  errorCode?: string;                  // Error code for programmatic handling
  timestamp: string;                   // Submission timestamp
}

Utility Methods

validateStellarAddress()

verifier.validateStellarAddress(address: string): boolean

Validate Stellar address format.

validateTransactionHash()

verifier.validateTransactionHash(txHash: string): boolean

Validate transaction hash format (64 hexadecimal characters).

getConfig()

verifier.getConfig(): Required<StellaVerifierConfig>

Get current SDK configuration.

🎨 React Hooks

useStellaVerifier()

const {
  getAppsByDeveloper,
  submitTransaction,
  validateStellarAddress,
  validateTransactionHash,
  isLoading,
  error,
  verifier
} = useStellaVerifier({
  timeout?: number,
  retryAttempts?: number,
  debug?: boolean,
  autoInit?: boolean
});

Features:

• Automatic loading states
• Error handling
• Retry logic
• TypeScript support

🌐 Network Configuration

The SDK uses a unified API endpoint for both testnet and mainnet:

• API URL: https://stellarrewards.xyz/api
• Network handling: API internally differentiates between testnet and mainnet based on the network parameter
• No additional configuration needed

🛡️ Error Handling

import { StellaVerifierError, ERROR_CODES } from 'stella-verifier-sdk';

try {
  const result = await verifier.submitTransaction({
    txHash: 'invalid-hash',
    network: 'testnet'
  });
} catch (error) {
  if (error instanceof StellaVerifierError) {
    switch (error.code) {
      case ERROR_CODES.INVALID_TRANSACTION_HASH:
        console.log('Invalid transaction hash format');
        break;
      case ERROR_CODES.TRANSACTION_NOT_FOUND:
        console.log('Transaction not found on the Stellar network');
        break;
      case ERROR_CODES.INVALID_ADDRESS:
        console.log('Invalid Stellar address format');
        break;
      default:
        console.log('Unknown error:', error.message);
    }
  }
}

🔄 Migration from v1.x

Breaking Changes

1. Network parameter moved: From constructor to individual function calls
2. Simplified API: Removed non-core methods (registerApp, getAppStats, etc.)
3. Auto app ID extraction: submitTransaction no longer requires appId parameter
4. Function renamed: verifyTransaction → submitTransaction

Migration Guide

// ❌ Old v1.x syntax
const verifier = new StellaVerifier({ network: 'testnet' });
const result = await verifier.verifyTransaction({
  transactionHash: 'hash',
  appId: 'app-id'
});

// ✅ New v2.0.1 syntax
const verifier = new StellaVerifier();
const result = await verifier.submitTransaction({
  txHash: 'hash',
  network: 'testnet'
});

📖 Examples

Complete Integration Example

import { StellaVerifier } from 'stella-verifier-sdk';

async function integrateStellaRewards() {
  const verifier = new StellaVerifier({ debug: true });
  
  // Get developer's apps
  const apps = await verifier.getAppsByDeveloper({
    address: 'GAFTF57BRPZR23B23CMZVLOGGIJM5ND2DD7QU7P6QAHPFSGNNYIL5G2V',
    network: 'testnet'
  });
  
  console.log(`Found ${apps.length} apps:`, apps);
  
  // Submit a transaction
  const result = await verifier.submitTransaction({
    txHash: 'cf1bee75d4ac0a216cdd4fa826831424a6d86b345698cfee0a5e9979eb7b946a',
    network: 'testnet'
  });
  
  if (result.success) {
    console.log(`✅ Transaction submitted!`);
    console.log(`📊 App ID: ${result.appId}`);
    console.log(`💰 Fee charged: ${result.feeCharged} XLM`);
    console.log(`📈 Volume: ${result.volume} XLM`);
  } else {
    console.log(`❌ Submission failed: ${result.message}`);
  }
}

🔧 Development

# Install dependencies
npm install

# Build the package
npm run build

# Run tests
npm test

# Lint code
npm run lint

📄 License

MIT License - see LICENSE file for details.

🤝 Contributing

Contributions are welcome! Please read our contributing guidelines and submit pull requests.

📞 Support

• GitHub Issues: stella-reward/verifier-sdk/issues
• Documentation: docs.stella-reward.com
• Email: [email protected]

Version: 2.0.1
API Endpoint: https://stellarrewards.xyz/api
Network Support: Testnet & Mainnet
License: MIT