Bagel SDK

The Bagel SDK enables developers to integrate private Solana transactions into their applications. It provides a simple interface for creating stealth addresses and sending private transactions.

Installation

npm install bagel-sdk

Basic Usage

import { createBagelSDK } from 'bagel-sdk';
 
// Initialize the SDK with API endpoint
const bagelSDK = createBagelSDK({
  baseURL: 'https://api.bagel.xyz',
});
 
// Use the SDK to create a stealth transaction
async function sendPrivateTransaction() {
  // 1. Resolve the recipient's Bagel ID to get their public keys
  const recipient = await bagelSDK.resolveRecipient('example.bagel.xyz');
  
  // 2. Create a stealth address for the recipient
  const { stealthAddress, ephemeralPublic } = await bagelSDK.createStealthAddress(
    recipient.viewingPublicKey,
    recipient.spendingPublicKey
  );
  
  // 3. Send SOL to the stealth address using your preferred method
  // (Implementation depends on your application's wallet integration)
  
  // 4. Publish the ephemeral key so the recipient can find the payment
  await bagelSDK.publishEphemeralKey({
    recipientId: 'example.bagel.xyz',
    ephemeralPublicKey: ephemeralPublic
  });
}

API Reference

Creating an SDK Instance

const bagelSDK = createBagelSDK({
  baseURL: 'https://api.bagel.xyz', // Bagel API endpoint
});

Resolving a Recipient

async function resolveRecipient(name: string): Promise<RecipientInfo>

This function resolves a Bagel domain (e.g., "username.bagel.xyz") to retrieve the recipient's public keys.

Returns:

interface RecipientInfo {
  viewingPublicKey: string;  // Hex-encoded public viewing key
  spendingPublicKey?: string; // Hex-encoded public spending key
}

Example:

const recipient = await bagelSDK.resolveRecipient('alice.bagel.xyz');
console.log(recipient.viewingPublicKey);

Creating a Stealth Address

async function createStealthAddress(
  recipientViewingPublicKey: string,
  recipientSpendingPublicKey: string,
): Promise<{
  ephemeralSecret: string;
  ephemeralPublic: string;
  stealthAddress: string;
}>

This function creates a unique stealth address for sending funds to a recipient.

Parameters:

• recipientViewingPublicKey: The recipient's public viewing key (hex-encoded)
• recipientSpendingPublicKey: The recipient's public spending key (hex-encoded)

Returns:

• ephemeralSecret: The ephemeral private key (hex-encoded)
• ephemeralPublic: The ephemeral public key (hex-encoded)
• stealthAddress: The stealth address (Solana base58-encoded)

Example:

const { stealthAddress, ephemeralPublic } = await bagelSDK.createStealthAddress(
  recipient.viewingPublicKey,
  recipient.spendingPublicKey
);

Publishing an Ephemeral Key

async function publishEphemeralKey(params: {
  recipientId: string;
  ephemeralPublicKey: string;
}): Promise<any>

This function publishes an ephemeral public key to the Bagel registry so that the recipient can discover and claim the payment.

Parameters:

• recipientId: The recipient's Bagel ID (e.g., "username.bagel.xyz")
• ephemeralPublicKey: The ephemeral public key (hex-encoded)

Example:

await bagelSDK.publishEphemeralKey({
  recipientId: 'alice.bagel.xyz',
  ephemeralPublicKey: ephemeralPublic
});

Sending a Transaction

async function sendTransaction(params: SendTransactionParams): Promise<string>

This function registers the ephemeral key and returns the stealth address.

Parameters:

interface SendTransactionParams {
  to: string;              // Stealth address
  amount: number;          // Amount to send
  ephemeralPubKey: string; // Ephemeral public key
  recipientId: string;     // Recipient's Bagel ID
}

Example:

const result = await bagelSDK.sendTransaction({
  to: stealthAddress,
  amount: 1.0, // SOL
  ephemeralPubKey: ephemeralPublic,
  recipientId: 'alice.bagel.xyz'
});

Integration Guide

Integrating with Web Applications

1. Install the SDK:

   npm install bagel-sdk

2. Initialize the SDK:

   import { createBagelSDK } from 'bagel-sdk';
    
   const bagelSDK = createBagelSDK({
     baseURL: 'https://api.bagel.xyz',
   });

3. Create a Send Function:

   async function sendPrivatePayment(recipientId, amount) {
     try {
       // Resolve recipient
       const recipient = await bagelSDK.resolveRecipient(recipientId);
       
       // Create stealth address
       const { stealthAddress, ephemeralPublic } = await bagelSDK.createStealthAddress(
         recipient.viewingPublicKey,
         recipient.spendingPublicKey
       );
       
       // Send transaction using your wallet provider
       // Example with phantom wallet:
       const transaction = await createTransferTransaction(stealthAddress, amount);
       const signature = await window.phantom.solana.signAndSendTransaction(transaction);
       
       // Publish ephemeral key
       await bagelSDK.publishEphemeralKey({
         recipientId,
         ephemeralPublicKey: ephemeralPublic
       });
       
       return signature;
     } catch (error) {
       console.error('Error sending private payment:', error);
       throw error;
     }
   }

Best Practices

1. Error Handling: Implement proper error handling for network failures and invalid inputs
2. User Experience: Provide clear feedback during the resolution and transaction processes
3. Security: Never expose or log ephemeral private keys
4. Validation: Validate recipient IDs and amounts before creating transactions
5. Testing: Test with small amounts before implementing in production

This SDK enables developers to add privacy features to their Solana applications with minimal effort, improving user experience while maintaining the security and privacy guarantees of the Bagel protocol.