@zebec-network/zebec-vault-sdk 5.2.1 → 5.2.3

package/README.md

@@ -2,7 +2,7 @@
 
 A Typescript SDK for interacting with Zebec Vault on Solana, enabling secure multi operations, token streaming, staking, and virtual card management.
 
-# **Features**
+## **Features**
 
 - **Vault Management**: Create and manage secure vaults with proposal-based execution
 - **Token Operations**: Deposit and withdraw SOL and SPL tokens
@@ -11,7 +11,7 @@ A Typescript SDK for interacting with Zebec Vault on Solana, enabling secure mul
 - **Virtual Cards**: Create and load Zebec cards with automatic token swapping
 - **Jupiter Integration**: Built-in token swapping for card operations
 
-# **Installation**
+## **Installation**
 
 ```jsx
 npm install @zebec-network/zebec-vault-sdk
@@ -21,23 +21,22 @@ npm install @zebec-network/zebec-vault-sdk
 yarn add @zebec-network/zebec-vault-sdk
 ```
 
-# **Quick Start**
+## **Quick Start**
 
-## **Setup**
+### **Setup**
 
 ```tsx
 import { Connection, Keypair } from "@solana/web3.js";
 import { createAnchorProvider, ZebecVaultService } from "@zebec-network/zebec-vault-sdk";
 
 // Create connection
-const connection = new Connection("https://api.mainnet-beta.solana.com"); // use private dedicatd rpc for production
+const connection = new Connection("https://api.mainnet-beta.solana.com"); // use a private dedicated RPC for production
 
 // Create wallet adapter
-// for frontend application you can use wallet provided by the wallet provider
-// for example:
+// For a frontend application, use the wallet provided by the wallet adapter:
 const wallet = useAnchorWallet();
 
-// for server side app you can use Wallet class provided by @coral-xyz/anchor
+// For a server-side app, use the Wallet class from @coral-xyz/anchor:
 const wallet = new Wallet(keypair); // create keypair from secret key
 
 // Create provider
@@ -51,29 +50,29 @@ const vaultService = ZebecVaultService.create(provider, "mainnet-beta");
 
 ### **Vault Operations**
 
-Each user has a vault that is derived from the seed containing user’s wallet. Then a vault signer is derived from the vault taking it as a seed. The vault signer is responsible for holding SPL Tokens and Sol balances and signing the transaction during CPI executions.
+Each user has a vault that is derived from a seed containing the user's wallet. A vault signer is then derived from the vault as a seed. The vault signer holds SPL token and SOL balances and signs transactions during CPI executions.
 
-**Create a vault**
+#### Create a vault
 
-```jsx
+```tsx
 const payload = await vaultService.createVault({
-	payer: wallet.publicKey, // optional if using AnchorProvider
+  payer: wallet.publicKey, // optional if using AnchorProvider
 });
 
 const signature = await payload.execute();
 console.log("Vault created:", signature);
 ```
 
-**Get Vault Information**
+#### Get Vault Information
 
 ```tsx
-// Get specific user's vault
+// Get a specific user's vault (param is optional when using AnchorProvider)
 const vaultInfo = await vaultService.getVaultInfoOfUser(userAddress);
 
 if (vaultInfo) {
-	console.log("Vault:", vaultInfo.vault.toString());
-	console.log("Owner:", vaultInfo.owner.toString());
-	console.log("Created:", new Date(vaultInfo.createdDate * 1000));
+  console.log("Vault:", vaultInfo.vault.toString());
+  console.log("Owner:", vaultInfo.owner.toString());
+  console.log("Created:", new Date(vaultInfo.createdDate * 1000));
 }
 
 // Get all vaults
@@ -81,101 +80,102 @@ const allVaults = await vaultService.getAllVaultsInfo();
 console.log(`Total vaults: ${allVaults.length}`);
 ```
 
-**Deposit SOL**
+#### Deposit SOL
 
 ```tsx
 const payload = await vaultService.depositSol({
-	depositor: wallet.publicKey,
-	amount: 1.5, // SOL amount
+  depositor: wallet.publicKey,
+  amount: 1.5, // SOL amount
 });
+
+const signature = await payload.execute();
 ```
 
