@zebec-network/zebec-vault-sdk 5.0.3 → 5.1.0

package/README.md

@@ -1,577 +1,607 @@
-# Zebec Vault SDK
-
-A TypeScript SDK for interacting with Zebec Vault on Solana, enabling secure multi operations, token streaming, staking, and virtual card management.
-
-## Features
-
-- **Vault Management**: Create and manage secure vaults with proposal-based execution
-- **Token Operations**: Deposit and withdraw SOL and SPL tokens
-- **Streaming Payments**: Create, manage, and cancel payment streams
-- **Staking**: Stake tokens with customizable lock periods
-- **Virtual Cards**: Create and load Zebec cards with automatic token swapping
-- **Multi-Signature Support**: Execute operations through proposals with multiple signers
-- **Jupiter Integration**: Built-in token swapping for card operations
-
-## Installation
-
-```bash
-npm install @zebec-network/zebec-vault-sdk
-```
-
-```bash
-yarn add @zebec-network/zebec-vault-sdk
-```
-
-## Quick Start
-
-### Setup
-
-```typescript
-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
-
-// Create wallet adapter
-// for frontend application you can use wallet provided by the wallet provider
-const wallet = useAnchorWallet(); 
-// for server side app you can use Wallet class provided by @coral-xyz/anchor
-const wallet = new Wallet(keypair) // create keypair from secret key 
-
-// Create provider
-const provider = createAnchorProvider(connection, wallet);
-
-// Initialize service
-const vaultService = ZebecVaultService.create(provider, 'mainnet-beta');
-```
-
-## Core Features
-
-### 1. Vault Operations
-
-#### Create a Vault
-
-```typescript
-const payload = await vaultService.createVault({
-  payer: wallet.publicKey // optional if using AnchorProvider
-});
-
-const signature = await payload.execute();
-console.log('Vault created:', signature);
-```
-
-#### Deposit SOL
-
-```typescript
-const payload = await vaultService.depositSol({
-  depositor: wallet.publicKey,
-  amount: 1.5 // SOL amount
-});
-
-await payload.execute();
-```
-
-#### Deposit SPL Tokens
-
-```typescript
-const payload = await vaultService.deposit({
-  depositor: wallet.publicKey,
-  tokenMint: 'TOKEN_MINT_ADDRESS',
-  amount: 100 // token amount
-});
-
-await payload.execute();
-
-// Note: if WSOL address is given in tokenMint, it will wrap SOL to WSOL and deposit.
-```
-
-#### Withdraw SOL
-
-```typescript
-const payload = await vaultService.withdrawSol({
-  withdrawer: wallet.publicKey,
-  amount: 0.5
-});
-
-await payload.execute();
-```
-
-#### Withdraw SPL Tokens
-
-```typescript
-const payload = await vaultService.withdraw({
-  withdrawer: wallet.publicKey,
-  tokenMint: 'TOKEN_MINT_ADDRESS',
-  amount: 50
-});
-
-await payload.execute();
-
-// Note: if WSOL is address in given in tokenMint, it will with withdraw WSOL and unwrap into withdrawer wallet.
-```
-
-### 2. Proposal System
-
-#### Create a Proposal
-
-```typescript
-import { SystemProgram } from '@solana/web3.js';
-
-// Create custom instructions
-const instruction = SystemProgram.transfer({
-  fromPubkey: vaultSigner,
-  toPubkey: recipient,
-  lamports: 1000000
-});
-
-const payload = await vaultService.createProposal({
-  proposer: wallet.publicKey,
-  name: 'Transfer SOL',
-  actions: [instruction]
-});
-
-await payload.execute();
-```
-
-#### Execute a Proposal
-
-```typescript
-const payload = await vaultService.executeProposal({
-  caller: wallet.publicKey,
-  proposal: proposalAddress,
-  addressLookupTables: [lookupTableAddress] // optional
-});
-
-await payload.execute();
-```
-
-#### Execute Proposal Directly (Single Transaction)
-
-```typescript
-const payload = await vaultService.executeProposalDirect({
-  proposer: wallet.publicKey,
-  actions: [instruction1, instruction2],
-  addressLookupTables: [lookupTableAddress]
-});
-
-await payload.execute();
-```
-
-### 3. Payment Streaming
-
-#### Create a Stream
-
-```typescript
-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'
-});
-
-await payload.execute();
-```
-
-#### Create Multiple Streams
-
-```typescript
-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
-    }
-  ]
-});
-
-// Execute all streams in multiple transactions
-await payload.executeAll();
-```
-
-#### Pause/Resume a Stream
-
-```typescript
-const payload = await vaultService.pauseResumeStream({
-  vaultOwner: wallet.publicKey,
-  streamMetadata: streamAddress
-});
-
-await payload.execute();
-```
-
-#### Cancel a Stream
-
-```typescript
-const payload = await vaultService.cancelStream({
-  vaultOwner: wallet.publicKey,
-  streamMetadata: streamAddress
-});
-
-await payload.execute();
-```
-
-#### Withdraw from Stream
-
-```typescript
-const payload = await vaultService.withdrawStream({
-  vaultOwner: wallet.publicKey,
-  streamMetadata: streamAddress
-});
-
-await payload.execute();
-```
-
-#### Change Stream Receiver
-
-```typescript
-const payload = await vaultService.changeStreamReceiver({
-  vaultOwner: wallet.publicKey,
-  streamMetadata: streamAddress,
-  newRecipient: newRecipientAddress
-});
-
-await payload.execute();
-```
-
-#### Get Stream Information
-
-```typescript
-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
-});
-```
-
-### 4. Staking
-
-#### Stake Tokens
-
-```typescript
-const payload = await vaultService.stake({
-  lockupName: 'main-lockup',
-  vaultOwner: wallet.publicKey,
-  amount: 1000,
-  lockPeriod: 7776000, // 90 days in seconds
-  nonce: 0n
-});
-
-await payload.execute();
-```
-
-#### Unstake Tokens
-
-```typescript
-const payload = await vaultService.unstake({
-  lockupName: 'main-lockup',
-  vaultOwner: wallet.publicKey,
-  nonce: 0n
-});
-
-await payload.execute();
-```
-
-#### Get Stake Nonce Information
-
-```typescript
-const nonceInfo = await vaultService.getStakeUserNonceInfo(
-  'main-lockup',
-  wallet.publicKey
-);
-
-console.log('Current nonce:', nonceInfo?.nonce);
-```
-
-### 5. Virtual Cards
-
-#### Create a Silver Card
-
-```typescript
-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'
-});
-
-await payload.execute();
-```
-
-#### Load a Carbon Card
-
-```typescript
-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'
-});
-
-await payload.execute();
-```
-
-#### Swap and Create Silver Card
-
-```typescript
-// First, get a Jupiter quote
-const quoteResponse = await fetch(
-  `https://quote-api.jup.ag/v6/quote?inputMint=${inputMint}&outputMint=${USDC}&amount=${amount}&slippageBps=50`
-);
-const quoteInfo = await quoteResponse.json();
-
-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
-});
-
-await payload.execute();
-```
-
-#### Swap and Load Carbon Card
-
-```typescript
-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
-});
-
-await payload.execute();
-```
-
-#### Get Card Custom Token Fees
-
-```typescript
-const tokenFees = await vaultService.getCardCustomTokenFees();
-
-tokenFees.forEach(fee => {
-  console.log(`Token: ${fee.tokenAddress}, Fee: ${fee.fee}%`);
-});
-```
-
-## Query Functions
-
-### Get Vault Information
-
-```typescript
-// Get specific user's vault
-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));
-}
-
-// Get all vaults
-const allVaults = await vaultService.getAllVaultsInfo();
-console.log(`Total vaults: ${allVaults.length}`);
-```
-
-### Get Proposals
-
-```typescript
-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);
-});
-```
-
-## Readonly Provider
-
-For read-only operations without a wallet:
-
-```typescript
-import { createReadonlyProvider } from '@zebec-network/zebec-vault-sdk';
-
-const readonlyProvider = createReadonlyProvider(
-  connection,
-  optionalWalletAddress
-);
-
-const service = ZebecVaultService.create(readonlyProvider, 'mainnet-beta');
-
-// Can only call query methods
-const vaultInfo = await service.getVaultInfoOfUser(someAddress);
-```
-
-## Error Handling
-
-The SDK provides custom error types:
-
-```typescript
-import {
-  AmountOutOfRangeError,
-  DailyCardLimitReachedError,
-  NotEnoughBalanceError,
-  AssociatedTokenAccountDoesNotExistsError
-} from '@zebec-network/zebec-vault-sdk';
-
-try {
-  await payload.execute();
-} catch (error) {
-  if (error instanceof AmountOutOfRangeError) {
-    console.error('Amount must be between', error.minRange, 'and', error.maxRange);
-  } else if (error instanceof DailyCardLimitReachedError) {
-    console.error('Daily limit:', error.dailyCardLimit);
-  } else if (error instanceof NotEnoughBalanceError) {
-    console.error('Insufficient balance');
-  }
-}
-```
-
-## Advanced Features
-
-### Program Derived Addresses (PDAs)
-
-```typescript
-import {
-  deriveUserVault,
-  deriveVaultSigner,
-  deriveStreamConfigPda,
-  deriveCardConfigPda,
-  deriveLockupAddress
-} from '@zebec-network/zebec-vault-sdk';
-
-const [vaultAddress, vaultBump] = deriveUserVault(
-  userAddress,
-  vaultProgramId
-);
-
-const [signerAddress, signerBump] = deriveVaultSigner(
-  vaultAddress,
-  vaultProgramId
-);
-```
-
-### Transaction Utilities
-
-```typescript
-import {
-  calculateProposalSize,
-  transactionInstructionToProposalAction
-} from '@zebec-network/zebec-vault-sdk';
-
-// Calculate proposal size
-const size = calculateProposalSize('proposal-name', actions);
-
-// Convert instruction to proposal action
-const action = transactionInstructionToProposalAction(instruction);
-```
-
-## Network Configuration
-
-```typescript
-// Mainnet
-const mainnetService = ZebecVaultService.create(provider, 'mainnet-beta');
-
-// Devnet
-const devnetService = ZebecVaultService.create(provider, 'devnet');
-```
-
-## Constants
-
-```typescript
-import {
-  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']);
-```
-
-## Types
-
-The SDK exports comprehensive TypeScript types:
-
-```typescript
-import type {
-  VaultInfo,
-  ProposalInfo,
-  ProposalAction,
-  CreateStreamFromVaultParams,
-  StreamMetadataInfo,
-  TokenFeeRecord,
-  QuoteInfo,
-  StakeUserNonceInfo
-} from '@zebec-network/zebec-vault-sdk';
-```
-
-## Best Practices
-
-1. **Always check balances** before operations
-2. **Use proposals** for critical operations requiring multiple approvals
-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
-
-## Support
-
-- **Documentation**: [Zebec Network Docs](https://docs.zebec.io)
-- **GitHub**: [zebec-network](https://github.com/zebec-network)
-- **Discord**: [Join our community](https://discord.gg/zebec)
-
-## License
-
-MIT
-
-## Contributing
-
-Contributions are welcome! Please read our contributing guidelines before submitting pull requests.
+# Introduction
+
+A Typescript SDK for interacting with Zebec Vault on Solana, enabling secure multi operations, token streaming, staking, and virtual card management.
+
+# **Features**
+
+- **Vault Management**: Create and manage secure vaults with proposal-based execution
+- **Token Operations**: Deposit and withdraw SOL and SPL tokens
+- **Streaming Payments**: Create, manage, and cancel payment streams
+- **Staking**: Stake tokens with customizable lock periods
+- **Virtual Cards**: Create and load Zebec cards with automatic token swapping
+- **Jupiter Integration**: Built-in token swapping for card operations
+
+# **Installation**
+
+```jsx
+npm install @zebec-network/zebec-vault-sdk
+```
+
+```jsx
+yarn add @zebec-network/zebec-vault-sdk
+```
+
+# **Quick Start**
+
+## **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
+
+// Create wallet adapter
+// for frontend application you can use wallet provided by the wallet provider
+// for example:
+const wallet = useAnchorWallet();
+
+// for server side app you can use Wallet class provided by @coral-xyz/anchor
+const wallet = new Wallet(keypair); // create keypair from secret key
+
+// Create provider
+const provider = createAnchorProvider(connection, wallet);
+
+// Initialize service
+const vaultService = ZebecVaultService.create(provider, "mainnet-beta");
+```
+
+## Core Features
+
+### **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.
+
+**Create a vault**
+
+```jsx
+const payload = await vaultService.createVault({
+ payer: wallet.publicKey, // optional if using AnchorProvider
+});
+
+const signature = await payload.execute();
+console.log("Vault created:", signature);
+```
+
+**Get Vault Information**
+
+```tsx
+// Get specific user's vault
+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));
+}
+
+// Get all vaults
+const allVaults = await vaultService.getAllVaultsInfo();
+console.log(`Total vaults: ${allVaults.length}`);
+```
+
+**Deposit SOL**
+
+```tsx
+const payload = await vaultService.depositSol({
+ depositor: wallet.publicKey,
+ amount: 1.5, // SOL amount
+});
+```
+
+**Deposit SPL Tokens**
+
+```tsx
+const payload = await vaultService.deposit({
+ 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.***
+>
+
+**Withdraw SOL**
+
+```tsx
+const payload = await vaultService.withdrawSol({
+ withdrawer: wallet.publicKey,
+ amount: 0.5,
+});
+
+const signature = await payload.execute();
+```
+
+**Withdraw SPL Tokens**
+
+```tsx
+const payload = await vaultService.withdraw({
+ 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.***
+>
+
+### 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.
+
+**Create a Proposal**
+
+```tsx
+import { SystemProgram, Keypair } from "@solana/web3.js";
+import { parseSol } from "@zebec-network/solana-common";
+
+const [vault] = deriveUserVault(wallet.publicKey, service.vaultV1ProgramId);
+const [vaultSigner] = deriveVaultSigner(vault, service.vaultV1ProgramId);
+const recipient = "<Recipient PublicKey>";
+
+// Create custom instructions. For example:
+const instruction = SystemProgram.transfer({
+ 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],
+});
+
+const signature = await payload.execute();
+```
+
+### **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);
+});
+```
+
+**Append Actions**
+
+```tsx
+import { SystemProgram } from "@solana/web3.js";
+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)),
+});
+
+const payload = await service.appendActions({
+  actions: actionsB,
+  proposal,
+});
+
+const signature = await payload.execute()
+```
+
+**Delete Proposal**
+
+```tsx
+const proposal = "<Proposal PublicKey>";
+const payload = await service.deleteProposal({ proposal });
+const deleteProposalSignature = await payload.execute();
+```
+
+**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
+});
+
+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.
+
+```tsx
+const [vault] = deriveUserVault(wallet.publicKey, service.vaultV1ProgramId);
+const [vaultSigner] = deriveVaultSigner(vault, service.vaultV1ProgramId);
+const recipient = "<Recipient PublicKey>";
+
+const instruction1 = SystemProgram.transfer({
+  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"),
+});
+
+const payload = await vaultService.executeProposalDirect({
+  proposer: wallet.publicKey,
+  actions: [instruction1, instruction2],
+  addressLookupTables: [lookupTableAddress],
+});
+
+const signature = await payload.execute();
+```
+
+### **Payment Streaming**
+
+**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",
+});
+
+const await payload.execute();
+```
+
+**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.
+
+```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;
+})[];
+```
+
+```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
+  },
+ ],
+});
+
+// Execute all streams in multiple transactions
+const result = await payload.execute();
+```
+
+### **Pause/Resume a Stream**
+
+```tsx
+const payload = await vaultService.pauseResumeStream({
+ vaultOwner: wallet.publicKey,
+ streamMetadata: streamAddress,
+});
+
+const signature = await payload.execute();
+```
+
+### **Cancel a Stream**
+
+```tsx
+const payload = await vaultService.cancelStream({
+ vaultOwner: wallet.publicKey,
+ streamMetadata: streamAddress,
+});
+
+await payload.execute();
+
+```
+
+### **Withdraw from Stream**
+
+```tsx
+const payload = await vaultService.withdrawStream({
+ vaultOwner: wallet.publicKey,
+ streamMetadata: streamAddress,
+});
+
+await payload.execute();
+```
+
+### **Change Stream Receiver**
+
+```tsx
+const payload = await vaultService.changeStreamReceiver({
+ vaultOwner: wallet.publicKey,
+ streamMetadata: streamAddress,
+ newRecipient: newRecipientAddress,
+});
+
+await payload.execute();
+
+```
+
+### **Get Stream Information**
+
+```tsx
+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,
+});
+```
+
+### Staking
+
+**Stake Tokens**
+
+```tsx
+const payload = await vaultService.stake({
+ lockupName: "main-lockup",
+ vaultOwner: wallet.publicKey,
+ amount: 1000,
+ lockPeriod: 7776000, // 90 days in seconds
+ nonce: 0n,
+});
+
+await payload.execute();
+
+```
+
+**Unstake Tokens**
+
+```tsx
+const payload = await vaultService.unstake({
+ lockupName: "main-lockup",
+ vaultOwner: wallet.publicKey,
+ nonce: 0n,
+});
+
+await payload.execute();
+
+```
+
+**Get Stake Nonce Information**
+
+```tsx
+const nonceInfo = await vaultService.getStakeUserNonceInfo("main-lockup", wallet.publicKey);
+
+console.log("Current nonce:", nonceInfo ? nonceInfo.nonce : 0n);
+```
+
+### Zebec Cards
+
+**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",
+});
+
+await payload.execute();
+
+```
+
+**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",
+});
+
+await payload.execute();
+
+```
+
+**Swap and Create Silver Card**
+
+```tsx
+// First, get a Jupiter quote
+const quoteResponse = await fetch(
+ `https://quote-api.jup.ag/v6/quote?inputMint=${inputMint}&outputMint=${USDC}&amount=${amount}&slippageBps=50`,
+);
+const quoteInfo = await quoteResponse.json();
+
+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
+});
+
+await payload.execute();
+
+```
+
+**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,
+});
+
+await payload.execute();
+```
+
+**Get Card Custom Token Fees**
+
+```tsx
+const tokenFees = await vaultService.getCardCustomTokenFees();
+
+tokenFees.forEach((fee) => {
+ console.log(`Token: ${fee.tokenAddress}, Fee: ${fee.fee}%`);
+});
+```
+
+### **Read-only Provider**
+
+For read-only operations without a wallet:
+
+```tsx
+import { createReadonlyProvider } from "@zebec-network/zebec-vault-sdk";
+
+const readonlyProvider = createReadonlyProvider(connection, optionalWalletAddress);
+
+const service = ZebecVaultService.create(readonlyProvider, "mainnet-beta");
+
+// Can only call query methods
+const vaultInfo = await service.getVaultInfoOfUser(someAddress);
+```
+
+### **Advanced Features**
+
+**Program Derived Addresses (PDAs)**
+
+```tsx
+import {
+ deriveUserVault,
+ deriveVaultSigner,
+ deriveStreamConfigPda,
+ deriveCardConfigPda,
+ deriveLockupAddress,
+} from "@zebec-network/zebec-vault-sdk";
+
+const [vaultAddress, vaultBump] = deriveUserVault(userAddress, vaultProgramId);
+
+const [signerAddress, signerBump] = deriveVaultSigner(vaultAddress, vaultProgramId);
+```
+
+**Transaction Utilities**
+
+```tsx
+import { calculateProposalSize, transactionInstructionToProposalAction } from "@zebec-network/zebec-vault-sdk";
+
+// Calculate proposal size
+const size = calculateProposalSize("proposal-name", actions);
+
+// Convert instruction to proposal action
+const action = transactionInstructionToProposalAction(instruction);
+
+```
+
+**Network Configuration**
+
+```tsx
+// Mainnet
+const mainnetService = ZebecVaultService.create(provider, "mainnet-beta");
+
+// Devnet
+const devnetService = ZebecVaultService.create(provider, "devnet");
+```
+
+### **Constants**
+
+```tsx
+import {
+ 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"]);
+
+```
+
+### **Types**
+
+The SDK exports comprehensive TypeScript types:
+
+```tsx
+import type {
+ VaultInfo,
+ ProposalInfo,
+ ProposalAction,
+ CreateStreamFromVaultParams,
+ StreamMetadataInfo,
+ TokenFeeRecord,
+ QuoteInfo,
+ StakeUserNonceInfo,
+} 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

package/dist/service.js

@@ -1006,17 +1006,21 @@ class ZebecVaultService {
         const STREAM_NAME_BUFFER_SIZE = 128;
         const streamNameArray = new Uint8Array(STREAM_NAME_BUFFER_SIZE);
         streamNameArray.set(anchor_1.utils.bytes.utf8.encode(params.streamName));
+        const autoWithdrawFrequency = params.autoWithdrawFrequency ?? 0;
+        if (params.automaticWithdrawal && autoWithdrawFrequency <= 0) {
+            throw new Error("autoWithdrawFrequency must be greater than 0 when automaticWithdrawal is enabled");
+        }
         const ix = await this.getCreateStreamFromVaultInstruction(vaultOwner, vault, vaultSigner, vaultSignerAta, receiverVaultSigner, receiverVaultSignerAta, streamToken, streamMetadata, streamConfig, withdrawAccount, streamVault, streamVaultAta, this.streamProgramId, {
             amount,
             automaticWithdrawal: params.automaticWithdrawal,
-            autoWithdrawFrequency: new anchor_1.BN(params.autoWithdrawFrequency),
+            autoWithdrawFrequency: new anchor_1.BN(autoWithdrawFrequency),
             cancelableByRecipient: params.cancelableByRecipient,
             cancelableBySender: params.cancelableBySender,
             canTopup: params.canTopup,
             cliffPercentage,
             duration: new anchor_1.BN(params.duration),
             isPausable: params.isPausable,
-            numberOfWithdrawls: new anchor_1.BN(Math.floor(params.duration / params.autoWithdrawFrequency)),
+            numberOfWithdrawls: autoWithdrawFrequency > 0 ? new anchor_1.BN(Math.floor(params.duration / autoWithdrawFrequency)) : new anchor_1.BN(0),
             rateUpdatable: params.rateUpdatable,
             startNow: params.startNow,
             startTime: new anchor_1.BN(params.startTime),
@@ -1050,17 +1054,21 @@ class ZebecVaultService {
             const STREAM_NAME_BUFFER_SIZE = 128;
             const streamNameArray = new Uint8Array(STREAM_NAME_BUFFER_SIZE);
             streamNameArray.set(anchor_1.utils.bytes.utf8.encode(info.streamName));
+            const autoWithdrawFrequency = info.autoWithdrawFrequency ?? 0;
+            if (info.automaticWithdrawal && autoWithdrawFrequency <= 0) {
+                throw new Error("autoWithdrawFrequency must be greater than 0 when automaticWithdrawal is enabled");
+            }
             const ix = await this.getCreateStreamFromVaultInstruction(vaultOwner, vault, vaultSigner, vaultSignerAta, receiverVaultSigner, receiverVaultSignerAta, streamToken, streamMetadata, streamConfig, withdrawAccount, streamVault, streamVaultAta, this.streamProgramId, {
                 amount,
                 automaticWithdrawal: info.automaticWithdrawal,
-                autoWithdrawFrequency: new anchor_1.BN(info.autoWithdrawFrequency),
+                autoWithdrawFrequency: new anchor_1.BN(autoWithdrawFrequency),
                 cancelableByRecipient: info.cancelableByRecipient,
                 cancelableBySender: info.cancelableBySender,
                 canTopup: info.canTopup,
                 cliffPercentage,
                 duration: new anchor_1.BN(info.duration),
                 isPausable: info.isPausable,
-                numberOfWithdrawls: new anchor_1.BN(Math.floor(info.duration / info.autoWithdrawFrequency)),
+                numberOfWithdrawls: autoWithdrawFrequency > 0 ? new anchor_1.BN(Math.floor(info.duration / autoWithdrawFrequency)) : new anchor_1.BN(0),
                 rateUpdatable: info.rateUpdatable,
                 startNow: info.startNow,
                 startTime: new anchor_1.BN(info.startTime),

package/dist/types.d.ts

@@ -172,7 +172,7 @@ export type CreateStreamFromVaultParams = {
     isPausable: boolean;
     startNow: boolean;
     startTime: number;
-    autoWithdrawFrequency: number;
+    autoWithdrawFrequency?: number;
     streamName: string;
     transferableByRecipient: boolean;
     transferableBySender: boolean;
@@ -194,7 +194,7 @@ export type createMultipleStreamFromVaultParams = {
         isPausable: boolean;
         startNow: boolean;
         startTime: number;
-        autoWithdrawFrequency: number;
+        autoWithdrawFrequency?: number;
         streamName: string;
         transferableByRecipient: boolean;
         transferableBySender: boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zebec-network/zebec-vault-sdk",
-  "version": "5.0.3",
+  "version": "5.1.0",
   "description": "An SDK for zebec vault solana program",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -41,7 +41,7 @@
     "@solana/web3.js": "^1.98.2",
     "@types/bn.js": "^5.2.0",
     "@zebec-network/core-utils": "^1.1.1",
-    "@zebec-network/solana-common": "^2.3.0",
+    "@zebec-network/solana-common": "^2.3.1",
     "bignumber.js": "^9.3.1",
     "buffer": "^6.0.3"
   }