@unifiedflow/unified-flow-sdk 1.0.3 → 1.0.5

package/README.md

@@ -1,227 +1,275 @@
 # @unifiedflow/unified-flow-sdk
 
-TypeScript SDK for interacting with the **Unified Flow** on-chain token vesting and streaming program on Solana.
+TypeScript SDK for interacting with the **Unified Flow** on-chain token vesting and streaming protocol on Solana.
 
 ---
 
-## Installation
+# Installation
 
 ```bash
 npm install @unifiedflow/unified-flow-sdk
-# or
-yarn add @unifiedflow/unified-flow-sdk
 ```
 
-### Peer Dependencies
+or
 
 ```bash
-npm install @coral-xyz/anchor @solana/web3.js @solana/spl-token
+yarn add @unifiedflow/unified-flow-sdk
 ```
 
-> **Version note:** Make sure your project uses the same `@coral-xyz/anchor` version as the SDK to avoid type conflicts. Add to `package.json` if needed:
-> ```json
-> { "overrides": { "@coral-xyz/anchor": "<sdk-anchor-version>" } }
-> ```
+## Peer Dependencies
+
+```bash
+npm install \
+  @coral-xyz/anchor \
+  @solana/web3.js \
+  @solana/spl-token
+```
 
 ---
 
-## Quick Start
+# Quick Start
 
-### 1. Initialize the Client
+## Initialize Client
 
-```typescript
-import { useAnchorWallet, useConnection } from "@solana/wallet-adapter-react";
-import { AnchorProvider, Program } from "@coral-xyz/anchor";
-import { IDL, UnifiedFlow, UnifiedFlowClient } from "@unifiedflow/unified-flow-sdk";
+```ts
 import { useMemo } from "react";
+import { Program, AnchorProvider } from "@coral-xyz/anchor";
+import { useConnection } from "@solana/wallet-adapter-react";
+
+import {
+  IDL,
+  UnifiedFlowClient,
+  type UnifiedFlow,
+} from "@unifiedflow/unified-flow-sdk";
+
+import { useWalletSession } from "@wallet-standard/react";
 
 export function useUnifiedFlowClient() {
   const { connection } = useConnection();
-  const wallet = useAnchorWallet();
+  const wallet = useWalletSession();
 
   return useMemo(() => {
     if (!wallet) return null;
 
-    const provider = new AnchorProvider(connection, wallet, {
-      commitment: "confirmed",
-    });
-
-    const program = new Program(IDL, provider) as any;
-    return new UnifiedFlowClient(program);
+    const provider = new AnchorProvider(
+      connection,
+      {} as any,
+      { commitment: "confirmed" }
+    );
+
+    const program = new Program(
+      IDL,
+      provider
+    ) as Program<UnifiedFlow>;
+
+    return new UnifiedFlowClient(
+      program,
+      wallet,
+      connection,
+      "confirmed"
+    );
   }, [wallet, connection]);
 }
 ```
 
-### 2. Use in a Component
+---
+
+# Transaction Status Tracking
+
+All transaction methods support an optional status callback.
+
+```ts
+await client.withdraw(streamPDA, (status) => {
+  switch (status) {
+    case "wallet_approval":
+      console.log("Waiting for wallet approval");
+      break;
+
+    case "sending":
+      console.log("Sending transaction");
+      break;
+
+    case "confirming":
+      console.log("Confirming transaction");
+      break;
+  }
+});
+```
 
-```typescript
-const client = useUnifiedFlowClient();
+Available phases:
 
-if (!client) return <p>Connect your wallet</p>;
+```ts
+type TxProgressPhase =
+  | "wallet_approval"
+  | "sending"
+  | "confirming";
 ```
 
 ---
 
-## Vesting Types
+# Vesting Types
 
-| Value | Type        | Description                                      |
-|-------|-------------|--------------------------------------------------|
-| `0`   | `LINEAR`    | Tokens vest continuously over time               |
-| `1`   | `CLIFF`     | All tokens unlock at a single cliff timestamp    |
-| `2`   | `MILESTONE` | Tokens unlock per milestone, approved by creator |
+| Value | Type      | Description                        |
+| ----- | --------- | ---------------------------------- |
+| 0     | LINEAR    | Continuous linear vesting          |
+| 1     | CLIFF     | Entire allocation unlocks at cliff |
+| 2     | MILESTONE | Unlocks milestone-by-milestone     |
 
 ---
 
-## API Reference
+# API Reference
 
-### `createStream`
+## createStream
 
-Create a new vesting stream.
+Creates a new stream.
 
