@vaultedge/v1-core

🚀 Production-ready smart contract artifacts and interfaces for VaultEdge protocol with enterprise-grade security and performance optimizations.

📋 Table of Contents

• 🎯 Quick Start

• 🔒 Security Features

• 🏗️ Scaffold-ETH Integration

• 📖 API Reference

• 💡 Usage Examples

• 🔧 Advanced Features

• 📦 Package Contents

• 🤝 Contributing

🎯 Quick Start

1. Secure Installation

⚠️ SECURITY NOTICE: Always pin to exact versions for smart contract projects!

# ✅ SECURE - Recommended installation (exact version)
npm install @vaultedge/[email protected] --save-exact
# or
yarn add @vaultedge/[email protected] --exact

2. Basic Usage

import { addresses, getConfigForChainId } from '@vaultedge/v1-core'

// Get contract addresses for Sonic Testnet
const sonicConfig = getConfigForChainId(64165)
const controllerAddress = sonicConfig.deployedContracts.vaultedgeController.address

// Or access directly
const controllerAddr = addresses[64165].deployedContracts.vaultedgeController.address

3. Scaffold-ETH Integration

import { deployedContracts } from '@vaultedge/v1-core/scaffold-eth'
import { useScaffoldReadContract } from '~~/hooks/scaffold-eth'

// Works seamlessly with Scaffold-ETH hooks
const { data: owner } = useScaffoldReadContract({
  contractName: "VaultedgeController",
  functionName: "owner"
})

🔒 Security Features

Post-Install Security Warnings

This package automatically warns about insecure installation patterns:

🔒 VAULTEDGE SECURITY NOTICE
═══════════════════════════════════════════════════════════

⚠️  IMPORTANT: Pin this package version to prevent supply chain attacks!

✅ SECURE (recommended):
   npm install @vaultedge/[email protected] --save-exact
   yarn add @vaultedge/[email protected] --exact

❌ INSECURE (avoid):
   npm install @vaultedge/v1-core        # Uses latest, unpredictable
   npm install @vaultedge/v1-core@^0.1.0 # Allows minor updates, risky

Why Security Matters for Smart Contracts

• High-Value Targets: Smart contract projects are prime targets for supply chain attacks
• Immutable Deployments: Once deployed, contracts can't be easily updated
• Financial Risk: Bugs can lead to significant financial losses
• Reproducible Builds: Exact versions ensure consistent deployments

Security Best Practices

• ✅ Pin exact versions - No ^ or ~ in package.json
• ✅ Commit lock files - Include package-lock.json in version control
• ✅ Use npm ci - In production deployments
• ✅ Regular audits - Run npm audit frequently
• ✅ Monitor dependencies - Use tools like Snyk or Dependabot

🏗️ Scaffold-ETH Integration

Drop-in Compatibility

This package provides seamless integration with Scaffold-ETH 2 projects through pre-generated contract deployments.

Setup in Scaffold-ETH Projects

1. Install the package (with exact version):

npm install @vaultedge/[email protected] --save-exact

2. Import deployed contracts:

import { deployedContracts } from '@vaultedge/v1-core/scaffold-eth'

3. Use with Scaffold-ETH hooks:

import { useScaffoldReadContract, useScaffoldWriteContract } from '~~/hooks/scaffold-eth'

// Read contract data
const { data: controller } = useScaffoldReadContract({
  contractName: "VaultedgeController",
  functionName: "owner"
})

// Write to contract
const { writeAsync: createVault } = useScaffoldWriteContract({
  contractName: "BorrowerOperations", 
  functionName: "openVault",
  args: [collAmount, debtAmount, upperHint, lowerHint]
})

// Get contract instance
const { data: vaultManager } = useScaffoldContract({
  contractName: "VaultManagerDiamond"
})

Supported Networks in Scaffold-ETH

• Sonic Testnet (Chain ID: 64165)
• Linea Testnet (Chain ID: 59141)

Contract Types Available

All VaultEdge protocol contracts are available:

• VaultedgeController - Main protocol controller
• BorrowerOperations - Vault management operations
• VaultManagerDiamond - Diamond proxy for vault management
• StabilityPool - Stability pool for liquidations
• ActivePool - Active collateral pool
• DefaultPool - Default collateral pool
• And many more...

📖 API Reference

Core Functions

getConfigForChainId(chainId: number)

Get complete configuration for a specific chain.

import { getConfigForChainId } from '@vaultedge/v1-core'

const config = getConfigForChainId(64165) // Sonic Testnet
console.log(config.deployedContracts.vaultedgeController.address)

