Skip to content

user_docs.md

Latest commit

 

History

History
209 lines (138 loc) · 7.63 KB

user_docs.md

File metadata and controls

209 lines (138 loc) · 7.63 KB
Raw

Token Staking: User Guide

What is Token Staking?

Token Staking is a decentralized application (dApp) that allows you to "stake" your tokens to help secure the network and earn rewards. Think of staking like putting your money in a savings account - you lock up your tokens for a period of time and get rewarded for doing so.

Why Should You Stake?

Benefits of Staking

  • Earn Rewards: Get additional tokens as rewards for staking
  • Support the Network: Help secure and maintain the token ecosystem
  • Flexible Terms: Choose your own lock-up periods based on your preferences
  • Compound Growth: Stake your rewards to earn even more

How It's Different from Traditional Banking

  • Decentralized: No banks or middlemen - everything runs on smart contracts
  • Transparent: All transactions are visible on the blockchain
  • You Stay in Control: You always own your tokens, even when staked
  • Programmable: Automated systems handle rewards and unlocking

How Does Staking Work?

The Basic Process

  1. Approve Tokens: Give permission for the staking contract to use your staking tokens
  2. Choose Lock Period: Decide how long you want to lock your tokens (can be zero for no lock)
  3. Stake Your Tokens: Send your tokens to the staking contract
  4. Wait: Your tokens are locked for the chosen period
  5. Unstake: After the lock period ends, withdraw your tokens back to your wallet

Time Locks Explained

When you stake, you can choose a "time lock" - this is how long your tokens will be locked up (in days):

  • No Lock (0 days): You can unstake anytime, but may earn fewer rewards
  • Short Lock (30 days): You'll get some extra rewards
  • Long Lock (90 days): Long locks could be rewarded even greatly

Important: Once you stake with a time lock, you cannot get your tokens back until that time period ends.

Project Architecture

How the System is Built

Our staking system uses a modular design with two main smart contracts working together:

StakingVault (The Main Interface)

This is where you interact with the system. It handles:

  • Receiving your stake requests
  • Managing token transfers (moving tokens in and out)
  • Enforcing time locks (making sure you can't unstake too early)
  • Security controls (pausing system if needed)

Think of this as the "front desk" - it's what you interact with directly.

StakingStorage (The Record Keeper)

This contract keeps track of everything behind the scenes:

  • Recording all stakes with unique IDs
  • Tracking total amounts for each user and globally
  • Historical data showing how staking amounts changed over time
  • Managing stake lifecycle (creation, tracking, deletion)

Think of this as the "database" - it remembers everything that happens.

Why Two Contracts?

We separated these functions because:

  • Security: If one part has issues, the other is protected
  • Efficiency: Each contract focuses on what it does best
  • Upgradeability: We can improve parts of the system independently
  • Gas Optimization: More efficient transaction costs

Key Features

Individual Stake Tracking

  • Each stake gets a unique ID number
  • You can have multiple stakes with different time locks
  • View all your active stakes anytime
  • Unstake individual stakes when they mature

Historical Data

  • System tracks staking amounts over time
  • Useful for calculating time-based rewards
  • Helps with governance and analytics
  • Provides transparency about network growth

Batch Operations

  • Unstake multiple stakes in one transaction
  • Administrators can help with bulk operations
  • Saves on transaction fees
  • More convenient for power users

Integration Ready

  • Works with external claiming systems
  • Can stake directly from token distribution events
  • Supports automated staking workflows
  • Built for ecosystem integration

Security & Safety

Multiple Protection Layers

  1. Role-Based Access: Different permission levels for different operations
  2. Time Lock Enforcement: Cannot unstake before the chosen time period
  3. Pause Mechanism: System can be paused in emergencies
  4. Reentrancy Protection: Prevents certain types of attacks
  5. Audited Code: Uses well-tested OpenZeppelin libraries

Your Tokens Are Safe

  • You Always Own Them: Tokens are held in secure smart contracts, not controlled by any person
  • Transparent Operations: All code is open source and verifiable
  • Emergency Controls: System can be paused if any issues are discovered
  • Battle-Tested Libraries: Built using proven, audited code components

Getting Started

What You Need

  1. Staking Tokens: The tokens you want to stake
  2. Crypto Wallet: Like MetaMask, to interact with the blockchain
  3. Small Amount of ETH: To pay for transaction fees (gas)
  4. Basic Understanding: Of how long you want to lock your tokens

Step-by-Step Process

  1. Connect Your Wallet to the staking interface
  2. Check Your Balance to see how many staking tokens you have
  3. Approve Tokens by confirming a transaction that lets the contract use your tokens
  4. Choose Stake Amount - how many tokens you want to stake
  5. Select Time Lock - how long you want to lock them (or choose no lock)
  6. Confirm Transaction and pay the gas fee
  7. Wait for Confirmation - usually takes a few minutes
  8. Track Your Stakes using your stake IDs

When You Want to Unstake

  1. Check If Matured - make sure your time lock period has passed
  2. Call Unstake Function with your stake ID
  3. Confirm Transaction and pay gas fee
  4. Receive Your Tokens back in your wallet

Important Things to Remember

Before You Stake

  • Only stake what you can afford to lock up for the chosen time period
  • Understand time locks - you cannot get tokens back early
  • Have some ETH for transaction fees
  • Start small while you learn how the system works

Managing Your Stakes

  • Keep track of stake IDs - you'll need them to unstake
  • Remember your time locks - mark your calendar for when you can unstake
  • Monitor the system for any announcements or updates
  • Consider your needs - don't lock up tokens you might need soon

Best Practices

  • Diversify time locks - don't put everything in one long lock
  • Stay informed about the project and any changes
  • Understand the risks - all DeFi involves some risk
  • Ask questions in community channels if you're unsure

Common Questions

Can I lose my staked tokens?

Your tokens are held in secure smart contracts and should be safe, but like all blockchain applications, there are inherent risks. The contracts are audited and use proven security practices.

What if I need my tokens before the lock period ends?

You cannot unstake before your chosen time lock expires. This is enforced by the smart contract and cannot be overridden.

How do I know when I can unstake?

You can check the status of your stakes using the viewing functions. The system will tell you when each stake matures.

What happens if the system is paused?

If paused, you cannot stake or unstake until it's unpaused. This is an emergency safety feature.

Can I stake more tokens to an existing stake?

No, each stake is separate. You would create a new stake with additional tokens.

Getting Help

If you need assistance:

  • Read this documentation thoroughly
  • Check the project's official community channels
  • Look for tutorial videos or guides
  • Ask experienced community members
  • Contact the development team through official channels

Remember: Never share your private keys or seed phrases with anyone, and always verify you're using the official staking interface.