-**Deposit SPL Tokens**
+#### Deposit SPL Tokens
 
 ```tsx
 const payload = await vaultService.deposit({
-	depositor: wallet.publicKey,
-	tokenMint: "TOKEN_MINT_ADDRESS",
-	amount: 100, // token amount
+  depositor: wallet.publicKey,
+  tokenMint: "TOKEN_MINT_ADDRESS",
+  amount: 100, // token amount
 });
 
 const signature = await payload.execute();
 ```
 
-> **_Note: If WSOL address is given in tokenMint, it will wrap SOL to WSOL and deposit as spl token._**
+> **_Note: If the WSOL address is given as `tokenMint`, SOL will be wrapped to WSOL and deposited as an SPL token._**
 
-**Withdraw SOL**
+#### Withdraw SOL
 
 ```tsx
 const payload = await vaultService.withdrawSol({
-	withdrawer: wallet.publicKey,
-	amount: 0.5,
+  withdrawer: wallet.publicKey,
+  amount: 0.5,
 });
 
 const signature = await payload.execute();
 ```
 
-**Withdraw SPL Tokens**
+#### Withdraw SPL Tokens
 
 ```tsx
 const payload = await vaultService.withdraw({
-	withdrawer: wallet.publicKey,
-	tokenMint: "TOKEN_MINT_ADDRESS",
-	amount: 50,
+  withdrawer: wallet.publicKey,
+  tokenMint: "TOKEN_MINT_ADDRESS",
+  amount: 50,
 });
 
 const signature = await payload.execute();
 ```
 
-> **_Note: If WSOL is address in given in tokenMint, it will with withdraw WSOL and unwrap into withdrawer wallet._**
+> **_Note: If the WSOL address is given as `tokenMint`, WSOL will be withdrawn and unwrapped into the withdrawer's wallet._**
 
 ### Proposal System
 
-Proposal System includes methods like creating proposal, appending actions and executing proposal. A proposal is like a transaction in Solana but with extra fields like proposal stage, created date, expiry dates, execution status, name, etc. Each Proposal contains one or more Proposal Action which is similar to Transaction Instruction in Solana. While executing the proposal, the Proposal Actions get executed in order in which its resides inside a Proposal. You can delete the Proposal and claim SOLs used in creating the Proposal. Each Proposal belongs to a vault and only signer of that vault can execute the Proposal, delete or append any Proposal Actions in the Proposal.
+The Proposal System includes methods for creating proposals, appending actions, and executing proposals. A proposal is like a Solana transaction but with extra fields such as proposal stage, created date, expiry date, execution status, and name. Each proposal contains one or more `ProposalAction`, which is similar to a `TransactionInstruction` in Solana. During execution, proposal actions run in order. You can delete a proposal to reclaim the SOL rent used to create it. Each proposal belongs to a vault and only the vault signer can execute, delete, or append actions to it.
 
-**Create a Proposal**
+#### Create a Proposal
 
 ```tsx
-import { SystemProgram, Keypair } from "@solana/web3.js";
+import { SystemProgram } from "@solana/web3.js";
 import { parseSol } from "@zebec-network/solana-common";
+import { deriveUserVault, deriveVaultSigner } from "@zebec-network/zebec-vault-sdk";
 
-const [vault] = deriveUserVault(wallet.publicKey, service.vaultV1ProgramId);
-const [vaultSigner] = deriveVaultSigner(vault, service.vaultV1ProgramId);
+const [vault] = deriveUserVault(wallet.publicKey, vaultService.vaultV1ProgramId);
+const [vaultSigner] = deriveVaultSigner(vault, vaultService.vaultV1ProgramId);
 const recipient = "<Recipient PublicKey>";
 
 // Create custom instructions. For example:
 const instruction = SystemProgram.transfer({
-	fromPubkey: vaultSigner,
-	toPubkey: recipient,
-	lamports: Number(parseSol(1)),
+  fromPubkey: vaultSigner,
+  toPubkey: recipient,
+  lamports: Number(parseSol(1)),
 });
 
-const proposalKeypair = Keypair.generate();
-console.log("Proposal:", proposalKeypair.publicKey.toString());
-
 const payload = await vaultService.createProposal({
-	proposer: wallet.publicKey,
-	name: "Transfer SOL",
-	actions: [instruction],
+  proposer: wallet.publicKey,
+  name: "Transfer SOL",
+  actions: [instruction],
+  // proposalKeypair: Keypair.generate(), // optional; auto-generated if omitted
 });
 
 const signature = await payload.execute();
 ```
 
