# User Trading Guide

Complete guide for investors and traders to buy, hold, and earn yield from YRT tokens.

***

## Who Is This For?

* **Retail Investors** - Looking to invest in property yield with small capital
* **Traders** - Looking to profit from YRT price movements
* **Yield Seekers** - Looking for passive income from property cash flows

***

## Quick Start (4 Steps)

{% @mermaid/diagram content="graph LR
Step1\[1. Setup Wallet] --> Step2\[2. Get Test Tokens]
Step2 --> Step3\[3. Browse Properties]
Step3 --> Step4\[4. Buy YRT]
Step4 --> Step5\[5. Receive Yield]" %}

***

## Step 1: Get Test Tokens

### 1a. Get Base Sepolia ETH (For Gas)

**Faucet:** <https://www.coinbase.com/faucets/base-ethereum-sepolia-faucet>

1. Connect your Coinbase Wallet
2. Click "Send me ETH"
3. Receive 0.05 ETH (\~$100 worth on testnet)
4. Wait 30 seconds for confirmation

**Check balance:**

```
Open wallet → Should see "0.05 ETH"
```

### 1b. Get MockUSDC (To Buy YRT)

**Contract Address:** `0x70667aea00Fc7f087D6bFFB9De3eD95Af37140a4`

**Method 1: Via Owna Finance dApp (Recommended)**

1. Visit Owna Finance dApp
2. Connect wallet
3. Click "Get Test USDC" button
4. Approve transaction
5. Receive 1000 USDC

**Method 2: Direct Contract Call**

```typescript
// Using ethers.js
import { ethers } from "ethers";

const USDC_ADDRESS = "0x70667aea00Fc7f087D6bFFB9De3eD95Af37140a4";
const USDC_ABI = [
    "function faucet() external",
    "function balanceOf(address) view returns (uint256)"
];

const usdc = new ethers.Contract(USDC_ADDRESS, USDC_ABI, signer);

// Get 1000 USDC
await usdc.faucet();

// Check balance
const balance = await usdc.balanceOf(userAddress);
console.log(`USDC Balance: ${ethers.utils.formatUnits(balance, 18)}`);
```

**Note:** MockUSDC has 18 decimals (real USDC has 6 decimals on mainnet).

***

## Step 2: Browse Properties

### View Available Properties

**On Owna Finance dApp:**

1. Visit <https://owna.finance> (or testnet URL)
2. Click "Explore Properties"
3. See property cards:

```
┌─────────────────────────────────────┐
│  Green Valley Apartment             │
│  Jakarta, Indonesia                 │
│                                     │
│  Current Price: 1.25 USDC/YRT      │
│  TVL: $125,000                      │
│  Period: Q1 2024                    │
│  Maturity: Mar 31, 2024             │
│  Historical Yield: 10% APY          │
│                                     │
│  [ View Details ] [ Trade Now ]     │
└─────────────────────────────────────┘
```

### Property Details Page

Click "View Details" to see:

* **Property Information**
  * Address, type, size
  * Rental income history
  * Occupancy rate
  * Property images
* **Token Information**
  * YRT token address
  * Total supply
  * Current holders
  * Your balance
* **Current Period**
  * Period number (e.g., Q1)
  * Start date
  * Maturity date
  * Days remaining
  * Yield deposited
* **Price Chart**
  * 24h, 7d, 30d, All time
  * Volume
  * Number of trades
* **Distribution History**
  * Past period yields
  * Your historical earnings
  * Average APY

***

## Step 3: Buy YRT Tokens

### Understanding the Trade

**You are buying:**

* YRT tokens representing ownership share in property cash flow
* Right to receive proportional yield at maturity

**Price determination:**

* Set by AMM (Automated Market Maker)
* Changes based on supply/demand
* More buyers = price goes up
* More sellers = price goes down

### Calculate Expected Output

**Before buying, check how much YRT you'll receive:**

```typescript
import { ethers } from "ethers";

const ROUTER_ADDRESS = "0xE5b501b4d2CCD234FcD94906C561B8d5B1e4cEb7";
const ROUTER_ABI = [...]; // Import from @/abis/OwnaRouter.json

const router = new ethers.Contract(ROUTER_ADDRESS, ROUTER_ABI, provider);

// Calculate output for 100 USDC input
const amountsOut = await router.getAmountsOut(
    ethers.utils.parseUnits("100", 18), // 100 USDC
    [USDC_ADDRESS, YRT_ADDRESS]
);

const expectedYRT = ethers.utils.formatUnits(amountsOut[1], 18);
console.log(`100 USDC → ${expectedYRT} YRT`);

// Calculate effective price
const effectivePrice = 100 / parseFloat(expectedYRT);
console.log(`Effective price: ${effectivePrice.toFixed(4)} USDC/YRT`);
```

### Set Slippage Tolerance

Slippage protects you from price changes during transaction:

```
Low Slippage (0.1-0.5%): Safe but may fail if price moves
Medium Slippage (0.5-1%): Balanced
High Slippage (1-5%): More likely to succeed but worse price
```

**Calculate minimum output:**

```typescript
const slippageTolerance = 0.01; // 1%
const minYRTOut = expectedYRT * (1 - slippageTolerance);

console.log(`Min output with 1% slippage: ${minYRTOut} YRT`);
```

### Execute Buy Transaction

**Step-by-step:**

1. **Approve USDC spending**

   ```typescript
   const usdc = new ethers.Contract(USDC_ADDRESS, ERC20_ABI, signer);

   // Approve router to spend USDC
   const approveTx = await usdc.approve(
       ROUTER_ADDRESS,
       ethers.utils.parseUnits("100", 18) // Amount to spend
   );
   await approveTx.wait();
   console.log("USDC approved ✅");
   ```
2. **Execute swap**

   ```typescript
   const router = new ethers.Contract(ROUTER_ADDRESS, ROUTER_ABI, signer);

   const deadline = Math.floor(Date.now() / 1000) + 60 * 20; // 20 minutes

   const swapTx = await router.swapExactTokensForTokens(
       ethers.utils.parseUnits("100", 18), // Input: 100 USDC
       ethers.utils.parseUnits(minYRTOut.toString(), 18), // Min output
       [USDC_ADDRESS, YRT_ADDRESS], // Path
       userAddress, // Recipient
       deadline // Deadline
   );

   const receipt = await swapTx.wait();
   console.log("Swap successful ✅");
   console.log(`Tx hash: ${receipt.transactionHash}`);
   ```
3. **Check YRT balance**

   ```typescript
   const yrt = new ethers.Contract(YRT_ADDRESS, ERC20_ABI, provider);
   const balance = await yrt.balanceOf(userAddress);
   console.log(`YRT Balance: ${ethers.utils.formatUnits(balance, 18)}`);
   ```

**On dApp UI:**

1. Click "Trade Now" on property card
2. Enter amount: "100 USDC"
3. Review: "You'll receive \~90.5 YRT"
4. Set slippage: "1%"
5. Click "Swap"
6. Approve in wallet popup
7. Wait for confirmation
8. Success! You now own YRT 🎉

***

## Step 4: Hold & Earn Yield

### No Action Required!

**You don't need to:**

* ❌ Stake tokens
* ❌ Lock tokens
* ❌ Claim manually
* ❌ Check every day

**Automatic process:**

1. **Hold YRT** - Keep tokens in your wallet
2. **Wait for maturity** - Property generates yield
3. **Snapshot happens** - Chainlink records your balance automatically
4. **Yield distributed** - USDC appears in wallet automatically

### Track Your Position

**Check on dApp:**

```
┌─────────────────────────────────────┐
│  Your Position                      │
│                                     │
│  Property: Green Valley Apartment   │
│  Your YRT: 90.5 tokens              │
│  Your Share: 9.05%                  │
│                                     │
│  Current Period: Q1 2024            │
│  Days to Maturity: 15 days          │
│  Expected Yield: ~905 USDC (est)    │
│                                     │
│  Snapshot Status: Not taken yet     │
│                                     │
│  [ Sell ] [ Add More ]              │
└─────────────────────────────────────┘
```

### Understanding Yield Calculation

**Formula:**

```
Your Yield = (Your Balance / Total Supply) × Total Yield

Example:
- You hold: 90.5 YRT
- Total supply at snapshot: 1000 YRT
- Your share: 9.05%
- Total yield deposited: 10,000 USDC
- Your yield: 0.0905 × 10,000 = 905 USDC
```

**Check expected yield:**

```typescript
const claimable = await factory.calculateClaimableYield(
    seriesId,
    periodId,
    userAddress
);

console.log(`Expected yield: ${ethers.utils.formatUnits(claimable, 18)} USDC`);
```

### Snapshot Timeline

**Before Snapshot:**

* You can buy/sell freely
* Price fluctuates based on trading
* No yield calculations yet

**At Maturity (Snapshot Time):**

* Chainlink automatically triggers snapshot
* Your balance is recorded (e.g., 90.5 YRT)
* **This frozen balance determines your yield!**

**After Snapshot:**

* You can still sell YRT
* **You still receive yield** even if you sell! ✅
* Yield calculated from snapshot balance

### Receive Yield

**Automatic Delivery:**

```
Timeline:
1. Maturity date reached
2. Chainlink triggers snapshot 📸
3. Property owner deposits yield
4. AutoDistributor sends USDC to all holders
5. ✅ USDC appears in your wallet!

No claim transaction needed!
```

**Check USDC balance:**

```typescript
const usdc = new ethers.Contract(USDC_ADDRESS, ERC20_ABI, provider);
const balance = await usdc.balanceOf(userAddress);
console.log(`USDC Balance: ${ethers.utils.formatUnits(balance, 18)}`);
```

**On wallet:**

```
Before: 50 USDC
After distribution: 955 USDC (50 + 905 yield)
```

***

## Advanced Trading Strategies

### Strategy 1: Buy & Hold (Recommended for Beginners)

**Approach:**

1. Research property fundamentals
2. Buy YRT for long-term hold
3. Hold through maturity
4. Collect yield automatically
5. Decide whether to hold for next period or sell

**Pros:**

* ✅ Predictable returns
* ✅ No active management
* ✅ Guaranteed yield (if held through snapshot)

**Cons:**

* ❌ Capital locked until you sell
* ❌ Price may decrease

**Best for:** Investors seeking passive income

### Strategy 2: Swing Trading

**Approach:**

1. Buy when price is low
2. Sell when price rises
3. Profit from price movements

**Example:**

```
Day 1: Buy 100 YRT at 1.0 USDC = 100 USDC
Day 30: Price rises to 1.3 USDC
Day 30: Sell 100 YRT = 130 USDC
Profit: 30 USDC (30%)
```

**Pros:**

* ✅ Can profit before maturity
* ✅ Flexible exit

**Cons:**

* ❌ May miss yield distribution
* ❌ Price may go down instead
* ❌ More gas costs

**Best for:** Active traders with market knowledge

### Strategy 3: Post-Snapshot Selling

**Approach:**

1. Buy before snapshot
2. Hold through snapshot
3. Sell immediately after snapshot
4. Receive yield later

**Example:**

```
Day 85: Buy 100 YRT at 1.0 USDC = 100 USDC
Day 90: Snapshot taken (you have 100 YRT)
Day 91: Sell 100 YRT at 1.1 USDC = 110 USDC
Day 92: Receive 10 USDC yield automatically

Total: 110 + 10 = 120 USDC
Profit: 20 USDC (20%)
```

**Pros:**

* ✅ Get yield AND sell early
* ✅ Unlock capital faster

**Cons:**

* ❌ Risk if price drops after snapshot
* ❌ Miss next period's yield

**Best for:** Traders wanting yield + liquidity

***

## Risk Management

### Diversification

Don't put all capital in one property:

```
Portfolio Example ($1000):
- Property A (Green Valley): $300 (30%)
- Property B (Villa Bali): $300 (30%)
- Property C (Sudirman): $200 (20%)
- USDC Reserve: $200 (20%)
```

### Position Sizing

Rule of thumb:

```
Conservative: 10-20% of portfolio per property
Moderate: 20-40% per property
Aggressive: 40-60% per property
```

### Stop Loss

Set mental stop loss:

```
Example:
- Buy at: 1.0 USDC/YRT
- Stop loss: 0.9 USDC/YRT (-10%)
- If price drops to 0.9, sell to prevent further loss
```

***

## Common Scenarios

### Scenario 1: Hold Through Multiple Periods

```
Q1 2024:
- Buy: 100 YRT
- Snapshot: Hold 100 YRT
- Yield: Receive 1,000 USDC

Q2 2024:
- Still hold: 100 YRT
- Snapshot: Hold 100 YRT
- Yield: Receive 1,200 USDC

Q3 2024:
- Still hold: 100 YRT
- Snapshot: Hold 100 YRT
- Yield: Receive 1,100 USDC

Total yield over 3 quarters: 3,300 USDC
```

### Scenario 2: Sell After Snapshot

```
Q1 Timeline:
Day 1: Buy 100 YRT at 1.0 USDC (cost: 100 USDC)
Day 90: Snapshot (balance: 100 YRT) ← Yield locked
Day 91: Sell 100 YRT at 1.1 USDC (receive: 110 USDC)
Day 92: Receive 1,000 USDC yield automatically

Outcome:
- Sold tokens: +110 USDC
- Yield received: +1,000 USDC
- Total: 1,110 USDC
- Profit: 1,010 USDC (10.1x)
```

### Scenario 3: Buy After Snapshot

```
Q1 Timeline:
Day 90: Snapshot taken (you don't hold any)
Day 91: Buy 100 YRT at 0.95 USDC (cost: 95 USDC)
Day 92: Distribution happens (you receive: 0 USDC) ← Expected!

Q2 Timeline:
Day 180: Snapshot taken (you hold 100 YRT)
Day 181: Receive Q2 yield: 1,200 USDC ✅

Lesson: Buying after snapshot means waiting for next period yield.
```

***

## Troubleshooting

### "Transaction Failed: Insufficient Output Amount"

**Cause:** Price moved unfavorably, output below `amountOutMin`.

**Solution:**

1. Increase slippage tolerance (1% → 2%)
2. Reduce trade size
3. Try again

### "Transaction Failed: K"

**Cause:** AMM constant product formula validation failed.

**Solution:**

* This is extremely rare, indicates pool manipulation
* Wait a few blocks and retry

### "Yield Not Received"

**Checks:**

1. **Was snapshot taken?**

   ```typescript
   const taken = await token.isSnapshotTakenForPeriod(periodId);
   console.log(`Snapshot taken: ${taken}`);
   ```
2. **Did you hold at snapshot time?**

   ```typescript
   const balance = await token.getSnapshotBalanceForPeriod(periodId, userAddress);
   console.log(`Your snapshot balance: ${balance}`);
   ```
3. **Was yield deposited?**

   ```typescript
   const periodInfo = await factory.periodInfo(seriesId, periodId);
   console.log(`Total yield: ${periodInfo.totalYield}`);
   ```
4. **Was distribution executed?**
   * Check AutoDistributor events
   * Ask in Discord/Telegram

### "Can't Sell Tokens"

**Possible causes:**

1. **Insufficient balance** - Check YRT balance
2. **Not approved** - Approve router first
3. **Slippage too low** - Increase slippage
4. **Insufficient liquidity** - Check pool reserves

***

## Related Documentation

* [Quick Start Guide](https://owna-finance.gitbook.io/owna-finance-docs/how-owna-finance-works/getting-started) - General overview
* [AMM Pricing Formula](https://owna-finance.gitbook.io/owna-finance-docs/advanced-topics/amm-pricing) - How pricing works
* [Snapshot System](https://owna-finance.gitbook.io/owna-finance-docs/advanced-topics/snapshots) - How yield distribution works
* [FAQ](https://owna-finance.gitbook.io/owna-finance-docs/resources/faq) - Common questions
* [Glossary](https://owna-finance.gitbook.io/owna-finance-docs/resources/glossary) - Term definitions

***

**Happy Trading! 📈💰**

**Need Help?**

* Read [FAQ](https://owna-finance.gitbook.io/owna-finance-docs/resources/faq)
* Ask in Discord (link in docs)
* Check [Glossary](https://owna-finance.gitbook.io/owna-finance-docs/resources/glossary) for terms

***

**Last Updated:** January 2025