getConfigByName(networkName: string)

Get configuration by network name.

import { getConfigByName } from '@vaultedge/v1-core'

const config = getConfigByName('sonicTestnet')
console.log(config.deployedContracts.vaultedgeController.address)

isSupportedChain(chainId: number)

Check if a chain is supported.

import { isSupportedChain } from '@vaultedge/v1-core'

if (isSupportedChain(64165)) {
  // Chain is supported
}

getNetworkName(chainId: number)

Get network name from chain ID.

import { getNetworkName } from '@vaultedge/v1-core'

const name = getNetworkName(64165) // Returns 'sonicTestnet'

Network Helper Functions

Helper functions for working with networks:

import { 
  getConfigForChainId,
  getConfigByName,
  isSupportedChain,
  getNetworkName 
} from '@vaultedge/v1-core'

// Get configuration for a specific chain
const config = getConfigForChainId(64165)
const controllerAddress = config.deployedContracts.vaultedgeController.address

// Check if chain is supported
if (isSupportedChain(64165)) {
  console.log('Sonic Testnet is supported')
}

Constants

Static Metadata

import { TOKEN_METADATA, CONTRACT_NAMES } from '@vaultedge/v1-core'

// Token information
const veUSDInfo = TOKEN_METADATA.veUSD
console.log(`${veUSDInfo.name} (${veUSDInfo.symbol}) - ${veUSDInfo.decimals} decimals`)

// Contract names for TypeChain or tooling
const controllerName = CONTRACT_NAMES.VaultedgeController

Fetch Protocol Parameters On-Chain

import { getConfigForChainId } from '@vaultedge/v1-core'
import { ethers } from 'ethers'

// Get contract configuration
const config = getConfigForChainId(64165)
const provider = new ethers.JsonRpcProvider('https://rpc.sonic.fantom.network')
const controller = new ethers.Contract(
  config.deployedContracts.vaultedgeController.address,
  config.deployedContracts.vaultedgeController.abi,
  provider
)

// Fetch live parameters from contract
const minCollRatio = await controller.MCR() // Minimum Collateral Ratio
const minDebt = await controller.MIN_NET_DEBT() // Minimum debt amount
const borrowingFeeFloor = await controller.BORROWING_FEE_FLOOR() // Min borrowing fee

🔗 On-Chain Parameter Fetching

Since protocol parameters can change via governance, it's recommended to fetch them directly from the deployed contracts rather than using hardcoded values:

import { getConfigForChainId } from '@vaultedge/v1-core'
import { ethers } from 'ethers'

async function getProtocolParameters(chainId: number) {
  const config = getConfigForChainId(chainId)
  const provider = new ethers.JsonRpcProvider(/* your RPC URL */)
  
  const controller = new ethers.Contract(
    config.deployedContracts.vaultedgeController.address,
    config.deployedContracts.vaultedgeController.abi,
    provider
  )
  
  return {
    mcr: await controller.MCR(),                    // Minimum Collateral Ratio
    minNetDebt: await controller.MIN_NET_DEBT(),    // Minimum debt amount  
    borrowingFeeFloor: await controller.BORROWING_FEE_FLOOR(),
    liquidationReserve: await controller.LIQUIDATION_RESERVE(),
    // Add other parameters as needed
  }
}

// Usage
const params = await getProtocolParameters(64165) // Sonic Testnet
console.log('Live protocol parameters:', params)

💡 Usage Examples

Example 1: Basic Contract Interaction

import { addresses, getConfigForChainId } from '@vaultedge/v1-core'
import { ethers } from 'ethers'

// Get contract configuration
const config = getConfigForChainId(64165) // Sonic Testnet
const controllerAddr = config.deployedContracts.vaultedgeController.address

// Create contract instance
const provider = new ethers.JsonRpcProvider('https://rpc.sonic.fantom.network')
const controller = new ethers.Contract(
  controllerAddr,
  config.deployedContracts.vaultedgeController.abi,
  provider
)

// Read contract data
const owner = await controller.owner()
console.log('Controller owner:', owner)

Example 2: Multi-Network Support

import { SUPPORTED_CHAIN_IDS, getConfigForChainId } from '@vaultedge/v1-core'

// Iterate through all supported networks
for (const [networkName, chainId] of Object.entries(SUPPORTED_CHAIN_IDS)) {
  const config = getConfigForChainId(chainId)
  console.log(`${networkName} (${chainId}):`, 
    config.deployedContracts.vaultedgeController.address)
}