-### **Get Proposals**
+#### Get Proposals
 
 ```tsx
 const proposals = await vaultService.getProposalsInfoOfVault(vaultAddress);
 
 proposals.forEach((proposal) => {
-	console.log("Proposal:", proposal.name);
-	console.log("Status:", proposal.proposalStage);
-	console.log("Actions:", proposal.actions.length);
-	console.log("Executed:", proposal.isExecuted);
+  console.log("Proposal:", proposal.name);
+  console.log("Status:", proposal.proposalStage);
+  console.log("Actions:", proposal.actions.length);
+  console.log("Executed:", proposal.isExecuted);
 });
 ```
 
-**Append Actions**
+#### Append Actions
 
 ```tsx
 import { SystemProgram } from "@solana/web3.js";
@@ -184,66 +184,71 @@ import { parseSol } from "@zebec-network/solana-common";
 const proposal = "<Proposal PublicKey>";
 
 const instruction = SystemProgram.transfer({
-	fromPubkey: vaultSigner,
-	toPubkey: wallet.publicKey,
-	lamports: Number(parseSol(0.01)),
+  fromPubkey: vaultSigner,
+  toPubkey: wallet.publicKey,
+  lamports: Number(parseSol(0.01)),
 });
 
-const payload = await service.appendActions({
-	actions: actionsB,
-	proposal,
+const payload = await vaultService.appendActions({
+  proposal,
+  actions: [instruction],
 });
 
 const signature = await payload.execute();
 ```
 
-**Delete Proposal**
+#### Delete Proposal
 
 ```tsx
 const proposal = "<Proposal PublicKey>";
-const payload = await service.deleteProposal({ proposal });
+const payload = await vaultService.deleteProposal({ proposal });
 const deleteProposalSignature = await payload.execute();
 ```
 
-**Execute a Proposal**
+#### Execute a Proposal
 
 ```tsx
 const proposal = "<Proposal PublicKey>";
 const lookupTableAddress = "<Lookup Table Address PublicKey>";
 
 const payload = await vaultService.executeProposal({
-	caller: wallet.publicKey,
-	proposal,
-	addressLookupTables: [lookupTableAddress], // optional
+  caller: wallet.publicKey,
+  proposal,
+  addressLookupTables: [lookupTableAddress], // optional
 });
 
 const signature = await payload.execute();
 ```
 
