SDK Reference

Glitch Gremlin SDK Reference

Installation

npm install @glitch-gremlin/sdk

Core Concepts

GlitchSDK

The main class for interacting with the Glitch Gremlin platform.

import { GlitchSDK, TestType } from '@glitch-gremlin/sdk';

const sdk = new GlitchSDK({
    cluster: 'devnet',  // or 'mainnet-beta'
    wallet: yourWallet  // Solana wallet instance
});

API Reference

Chaos Testing

createChaosRequest

Creates a new chaos test request.

const request = await sdk.createChaosRequest({
    targetProgram: "Program ID to test",
    testType: TestType.FUZZ,
    duration: 300,    // seconds
    intensity: 5      // 1-10 scale
});

Parameters:

• targetProgram: PublicKey or string of program to test

• testType: FUZZ | LOAD | EXPLOIT | CONCURRENCY

• duration: 60-3600 seconds

• intensity: 1-10 scale

• params?: Optional test-specific parameters

Returns:

{
    requestId: string;
    waitForCompletion: () => Promise<ChaosResult>;
}

getRequestStatus

Get status of an existing request.

const status = await sdk.getRequestStatus("request-id");

Returns:

{
    requestId: string;
    status: 'completed' | 'failed';
    resultRef: string;  // IPFS/Arweave reference
    logs: string[];
    metrics?: {
        totalTransactions: number;
        errorRate: number;
        avgLatency: number;
    };
}

Governance

createProposal

Create a new governance proposal.

const proposal = await sdk.createProposal({
    title: "Test Popular DEX",
    description: "Run chaos tests on XYZ DEX",
    targetProgram: "DEX_PROGRAM_ID",
    testParams: {
        testType: TestType.EXPLOIT,
        duration: 600,
        intensity: 8
    },
    stakingAmount: 1000
});

Parameters:

• title: Proposal title

• description: Detailed description

• targetProgram: Program to test

• testParams: ChaosRequestParams

• stakingAmount: Amount of GLITCH to stake

Returns:

{
    id: string;
    signature: string;
}

vote

Vote on a governance proposal.

const txSignature = await sdk.vote(proposalId, true);

Staking

stakeTokens

Stake GLITCH tokens.

const txSignature = await sdk.stakeTokens(
    amount,     // Amount to stake
    lockupPeriod // Duration in seconds
);

Parameters:

• amount: Number of tokens to stake

• lockupPeriod: Lock duration (86400-31536000 seconds)

unstakeTokens

Unstake previously staked tokens.

const txSignature = await sdk.unstakeTokens(stakeId);

Token Economics

calculateChaosRequestFee

Calculate the fee for a chaos request.

const fee = await sdk.calculateChaosRequestFee({
    testType: TestType.FUZZ,
    duration: 300,
    intensity: 5
});

Error Handling

The SDK throws GlitchError with specific error codes:

try {
    await sdk.createChaosRequest(params);
} catch (error) {
    if (error instanceof GlitchError) {
        console.error(`Error ${error.code}: ${error.message}`);
    }
}

Common error codes:

• 1001: Insufficient funds

• 1002: Invalid program address

• 1003: Request timeout

• 1004: Invalid test type

• 1005: Invalid intensity

• 1006: Invalid duration

• 1007: Rate limit exceeded

• 1008: Insufficient stake amount

• 1009: Insufficient voting balance

• 1010: Already voted

• 1011: Invalid proposal ID

• 1012: Execution failed

• 1013: Proposal not passed

• 1014: Invalid lockup period

• 1015: Stake not found

• 1016: Tokens still locked

• 1008: Insufficient stake amount

• 1009: Insufficient voting balance

• 1010: Already voted

• 1011: Invalid proposal ID

• 1012: Execution failed

• 1013: Proposal not passed

• 1014: Invalid lockup period

• 1015: Stake not found

• 1016: Tokens still locked

Rate Limits

• 2 second cooldown between chaos requests

• Maximum 3 requests per minute per address

• 1 proposal per address per day

• Voting cooldown period between votes

• Maximum 10 active proposals at once

• Staking lockup period: 1 day to 1 year

Best Practices

1. Always handle errors appropriately:

try {
    const request = await sdk.createChaosRequest(params);
    const result = await request.waitForCompletion();
} catch (error) {
    if (error instanceof GlitchError) {
        // Handle specific error cases
    } else {
        // Handle unexpected errors
    }
}

1. Use appropriate test durations:

// Start with shorter tests
const request = await sdk.createChaosRequest({
    ...params,
    duration: 60,    // Start with 1 minute
    intensity: 1     // Start with low intensity
});

// Then scale up
const fullTest = await sdk.createChaosRequest({
    ...params,
    duration: 300,   // Increase to 5 minutes
    intensity: 5     // Increase intensity
});

1. Monitor test results:

const request = await sdk.createChaosRequest(params);
const result = await request.waitForCompletion();

if (result.metrics && result.metrics.errorRate > 0.1) {
    console.warn('High error rate detected:', result.metrics);
}

Examples

See the examples directory for complete usage examples:

• quick-test.ts: Simple test using an ephemeral wallet

• basic-test.ts: More detailed test with custom parameters

• governance-proposal.ts: Example of creating a governance proposal