# SDK Reference

## Glitch Gremlin SDK Reference

![Version](https://img.shields.io/badge/version-0.1.0-blue.svg)

### Installation

```bash
npm install @glitch-gremlin/sdk
```

### Core Concepts

#### GlitchSDK

The main class for interacting with the Glitch Gremlin platform.

```typescript
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.

```typescript
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:

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

**getRequestStatus**

Get status of an existing request.

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

Returns:

```typescript
{
    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.

```typescript
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:

```typescript
{
    id: string;
    signature: string;
}
```

**vote**

Vote on a governance proposal.

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

#### Staking

**stakeTokens**

Stake GLITCH tokens.

```typescript
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.

```typescript
const txSignature = await sdk.unstakeTokens(stakeId);
```

#### Token Economics

**calculateChaosRequestFee**

Calculate the fee for a chaos request.

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

### Error Handling

The SDK throws `GlitchError` with specific error codes:

```typescript
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:

```typescript
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
    }
}
```

2. Use appropriate test durations:

```typescript
// 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
});
```

3. Monitor test results:

```typescript
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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://ggai.gitbook.io/ggai-docs/developer-tools-and-documentation/sdk-reference.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.