@zebec-network/zebec-vault-sdk 5.0.2 → 5.0.4

package/README.md

@@ -1,219 +1,562 @@
-# 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,
+ });
 
-```ts
-const vaultsInfo = await service.getVaultsInfoOfUser(wallet.publicKey);
-console.log("vaults info:", JSON.stringify(vaultsInfo, null, 2));
-const vault = vaultsInfo[0].vault;
+ await payload.execute();
+
+// 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
 
-```ts
-const vault = <vault public key>;
-const amount = 2;
-const payload = await service.depositSol({ amount, vault });
-const signature = await payload.execute({ commitment: "finalized" });
+```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();
 ```
 
-### Withdraw Sol
+#### Execute a Proposal
+
+```typescript
+const payload = await vaultService.executeProposal({
+ caller: wallet.publicKey,
+ proposal: proposalAddress,
+ addressLookupTables: [lookupTableAddress], // optional
+});
 
-```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
+#### Execute Proposal Directly (Single Transaction)
 
-```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" });
+```typescript
+const payload = await vaultService.executeProposalDirect({
+ proposer: wallet.publicKey,
+ actions: [instruction1, instruction2],
+ addressLookupTables: [lookupTableAddress],
+});
+
+await payload.execute();
 ```
 
-### Withdraw Token
+### 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 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
+#### 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();
+```
 
-```ts
-const proposer = <wallet public key>;
-const vault = <vault public key>;
+#### Pause/Resume a Stream
 
-const memoInstruction = new TransactionInstruction({
- keys: [],
- programId: MEMO_PROGRAM_ID,
- data: Buffer.from("This is test memo", "utf8"),
+```typescript
+const payload = await vaultService.pauseResumeStream({
+ vaultOwner: wallet.publicKey,
+ streamMetadata: streamAddress,
 });
-const actions = [memoInstruction];
 
-const payload = await service.executeProposalDirect({
- actions,
- proposer,
- vault,
+await payload.execute();
+```
+
+#### Cancel a Stream
+
+```typescript
+const payload = await vaultService.cancelStream({
+ vaultOwner: wallet.publicKey,
+ streamMetadata: streamAddress,
 });
 
-const signature = await payload.execute({ commitment: "finalized" });
-console.log("Execute Proposal Direct Signature:", signature);
+await payload.execute();
 ```
 
-### Create Proposal
+#### Withdraw from Stream
 
-```ts
-const proposer = <wallet public key>;
-const receiver = <wallet public Key>;
-const vault = <vault public key>;
+```typescript
+const payload = await vaultService.withdrawStream({
+ vaultOwner: wallet.publicKey,
+ streamMetadata: streamAddress,
+});
 
-const [vaultSigner] = deriveVaultSigner(vault, service.programId);
-const name = "Transfer Funds";
-const ix = SystemProgram.transfer({
- fromPubkey: vaultSigner,
- toPubkey: receiver,
- lamports: Number(parseSol(1)),
+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,
 });
-const actions = [ix];
-const proposalKeypair = Keypair.generate();
 
-const createProposalPayload = await service.createProposal({
- actions,
- name,
- proposer,
- vault,
- proposalKeypair,
+await payload.execute();
+```
+
+#### Unstake Tokens
+
+```typescript
+const payload = await vaultService.unstake({
+ lockupName: "main-lockup",
+ vaultOwner: wallet.publicKey,
+ nonce: 0n,
 });
 
-const signature = await createProposalPayload.execute({ commitment: "finalized" });
+await payload.execute();
+```
+
+#### Get Stake Nonce Information
+
+```typescript
+const nonceInfo = await vaultService.getStakeUserNonceInfo("main-lockup", wallet.publicKey);
+
+console.log("Current nonce:", nonceInfo?.nonce);
 ```
 
-### Append Actions
+### 5. Virtual Cards
+
+#### Create a Silver Card
 
-```ts
-const proposal = <proposal public key>;
+```typescript
+const nextIndex = await vaultService.getNextCardIndex();
 
-const ixB = new TransactionInstruction({
- keys: [],
- programId: MEMO_PROGRAM_ID,
- data: Buffer.from("This is test memo", "utf8"),
+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",
 });
-const actionsB = [ixB];
 
-const appendActionsPayload = await service.appendActions({
- actions: actionsB,
- proposal,
+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",
 });
 
-const appendActionsSignature = await appendActionsPayload.execute({ commitment: "confirmed" });
+await payload.execute();
 ```
 
-### Execute Proposal
+#### 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();
+```
 
-```ts
-const proposal = <proposal public key>;
-const payload = await service.executeProposal({
-   proposal,
+#### 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 signature = await payload.execute({ commitment: "confirmed" });
-console.log("Execute Proposal Signature:", signature);
+await payload.execute();
 ```
 
-### Delete Proposal
+#### Get Card Custom Token Fees
 
-```ts
-const proposal = <proposal public key>;
+```typescript
+const tokenFees = await vaultService.getCardCustomTokenFees();
 
-const deleteProposalPayload = await service.deleteProposal({ proposal });
-const deleteProposalSignature = await deleteProposalPayload.execute({
- commitment: "confirmed",
+tokenFees.forEach((fee) => {
+ console.log(`Token: ${fee.tokenAddress}, Fee: ${fee.fee}%`);
 });
-console.log("Delete Proposal Signature:", deleteProposalSignature);
 ```
 
-### Get Proposals Info of a Vault
+## Query Functions
 
-```ts
-const vault = <vault public key>;
+### Get Vault Information
 
-const proposalsInfo = await service.getProposalsInfoOfVault(vault);
+```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);
+});
 ```
 
-### Get All Vaults Info
+## Readonly Provider
 
-```ts
-const vaultsInfo = await service.getAllVaultsInfo();
+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.

package/dist/constants.js

@@ -9,7 +9,7 @@ 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";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zebec-network/zebec-vault-sdk",
-  "version": "5.0.2",
+  "version": "5.0.4",
   "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"
   }