Example 3: Fetch Protocol Parameters

import { getConfigForChainId } from '@vaultedge/v1-core'
import { ethers } from 'ethers'

// Get contract and connect to provider
const config = getConfigForChainId(64165) // Sonic Testnet
const provider = new ethers.JsonRpcProvider('https://rpc.sonic.fantom.network')
const controller = new ethers.Contract(
  config.deployedContracts.vaultedgeController.address,
  config.deployedContracts.vaultedgeController.abi,
  provider
)

// Fetch live protocol parameters
const protocolConfig = {
  minCollateralRatio: await controller.MCR(),
  liquidationReserve: await controller.LIQUIDATION_RESERVE(),
  minDebtAmount: await controller.MIN_NET_DEBT()
}

console.log('Live protocol config:', protocolConfig)

Example 4: On-Chain Protocol Calculations

import { getConfigForChainId } from '@vaultedge/v1-core'
import { ethers } from 'ethers'

// Get contract configuration
const config = getConfigForChainId(64165)
const provider = new ethers.JsonRpcProvider('https://rpc.sonic.fantom.network')
const controller = new ethers.Contract(
  config.deployedContracts.vaultedgeController.address,
  config.deployedContracts.vaultedgeController.abi,
  provider
)

// Fetch MCR from contract and calculate minimum collateral
const mcr = await controller.MCR() // Get live MCR from contract
const debtAmount = ethers.parseEther('1000') // 1000 veUSD

function calculateMinCollateral(debtAmount: bigint, mcr: bigint): bigint {
  return (debtAmount * mcr) / ethers.parseEther('1') // MCR is in 18 decimals
}

const minCollateral = calculateMinCollateral(debtAmount, mcr)
console.log('Minimum collateral needed:', ethers.formatEther(minCollateral))

Example 5: Multi-Network Configuration

import { 
  getConfigForChainId,
  getNetworkName,
  SUPPORTED_CHAIN_IDS
} from '@vaultedge/v1-core'

// Access multiple networks
for (const [networkName, chainId] of Object.entries(SUPPORTED_CHAIN_IDS)) {
  const config = getConfigForChainId(chainId)
  console.log(`${networkName} (${chainId}):`)
  console.log('- Controller:', config.deployedContracts.vaultedgeController.address)
  console.log('- Stability Pool:', config.deployedContracts.stabilityPool.address)
}

🔧 Advanced Features

Direct Artifact Access

Access raw contract artifacts for advanced use cases:

// Import specific contract artifacts
import VaultedgeControllerArtifact from '@vaultedge/v1-core/artifacts/contracts/VaultedgeController.sol/VaultedgeController.json'
import BorrowerOperationsArtifact from '@vaultedge/v1-core/artifacts/contracts/BorrowerOperations.sol/BorrowerOperations.json'

// Use with your preferred contract library
const contract = new ethers.Contract(
  address,
  VaultedgeControllerArtifact.abi,
  provider
)

Import Solidity Interfaces

// Import interfaces in your Solidity contracts
import '@vaultedge/v1-core/contracts/Interfaces/IVaultedgeController.sol';
import '@vaultedge/v1-core/contracts/Interfaces/IStabilityPool.sol';
import '@vaultedge/v1-core/contracts/Interfaces/IBorrowerOperations.sol';

contract MyContract {
  IVaultedgeController public controller;
  
  constructor(address _controller) {
    controller = IVaultedgeController(_controller);
  }
}

📦 Package Contents

Contract Artifacts

• ABIs - Application Binary Interfaces for all contracts
• Bytecode - Compiled contract bytecode
• Metadata - Contract compilation metadata
• Interfaces - Solidity interface definitions

Network Configurations

• Sonic Testnet (64165) - Full deployment configuration
• Linea Testnet (59141) - Full deployment configuration
• Helper Functions - Network-specific utilities

Static Constants

• Token Metadata - veUSD token information
• Contract Names - Contract identifiers for tooling

Integration Modules

• Scaffold-ETH - Drop-in compatibility with Scaffold-ETH 2
• TypeScript - Full type definitions and interfaces

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

# Clone the main VaultEdge contracts repository
git clone https://github.com/vaultedge/vaultedge-contracts.git

# Navigate to the published package
cd vaultedge-contracts/published/contracts-core

# Install dependencies
npm install

# Build the package
npm run build

# Run tests
npm test

📄 License

This project is licensed under the GPL-3.0-or-later License - see the LICENSE file for details.

Built with ❤️ by the Vaultedge team

⭐ Star us on GitHub