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

package/README.md

@@ -1,219 +1,577 @@
-# Zebec Vault Sdk
+# 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
-yarn add @zebec-network/zebec-vault-sdk
+npm install @zebec-network/zebec-vault-sdk
 ```
 
 ```bash
-npm install @zebec-network/zebec-vault-sdk
+yarn add @zebec-network/zebec-vault-sdk
 ```
 
-## Dependency Map
+## Quick Start
 
-![Vault SDK Dependency Map](./assets/VaultSDKDependencyMap.png)
+### Setup
 
-## Development
+```typescript
+import { Connection, Keypair } from '@solana/web3.js';
+import { createAnchorProvider, ZebecVaultService } from '@zebec-network/zebec-vault-sdk';
 
-To build the package
+// Create connection
+const connection = new Connection('https://api.mainnet-beta.solana.com'); // use private dedicatd rpc for production
 
-```bash
-yarn build
+// 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');
 ```
 
-To run specific test filess
+## Core Features
 
-```bash
-yarn test <test file path> -f "<regex for test name>"
-// example:
-// yarn test ./test/<filename>.test.ts
+### 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);
 ```
 
-## publish
+#### Deposit SOL
 
-Build package and bump package version to specific need and publish
+```typescript
+const payload = await vaultService.depositSol({
+  depositor: wallet.publicKey,
+  amount: 1.5 // SOL amount
+});
 
-```bash
-npm publish --access public
+await payload.execute();
 ```
 
-## Usage
+#### Deposit SPL Tokens
 
-### Create Vault Instance
+```typescript
+const payload = await vaultService.deposit({
+  depositor: wallet.publicKey,
+  tokenMint: 'TOKEN_MINT_ADDRESS',
+  amount: 100 // token amount
+});
 
-```ts
-const network = "devnet";
-const wallet = <Anchor wallet>;
-const connection = <Connection Instance>;
-const provider = createAnchorProvider(connection, wallet);
-const service = await ZebecVaultService.create(provider, network);
+await payload.execute();
+
+// Note: if WSOL address is given in tokenMint, it will wrap SOL to WSOL and deposit.
 ```
 
-### Create Vault
+#### Withdraw SOL
 
-```ts
-const vaultKeypair = Keypair.generate();
-console.log("Vault Keypair:", vaultKeypair.publicKey.toBase58());
-const payload = await service.createVault({
-	vaultKeypair,
+```typescript
+const payload = await vaultService.withdrawSol({
+  withdrawer: wallet.publicKey,
+  amount: 0.5
 });
 
-const signature = await payload.execute({ commitment: "finalized" });
-console.log("Signature:", signature);
+await payload.execute();
 ```
 
-### Get Vault Info of User
+#### Withdraw SPL Tokens
+
+```typescript
+const payload = await vaultService.withdraw({
+  withdrawer: wallet.publicKey,
+  tokenMint: 'TOKEN_MINT_ADDRESS',
+  amount: 50
+});
+
+await payload.execute();
 
-```ts
-const vaultsInfo = await service.getVaultsInfoOfUser(wallet.publicKey);
-console.log("vaults info:", JSON.stringify(vaultsInfo, null, 2));
-const vault = vaultsInfo[0].vault;
+// Note: if WSOL is address in given in tokenMint, it will with withdraw WSOL and unwrap into withdrawer wallet.
 ```
 