-**Execute Proposal Directly (Single Transaction)**
-Proposal Action can be directly executed without creating Proposal. However, it may cause transaction size limit while some size limit can be mitigated using address lookup table.
+#### Execute Proposal Directly (Single Transaction)
+
+Proposal actions can be executed directly without creating a persistent proposal. However, this may hit the transaction size limit; some cases can be mitigated using address lookup tables.
 
 ```tsx
-const [vault] = deriveUserVault(wallet.publicKey, service.vaultV1ProgramId);
-const [vaultSigner] = deriveVaultSigner(vault, service.vaultV1ProgramId);
+import { SystemProgram, TransactionInstruction } from "@solana/web3.js";
+import { parseSol } from "@zebec-network/solana-common";
+import { deriveUserVault, deriveVaultSigner } from "@zebec-network/zebec-vault-sdk";
+
+const [vault] = deriveUserVault(wallet.publicKey, vaultService.vaultV1ProgramId);
+const [vaultSigner] = deriveVaultSigner(vault, vaultService.vaultV1ProgramId);
 const recipient = "<Recipient PublicKey>";
 
 const instruction1 = SystemProgram.transfer({
-	fromPubkey: vaultSigner,
-	toPubkey: recipient,
-	lamports: Number(parseSol(1)),
+  fromPubkey: vaultSigner,
+  toPubkey: recipient,
+  lamports: Number(parseSol(1)),
 });
 
 const instruction2 = new TransactionInstruction({
-	keys: [],
-	programId: MEMO_PROGRAM_ID,
-	data: Buffer.from("Transfer 1 sol from vault signer to recipient", "utf8"),
+  keys: [],
+  programId: MEMO_PROGRAM_ID,
+  data: Buffer.from("Transfer 1 sol from vault signer to recipient", "utf8"),
 });
 
 const payload = await vaultService.executeProposalDirect({
-	proposer: wallet.publicKey,
-	actions: [instruction1, instruction2],
-	addressLookupTables: [lookupTableAddress],
+  proposer: wallet.publicKey,
+  actions: [instruction1, instruction2],
+  addressLookupTables: [lookupTableAddress],
 });
 
 const signature = await payload.execute();
@@ -251,80 +256,104 @@ const signature = await payload.execute();
 
 ### **Payment Streaming**
 
-**Create a Stream**
+#### Create a Stream
 
 ```tsx
 const payload = await vaultService.createStreamFromVault({
- vaultOwner: wallet.publicKey,
- receiver: recipientAddress,
- streamToken: tokenMintAddress,
- amount: 1000, // total amount
- duration: 2592000, // 30 days in seconds
- startNow: true,
- startTime: Math.floor(Date.now() / 1000),
- automaticWithdrawal: false,
- cancelableByRecipient: true,
- cancelableBySender: true,
- isPausable: true,
- transferableByRecipient: false,
- transferableBySender: false,
- canTopup: true,
- rateUpdatable: false,
- cliffPercentage: 0, // 0-100
- autoWithdrawFrequency: 86400, // 1 day
- streamName: "Monthly Payment",
+  vaultOwner: wallet.publicKey,
+  receiver: recipientAddress,
+  streamToken: tokenMintAddress,
+  streamConfigName: "Config-001", // name of the stream configuration to use
+  amount: 1000, // total amount
+  duration: 2592000, // 30 days in seconds
+  startNow: true,
+  startTime: Math.floor(Date.now() / 1000),
+  automaticWithdrawal: false,
+  cancelableByRecipient: true,
+  cancelableBySender: true,
+  isPausable: true,
+  transferableByRecipient: false,
+  transferableBySender: false,
+  canTopup: true,
+  rateUpdatable: false,
+  cliffPercentage: 0, // 0-100
+  autoWithdrawFrequency: 86400, // 1 day in seconds; required when automaticWithdrawal is true
+  streamName: "Monthly Payment",
 });
 
-const await payload.execute();
+const signature = await payload.execute();
 ```
 
-**Create Multiple Streams**
+#### Create Multiple Streams
 
-There is a difference in payload that is return for creating multiple stream. While other payload is an instance of `TransactionPayload` class, the payload returned for creating multiple stream is an instance of `MultiTransactionPayload`. After invoking execute method in payload, it returns `MultiTransactionPayloadExecuteReturn` type which is an Array of union of `PromiseSettledResult<*string*>` and an object consisting of transactions data and transactions. The `PromiseSettledResult<*string*>` contains signature string as a value if the execution is success otherwise it it contains reason for the failure.
+There is a difference in the payload returned for creating multiple streams. While other payloads are instances of `TransactionPayload`, the payload returned for multiple streams is an instance of `MultiTransactionPayload`. After calling `execute()`, it returns `MultiTransactionPayloadExecuteReturn`, which is an array of settled promise results — each containing either a transaction signature on success or a failure reason.
 
 ```tsx
 export type MultiTransactionPayloadExecuteReturn = (PromiseSettledResult<string> & {
-	transactionData: {
-		readonly instructions: web3.TransactionInstruction[];
-		readonly feePayer: web3.PublicKey;
-		readonly signers?: web3.Signer[];
-		readonly addressLookupTableAccounts?: web3.AddressLookupTableAccount[];
-	};
-	transaction: web3.VersionedTransaction;
+  transactionData: {
+    readonly instructions: web3.TransactionInstruction[];
+    readonly feePayer: web3.PublicKey;
+    readonly signers?: web3.Signer[];
+    readonly addressLookupTableAccounts?: web3.AddressLookupTableAccount[];
+  };
+  transaction: web3.VersionedTransaction;
 })[];
 ```
 
 ```tsx
 const payload = await vaultService.createMultipleStreamFromVault({
-	vaultOwner: wallet.publicKey,
-	streamInfo: [
-		{
-			receiver: recipient1,
-			streamToken: tokenMint,
-			amount: 500,
-			duration: 2592000,
-			// ... other stream parameters
-		},
-		{
-			receiver: recipient2,
-			streamToken: tokenMint,
-			amount: 1000,
-			duration: 2592000,
-			// ... other stream parameters
-		},
-	],
+  vaultOwner: wallet.publicKey,
+  streamConfigName: "Config-001", // applies to all streams
+  streamInfo: [
+    {
+      receiver: recipient1,
+      streamToken: tokenMint,
+      amount: 500,
+      duration: 2592000,
+      startNow: false,
+      startTime: Math.floor(Date.now() / 1000) + 30,
+      automaticWithdrawal: false,
+      cancelableByRecipient: false,
+      cancelableBySender: false,
+      isPausable: false,
+      transferableByRecipient: false,
+      transferableBySender: false,
+      canTopup: false,
+      rateUpdatable: false,
+      cliffPercentage: 0,
+      streamName: "Stream 1",
+    },
+    {
+      receiver: recipient2,
+      streamToken: tokenMint,
+      amount: 1000,
+      duration: 2592000,
+      startNow: false,
+      startTime: Math.floor(Date.now() / 1000) + 30,
+      automaticWithdrawal: false,
+      cancelableByRecipient: false,
+      cancelableBySender: false,
+      isPausable: false,
+      transferableByRecipient: false,
+      transferableBySender: false,
+      canTopup: false,
+      rateUpdatable: false,
+      cliffPercentage: 0,
+      streamName: "Stream 2",
+    },
+  ],
 });
 
