Skip to content

README.md

Latest commit

 

History

History
150 lines (105 loc) · 4.58 KB

README.md

File metadata and controls

150 lines (105 loc) · 4.58 KB

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:

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

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