> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sendai.fun/llms.txt
> Use this file to discover all available pages before exploring further.

# Fraction SDK

> TypeScript SDK for integrating with the Fraction protocol on Solana

## Installation

Install the Fraction SDK using your preferred package manager:

<CodeGroup>
  ```bash pnpm theme={"system"}
  pnpm install @sendaifun/fraction
  ```

  ```bash npm theme={"system"}
  npm install @sendaifun/fraction
  ```

  ```bash yarn theme={"system"}
  yarn add @sendaifun/fraction
  ```
</CodeGroup>

## Quick Start

### Initialize Client

```typescript theme={"system"}
import { Fraction } from '@sendaifun/fraction';
import { Connection, Keypair } from '@solana/web3.js';

const connection = new Connection('https://api.devnet.solana.com');
const payer = Keypair.generate();

// Initialize client
const client = new Fraction(
  'https://api.devnet.solana.com', // RPC endpoint
  payer.publicKey                  // Transaction payer
);
```

### Create Revenue Split Configuration

```typescript theme={"system"}
const participants = [
  { wallet: teamMember1.publicKey, shareBps: 4000 }, // 40%
  { wallet: teamMember2.publicKey, shareBps: 3000 }, // 30%
  { wallet: teamMember3.publicKey, shareBps: 2000 }, // 20%
  { wallet: teamMember4.publicKey, shareBps: 1000 }, // 10%
];

const { tx, fractionConfigPda } = await client.createFraction({
  participants,
  authority: authority.publicKey,
  name: 'team-revenue-split',
  botWallet: distributionAgent.publicKey
});
```

### Execute Distribution

```typescript theme={"system"}
// Agent triggers distribution
const tx = await client.claimAndDistribute(
  fractionConfigPda,     // Configuration account
  usdcMint               // Token mint to distribute
);
```

## API Reference

### Client Class

#### Constructor

```typescript theme={"system"}
new Fraction(rpc?: string, payer?: PublicKey)
```

<ParamField path="rpc" type="string" optional>
  RPC endpoint URL (defaults to mainnet-beta)
</ParamField>

<ParamField path="payer" type="PublicKey" optional>
  Transaction fee payer (only required for versioned transactions)
</ParamField>

#### Methods

<Expandable title="createFraction">
  <ParamField path="input" type="CreatorFractionInputArgs" required>
    Configuration for the new fraction setup
  </ParamField>

  ```typescript theme={"system"}
  type CreatorFractionInputArgs = {
    participants: Participant[];
    authority: PublicKey;
    name?: string;
    botWallet: PublicKey;
  }
  ```

  **Returns:** `Promise<{ tx: Transaction | VersionedTransaction, fractionConfigPda: PublicKey }>`

  Creates a new revenue split configuration with the specified participants and settings.
</Expandable>

<Expandable title="updateFraction">
  <ParamField path="config" type="PublicKey" required>
    The fraction configuration account to update
  </ParamField>

  <ParamField path="input" type="UpdateFractionInputArgs" required>
    Updated configuration parameters
  </ParamField>

  ```typescript theme={"system"}
  type UpdateFractionInputArgs = {
    participants: Participant[];
    botWallet?: PublicKey;
  }
  ```

  **Returns:** `Promise<Transaction | VersionedTransaction>`

  Updates an existing fraction configuration with new participants or agent wallet.
</Expandable>

<Expandable title="claimAndDistribute">
  <ParamField path="config" type="PublicKey" required>
    The fraction configuration account
  </ParamField>

  <ParamField path="mint" type="PublicKey" required>
    The SPL token mint to distribute
  </ParamField>

  **Returns:** `Promise<Transaction | VersionedTransaction>`

  Executes distribution of accumulated tokens to all participants according to their configured shares.
</Expandable>

### State Queries

<Expandable title="getFractionsByParticipant">
  <ParamField path="participant" type="PublicKey" required>
    Wallet address of the participant
  </ParamField>

  **Returns:** `Promise<FractionConfig[]>`

  Retrieves all fraction configurations where the specified wallet is a participant.
</Expandable>