-// Execute all streams in multiple transactions
-const result = await payload.execute();
+// Execute all streams in separate transactions
+const results = await payload.execute();
 ```
 
 ### **Pause/Resume a Stream**
 
 ```tsx
 const payload = await vaultService.pauseResumeStream({
-	vaultOwner: wallet.publicKey,
-	streamMetadata: streamAddress,
+  vaultOwner: wallet.publicKey,
+  streamMetadata: streamAddress,
 });
 
 const signature = await payload.execute();
@@ -334,8 +363,8 @@ const signature = await payload.execute();
 
 ```tsx
 const payload = await vaultService.cancelStream({
-	vaultOwner: wallet.publicKey,
-	streamMetadata: streamAddress,
+  vaultOwner: wallet.publicKey,
+  streamMetadata: streamAddress,
 });
 
 await payload.execute();
@@ -345,8 +374,8 @@ await payload.execute();
 
 ```tsx
 const payload = await vaultService.withdrawStream({
-	vaultOwner: wallet.publicKey,
-	streamMetadata: streamAddress,
+  vaultOwner: wallet.publicKey,
+  streamMetadata: streamAddress,
 });
 
 await payload.execute();
@@ -356,9 +385,9 @@ await payload.execute();
 
 ```tsx
 const payload = await vaultService.changeStreamReceiver({
-	vaultOwner: wallet.publicKey,
-	streamMetadata: streamAddress,
-	newRecipient: newRecipientAddress,
+  vaultOwner: wallet.publicKey,
+  streamMetadata: streamAddress,
+  newRecipient: newRecipientAddress,
 });
 
 await payload.execute();
@@ -370,46 +399,46 @@ await payload.execute();
 const streamInfo = await vaultService.getStreamMetadataInfo(streamAddress);
 
 console.log("Stream details:", {
-	sender: streamInfo.parties.sender,
-	receiver: streamInfo.parties.receiver,
-	token: streamInfo.financials.streamToken,
-	deposited: streamInfo.financials.depositedAmount,
-	withdrawn: streamInfo.financials.withdrawnAmount,
-	startTime: new Date(streamInfo.schedule.startTime * 1000),
-	endTime: new Date(streamInfo.schedule.endTime * 1000),
-	isPaused: streamInfo.schedule.pausedTimestamp > 0,
+  sender: streamInfo.parties.sender,
+  receiver: streamInfo.parties.receiver,
+  token: streamInfo.financials.streamToken,
+  deposited: streamInfo.financials.depositedAmount,
+  withdrawn: streamInfo.financials.withdrawnAmount,
+  startTime: new Date(streamInfo.schedule.startTime * 1000),
+  endTime: new Date(streamInfo.schedule.endTime * 1000),
+  isPaused: streamInfo.schedule.pausedTimestamp > 0,
 });
 ```
 
 ### Staking
 
