Axionvera Network

Axionvera Network is a Soroban (Stellar) vault and reward distribution project. This repository contains:

• a Soroban smart contract for deposits, withdrawals, and rewards
• a Rust network node service around the contract
• deployment scripts and infrastructure code
• tests and contributor documentation

What The Contract Does

The vault contract supports four main user actions:

1. Deposit a token into the vault.
2. Withdraw deposited funds later.
3. Receive proportional rewards when an admin distributes them.
4. Claim accrued rewards.

The reward model is index-based, which means the contract updates a global reward index instead of looping through every user during a distribution.

Start Here

If you are onboarding as a contributor, these are the best first reads:

• docs/contract-spec.md
• docs/contract-storage.md
• contracts/vault-contract/src/lib.rs
• contracts/vault-contract/src/storage.rs
• ARCHITECTURE.md

Contract At A Glance

Key ideas:

• total_deposits tracks the total deposited amount.
• reward_index tracks cumulative rewards per deposited unit.
• each user stores a personal reward index snapshot and accrued rewards.
• rewards are realized lazily on user interaction.

Core public functions:

• initialize(admin, deposit_token, reward_token)
• deposit(from, amount)
• withdraw(to, amount)
• distribute_rewards(amount)
• claim_rewards(user)
• balance(user)
• total_deposits()
• reward_index()
• pending_rewards(user)

Storage Overview

The contract stores both global and per-user state.

Global keys:

• initialization flag
• admin address
• deposit token address
• reward token address
• total deposits
• reward index

Per-user keys:

• deposited balance
• last synced reward index
• accrued but unclaimed rewards

Read the full walkthrough in docs/contract-storage.md.

Example Flow

vault.initialize(&admin, &deposit_token_id, &reward_token_id);

vault.deposit(&alice, &100);
vault.deposit(&bob, &300);

vault.distribute_rewards(&400);

assert_eq!(vault.pending_rewards(&alice), 100);
assert_eq!(vault.pending_rewards(&bob), 300);

assert_eq!(vault.claim_rewards(&alice), 100);
assert_eq!(vault.claim_rewards(&bob), 300);

Repository Layout

• contracts/vault-contract - Soroban vault contract in Rust
• network-node - network service and API layer
• docs - contract and architecture documentation
• scripts - deployment and helper scripts
• tests - integration and TypeScript tests
• terraform - infrastructure as code

Local Setup

Prerequisites:

• Rust stable
• wasm32-unknown-unknown target
• Soroban CLI
• Node.js 18+

Basic setup:

git clone https://github.com/your-org/axionvera-network.git
cd axionvera-network
npm install
rustup target add wasm32-unknown-unknown

Build the contract:

npm run build:contracts

Testing

Contract tests:

cargo test -p axionvera-vault-contract

Project-level shortcuts:

npm run test:rust
npm test

Contributor Notes

• Start with the tests if you want executable examples of the contract behavior.
• Read storage docs before changing accounting logic.
• If you touch deposits, withdrawals, or rewards, verify both state changes and emitted events.

More Documentation

• docs/contract-spec.md
• docs/contract-storage.md
• docs/architecture.md
• ARCHITECTURE.md
• CONTRIBUTING.md

Dynamic Reward Engine

The contracts/rewards crate provides a deterministic reward simulation engine for adapting epoch rewards to protocol conditions before distribution. Operators provide a RewardFormula, aggregate ProtocolMetrics, participant metrics, and a requested reward pool. The engine:

1. Normalizes protocol activity against a target activity score.
2. Normalizes participation breadth against a target participant count.
3. Blends both signals with basis-point weights that must sum to 10,000.
4. Scales emissions between the formula's minimum and maximum emission rates.
5. Allocates the adjusted pool by each participant's stake + activity_score, assigning integer remainder to the final participant so allocations exactly conserve the adjusted pool.

The simulation tests in contracts/rewards/src/test.rs document low-activity, target-activity, deterministic replay, pool-conservation, and invalid-input edge cases.