<Expandable title="getFractionsByConfig">
  <ParamField path="config" type="PublicKey" required>
    The fraction configuration account
  </ParamField>

  **Returns:** `Promise<FractionConfig>`

  Retrieves the details of a specific fraction configuration account.
</Expandable>

<Expandable title="getFractionBalance">
  <ParamField path="config" type="PublicKey" required>
    The fraction configuration account
  </ParamField>

  **Returns:** `Promise<FractionConfig>`

  Gets the current treasury balance for the specified configuration.
</Expandable>

## Advanced Usage

### Low-Level Instructions

For advanced users who need fine-grained control over transaction building:

```typescript theme={"system"}
import { createFractionIx, getProgram } from '@sendaifun/fraction';

const program = getProgram(connection);

// Create instruction
const { ix, fractionConfigPda } = await createFractionIx(program, {
  participants: participants,
  authority: authority.publicKey,
  botWallet: agent.publicKey
});

// Build composite transaction
const tx = new Transaction()
  .add(setupInstruction)
  .add(ix)
  .add(followupInstruction);
```

### Treasury Management

Calculate and manage treasury accounts:

```typescript theme={"system"}
import { getAssociatedTokenAddressSync } from '@solana/spl-token';

// Calculate treasury address
const treasuryAddress = getAssociatedTokenAddressSync(
  tokenMint,          // Token to be distributed
  fractionConfigPda,  // Treasury owner (PDA)
  true                // Allow off-curve addresses
);

// Fund treasury
await transfer(
  connection,
  payer,
  sourceTokenAccount,
  treasuryAddress,
  authority,
  amount
);
```

## Examples

### Enterprise Revenue Distribution

```typescript theme={"system"}
import { Fraction } from '@sendaifun/fraction';
import { Connection, Keypair } from '@solana/web3.js';

const connection = new Connection('https://api.mainnet-beta.solana.com');
const client = new Fraction(connection.rpcEndpoint, authority.publicKey);

// Define revenue allocation
const participants = [
  { wallet: founder.publicKey, shareBps: 4000 },    // 40% founder
  { wallet: team.publicKey, shareBps: 3000 },       // 30% team  
  { wallet: investors.publicKey, shareBps: 2000 },  // 20% investors
  { wallet: operations.publicKey, shareBps: 1000 }  // 10% operations
];

// Deploy configuration
const { tx, fractionConfigPda } = await client.createFraction({
  participants,
  authority: company.publicKey,
  name: 'quarterly-revenue-2024',
  botWallet: automatedAgent.publicKey
});

// Sign and submit
await connection.sendTransaction(tx, [authority]);
```

### Multi-Token Distribution

```typescript theme={"system"}
const tokens = [
  { mint: usdcMint, name: 'USDC Revenue' },
  { mint: solMint, name: 'SOL Rewards' },
  { mint: projectToken, name: 'Token Emissions' }
];

// Distribute multiple tokens using same configuration
for (const token of tokens) {
  const distributionTx = await client.claimAndDistribute(
    fractionConfigPda,
    token.mint
  );
  
  await connection.sendTransaction(distributionTx, [agent]);
  console.log(`Distributed ${token.name}`);
}
```

### Dynamic Updates

```typescript theme={"system"}
// Quarterly rebalancing
const newAllocation = [
  { wallet: founder.publicKey, shareBps: 3500 },    // Reduced to 35%
  { wallet: team.publicKey, shareBps: 3500 },       // Increased to 35%
  { wallet: investors.publicKey, shareBps: 2000 },  // Maintained 20%
  { wallet: operations.publicKey, shareBps: 1000 }  // Maintained 10%
];

const updateTx = await client.updateFraction(fractionConfigPda, {
  participants: newAllocation,
  botWallet: newAgent.publicKey // Optional: update agent
});

await connection.sendTransaction(updateTx, [authority]);
```

## Error Handling

### Common Validation Errors

The SDK implements client-side validation with clear error messages:

| Error                        | Description                                |
| ---------------------------- | ------------------------------------------ |
| `InvalidShareDistribution`   | Participant shares don't sum to 10,000 BPS |
| `NoFundsToDistribute`        | Treasury account is empty                  |
| `DuplicateParticipantWallet` | Same wallet appears multiple times         |
| `BotWalletConflict`          | Agent wallet matches participant wallet    |
| `SystemProgramParticipant`   | System program cannot have non-zero shares |