-**Stake Tokens**
+#### Stake Tokens
 
 ```tsx
 const payload = await vaultService.stake({
-	lockupName: "main-lockup",
-	vaultOwner: wallet.publicKey,
-	amount: 1000,
-	lockPeriod: 7776000, // 90 days in seconds
-	nonce: 0n,
+  lockupName: "main-lockup",
+  vaultOwner: wallet.publicKey,
+  amount: 1000,
+  lockPeriod: 7776000, // 90 days in seconds; must be one of the lockup's valid periods
+  nonce: 0n,
 });
 
 await payload.execute();
 ```
 
-**Unstake Tokens**
+#### Unstake Tokens
 
 ```tsx
 const payload = await vaultService.unstake({
-	lockupName: "main-lockup",
-	vaultOwner: wallet.publicKey,
-	nonce: 0n,
+  lockupName: "main-lockup",
+  vaultOwner: wallet.publicKey,
+  nonce: 0n,
 });
 
 await payload.execute();
 ```
 
-**Get Stake Nonce Information**
+#### Get Stake Nonce Information
 
 ```tsx
 const nonceInfo = await vaultService.getStakeUserNonceInfo("main-lockup", wallet.publicKey);
@@ -419,85 +448,94 @@ console.log("Current nonce:", nonceInfo ? nonceInfo.nonce : 0n);
 
 ### Zebec Cards
 
-**Create a Silver Card**
+#### Create a Silver Card
 
 ```tsx
 const nextIndex = await vaultService.getNextCardIndex();
 
 const payload = await vaultService.createSilverCard({
-	vaultOwnerAddress: wallet.publicKey,
-	nextCardIndex: nextIndex,
-	amount: 100, // USDC amount
-	usdcAddress: USDC_MINT_ADDRESS,
-	emailHash: Buffer.from("your-32-byte-hash"),
-	currency: "USD",
+  vaultOwnerAddress: wallet.publicKey,
+  nextCardIndex: nextIndex,
+  amount: 100, // USDC amount
+  usdcAddress: USDC_MINT_ADDRESS,
+  emailHash: Buffer.from("your-32-byte-hash"), // must be exactly 32 bytes
+  currency: "USD",
 });
 
 await payload.execute();
 ```
 
-**Load a Carbon Card**
+#### Load a Carbon Card
 
 ```tsx
 const nextIndex = await vaultService.getNextCardIndex();
 
 const payload = await vaultService.loadCarbonCard({
-	vaultOwnerAddress: wallet.publicKey,
-	nextCardIndex: nextIndex,
-	amount: 50,
-	usdcAddress: USDC_MINT_ADDRESS,
-	emailHash: Buffer.from("your-32-byte-hash"),
-	currency: "USD",
-	reloadCardId: "CARD_ID",
+  vaultOwnerAddress: wallet.publicKey,
+  nextCardIndex: nextIndex,
+  amount: 50,
+  usdcAddress: USDC_MINT_ADDRESS,
+  emailHash: Buffer.from("your-32-byte-hash"), // must be exactly 32 bytes
+  currency: "USD",
+  reloadCardId: "CARD_ID",
 });
 
 await payload.execute();
 ```
 
-**Swap and Create Silver Card**
+#### Swap and Create Silver Card
 
 ```tsx
 // First, get a Jupiter quote
+const quoteParams = new URLSearchParams({
+  inputMint: inputMint,
+  outputMint: USDC_MINT_ADDRESS,
+  amount: parsedAmount, // in smallest units
+  slippageBps: "50",
+  swapMode: "ExactIn",
+});
 const quoteResponse = await fetch(
-	`https://quote-api.jup.ag/v6/quote?inputMint=${inputMint}&outputMint=${USDC}&amount=${amount}&slippageBps=50`,
+  `https://lite-api.jup.ag/swap/v1/quote?${quoteParams}`,
 );
 const quoteInfo = await quoteResponse.json();
 
