# dew-finance-contracts

Dew Finance is a chain-abstracted vault protocol built on the NEAR blockchain. The protocol consists of two primary smart contracts that work together to provide comprehensive vault functionality:

1. **Dew Kernel** - Orchestration layer that manages multiple vault contracts, cross-chain operations, governance, and protocol-wide coordination
2. **Dew Vault** - Individual vault contracts for asset management, share handling, and deposit/withdrawal operations. These can be NEAR-native or EVM vaults.

Powered by NEAR Intents and Chain Signatures, Dew Finance enables cross-chain asset allocation into any yield-generating DeFi protocol from a single kernel.

## Architecture Overview

### Dew Kernel (`src/`)

The Dew Kernel focuses on protocol policy orchestration and cross-chain transaction coordination.

**Core Functions:**

- **Policy Orchestration**: Governs proposals, roles, and execution policies that gate sensitive calls across the protocol.
- **Cross-Chain Execution**: Routes intent-based operations through Chain Signatures and MPC services for multi-chain deployments.
- **Composable Integration**: Exposes a minimal interface so other contracts can plug into kernel-managed governance or transaction relaying without inheriting vault logic.

#### Permission

The Permission module (`src/permission/`) implements role-based access control with a proposal-policy-based governance system.

**Core Functions:**

- **Role Management**: `grant_role()` and `revoke_role()` assign roles to AccountIds and Codehashes (for trusted agents)
- **Proposal System**: `propose_execution()` creates proposals for protected operations requiring role-based approval
- **Voting Mechanism**: `vote_on_proposal()` enables role holders to approve or reject proposals with automatic execution once thresholds are met
- **Policy Configuration**: Defines execution policies for different operation types (vault config, chain signatures, message signing)
- **Global Lock System**: Contract-level locking mechanism (`acquire_lock()`, `release_lock()`) for coordinating critical operations

**Key Features:**

- **Dual Role Targets**: Supports both direct AccountId roles and Codehash roles, letting you authorize registered agents with hardware attestation
- **Proposal-Based Governance**: Protected operations require proposal creation and role-based voting instead of direct signature verification
- **Multiple Policy Types**: VaultConfiguration, ChainSigTransaction, NearNativeTransaction, and ChainSigMessage policies
- **Activation Delays**: Policy and configuration changes support delayed activation with configurable time intervals for safety
- **Pending Actions**: Tracks operations that must complete before lock release for atomic multi-step operations

#### Agent

The Agent module (`src/agent/`) manages trusted shade agent registration and verification (Forked from <https://github.com/NearDeFi/shade-agent-js/tree/main/contracts/sandbox> )

#### Vault Manager

The Vault Manager module (`src/vault_manager/`) coordinates operations across multiple vault contracts.

**Core Functions:**

- **NEAR Vault Management**: `near_vault_manager.rs` handles NEAR-native vault contract integration
- **Cross-Contract Operations**: Coordination methods for vault deposit/withdrawal processing

#### Chain Signatures

The Chain Signatures module (`src/chainsig.rs`) enables cross-chain transaction execution.

**Core Functions:**

- **Cross-Chain Execution**: Execute transactions on multiple blockchain types (EVM, Solana, etc.)
- **Message Signing**: Off-chain verification capabilities for secure operations
- **Transaction Encoding**: Format transactions for different blockchain types
- **Signature Requests**: Integration with NEAR MPC service for secure multi-party computation

### Dew Vault (`vault/`)

The Dew Vault is a specialized contract that handles individual vault operations, share management, and asset processing.

#### Accountant

The Accountant contract (`vault/src/accountant/`) manages vault-level exchange rates, calculates fees, and implements safety mechanisms to protect against price anomalies. All vault accounting logic now lives here so vaults can adopt the accountant without coupling to the governance contract.

**Core Functions:**

- **Exchange Rate Updates**: `update_exchange_rate()` updates rates for all accepted assets with proportional fee adjustments and validation
- **Fee Calculations**: Calculate management fees (time-based annualized) and performance fees (high water mark based)
- **Safety Mechanisms**: Pause automatically on price deviations, timing violations, or stale data
- **Fee Distribution**: `claim_fees()` and `claim_protocol_fees()` distribute accumulated fees to vault creators and the protocol

**Key Features:**

- **Management Fees**: Continuous time-based annualized fees applied during rate updates
- **Performance Fees**: High water mark based fees on gains, with optional yield hurdle support requiring manual crystallization
- **Price Validation**: Configurable deviation bounds, time intervals, and staleness tolerance with automatic pause triggers

#### Core Features

**NEP-141 Share Token Implementation:**

- Full fungible token standard implementation for vault shares
- Share minting and burning for deposits and withdrawals
- Transfer and approval functionality for share management

**Deposit System:**

- **Transfer Callback Deposits**: Supports both NEP-141 (`ft_on_transfer`) and NEP-245 (`mt_on_transfer`) deposits
- **Flexible Processing**: Users choose immediate or async processing via message flags
- **Slippage Protection**: Minimum share requirements protect against unfavorable rate changes
- **Asset Validation**: All deposits validate asset acceptance and configuration limits

**Redeem System:**

- **Dual Redeem Methods**: Automatic routing (`redeem()`) and explicit async (`request_redeem()`)
- **Two-Phase Confirmation**: Lock exchange rates, then process transfers after activation delay
- **Size-Based Routing**: Small redeems process immediately, large redeems use async processing
- **Slippage Protection**: Minimum asset requirements ensure acceptable exchange rates

**Teller System:**

- **Pending Operations**: System for async deposits and withdrawals
- **Operation Tracking**: Unique IDs and user lookup for comprehensive state management
- **Confirmation System**: Support for confirmed withdrawals with locked exchange rates
- **Query Methods**: Comprehensive state queries for pending operations

**Kernel Authorization:**

- **Protected Operations**: All critical functions require Dew Kernel authorization
- **Interface Implementation**: Implements `DewVaultInterface` for kernel-vault communication
- **Security Model**: Simple predecessor-based authorization for kernel operations

## Key Concepts

### Kernel-Vault Coordination

The Dew Kernel and Dew Vault work together through a well-defined interface:

1. **Vault Registration**: Kernel tracks and manages multiple vault contracts
2. **Cross-Vault Operations**: Kernel coordinates operations across multiple vaults
3. **Governance Flow**: Proposal creation → Role-based voting → Auto-execution
4. **Asset Management**: Vault Accountant contract manages exchange rates/config changes while Kernel enforces governance policies
5. **Authorization**: Vaults only accept operations from authorized kernel contracts

### Proposal-Based Governance

All protected operations use a comprehensive governance system:

1. **Proposal Creation**: Protected operations require proposal via `propose_execution()`
2. **Role-Based Voting**: Configurable approval thresholds with role-based permissions
3. **Auto-Execution**: Single-vote policies execute immediately, multi-vote policies require consensus
4. **Policy Management**: Each protected function has its own policy with configurable requirements
5. **Activation Delays**: Configuration and policy changes support delayed activation for safety

## Build

From the repository root:

```bash
./build.sh
cd vault && cargo near build
```

## Test

Before running integration tests, build the mock contracts from the repository root:

```bash
cd mock_contracts/mock_mt && cargo near build
cd ../mock_ft && cargo near build
```

Run unit tests from the root:

```bash
./build.sh test-unit
```

Run integration tests from the root:

```bash
./build.sh test-integration
```