### Error Handling Pattern

```typescript theme={"system"}
async function safeDistribution(config: PublicKey, mint: PublicKey) {
  try {
    const tx = await client.claimAndDistribute(config, mint);
    const signature = await connection.sendTransaction(tx, [agent]);
    return { success: true, signature };
  } catch (error) {
    if (error.message.includes('NoFundsToDistribute')) {
      return { success: false, reason: 'Treasury empty' };
    }
    throw error; // Re-throw unexpected errors
  }
}
```

## Type Definitions

### Core Types

```typescript theme={"system"}
type Participant = {
  wallet: PublicKey;
  shareBps: number; // 0-10,000 basis points (0-100%)
}

type FractionConfig = {
  authority: PublicKey;
  name: string;
  participants: Participant[];
  botWallet: PublicKey;
  incentiveBps: number;
  bump: number;
}
```

<Note>
  **Basis Points (BPS)**: Share allocations use basis points where 10,000 BPS = 100%. For example, 4000 BPS = 40%.
</Note>

### Configuration Derivation

```typescript theme={"system"}
import { PublicKey } from '@solana/web3.js';

// Derive configuration PDA
const [configPda, bump] = PublicKey.findProgramAddressSync(
  [
    Buffer.from("fraction_config"),
    authority.toBuffer(),
    Buffer.from(configurationName)
  ],
  programId
);
```

## Program IDL

The complete Interface Description Language (IDL) for the Fraction protocol:

```json theme={"system"}
{
  "address": "FracVQuBhSeBvbw1qNrJKkDmcdPcFYWdneoKbJa3HMrj",
  "metadata": {
    "name": "fraction",
    "version": "0.1.0",
    "spec": "0.1.0",
    "description": "Created with Anchor"
  },
  "instructions": [
    {
      "name": "claim_and_distribute",
      "discriminator": [3],
      "accounts": [
        { "name": "bot_wallet", "writable": true, "signer": true },
        { "name": "authority" },
        {
          "name": "fraction_config",
          "writable": true,
          "pda": {
            "seeds": [
              {
                "kind": "const",
                "value": [
                  102, 114, 97, 99, 116, 105, 111, 110, 95, 99, 111, 110, 102,
                  105, 103
                ]
              },
              {
                "kind": "account",
                "path": "fraction_config.authority",
                "account": "FractionConfig"
              },
              {
                "kind": "account",
                "path": "fraction_config.name",
                "account": "FractionConfig"
              }
            ]
          }
        },
        {
          "name": "treasury",
          "writable": true,
          "pda": {
            "seeds": [
              { "kind": "account", "path": "fraction_config" },
              { "kind": "account", "path": "token_program" },
              { "kind": "account", "path": "treasury_mint" }
            ],
            "program": {
              "kind": "const",
              "value": [
                140, 151, 37, 143, 78, 36, 137, 241, 187, 61, 16, 41, 20, 142,
                13, 131, 11, 90, 19, 153, 218, 255, 16, 132, 4, 142, 123, 216,
                219, 233, 248, 89
              ]
            }
          }
        },
        { "name": "treasury_mint" },
        { "name": "bot_token_account", "writable": true },
        { "name": "participant_token_account_0", "writable": true },
        { "name": "participant_token_account_1", "writable": true },
        { "name": "participant_token_account_2", "writable": true },
        { "name": "participant_token_account_3", "writable": true },
        { "name": "participant_token_account_4", "writable": true },
        { "name": "token_program" },
        {
          "name": "system_program",
          "address": "11111111111111111111111111111111"
        }
      ],
      "args": []
    },
    {
      "name": "initialize_fraction",
      "discriminator": [1],
      "accounts": [
        { "name": "authority", "writable": true, "signer": true },
        {
          "name": "fraction_config",
          "writable": true,
          "pda": {
            "seeds": [
              {
                "kind": "const",
                "value": [
                  102, 114, 97, 99, 116, 105, 111, 110, 95, 99, 111, 110, 102,
                  105, 103
                ]
              },
              { "kind": "account", "path": "authority" },
              { "kind": "arg", "path": "name" }
            ]
          }
        },
        {
          "name": "system_program",
          "address": "11111111111111111111111111111111"
        }
      ],
      "args": [
        { "name": "name", "type": "string" },
        {
          "name": "participants",
          "type": { "array": [{ "defined": { "name": "Participant" } }, 5] }
        },
        { "name": "bot_wallet", "type": "pubkey" }
      ]
    },
    {
      "name": "update_fraction",
      "discriminator": [2],
      "accounts": [
        {
          "name": "authority",
          "signer": true,
          "relations": ["fraction_config"]
        },
        {
          "name": "fraction_config",
          "writable": true,
          "pda": {
            "seeds": [
              {
                "kind": "const",
                "value": [
                  102, 114, 97, 99, 116, 105, 111, 110, 95, 99, 111, 110, 102,
                  105, 103
                ]
              },
              {
                "kind": "account",
                "path": "fraction_config.authority",
                "account": "FractionConfig"
              },
              {
                "kind": "account",
                "path": "fraction_config.name",
                "account": "FractionConfig"
              }
            ]
          }
        }
      ],
      "args": [
        {
          "name": "participants",
          "type": { "array": [{ "defined": { "name": "Participant" } }, 5] }
        },
        { "name": "bot_wallet", "type": "pubkey" }
      ]
    }
  ],
  "accounts": [{ "name": "FractionConfig", "discriminator": [1] }],
  "errors": [
    {
      "code": 6000,
      "name": "InvalidShareDistribution",
      "msg": "Invalid share distribution - must sum to 10,000"
    },
    { "code": 6001, "name": "NameTooLong", "msg": "Name too long" },
    {
      "code": 6002,
      "name": "NoFundsToDistribute",
      "msg": "No funds to distribute"
    },
    {
      "code": 6003,
      "name": "ArithmeticOverflow",
      "msg": "Arithmetic overflow"
    },
    {
      "code": 6004,
      "name": "DuplicateParticipantWallet",
      "msg": "Duplicate participant wallet detected"
    },
    {
      "code": 6005,
      "name": "BotWalletConflict",
      "msg": "Bot wallet cannot be the same as any participant wallet"
    },
    {
      "code": 6006,
      "name": "InvalidAuthority",
      "msg": "Invalid authority provided"
    },
    { "code": 6007, "name": "InvalidBot", "msg": "Invalid bot wallet" },
    {
      "code": 6008,
      "name": "SystemProgramParticipant",
      "msg": "System program cannot be a participant wallet"
    },
    { "code": 6009, "name": "InvalidAccount", "msg": "Invalid account owner" }
  ],
  "types": [
    {
      "name": "FractionConfig",
      "type": {
        "kind": "struct",
        "fields": [
          { "name": "authority", "type": "pubkey" },
          { "name": "name", "type": "string" },
          {
            "name": "participants",
            "type": { "array": [{ "defined": { "name": "Participant" } }, 5] }
          },
          { "name": "bot_wallet", "type": "pubkey" },
          { "name": "incentive_bps", "type": "u8" },
          { "name": "bump", "type": "u8" }
        ]
      }
    },
    {
      "name": "Participant",
      "type": {
        "kind": "struct",
        "fields": [
          { "name": "wallet", "type": "pubkey" },
          { "name": "share_bps", "type": "u16" }
        ]
      }
    }
  ]
}

```

<Note>
  **Program Address**: The Fraction protocol is deployed at `Ck2PtB73t36kjk4mLUztwsBV9jvq7q3mGfSNmQevwFgg`. This IDL can be used with Anchor clients or other Solana development tools for direct program interaction.
</Note>

## Best Practices

<Tip>
  **Share Distribution**: Always ensure participant shares sum to exactly 10,000 BPS (100%) to avoid validation errors.
</Tip>

<Tip>
  **Agent Selection**: Choose reliable agents for distribution triggers. Consider using services like Clockwork for automated scheduling.
</Tip>

<Warning>
  **Authority Security**: The authority can update configurations and should use secure key management practices.
</Warning>

<Info>
  **Multi-Token Support**: The same configuration can distribute different SPL tokens - just call `claimAndDistribute` with different mint addresses.
</Info>