+const nextIndex = await vaultService.getNextCardIndex();
+
 const payload = await vaultService.swapAndCreateSilverCard({
-	vaultOwnerAddress: wallet.publicKey,
-	quoteInfo: quoteInfo,
-	nextCardCounter: nextIndex,
-	emailHash: Buffer.from("your-32-byte-hash"),
-	currency: "USD",
-	wrapAndUnwrapSol: true, // if swapping SOL
+  vaultOwnerAddress: wallet.publicKey,
+  quoteInfo: quoteInfo,
+  nextCardCounter: nextIndex,
+  emailHash: Buffer.from("your-32-byte-hash"), // must be exactly 32 bytes
+  currency: "USD",
+  wrapAndUnwrapSol: true, // set to true when swapping SOL
 });
 
 await payload.execute();
 ```
 
-**Swap and Load Carbon Card**
+#### Swap and Load Carbon Card
 
 ```tsx
 const payload = await vaultService.swapAndLoadCarbonCard({
-	vaultOwnerAddress: wallet.publicKey,
-	quoteInfo: quoteInfo,
-	nextCardCounter: nextIndex,
-	emailHash: Buffer.from("your-32-byte-hash"),
-	currency: "USD",
-	reloadCardId: "CARD_ID",
-	wrapAndUnwrapSol: true,
+  vaultOwnerAddress: wallet.publicKey,
+  quoteInfo: quoteInfo,
+  nextCardCounter: nextIndex,
+  emailHash: Buffer.from("your-32-byte-hash"), // must be exactly 32 bytes
+  currency: "USD",
+  reloadCardId: "CARD_ID",
+  wrapAndUnwrapSol: true,
 });
 
 await payload.execute();
 ```
 
-**Get Card Custom Token Fees**
+#### Get Card Custom Token Fees
 
 ```tsx
 const tokenFees = await vaultService.getCardCustomTokenFees();
 
 tokenFees.forEach((fee) => {
-	console.log(`Token: ${fee.tokenAddress}, Fee: ${fee.fee}%`);
+  console.log(`Token: ${fee.tokenAddress}, Fee: ${fee.fee}%`);
 });
 ```
 
@@ -518,15 +556,12 @@ const vaultInfo = await service.getVaultInfoOfUser(someAddress);
 
 ### **Advanced Features**
 
-**Program Derived Addresses (PDAs)**
+#### Program Derived Addresses (PDAs)
 
 ```tsx
 import {
-	deriveUserVault,
-	deriveVaultSigner,
-	deriveStreamConfigPda,
-	deriveCardConfigPda,
-	deriveLockupAddress,
+  deriveUserVault,
+  deriveVaultSigner,
 } from "@zebec-network/zebec-vault-sdk";
 
 const [vaultAddress, vaultBump] = deriveUserVault(userAddress, vaultProgramId);
@@ -534,19 +569,19 @@ const [vaultAddress, vaultBump] = deriveUserVault(userAddress, vaultProgramId);
 const [signerAddress, signerBump] = deriveVaultSigner(vaultAddress, vaultProgramId);
 ```
 
-**Transaction Utilities**
+#### Transaction Utilities
 
 ```tsx
 import { calculateProposalSize, transactionInstructionToProposalAction } from "@zebec-network/zebec-vault-sdk";
 
-// Calculate proposal size
+// Calculate proposal size (in bytes)
 const size = calculateProposalSize("proposal-name", actions);
 
-// Convert instruction to proposal action
+// Convert a TransactionInstruction to a ProposalAction
 const action = transactionInstructionToProposalAction(instruction);
 ```
 
-**Network Configuration**
+#### Network Configuration
 
 ```tsx
 // Mainnet
@@ -560,37 +595,81 @@ const devnetService = ZebecVaultService.create(provider, "devnet");
 
 ```tsx
 import {
-	ZEBEC_VAULT_PROGRAM_ID,
-	JUPITER_AGGREGATOR_PROGRAM_ID,
-	CARD_LOOKUP_TABLE_ADDRESS,
-	STAKE_LOOKUP_TABLE_ADDRESS,
+  ZEBEC_VAULT_PROGRAM_ID,
+  JUPITER_AGGREGATOR_PROGRAM_ID,
+  CARD_LOOKUP_TABLE_ADDRESS,
+  STAKE_LOOKUP_TABLE_ADDRESS,
 } from "@zebec-network/zebec-vault-sdk";
 
 console.log("Vault Program:", ZEBEC_VAULT_PROGRAM_ID["mainnet-beta"]);
 ```
 