-### Deposit Sol
+### 2. Proposal System
+
+#### Create a Proposal
+
+```typescript
+import { SystemProgram } from '@solana/web3.js';
 
-```ts
-const vault = <vault public key>;
-const amount = 2;
-const payload = await service.depositSol({ amount, vault });
-const signature = await payload.execute({ commitment: "finalized" });
+// 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();
 ```
 
-### Withdraw Sol
+### 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'
+});
 
-```ts
-const vault = <vault public key>;
-const amount = 0.01;
-const payload = await service.withdrawSol({ amount, vault });
-const signature = await payload.execute({ commitment: "finalized" });
+await payload.execute();
 ```
 
-### Deposit Token
+#### 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
+    }
+  ]
+});
 
-```ts
-const tokenMint = "De31sBPcDejCVpZZh1fq8SNs7AcuWcBKuU3k2jqnkmKc";
-const vault = <vault public key>;
-const amount = 1000
-const payload = await service.depositToken({ amount, vault, tokenMint });
-const signature = await payload.execute({ commitment: "finalized" });
+// Execute all streams in multiple transactions
+await payload.executeAll();
 ```
 
-### Withdraw Token
+#### Pause/Resume a Stream
+
+```typescript
+const payload = await vaultService.pauseResumeStream({
+  vaultOwner: wallet.publicKey,
+  streamMetadata: streamAddress
+});
 
-```ts
-const vault = <vault public key>;
-const tokenMint = "De31sBPcDejCVpZZh1fq8SNs7AcuWcBKuU3k2jqnkmKc";
-const amount = 1;
-const payload = await service.withdrawToken({ amount, vault, tokenMint });
-const signature = await payload.execute({ commitment: "finalized" });
+await payload.execute();
 ```
 
-### Execute Proposal Direct
+#### Cancel a Stream
+
+```typescript
+const payload = await vaultService.cancelStream({
+  vaultOwner: wallet.publicKey,
+  streamMetadata: streamAddress
+});
 
-```ts
-const proposer = <wallet public key>;
-const vault = <vault public key>;
+await payload.execute();
+```
 
-const memoInstruction = new TransactionInstruction({
- keys: [],
- programId: MEMO_PROGRAM_ID,
- data: Buffer.from("This is test memo", "utf8"),
+#### Withdraw from Stream
+
+```typescript
+const payload = await vaultService.withdrawStream({
+  vaultOwner: wallet.publicKey,
+  streamMetadata: streamAddress
 });
-const actions = [memoInstruction];
 