-```typescript
-const builder = await client.createStream(
-  creator,          // PublicKey — stream creator / funder
-  recipient,        // PublicKey — token recipient
-  mint,             // PublicKey — SPL token mint
-  new BN(1_000_000),// amount — total tokens (in smallest unit)
-  new BN(startTs),  // start timestamp (Unix seconds)
-  new BN(cliffTs),  // cliff timestamp (set equal to startTs if no cliff)
-  new BN(endTs),    // end timestamp
-  0,                // vestingType: 0 = linear, 1 = cliff, 2 = milestone
-  [],               // milestones: MilestoneInput[] (empty for non-milestone)
-  new BN(nonce)     // unique nonce per creator+recipient pair
+```ts
+const result = await client.createStream(
+  recipient,
+  mint,
+  new BN(1_000_000),
+  new BN(startTs),
+  new BN(cliffTs),
+  new BN(endTs),
+  0,
+  [],
+  new BN(nonce)
 );
 
-const txSig = await builder.rpc();
+console.log(result.signature);
 ```
 
-**Milestone stream example:**
+### Milestone Example
 
-```typescript
-const milestones: MilestoneInput[] = [
+```ts
+const milestones = [
   { amount: new BN(250_000) },
   { amount: new BN(250_000) },
   { amount: new BN(500_000) },
 ];
 
-const builder = await client.createStream(
-  creator, recipient, mint,
+await client.createStream(
+  recipient,
+  mint,
   new BN(1_000_000),
-  new BN(startTs), new BN(startTs), new BN(endTs),
-  2,           // MILESTONE
+  new BN(startTs),
+  new BN(startTs),
+  new BN(endTs),
+  2,
   milestones,
   new BN(nonce)
 );
 ```
 
+Returns:
+
+```ts
+{
+  signature: string;
+}
+```
+
 ---
 
-### `withdraw`
+## withdraw
 
-Withdraw vested/unlocked tokens from a stream. Callable by the recipient.
+Withdraw vested tokens.
 
-```typescript
-const builder = await client.withdraw(
-  streamPDA,  // PublicKey — stream account address
-  recipient,  // PublicKey
-  mint        // PublicKey
+```ts
+const result = await client.withdraw(
+  streamPDA
 );
 
-const txSig = await builder.rpc();
+console.log(result.signature);
 ```
 
+The recipient must be the connected wallet.
+
 ---
 
-### `cancel`
+## cancel
 
-Cancel an active stream. Returns unvested tokens to the creator. Callable by the creator.
+Cancel a stream.
 
-```typescript
-const builder = await client.cancel(
-  streamPDA,  // PublicKey — stream account address
-  creator,    // PublicKey
-  recipient,  // PublicKey
-  mint        // PublicKey
+```ts
+const result = await client.cancel(
+  streamPDA
 );
 
-const txSig = await builder.rpc();
+console.log(result.signature);
 ```
 
+The creator must be the connected wallet.
+
 ---
 
-### `unlockMilestone`
+## unlockMilestone
 
-Unlock the next milestone in a milestone vesting stream. Callable by the creator.
+Unlock a milestone.
 
-```typescript
-const builder = await client.unlockMilestone(
-  streamPDA,       // PublicKey
-  creator,         // PublicKey
-  milestoneIndex   // number — 0-indexed
+```ts
+const result = await client.unlockMilestone(
+  streamPDA,
+  0
 );
 
-const txSig = await builder.rpc();
+console.log(result.signature);
 ```
 
 ---
 
-### `editMilestone`
+## editMilestone
 
-Change the token amount for a specific milestone (before it is unlocked).
+Update a milestone allocation.
 
-```typescript
-const builder = await client.editMilestone(
+```ts
+const result = await client.editMilestone(
   streamPDA,
-  creator,
   mint,
-  milestoneIndex,    // number
-  new BN(newAmount)  // BN
+  milestoneIndex,
+  new BN(newAmount)
 );
 
-const txSig = await builder.rpc();
+console.log(result.signature);
 ```
 
 ---
 
-### `editCliff`
+## editCliff
 
-Update the cliff timestamp on a cliff vesting stream.
+Update the cliff timestamp.
 
-```typescript
-const builder = await client.editCliff(
+```ts
+const result = await client.editCliff(
   streamPDA,
-  creator,
   new BN(newCliffTs)
 );
 
-const txSig = await builder.rpc();
+console.log(result.signature);
 ```
 
 ---
 
-### `editLinear`
+## editLinear
 
-Extend the end timestamp and/or top up tokens on a linear vesting stream. Both operations happen in a single transaction.
+Extend a linear stream and/or deposit additional tokens.
 
-```typescript
-const builder = await client.editLinear(
+```ts
+const result = await client.editLinear(
   streamPDA,
-  creator,
   mint,
-  new BN(newEndTs),    // new end timestamp
-  new BN(topupAmount)  // additional tokens to deposit (0 if no top-up)
+  new BN(newEndTs),
+  new BN(topupAmount)
 );
 
-const txSig = await builder.rpc();
+console.log(result.signature);
 ```
 
 ---
 
-## PDA Helpers
+# PDA Helpers
 
-The SDK exports PDA derivation utilities if you need raw account addresses:
-
-```typescript
+```ts
 import {
   getConfigPDA,
   getStreamPDA,
@@ -229,64 +277,68 @@ import {
   getFeeVaultPDA,
   getVaultATA,
 } from "@unifiedflow/unified-flow-sdk";
-
-const [streamPDA] = getStreamPDA(creator, recipient, nonce, programId);
-const [milestonePDA] = getMilestonePDA(streamPDA, milestoneIndex, programId);
 ```
 
----
+### Stream PDA
 
-## Chainlink Oracle
+```ts
+const [streamPDA] = getStreamPDA(
+  creator,
+  recipient,
+  nonce,
+  programId
+);
+```
 
-Withdrawal fees are denominated in USD and calculated on-chain via the Chainlink SOL/USD price feed. The SDK wires this up automatically — no extra configuration needed.
+### Milestone PDA
 
-| Constant              | Value                                        |
-|-----------------------|----------------------------------------------|
-| `CHAINLINK_PROGRAM_ID`| `HEvSKofvBgfaexv23kMabbYqxasxU3mQ4ibBMEmJWHny` |
-| `SOL_USD_FEED`        | `99B2bTijsU6f1GCT73HmdR7HCFFjGMBcPZY6jZ96ynrR` |
+```ts
+const [milestonePDA] = getMilestonePDA(
+  streamPDA,
+  milestoneIndex,
+  programId
+);
+```
 
 ---
 
-## Builder Pattern
-
-All client methods return an **Anchor instruction builder**. You have three options:
+# Chainlink Integration
 
-```typescript
-const builder = await client.withdraw(streamPDA, recipient, mint);
+Withdrawal fees are priced in USD and converted on-chain using Chainlink SOL/USD.
 
-// Execute and return transaction signature
-const txSig = await builder.rpc();
+```ts
+CHAINLINK_PROGRAM_ID
+= HEvSKofvBgfaexv23kMabbYqxasxU3mQ4ibBMEmJWHny
 
-// Build a Transaction object (e.g. for simulation or custom signing)
-const tx = await builder.transaction();
-
-// Simulate without sending
-const result = await builder.simulate();
+SOL_USD_FEED
+= 99B2bTijsU6f1GCT73HmdR7HCFFjGMBcPZY6jZ96ynrR
 ```
 
+The SDK automatically includes these accounts during withdrawals.
+
 ---
 
-## Error Reference
+# Error Reference
 
-| Error                         | Likely Cause                                              |
-|-------------------------------|-----------------------------------------------------------|
-| `AccountDiscriminatorMismatch`| Wrong cluster (e.g. calling devnet PDA on mainnet RPC)    |
-| `AccountNotInitialized`       | Stream or milestone PDA does not exist yet                |
-| `InvalidMilestoneIndex`       | `milestoneIndex` out of range                             |
-| `StreamNotActive`             | Stream already cancelled or fully vested                  |
+| Error                        | Description                           |
+| ---------------------------- | ------------------------------------- |
+| AccountDiscriminatorMismatch | Wrong cluster or incorrect account    |
+| AccountNotInitialized        | PDA account does not exist            |
+| InvalidMilestoneIndex        | Milestone index out of range          |
+| StreamNotActive              | Stream already completed or cancelled |
 
 ---
 
-## Network Support
+# Network Support
 
-| Network | Status |
-|---------|--------|
-| Devnet  | ✅ Supported |
-| Mainnet | ✅ Supported |
-| Localnet| ✅ Supported (bankrun / solana-test-validator) |
+| Network  | Status |
+| -------- | ------ |
+| Devnet   | ✅      |
+| Mainnet  | ✅      |
+| Localnet | ✅      |
 
 ---
 
-## License
+# License
 
-MIT
+MIT

package/dist/client.d.ts

@@ -8,6 +8,11 @@ export interface MilestoneInput {
     amount: anchor.BN;
 }
 export type TxProgressPhase = "wallet_approval" | "sending" | "confirming";
+export declare function getAnchorWallet(session: WalletSession): {
+    publicKey: anchor.web3.PublicKey;
+    signTransaction: <T extends anchor.web3.Transaction | anchor.web3.VersionedTransaction>(transaction: T) => Promise<T>;
+    signAllTransactions: <T extends anchor.web3.Transaction | anchor.web3.VersionedTransaction>(transactions: T[]) => Promise<T[]>;
+};
 export declare class UnifiedFlowClient {
     private readonly program;
     private readonly wallet;

package/dist/client.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.UnifiedFlowClient = exports.SOL_USD_FEED = exports.CHAINLINK_PROGRAM_ID = void 0;
+exports.getAnchorWallet = getAnchorWallet;
 const web3_js_1 = require("@solana/web3.js");
 const spl_token_1 = require("@solana/spl-token");
 const kit_1 = require("@solana/kit");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unifiedflow/unified-flow-sdk",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "description": "SDK for the Unified Flow program",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",