Sync

.gitignore

@@ -4,4 +4,15 @@ target
 # Deployment files (user-specific)
 scripts/deployments.json
 
-.env
+.env
+
+# Claude Code
+.claude/
+
+# TLDR tool
+.tldr/
+.tldrignore
+
+# Test artifacts
+leafs/testMerkl.json
+leafs/testMerkl.log

.tool-versions

@@ -0,0 +1 @@
+scarb 2.13.1

README.md

@@ -87,6 +87,133 @@ scarb build
 snforge test
 ```
 
+## Get Started as a Vault Builder
+
+This guide walks you through deploying and configuring vaults as a builder, covering both custodial and non-custodial approaches.
+
+### Step 1: Deploy Your Vault
+
+Use the deployment script to create your vault with the desired configuration:
+
+```bash
+cd scripts
+npm run deploy:vault
+```
+
+The script (`scripts/deployVault.ts`) will prompt you for:
+- **Vault Details**: Name, symbol, underlying asset address
+- **Fee Configuration**: Management, performance, and redemption fees
+- **Operational Parameters**: Report delay, max delta percentage, fees recipient
+- **Vault Type**: Choose between custodial or non-custodial
+
+#### Custodial vs Non-Custodial Vaults
+
+**Custodial Vaults:**
+- Use an existing, pre-deployed VaultAllocator
+- Suitable when you trust a third-party allocator
+- Faster deployment (vault + redeem request only)
+- Limited control over fund allocation strategies
+
+**Non-Custodial Vaults:**
+- Deploy a new VaultAllocator and Manager specific to your vault
+- Full control over fund allocation and strategy management
+- Requires additional setup for Merkle tree verification system
+- Higher security and customization capabilities
+
+### Step 2: Non-Custodial Setup (Advanced Fund Management)
+
+For non-custodial vaults, you need to set up the Merkle tree verification system for secure fund allocation:
+
+#### 2.1 Configure Allocation Strategies
+
+The VaultAllocator (`packages/vault_allocator`) provides secure fund allocation through:
+- **Manager Contract**: Merkle proof-based call verification
+- **Decoders & Sanitizers**: Pre-built integrations for protocols (AVNU, Vesu, ERC-4626)
+- **Merkle Tree Verification**: Whitelist system for allowed operations
+
+#### 2.2 Generate Merkle Tree Configuration
+
+Run the merkle tree generation script to create your allocation whitelist:
+
+```bash
+./export_merkle.sh [config_name]
+```
+
+This script:
+1. Executes test scenarios to generate valid operation leafs
+2. Creates a Merkle tree with allowed operations
+3. Outputs a JSON configuration file in `leafs/[config_name].json`
+
+The generated file contains:
+- **Metadata**: Vault, allocator, and manager addresses
+- **Leafs**: Whitelisted operations with their proofs
+- **Tree**: Complete Merkle tree structure
+
+#### 2.3 Set Management Root
+
+Configure the Manager contract with your Merkle root:
+
+```typescript
+// Using the deployed manager address from step 1
+const manager = new Contract(managerAbi, managerAddress, account);
+await manager.set_manage_root(vaultAddress, merkleRoot);
+```
+
+### Step 3: Off-Chain Integration with Curator SDK
+
+Use the Curator SDK (`sdk/src/curator/index.ts`) to generate secure calldata for vault operations:
+
+#### 3.1 Initialize the SDK
+
+```typescript
+import { VaultCuratorSDK } from './sdk/src/curator';
+
+// Load configuration from generated merkle file
+const curator = VaultCuratorSDK.fromFile('./leafs/your_config.json');
+```
+
+#### 3.2 Generate Operation Calldata
+
+The SDK provides helper methods for common operations:
+
+```typescript
+// Bring liquidity to vault
+const calls = curator.bringLiquidityHelper(true, amount); // true = with approval
+
+// Multi-step operations (approve + deposit)
+const calls = curator.depositHelper({
+  target: vaultAddress,
+  assets: depositAmount,
+  receiver: userAddress,
+  withApproval: true
+});
+
+// Advanced DeFi operations
+const calls = curator.multiRouteSwapHelper(swapParams, { withApproval: true });
+const calls = curator.ModifyPositionV1Helper(vesuParams, approvalParams);
+```
+
+#### 3.3 Execute Operations
+
+```typescript
+// Execute the generated calls
+const response = await account.execute(calls);
+```
+
+### Key Benefits
+
+- **Security**: Merkle proof verification ensures only whitelisted operations
+- **Flexibility**: Support for multiple DeFi protocols (AVNU, Vesu, ERC-4626)
+- **Efficiency**: Batch operations with automatic approval handling
+- **Auditability**: All operations are pre-defined and verifiable
+
+### Next Steps
+
+1. **Monitor**: Use the backend services for vault monitoring and analytics
+2. **Optimize**: Adjust strategies based on performance metrics
+3. **Scale**: Deploy multiple vaults with different strategies
+4. **Integrate**: Use the SDK in your applications for seamless vault management
+
 ### Scripts & Backend
 
 For deployment scripts and configuration utilities, see [scripts/README.md](scripts/README.md).

Scarb.lock

@@ -1,16 +1,37 @@
 # Code generated by scarb DO NOT EDIT.
 version = 1
 
+[[package]]
+name = "alexandria_bytes"
+version = "0.6.1"
+source = "registry+https://scarbs.xyz/"
+checksum = "sha256:b1a402330fe5356ca0a4f24d2b8dd1fb0a7e2568bf35c349319cadb53f0ed6fd"
+dependencies = [
+ "alexandria_data_structures",
+ "alexandria_math",
+]
+
+[[package]]
+name = "alexandria_data_structures"
+version = "0.6.1"
+source = "registry+https://scarbs.xyz/"
+checksum = "sha256:f011951982ca26ce64c212ca5aa739bd16461dae96a4fb9a8f8e360b1c5e7b94"
+
 [[package]]
 name = "alexandria_math"
-version = "0.6.0"
+version = "0.6.1"
 source = "registry+https://scarbs.xyz/"
-checksum = "sha256:1e08ebba0ed9f7217b8efc283d2ad41730257cf41a47ca88a94fb0fafad22e9e"
+checksum = "sha256:19160f0993a6643e8e71a3bce03e54a37f26b8cad94f21668d7cc9afd08d2047"
+
+[[package]]
+name = "ekubo"
+version = "0.1.0"
+source = "git+https://github.com/ekuboprotocol/starknet-contracts#cf2e95fd124bfb19491e1a7da9ffba4b63cc6c4e"
 
 [[package]]
 name = "openzeppelin"
-version = "3.0.0-alpha.1"
-source = "git+https://github.com/OpenZeppelin/cairo-contracts#a2bdd1bdbdf96a9291ba0f2269f1e11c451fddb9"
+version = "3.0.0-alpha.3"
+source = "git+https://github.com/OpenZeppelin/cairo-contracts#1e5a44ec50d7625395ca8322eec971ce8abb5bc1"
 dependencies = [
  "openzeppelin_access",
  "openzeppelin_account",
@@ -28,17 +49,17 @@ dependencies = [
 
 [[package]]
 name = "openzeppelin_access"
-version = "3.0.0-alpha.1"
-source = "git+https://github.com/OpenZeppelin/cairo-contracts#a2bdd1bdbdf96a9291ba0f2269f1e11c451fddb9"
+version = "3.0.0-alpha.3"
+source = "git+https://github.com/OpenZeppelin/cairo-contracts#1e5a44ec50d7625395ca8322eec971ce8abb5bc1"
 dependencies = [
  "openzeppelin_interfaces",
  "openzeppelin_introspection",
 ]
 
 [[package]]
 name = "openzeppelin_account"
-version = "3.0.0-alpha.1"
-source = "git+https://github.com/OpenZeppelin/cairo-contracts#a2bdd1bdbdf96a9291ba0f2269f1e11c451fddb9"
+version = "3.0.0-alpha.3"
+source = "git+https://github.com/OpenZeppelin/cairo-contracts#1e5a44ec50d7625395ca8322eec971ce8abb5bc1"
 dependencies = [
  "openzeppelin_interfaces",
  "openzeppelin_introspection",
@@ -47,8 +68,8 @@ dependencies = [
 
 [[package]]
 name = "openzeppelin_finance"
-version = "3.0.0-alpha.1"
-source = "git+https://github.com/OpenZeppelin/cairo-contracts#a2bdd1bdbdf96a9291ba0f2269f1e11c451fddb9"
+version = "3.0.0-alpha.3"
+source = "git+https://github.com/OpenZeppelin/cairo-contracts#1e5a44ec50d7625395ca8322eec971ce8abb5bc1"
 dependencies = [
  "openzeppelin_access",
  "openzeppelin_interfaces",
@@ -57,11 +78,10 @@ dependencies = [
 
 [[package]]
 name = "openzeppelin_governance"
-version = "3.0.0-alpha.1"
-source = "git+https://github.com/OpenZeppelin/cairo-contracts#a2bdd1bdbdf96a9291ba0f2269f1e11c451fddb9"
+version = "3.0.0-alpha.3"
+source = "git+https://github.com/OpenZeppelin/cairo-contracts#1e5a44ec50d7625395ca8322eec971ce8abb5bc1"
 dependencies = [
  "openzeppelin_access",
- "openzeppelin_account",
  "openzeppelin_interfaces",
  "openzeppelin_introspection",
  "openzeppelin_token",
@@ -70,26 +90,26 @@ dependencies = [
 
 [[package]]
 name = "openzeppelin_interfaces"
-version = "2.1.0"
-source = "git+https://github.com/OpenZeppelin/cairo-contracts#a2bdd1bdbdf96a9291ba0f2269f1e11c451fddb9"
+version = "2.1.0-alpha.0"
+source = "git+https://github.com/OpenZeppelin/cairo-contracts#1e5a44ec50d7625395ca8322eec971ce8abb5bc1"
 
 [[package]]
 name = "openzeppelin_introspection"
-version = "3.0.0-alpha.1"
-source = "git+https://github.com/OpenZeppelin/cairo-contracts#a2bdd1bdbdf96a9291ba0f2269f1e11c451fddb9"
+version = "3.0.0-alpha.3"
+source = "git+https://github.com/OpenZeppelin/cairo-contracts#1e5a44ec50d7625395ca8322eec971ce8abb5bc1"
 dependencies = [
  "openzeppelin_interfaces",
 ]
 
 [[package]]
 name = "openzeppelin_merkle_tree"
-version = "3.0.0-alpha.1"
-source = "git+https://github.com/OpenZeppelin/cairo-contracts#a2bdd1bdbdf96a9291ba0f2269f1e11c451fddb9"
+version = "3.0.0-alpha.3"
+source = "git+https://github.com/OpenZeppelin/cairo-contracts#1e5a44ec50d7625395ca8322eec971ce8abb5bc1"
 
 [[package]]
 name = "openzeppelin_presets"
-version = "3.0.0-alpha.1"
-source = "git+https://github.com/OpenZeppelin/cairo-contracts#a2bdd1bdbdf96a9291ba0f2269f1e11c451fddb9"
+version = "3.0.0-alpha.3"
+source = "git+https://github.com/OpenZeppelin/cairo-contracts#1e5a44ec50d7625395ca8322eec971ce8abb5bc1"
 dependencies = [
  "openzeppelin_access",
  "openzeppelin_account",
@@ -103,48 +123,47 @@ dependencies = [
 
 [[package]]
 name = "openzeppelin_security"
-version = "3.0.0-alpha.1"
-source = "git+https://github.com/OpenZeppelin/cairo-contracts#a2bdd1bdbdf96a9291ba0f2269f1e11c451fddb9"
+version = "3.0.0-alpha.3"
+source = "git+https://github.com/OpenZeppelin/cairo-contracts#1e5a44ec50d7625395ca8322eec971ce8abb5bc1"
 dependencies = [
  "openzeppelin_interfaces",
 ]
 
 [[package]]
 name = "openzeppelin_token"
-version = "3.0.0-alpha.1"
-source = "git+https://github.com/OpenZeppelin/cairo-contracts#a2bdd1bdbdf96a9291ba0f2269f1e11c451fddb9"
+version = "3.0.0-alpha.3"
+source = "git+https://github.com/OpenZeppelin/cairo-contracts#1e5a44ec50d7625395ca8322eec971ce8abb5bc1"
 dependencies = [
  "openzeppelin_access",
- "openzeppelin_account",
  "openzeppelin_interfaces",
  "openzeppelin_introspection",
  "openzeppelin_utils",
 ]
 
 [[package]]
 name = "openzeppelin_upgrades"
-version = "3.0.0-alpha.1"
-source = "git+https://github.com/OpenZeppelin/cairo-contracts#a2bdd1bdbdf96a9291ba0f2269f1e11c451fddb9"
+version = "3.0.0-alpha.3"
+source = "git+https://github.com/OpenZeppelin/cairo-contracts#1e5a44ec50d7625395ca8322eec971ce8abb5bc1"
 
 [[package]]
 name = "openzeppelin_utils"
-version = "3.0.0-alpha.1"
-source = "git+https://github.com/OpenZeppelin/cairo-contracts#a2bdd1bdbdf96a9291ba0f2269f1e11c451fddb9"
+version = "2.1.0-alpha.0"
+source = "git+https://github.com/OpenZeppelin/cairo-contracts#1e5a44ec50d7625395ca8322eec971ce8abb5bc1"
 dependencies = [
  "openzeppelin_interfaces",
 ]
 
 [[package]]
 name = "snforge_scarb_plugin"
-version = "0.48.0"
+version = "0.48.1"
 source = "registry+https://scarbs.xyz/"
-checksum = "sha256:8630dcf3fa4df36a3d45e6a2d053cf84c548ab154e829fece99373ae5852921c"
+checksum = "sha256:2dd27e8215eea8785b3930e9f452e11b429ca262b1c1fbb071bfc173b9ebc125"
 
 [[package]]
 name = "snforge_std"
-version = "0.48.0"
+version = "0.48.1"
 source = "registry+https://scarbs.xyz/"
-checksum = "sha256:981139c83359089540652c44f4a1a888c77409eedaa148377927cc63a604b67b"
+checksum = "sha256:89f759fa685d48ed0ba7152d2ac2eb168da08dfa8b84b2bee96e203dc5b2413e"
 dependencies = [
  "snforge_scarb_plugin",
 ]
@@ -172,7 +191,9 @@ dependencies = [
 name = "vault_allocator"
 version = "0.1.0"
 dependencies = [
+ "alexandria_bytes",
  "alexandria_math",
+ "ekubo",
  "openzeppelin",
  "snforge_std",
 ]

Scarb.toml

@@ -14,8 +14,8 @@ edition.workspace = true
 [workspace.package]
 version = "0.1.0"
 edition = "2024_07"
-cairo-version = "2.12.0"
-scarb-version = "2.12.0"
+cairo-version = "2.14.0"
+scarb-version = "2.14.0"
 authors = ["ForgeYields <forge.fi.contact@gmail.com>"]
 description = "Standard vault infrastructure for Starknet"
 documentation = ""
@@ -27,10 +27,12 @@ keywords = [
 ]
 
 [workspace.dependencies]
-starknet = "2.12.0"
+starknet = "2.14.0"
 openzeppelin = { git = "https://github.com/OpenZeppelin/cairo-contracts" }
-snforge_std = "0.48.0"
+snforge_std = "0.48.1"
 alexandria_math = "0.6.0"
+alexandria_bytes = "0.6.0"
+ekubo = { git = "https://github.com/ekuboprotocol/starknet-contracts" }
 
 
 [dependencies]