-const payload = await service.executeProposalDirect({
- actions,
- proposer,
- vault,
+await payload.execute();
+```
+
+#### Change Stream Receiver
+
+```typescript
+const payload = await vaultService.changeStreamReceiver({
+  vaultOwner: wallet.publicKey,
+  streamMetadata: streamAddress,
+  newRecipient: newRecipientAddress
 });
 
-const signature = await payload.execute({ commitment: "finalized" });
-console.log("Execute Proposal Direct Signature:", signature);
+await payload.execute();
 ```
 
-### Create Proposal
+#### Get Stream Information
 
-```ts
-const proposer = <wallet public key>;
-const receiver = <wallet public Key>;
-const vault = <vault public key>;
+```typescript
+const streamInfo = await vaultService.getStreamMetadataInfo(streamAddress);
 
-const [vaultSigner] = deriveVaultSigner(vault, service.programId);
-const name = "Transfer Funds";
-const ix = SystemProgram.transfer({
- fromPubkey: vaultSigner,
- toPubkey: receiver,
- lamports: Number(parseSol(1)),
+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
 });
-const actions = [ix];
-const proposalKeypair = Keypair.generate();
+```
+
+### 4. Staking
+
+#### Stake Tokens
 
-const createProposalPayload = await service.createProposal({
- actions,
- name,
- proposer,
- vault,
- proposalKeypair,
+```typescript
+const payload = await vaultService.stake({
+  lockupName: 'main-lockup',
+  vaultOwner: wallet.publicKey,
+  amount: 1000,
+  lockPeriod: 7776000, // 90 days in seconds
+  nonce: 0n
 });
 
-const signature = await createProposalPayload.execute({ commitment: "finalized" });
+await payload.execute();
 ```
 
-### Append Actions
+#### Unstake Tokens
 
-```ts
-const proposal = <proposal public key>;
+```typescript
+const payload = await vaultService.unstake({
+  lockupName: 'main-lockup',
+  vaultOwner: wallet.publicKey,
+  nonce: 0n
+});
+
+await payload.execute();
+```
 
-const ixB = new TransactionInstruction({
- keys: [],
- programId: MEMO_PROGRAM_ID,
- data: Buffer.from("This is test memo", "utf8"),
+#### 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
 });
-const actionsB = [ixB];
 
-const appendActionsPayload = await service.appendActions({
- actions: actionsB,
- proposal,
+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
 });
 
-const appendActionsSignature = await appendActionsPayload.execute({ commitment: "confirmed" });
+await payload.execute();
 ```
 
-### Execute Proposal
+#### Get Card Custom Token Fees
+
+```typescript
+const tokenFees = await vaultService.getCardCustomTokenFees();
 
-```ts
-const proposal = <proposal public key>;
-const payload = await service.executeProposal({
-   proposal,
+tokenFees.forEach(fee => {
+  console.log(`Token: ${fee.tokenAddress}, Fee: ${fee.fee}%`);
 });
+```
 
-const signature = await payload.execute({ commitment: "confirmed" });
-console.log("Execute Proposal Signature:", signature);
+## 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}`);
 ```
 
-### Delete Proposal
+### Get Proposals
 
-```ts
-const proposal = <proposal public key>;
+```typescript
+const proposals = await vaultService.getProposalsInfoOfVault(vaultAddress);
 
-const deleteProposalPayload = await service.deleteProposal({ proposal });
-const deleteProposalSignature = await deleteProposalPayload.execute({
- commitment: "confirmed",
+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("Delete Proposal Signature:", deleteProposalSignature);
 ```
 
-### Get Proposals Info of a Vault
+## 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
 
-```ts
-const vault = <vault public key>;
+```typescript
+// Mainnet
+const mainnetService = ZebecVaultService.create(provider, 'mainnet-beta');
 
-const proposalsInfo = await service.getProposalsInfoOfVault(vault);
+// Devnet
+const devnetService = ZebecVaultService.create(provider, 'devnet');
 ```
 
-### Get All Vaults Info
+## 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';
 
-```ts
-const vaultsInfo = await service.getAllVaultsInfo();
+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.

package/dist/constants.js

@@ -9,11 +9,11 @@ exports.ZEBEC_VAULT_PROGRAM_ID = {
 exports.TEN_BIGNUM = (0, bignumber_js_1.BigNumber)(10);
 exports.JUPITER_AGGREGATOR_PROGRAM_ID = "JUP6LkbZbjS1jKKwapdHNy74zcZ3tLUZoi5QNyVTaV4";
 exports.CARD_LOOKUP_TABLE_ADDRESS = {
-    "mainnet-beta": "CgPARkLEbygMJ8C9Z1u6MP57gvdnUERCxdhmR9bTFUSJ",
+    "mainnet-beta": "9BSK7XgPgAZJK6BEdiFDV8WKGye31uffvGjhQ1Zxob7F",
     devnet: "CgPARkLEbygMJ8C9Z1u6MP57gvdnUERCxdhmR9bTFUSJ",
 };
 exports.JUPITER_SWAP_API = "https://lite-api.jup.ag/swap/v1/swap";
 exports.STAKE_LOOKUP_TABLE_ADDRESS = {
-    "mainnet-beta": "C4R2sL6yj7bzKfbdfwCfH68DZZ3QnzdmedE9wQqTfAAA",
+    "mainnet-beta": "EoKjJejKr4XsBdtUuYwzZcYd6tpGNijxCGgQocxtxQ8t",
     devnet: "C4R2sL6yj7bzKfbdfwCfH68DZZ3QnzdmedE9wQqTfAAA",
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zebec-network/zebec-vault-sdk",
-  "version": "5.0.1",
+  "version": "5.0.3",
   "description": "An SDK for zebec vault solana program",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",