@unifiedflow/unified-flow-sdk 1.0.0 → 1.0.1

package/README.md

@@ -0,0 +1,292 @@
+# @unifiedflow/unified-flow-sdk
+
+TypeScript SDK for interacting with the **Unified Flow** on-chain token vesting and streaming program on Solana.
+
+---
+
+## Installation
+
+```bash
+npm install @unifiedflow/unified-flow-sdk
+# or
+yarn add @unifiedflow/unified-flow-sdk
+```
+
+### Peer Dependencies
+
+```bash
+npm install @coral-xyz/anchor @solana/web3.js @solana/spl-token
+```
+
+> **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>" } }
+> ```
+
+---
+
+## Quick Start
+
+### 1. Initialize the 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";
+import { useMemo } from "react";
+
+export function useUnifiedFlowClient() {
+  const { connection } = useConnection();
+  const wallet = useAnchorWallet();
+
+  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);
+  }, [wallet, connection]);
+}
+```
+
+### 2. Use in a Component
+
+```typescript
+const client = useUnifiedFlowClient();
+
+if (!client) return <p>Connect your wallet</p>;
+```
+
+---
+
+## 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 |
+
+---
+
+## API Reference
+
+### `createStream`
+
+Create a new vesting 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
+);
+
+const txSig = await builder.rpc();
+```
+
+**Milestone stream example:**
+
+```typescript
+const milestones: MilestoneInput[] = [
+  { amount: new BN(250_000) },
+  { amount: new BN(250_000) },
+  { amount: new BN(500_000) },
+];
+
+const builder = await client.createStream(
+  creator, recipient, mint,
+  new BN(1_000_000),
+  new BN(startTs), new BN(startTs), new BN(endTs),
+  2,           // MILESTONE
+  milestones,
+  new BN(nonce)
+);
+```
+
+---
+
+### `withdraw`
+
+Withdraw vested/unlocked tokens from a stream. Callable by the recipient.
+
+```typescript
+const builder = await client.withdraw(
+  streamPDA,  // PublicKey — stream account address
+  recipient,  // PublicKey
+  mint        // PublicKey
+);
+
+const txSig = await builder.rpc();
+```
+
+---
+
+### `cancel`
+
+Cancel an active stream. Returns unvested tokens to the creator. Callable by the creator.
+
+```typescript
+const builder = await client.cancel(
+  streamPDA,  // PublicKey — stream account address
+  creator,    // PublicKey
+  recipient,  // PublicKey
+  mint        // PublicKey
+);
+
+const txSig = await builder.rpc();
+```
+
+---
+
+### `unlockMilestone`
+
+Unlock the next milestone in a milestone vesting stream. Callable by the creator.
+
+```typescript
+const builder = await client.unlockMilestone(
+  streamPDA,       // PublicKey
+  creator,         // PublicKey
+  milestoneIndex   // number — 0-indexed
+);
+
+const txSig = await builder.rpc();
+```
+
+---
+
+### `editMilestone`
+
+Change the token amount for a specific milestone (before it is unlocked).
+
+```typescript
+const builder = await client.editMilestone(
+  streamPDA,
+  creator,
+  mint,
+  milestoneIndex,    // number
+  new BN(newAmount)  // BN
+);
+
+const txSig = await builder.rpc();
+```
+
+---
+
+### `editCliff`
+
+Update the cliff timestamp on a cliff vesting stream.
+
+```typescript
+const builder = await client.editCliff(
+  streamPDA,
+  creator,
+  new BN(newCliffTs)
+);
+
+const txSig = await builder.rpc();
+```
+
+---
+
+### `editLinear`
+
+Extend the end timestamp and/or top up tokens on a linear vesting stream. Both operations happen in a single transaction.
+
+```typescript
+const builder = await client.editLinear(
+  streamPDA,
+  creator,
+  mint,
+  new BN(newEndTs),    // new end timestamp
+  new BN(topupAmount)  // additional tokens to deposit (0 if no top-up)
+);
+
+const txSig = await builder.rpc();
+```
+
+---
+
+## PDA Helpers
+
+The SDK exports PDA derivation utilities if you need raw account addresses:
+
+```typescript
+import {
+  getConfigPDA,
+  getStreamPDA,
+  getMilestonePDA,
+  getFeeVaultPDA,
+  getVaultATA,
+} from "@unifiedflow/unified-flow-sdk";
+
+const [streamPDA] = getStreamPDA(creator, recipient, nonce, programId);
+const [milestonePDA] = getMilestonePDA(streamPDA, milestoneIndex, programId);
+```
+
+---
+
+## Chainlink Oracle
+
+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.
+
+| Constant              | Value                                        |
+|-----------------------|----------------------------------------------|
+| `CHAINLINK_PROGRAM_ID`| `HEvSKofvBgfaexv23kMabbYqxasxU3mQ4ibBMEmJWHny` |
+| `SOL_USD_FEED`        | `99B2bTijsU6f1GCT73HmdR7HCFFjGMBcPZY6jZ96ynrR` |
+
+---
+
+## Builder Pattern
+
+All client methods return an **Anchor instruction builder**. You have three options:
+
+```typescript
+const builder = await client.withdraw(streamPDA, recipient, mint);
+
+// Execute and return transaction signature
+const txSig = await builder.rpc();
+
+// Build a Transaction object (e.g. for simulation or custom signing)
+const tx = await builder.transaction();
+
+// Simulate without sending
+const result = await builder.simulate();
+```
+
+---
+
+## 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                  |
+
+---
+
+## Network Support
+
+| Network | Status |
+|---------|--------|
+| Devnet  | ✅ Supported |
+| Mainnet | ✅ Supported |
+| Localnet| ✅ Supported (bankrun / solana-test-validator) |
+
+---
+
+## License
+
+MIT

package/package.json

@@ -1,14 +1,18 @@
 {
   "name": "@unifiedflow/unified-flow-sdk",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "SDK for the Unified Flow program",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "scripts": {
     "build": "tsc"
   },
+  "files": [
+    "dist",
+    "README.md"
+  ],
   "dependencies": {
-    "@coral-xyz/anchor": "^0.30.0",
+    "@coral-xyz/anchor": "^0.32.1",
     "@solana/spl-token": "^0.4.0",
     "@solana/web3.js": "^1.90.0"
   },

package/src/client.ts

@@ -1,196 +0,0 @@
-import { Program, BN, Idl } from "@coral-xyz/anchor";
-import { PublicKey, SystemProgram } from "@solana/web3.js";
-import { TOKEN_PROGRAM_ID, ASSOCIATED_TOKEN_PROGRAM_ID, getAssociatedTokenAddressSync } from "@solana/spl-token";
-import { UnifiedFlow } from "./types";
-import { getConfigPDA, getFeeVaultPDA, getMilestonePDA, getStreamPDA, getVaultATA } from "./pda";
-
-export const CHAINLINK_PROGRAM_ID = new PublicKey("HEvSKofvBgfaexv23kMabbYqxasxU3mQ4ibBMEmJWHny");
-export const SOL_USD_FEED = new PublicKey("99B2bTijsU6f1GCT73HmdR7HCFFjGMBcPZY6jZ96ynrR");
-
-export interface MilestoneInput {
-  amount: BN;
-}
-
-export class UnifiedFlowClient {
-  constructor(public readonly program: Program<UnifiedFlow>) {}
-
-  /**
-   * Helper to derive the config PDA
-   */
-  public getConfigPDA(): PublicKey {
-    return getConfigPDA(this.program.programId)[0];
-  }
-
-  /**
-   * Create a new stream (Linear, Cliff, or Milestone)
-   */
-  public async createStream(
-    creator: PublicKey,
-    recipient: PublicKey,
-    mint: PublicKey,
-    amount: BN,
-    startTs: BN,
-    cliffTs: BN,
-    endTs: BN,
-    vestingType: number,
-    milestones: MilestoneInput[],
-    nonce: BN
-  ) {
-    const config = this.getConfigPDA();
-    const stream = getStreamPDA(creator, recipient, nonce, this.program.programId)[0];
-    const vault = getVaultATA(mint, stream);
-    const creatorTokenAccount = getAssociatedTokenAddressSync(mint, creator, true);
-
-    const builder = this.program.methods
-      .createStream(amount, startTs, cliffTs, endTs, vestingType, milestones, nonce)
-      .accounts({
-        creator,
-        recipient,
-        mint,
-        creatorTokenAccount,
-        tokenProgram: TOKEN_PROGRAM_ID,
-      });
-
-    if (vestingType === 2 && milestones.length > 0) { // VESTING_TYPE_MILESTONE = 2
-      const remainingAccounts = milestones.map((_, i) => ({
-        pubkey: getMilestonePDA(stream, i, this.program.programId)[0],
-        isWritable: true,
-        isSigner: false,
-      }));
-      builder.remainingAccounts(remainingAccounts);
-    }
-
-    return builder;
-  }
-
-  /**
-   * Withdraw unlocked/vested tokens from a stream
-   */
-  public async withdraw(
-    streamPDA: PublicKey,
-    recipient: PublicKey,
-    mint: PublicKey
-  ) {
-    const config = this.getConfigPDA();
-    const vault = getVaultATA(mint, streamPDA);
-    const recipientAta = getAssociatedTokenAddressSync(mint, recipient, true);
-    const feeVault = getFeeVaultPDA(this.program.programId)[0];
-
-    return this.program.methods
-      .withdraw()
-      .accounts({
-        recipient,
-        stream: streamPDA,
-        recipientAta,
-        chainlinkFeed: SOL_USD_FEED,
-        tokenProgram: TOKEN_PROGRAM_ID,
-      } as any);
-  }
-
-  /**
-   * Cancel an active stream and return remaining tokens to the creator
-   */
-  public async cancel(
-    streamPDA: PublicKey,
-    creator: PublicKey,
-    recipient: PublicKey,
-    mint: PublicKey
-  ) {
-    const config = this.getConfigPDA();
-    const vault = getVaultATA(mint, streamPDA);
-    const creatorTokenAccount = getAssociatedTokenAddressSync(mint, creator, true);
-    const recipientTokenAccount = getAssociatedTokenAddressSync(mint, recipient, true);
-
-    return this.program.methods
-      .cancel()
-      .accounts({
-        creator,
-        stream: streamPDA,
-        creatorTokenAccount,
-        recipientTokenAccount,
-        tokenProgram: TOKEN_PROGRAM_ID,
-      } as any);
-  }
-
-  /**
-   * Unlock a specific milestone
-   */
-  public async unlockMilestone(
-    streamPDA: PublicKey,
-    creator: PublicKey,
-    milestoneIndex: number
-  ) {
-    const milestonePDA = getMilestonePDA(streamPDA, milestoneIndex, this.program.programId)[0];
-
-    return this.program.methods
-      .unlockMilestone()
-      .accounts({
-        stream: streamPDA,
-        milestone: milestonePDA,
-      } as any);
-  }
-
-  /**
-   * Edit a milestone's amount (increase or decrease)
-   */
-  public async editMilestone(
-    streamPDA: PublicKey,
-    creator: PublicKey,
-    mint: PublicKey,
-    milestoneIndex: number,
-    newAmount: BN
-  ) {
-    const milestonePDA = getMilestonePDA(streamPDA, milestoneIndex, this.program.programId)[0];
-    const vault = getVaultATA(mint, streamPDA);
-    const creatorTokenAccount = getAssociatedTokenAddressSync(mint, creator, true);
-
-    return this.program.methods
-      .editMilestone(newAmount)
-      .accounts({
-        stream: streamPDA,
-        milestone: milestonePDA,
-        creatorTokenAccount,
-        tokenProgram: TOKEN_PROGRAM_ID,
-      } as any);
-  }
-
-  /**
-   * Edit the cliff timestamp of a cliff vesting stream
-   */
-  public async editCliff(
-    streamPDA: PublicKey,
-    creator: PublicKey,
-    newCliffTs: BN
-  ) {
-    const config = this.getConfigPDA();
-
-    return this.program.methods
-      .editCliff(newCliffTs)
-      .accounts({
-        stream: streamPDA,
-      } as any);
-  }
-
-  /**
-   * Edit a linear stream's end timestamp and/or top up tokens
-   */
-  public async editLinear(
-    streamPDA: PublicKey,
-    creator: PublicKey,
-    mint: PublicKey,
-    newEndTs: BN,
-    topupAmount: BN
-  ) {
-    const config = this.getConfigPDA();
-    const vault = getVaultATA(mint, streamPDA);
-    const creatorTokenAccount = getAssociatedTokenAddressSync(mint, creator, true);
-
-    return this.program.methods
-      .editLinear(newEndTs, topupAmount)
-      .accounts({
-        stream: streamPDA,
-        creatorTokenAccount,
-        tokenProgram: TOKEN_PROGRAM_ID,
-      } as any);
-  }
-}

package/src/index.ts

@@ -1,6 +0,0 @@
-export * from "./types";
-export * from "./pda";
-export * from "./client";
-
-import IDL from "./unified_flow.json";
-export { IDL };

package/src/pda.ts

@@ -1,53 +0,0 @@
-import { PublicKey } from "@solana/web3.js";
-import { getAssociatedTokenAddressSync } from "@solana/spl-token";
-import { BN } from "@coral-xyz/anchor";
-
-export const UNIFIED_FLOW_PROGRAM_ID = new PublicKey(
-  "8M5yieUh7pxwUi1YBByDF82nqoorZwaKi8dBoMVpurFa"
-);
-
-export function getConfigPDA(programId: PublicKey = UNIFIED_FLOW_PROGRAM_ID): [PublicKey, number] {
-  return PublicKey.findProgramAddressSync([Buffer.from("config")], programId);
-}
-
-export function getFeeVaultPDA(programId: PublicKey = UNIFIED_FLOW_PROGRAM_ID): [PublicKey, number] {
-  return PublicKey.findProgramAddressSync([Buffer.from("fee_vault")], programId);
-}
-
-export function getStreamPDA(
-  creator: PublicKey,
-  recipient: PublicKey,
-  nonce: BN,
-  programId: PublicKey = UNIFIED_FLOW_PROGRAM_ID
-): [PublicKey, number] {
-  const nonceBuffer = Buffer.alloc(8);
-  nonceBuffer.writeBigUInt64LE(BigInt(nonce.toString()));
-  
-  return PublicKey.findProgramAddressSync(
-    [
-      Buffer.from("stream"),
-      creator.toBuffer(),
-      recipient.toBuffer(),
-      nonceBuffer,
-    ],
-    programId
-  );
-}
-
-export function getMilestonePDA(
-  stream: PublicKey,
-  index: number,
-  programId: PublicKey = UNIFIED_FLOW_PROGRAM_ID
-): [PublicKey, number] {
-  return PublicKey.findProgramAddressSync(
-    [Buffer.from("milestone"), stream.toBuffer(), Buffer.from([index])],
-    programId
-  );
-}
-
-export function getVaultATA(
-  mint: PublicKey,
-  stream: PublicKey
-): PublicKey {
-  return getAssociatedTokenAddressSync(mint, stream, true);
-}