@zerodev/solana-sponsorship-sdk 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 ZeroDev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,109 @@
+# Solana Sponsorship SDK
+
+A TypeScript SDK for handling Solana transaction sponsorship, built with Bun.
+
+## Installation
+
+```bash
+bun add @solana/kit @solana-program/system @zerodev/solana-sponsorship-sdk
+```
+
+## Quick Start
+
+```typescript
+import {
+  createTransactionMessage,
+  pipe,
+  setTransactionMessageLifetimeUsingBlockhash,
+  address,
+  blockhash,
+  lamports,
+  createSolanaRpc,
+  devnet,
+  generateKeyPairSigner,
+  partiallySignTransactionMessageWithSigners,
+  appendTransactionMessageInstructions,
+  setTransactionMessageFeePayerSigner,
+  createNoopSigner,
+} from "@solana/kit";
+import { getTransferSolInstruction } from "@solana-program/system";
+import { sponsorTransaction, createSponsorshipRpc } from "@zerodev/solana-sponsorship-sdk";
+
+async function main() {
+  // Create RPC clients
+  const sponsorshipRpc = createSponsorshipRpc({
+    endpoint: `https://rpc.zerodev.app/api/v3/svm/${PROJECT_ID}/chain/9034109931`,
+  });
+  const solanaRpc = createSolanaRpc(devnet("https://api.devnet.solana.com"));
+
+  // Get a recent blockhash
+  const { value: { blockhash: recentBlockhash, lastValidBlockHeight } } = 
+    await solanaRpc.getLatestBlockhash({ commitment: "finalized" }).send();
+
+  // Generate test keypairs
+  const fromKeypair = await generateKeyPairSigner();
+  const toKeypair = await generateKeyPairSigner();
+
+  // Create transfer instruction
+  const transferInstruction = getTransferSolInstruction({
+    source: fromKeypair,
+    destination: toKeypair.address,
+    amount: lamports(0n),
+  });
+
+  // Get fee payer from sponsorship server
+  const feePayer = await sponsorshipRpc.getFeePayer().send();
+
+  // Create and sponsor the transaction
+  const sponsoredMessage = await pipe(
+    createTransactionMessage({ version: "legacy" }),
+    (message) => setTransactionMessageFeePayerSigner(
+      createNoopSigner(address(feePayer)),
+      message
+    ),
+    (message) => appendTransactionMessageInstructions(
+      [transferInstruction],
+      message
+    ),
+    (message) => setTransactionMessageLifetimeUsingBlockhash(
+      {
+        blockhash: blockhash(recentBlockhash),
+        lastValidBlockHeight,
+      },
+      message
+    )
+  );
+
+  // Sign and sponsor the transaction
+  const signedMessage = await partiallySignTransactionMessageWithSigners(sponsoredMessage);
+  const response = await sponsorTransaction(sponsorshipRpc, signedMessage);
+  console.log(
+    `Sponsored and broadcast by server: https://explorer.solana.com/tx/${response.signature}?cluster=devnet`
+  );
+}
+```
+
+## Documentation
+
+### Core Concepts
+
+- **Sponsorship RPC**: Create and manage transaction sponsorship
+- **Fee Payer**: Get and set the sponsor's fee payer
+- **Transaction Signing**: Handle transaction signing with sponsored fee payer
+- **Utils**: Helper functions for common operations
+
+### API Reference
+
+#### `createSponsorshipRpc(config: SponsorshipConfig)`
+Creates a sponsorship RPC client for interacting with the sponsorship server.
+
+#### `sponsorTransaction(rpc, message)`
+Sponsors a transaction and returns a `SponsorshipResponse`.
+`response.signature` is the broadcast transaction signature, and `response.message` is the sponsored base64 wire transaction returned by the server.
+
+#### `getFeePayer()`
+Gets the sponsor's fee payer address from the sponsorship server.
+
+## License
+
+MIT License

package/dist/index.d.ts

@@ -0,0 +1 @@
+export { type SponsorshipApi, type SponsorshipRpc, type SponsorshipRpcRequest, type SponsorshipRequest, type SponsorshipResponse, type SponsorshipConfig, type GetFeePayerResponse, type RpcError, type RpcResponse, SponsorshipError, createSponsorshipRpc, sponsorTransaction, setTransactionMessageSponsorFeePayer, setTransactionMessageSponsorFeePayerNoopSigner } from './sponsorship';

package/dist/index.js

@@ -0,0 +1 @@
+export { SponsorshipError, createSponsorshipRpc, sponsorTransaction, setTransactionMessageSponsorFeePayer, setTransactionMessageSponsorFeePayerNoopSigner } from './sponsorship';

package/dist/sponsorship.d.ts

@@ -0,0 +1,49 @@
+import { type Base64EncodedWireTransaction, Transaction, type TransactionMessage, type ITransactionMessageWithFeePayer, type ITransactionMessageWithFeePayerSigner, Address } from "@solana/kit";
+export type SponsorshipRequest = [
+    message: Base64EncodedWireTransaction
+];
+export type SponsorshipResponse = {
+    signature: string;
+    feePayer: string;
+    fee: number;
+    message: Base64EncodedWireTransaction;
+};
+export type GetFeePayerResponse = {
+    feePayer: Address;
+};
+export type RpcError = {
+    code: number;
+    message: string;
+    data?: unknown;
+};
+export type RpcResponse<T> = {
+    jsonrpc: "2.0";
+    id: string;
+    result?: T;
+    error?: RpcError | string;
+};
+export declare class SponsorshipError extends Error {
+    code: number;
+    data?: unknown;
+    constructor(rpcError: RpcError);
+}
+export interface SponsorshipApi {
+    requestSponsorship(request: SponsorshipRequest): SponsorshipResponse;
+    getFeePayer(): Address;
+}
+export interface SponsorshipRpcRequest<TResponse> {
+    send(options?: {
+        abortSignal?: AbortSignal;
+    }): Promise<TResponse>;
+}
+export interface SponsorshipRpc {
+    requestSponsorship(request: SponsorshipRequest): SponsorshipRpcRequest<SponsorshipResponse>;
+    getFeePayer(): SponsorshipRpcRequest<Address>;
+}
+export interface SponsorshipConfig {
+    endpoint: string;
+}
+export declare function createSponsorshipRpc(config: SponsorshipConfig): SponsorshipRpc;
+export declare function setTransactionMessageSponsorFeePayer<TMessage extends TransactionMessage>(rpc: SponsorshipRpc, message: TMessage): Promise<TMessage & ITransactionMessageWithFeePayer<string>>;
+export declare function setTransactionMessageSponsorFeePayerNoopSigner<TMessage extends TransactionMessage>(rpc: SponsorshipRpc, message: TMessage): Promise<TMessage & ITransactionMessageWithFeePayerSigner<string>>;
+export declare function sponsorTransaction(rpc: SponsorshipRpc, message: Transaction): Promise<SponsorshipResponse>;

package/dist/sponsorship.js

@@ -0,0 +1,103 @@
+import { createRpc, createRpcMessage, address, getBase64EncodedWireTransaction, createNoopSigner, } from "@solana/kit";
+export class SponsorshipError extends Error {
+    constructor(rpcError) {
+        super(rpcError.message);
+        this.name = "SponsorshipError";
+        this.code = rpcError.code;
+        this.data = rpcError.data;
+    }
+}
+function unwrapRpcResponse(response) {
+    if (response.error) {
+        // Handle both JSON-RPC error objects and plain string errors (e.g. from gateway)
+        const rpcError = typeof response.error === 'string'
+            ? { code: -1, message: response.error }
+            : response.error;
+        throw new SponsorshipError(rpcError);
+    }
+    return response.result;
+}
+// RPC API implementation
+const sponsorshipRpcApi = new Proxy({}, {
+    get(target, p, receiver) {
+        const methodName = p.toString();
+        if (methodName === "requestSponsorship") {
+            return (request) => ({
+                execute: async ({ signal, transport, }) => {
+                    const response = (await transport({
+                        payload: createRpcMessage({
+                            methodName: "zd_sponsorSolanaTransaction",
+                            params: request,
+                        }),
+                        signal,
+                    }));
+                    return unwrapRpcResponse(response);
+                },
+            });
+        }
+        if (methodName === "getFeePayer") {
+            return () => ({
+                execute: async ({ signal, transport, }) => {
+                    const response = (await transport({
+                        payload: createRpcMessage({
+                            methodName: "zd_getFeePayer",
+                            params: [],
+                        }),
+                        signal,
+                    }));
+                    return address(unwrapRpcResponse(response).feePayer);
+                },
+            });
+        }
+        return Reflect.get(target, p, receiver);
+    },
+});
+// Custom transport that reads JSON-RPC error bodies on non-200 responses.
+// @solana/kit's default transport throws on non-200 before reading the body,
+// which loses the JSON-RPC error details (simulation logs, error codes, etc.).
+function createSponsorshipTransport(url) {
+    return async ({ payload, signal }) => {
+        const response = await fetch(url, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(payload),
+            signal,
+        });
+        return await response.json();
+    };
+}
+// RPC client creation
+export function createSponsorshipRpc(config) {
+    return createRpc({
+        api: sponsorshipRpcApi,
+        transport: createSponsorshipTransport(config.endpoint),
+    });
+}
+// Set sponsor fee payer function
+export async function setTransactionMessageSponsorFeePayer(rpc, message) {
+    // Get the fee payer address from the RPC
+    const feePayer = await rpc.getFeePayer().send();
+    // Return the message with the fee payer set
+    return {
+        ...message,
+        feePayer: address(feePayer),
+    };
+}
+// Set sponsor fee payer function with noop signer
+export async function setTransactionMessageSponsorFeePayerNoopSigner(rpc, message) {
+    // Get the fee payer address from the RPC
+    const feePayer = await rpc.getFeePayer().send();
+    // Create a noop signer with the fee payer address
+    const feePayerSigner = createNoopSigner(address(feePayer));
+    // Return the message with the fee payer signer set
+    return {
+        ...message,
+        feePayer: feePayerSigner.address,
+        feePayerSigner,
+    };
+}
+// Main sponsorship function
+export async function sponsorTransaction(rpc, message) {
+    const encodedMessage = getBase64EncodedWireTransaction(message);
+    return rpc.requestSponsorship([encodedMessage]).send();
+}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@zerodev/solana-sponsorship-sdk",
+  "version": "0.0.1",
+  "description": "TypeScript SDK for sponsoring Solana transactions via ZeroDev",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zerodevapp/solana-sponsorship-sdk.git"
+  },
+  "homepage": "https://github.com/zerodevapp/solana-sponsorship-sdk#readme",
+  "bugs": {
+    "url": "https://github.com/zerodevapp/solana-sponsorship-sdk/issues"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "bun test",
+    "lint": "eslint src --ext .ts",
+    "format": "prettier --write \"src/**/*.ts\""
+  },
+  "keywords": [
+    "solana",
+    "blockchain",
+    "sponsor",
+    "sdk",
+    "typescript",
+    "zerodev"
+  ],
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "author": "ZeroDev",
+  "license": "MIT",
+  "devDependencies": {
+    "@solana/kit": "2.1.0",
+    "@solana-program/system": "0.7.0",
+    "@types/node": "20.17.23",
+    "typescript": "5.8.2",
+    "eslint": "8.57.1",
+    "prettier": "3.5.3",
+    "bun-types": "1.2.4"
+  },
+  "peerDependencies": {
+    "@solana/kit": "^2.1.0"
+  }
+}