@pincerpay/solana 0.1.0 → 0.2.0

package/README.md

@@ -1,6 +1,11 @@
 # @pincerpay/solana
 
-Solana infrastructure integrations for PincerPay: Kora gasless transactions and Squads SPN smart accounts.
+[![npm](https://img.shields.io/npm/v/@pincerpay/solana?style=flat-square)](https://www.npmjs.com/package/@pincerpay/solana)
+[![downloads](https://img.shields.io/npm/dm/@pincerpay/solana?style=flat-square)](https://www.npmjs.com/package/@pincerpay/solana)
+[![license](https://img.shields.io/npm/l/@pincerpay/solana?style=flat-square)](https://github.com/ds1/pincerpay/blob/master/LICENSE)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.7-blue?style=flat-square&logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
+
+Solana infrastructure integrations for [PincerPay](https://pincerpay.com): Kora gasless transactions and Squads SPN smart accounts.
 
 ## Install
 
@@ -10,12 +15,15 @@ npm install @pincerpay/solana
 
 ## Kora (Gasless Transactions)
 
-Agents pay transaction fees in USDC instead of SOL via Kora signer nodes.
+Agents pay transaction fees in USDC instead of SOL via [Kora](https://launch.solana.com/docs/kora/json-rpc-api) signer nodes.
 
 ### Quick Start
 
 ```typescript
-import { createKoraClient, createKoraFacilitatorSvmSigner } from "@pincerpay/solana/kora";
+import { createKoraClient, createKoraFacilitatorSvmSigner, parseKoraConfig } from "@pincerpay/solana/kora";
+
+// Parse config from environment variables (KORA_RPC_URL, KORA_API_KEY)
+const config = parseKoraConfig(process.env);
 
 // Low-level client
 const kora = createKoraClient({
@@ -31,7 +39,7 @@ const signer = createKoraFacilitatorSvmSigner({
   rpcUrls: { "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1": "https://api.devnet.solana.com" },
 });
 
-await signer.init(); // Fetches fee payer address
+await signer.init(); // Fetches fee payer address from Kora node
 ```
 
 ### API Reference
@@ -49,14 +57,16 @@ function createKoraFacilitatorSvmSigner(options: {
   rpcUrls?: Record<string, string>;
 }): FacilitatorSvmSigner & { init(): Promise<void> };
 
-function parseKoraConfig(
-  env: Record<string, string | undefined>
-): KoraConfig | null;
+// Parse KORA_RPC_URL and KORA_API_KEY from env — returns null if no URL
+function parseKoraConfig(env: Record<string, string | undefined>): KoraConfig | null;
+
+// Zod schema for KoraConfig validation
+const koraConfigSchema: z.ZodObject<{ rpcUrl: z.ZodString; apiKey: z.ZodOptional<z.ZodString> }>;
 ```
 
 ## Squads SPN (Smart Accounts)
 
-Decentralized policy co-signer for agent sub-accounts with on-chain spending limits.
+Decentralized policy co-signer for agent sub-accounts with on-chain spending limits via the [Squads Protocol](https://squads.so).
 
 ### Quick Start
 
@@ -65,6 +75,7 @@ import {
   deriveSmartAccountPda,
   createSpendingLimit,
   checkSpendingLimit,
+  revokeSpendingLimit,
   SpendingLimitPeriod,
 } from "@pincerpay/solana/squads";
 
@@ -88,6 +99,9 @@ const ix = await createSpendingLimit(
 // Check remaining allowance
 const limit = await checkSpendingLimit(smartAccountPda, 0, rpcUrl);
 // { exists: true, remainingAmount: 8_000_000n, period: "Day" }
+
+// Revoke a spending limit
+const revokeIx = await revokeSpendingLimit(smartAccountPda, 0, authorityAddress, rentCollectorAddress);
 ```
 
 ### API Reference
@@ -108,7 +122,7 @@ async function deriveSpendingLimitPda(
 ): Promise<[Address, number]>;
 ```
 
-#### Spending Limit Management
+#### High-Level Spending Limit Management
 
 ```typescript
 async function createSpendingLimit(
@@ -124,6 +138,31 @@ async function revokeSpendingLimit(
 ): Promise<Instruction>;
 ```
 
+#### Low-Level Instruction Builders
+
+For fine-grained control over transaction construction:
+
+```typescript
+// Create a new Squads Smart Account
+function createSmartAccountInstruction(config: SmartAccountConfig): Promise<Instruction>;
+
+// Add a spending limit to an existing Smart Account
+function addSpendingLimitInstruction(
+  config: SpendingLimitConfig, spendingLimitIndex: number, authority: Address
+): Promise<Instruction>;
+
+// Use (decrement) a spending limit
+function useSpendingLimitInstruction(...): Promise<Instruction>;
+
+// Remove a spending limit and reclaim rent
+function removeSpendingLimitInstruction(params: {
+  smartAccountPda: Address;
+  spendingLimitIndex: number;
+  authority: Address;
+  rentCollector: Address;
+}): Promise<Instruction>;
+```
+
 #### Types
 
 ```typescript
@@ -167,11 +206,24 @@ const [smartAccount] = await deriveSmartAccountPda(creator, 0);
 const limit = await checkSpendingLimit(smartAccount, 0, rpcUrl);
 ```
 
+### Parse Kora config from environment
+
+```typescript
+import { parseKoraConfig } from "@pincerpay/solana/kora";
+
+const config = parseKoraConfig(process.env);
+if (config) {
+  console.log("Kora enabled:", config.rpcUrl);
+} else {
+  console.log("Kora not configured, using local keypair for gas");
+}
+```
+
 ## Anti-Patterns
 
 ### Don't skip `signer.init()` for Kora
 
-The Kora signer must call `init()` before use — it fetches the fee payer address from the Kora node.
+The Kora signer must call `init()` before use -- it fetches the fee payer address from the Kora node.
 
 ### Don't use Squads on EVM
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pincerpay/solana",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "type": "module",
   "description": "Solana integration for PincerPay. Kora gasless transactions and Squads smart account support.",
   "license": "MIT",
@@ -24,7 +24,16 @@
     "gasless",
     "usdc",
     "smart-accounts",
-    "session-keys"
+    "session-keys",
+    "typescript",
+    "web3",
+    "crypto",
+    "on-chain",
+    "http-402",
+    "spl-token",
+    "transfer-checked",
+    "devnet",
+    "mainnet"
   ],
   "files": [
     "dist",
@@ -51,7 +60,7 @@
     "@solana/kit": "^5.5.1",
     "@x402/svm": "^2.3.0",
     "zod": "^3.24",
-    "@pincerpay/core": "0.1.0"
+    "@pincerpay/core": "0.2.0"
   },
   "devDependencies": {
     "@scure/base": "^1.2.6",