+### **Error Types**
+
+The SDK throws typed errors you can catch and inspect:
+
+```tsx
+import {
+  AmountOutOfRangeError,
+  DailyCardLimitReachedError,
+  InvalidUsdcAddressError,
+  NotEnoughBalanceError,
+  QuoteResponseError,
+  AssociatedTokenAccountDoesNotExistsError,
+} from "@zebec-network/zebec-vault-sdk";
+
+try {
+  await payload.execute();
+} catch (err) {
+  if (err instanceof AmountOutOfRangeError) {
+    console.error(`Amount must be between ${err.minRange} and ${err.maxRange}`);
+  } else if (err instanceof DailyCardLimitReachedError) {
+    console.error(`Daily limit: ${err.dailyCardLimit}, requested: ${err.requestedAmount}`);
+  } else if (err instanceof NotEnoughBalanceError) {
+    console.error("Insufficient balance");
+  } else if (err instanceof AssociatedTokenAccountDoesNotExistsError) {
+    console.error("Token account does not exist");
+  }
+}
+```
+
 ### **Types**
 
 The SDK exports comprehensive TypeScript types:
 
 ```tsx
 import type {
-	VaultInfo,
-	ProposalInfo,
-	ProposalAction,
-	CreateStreamFromVaultParams,
-	StreamMetadataInfo,
-	TokenFeeRecord,
-	QuoteInfo,
-	StakeUserNonceInfo,
+  VaultInfo,
+  ProposalInfo,
+  ProposalAction,
+  ProposalStage,
+  CreateStreamFromVaultParams,
+  createMultipleStreamFromVaultParams,
+  StreamMetadataInfo,
+  TokenFeeRecord,
+  QuoteInfo,
+  RouteInfo,
+  StakeUserNonceInfo,
+  CreateSilverCardParams,
+  LoadCarbonCardParams,
+  SwapAndCreateSilverCardParams,
+  SwapAndLoadCarbonCardParams,
+  CancelStreamParams,
+  PauseResumeStreamParams,
+  ChangeStreamReceiverParams,
+  WithdrawStreamParams,
+  ParsedCardConfigInfo,
+  WhitelistInfo,
+  Numeric,
 } from "@zebec-network/zebec-vault-sdk";
 ```
 
 ## **Best Practices**
 
-1. **Always check balances** before operations
-2. **Use proposals** for critical operations that require multiple instructions and cannot be executed in a single transaction.
-3. **Handle errors** appropriately with the provided error types
-4. **Verify stream parameters** before creation (duration, amounts, permissions)
-5. **Test on `devnet`** before deploying to `mainnet`
-6. **Use address lookup tables** for complex transactions to reduce size
+1. **Always check balances** before operations
+2. **Use proposals** for critical operations that require multiple instructions and cannot be executed in a single transaction
+3. **Handle errors** appropriately with the provided error types
+4. **Verify stream parameters** before creation (duration, amounts, permissions)
+5. **Test on `devnet`** before deploying to `mainnet`
+6. **Use address lookup tables** for complex transactions to reduce transaction size
+7. **Use a private dedicated RPC** for production workloads

package/package.json

@@ -8,8 +8,8 @@
 		"@zebec-network/core-utils": "^1.1.1",
 		"@zebec-network/solana-common": "^2.3.1",
 		"@zebec-network/zebec-card-v2-sdk": "^2.6.0",
-		"@zebec-network/zebec-stake-sdk": "^1.3.0",
-		"@zebec-network/zebec-stream-sdk": "^3.1.1",
+		"@zebec-network/zebec-stake-sdk": "^1.3.1",
+		"@zebec-network/zebec-stream-sdk": "^3.2.0",
 		"bignumber.js": "^9.3.1",
 		"buffer": "^6.0.3"
 	},
@@ -47,5 +47,5 @@
 		"test:single": "ts-mocha -p ./tsconfig.json -t 1000000000"
 	},
 	"types": "dist/index.d.ts",
-	"version": "5.2.1"
+	"version": "5.2.3"
 }