Skip to content

Commit 9aa7e0a

Browse files
sasuke0787sasuke0787
authored
Merge pull request 0LNetworkCommunity#136 from codilion/migrate-v8
Re-join & Vouch guide
2 parents 5b0265c + 2edf4d7 commit 9aa7e0a

File tree

2 files changed

+206
-0
lines changed

2 files changed

+206
-0
lines changed

‎docs/guides/founder/migrate-to-v8.md‎

Lines changed: 199 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,199 @@
1+
---
2+
sidebar_label: "Re-join & Vouch (v8)"
3+
description: |
4+
A plain-language guide **for Founder accounts** – anyone who held 0L coins *before* the Level-8 upgrade.
5+
These steps implement the community-approved **FILO** (First-In-Last-Out) proposal ([read the rationale](https://docs.openlibra.io/blog/proposals/back-to-filo-the-future-of-open-libra)).
6+
Learn why you must run a small "re-join" action and receive a quick "vouch" from a friend, plus what to do if things go wrong.
7+
---
8+
9+
import Tabs from "@theme/Tabs";
10+
import TabItem from "@theme/TabItem";
11+
12+
# Re-join & Vouch – Getting Your 0L Account Moving Again (v8 Upgrade)
13+
14+
**For Founder accounts** – anyone who held 0L coins before the Level-8 upgrade
15+
16+
This guide implements the community-approved **FILO** (First-In-Last-Out) proposal ([read the rationale](https://docs.openlibra.io/blog/proposals/back-to-filo-the-future-of-open-libra)). Learn why you must run a "re-join" action and receive a "vouch" from a friend to reactivate your account.
17+
18+
19+
20+
## Prerequisites
21+
22+
### Install the CLI
23+
All steps require the **Open Libra command-line tool** v8.0+:
24+
25+
```bash
26+
libra --version # Must show version ≥ 8.0
27+
```
28+
29+
If not installed, follow → Install the Open Libra CLI from [source code](https://docs.openlibra.io/getting-started/install-open-libra-cli) or [binaries](https://docs.openlibra.io/getting-started/install-open-libra-cli/install-open-libra-cli-binaries)
30+
31+
### Verify You're a Founder
32+
```bash
33+
libra query view 0x1::founder::is_founder <your-address>
34+
```
35+
If this returns **true**, continue with this guide.
36+
37+
## Quick Start ⚡
38+
39+
1. **Re-join the network**
40+
```bash
41+
libra txs user re-join
42+
```
43+
44+
2. **Get vouched by a friend**
45+
Ask them to run:
46+
```bash
47+
libra txs user vouch --vouch-for <your-address>
48+
```
49+
50+
3. **Wait for next epoch** (~24 hours)
51+
Your coins will begin unlocking automatically
52+
53+
54+
## Understanding the Process
55+
56+
### What is FILO?
57+
58+
FILO (First-In-Last-Out) is the v8 migration strategy that:
59+
- **Resets** all founder accounts to ensure fair participation
60+
- **Restarts** the gradual coin unlock schedule
61+
- **Requires** social proof via vouching to prevent abuse
62+
63+
[Full FILO proposal details →](https://docs.openlibra.io/blog/proposals/back-to-filo-the-future-of-open-libra)
64+
65+
### Why These Steps?
66+
67+
| Step | Purpose | Technical Details |
68+
|------|---------|-------------------|
69+
| **Re-join** | Signals your return and migrates account to v8 format | Calls `filo_migration::maybe_migrate` which initializes Activity, Founder status, SlowWallet reset, Vouch structures, and PageRank |
70+
| **Vouch** | Provides social proof you're a real person | Creates on-chain attestation via `vouch::vouch_for`, expires after 45 epochs |
71+
72+
## Step-by-Step Instructions
73+
74+
### 1. Prepare Your Account
75+
76+
**Requirements:**
77+
- Your 24-word mnemonic phrase
78+
- Latest 0L CLI installed
79+
- Network connection
80+
81+
### 2. Execute Re-join
82+
83+
```bash
84+
libra txs user re-join
85+
```
86+
87+
**What happens:**
88+
- Updates your account to v8 data structures
89+
- Resets your slow wallet to 0 unlocked balance
90+
- Initializes vouch and trust systems
91+
- Returns a transaction hash on success
92+
93+
### 3. Obtain a Vouch
94+
95+
Share your address with any active 0L user and request:
96+
```bash
97+
libra txs user vouch --vouch-for <your-address>
98+
```
99+
100+
**Vouch rules:**
101+
- Any active user can vouch (once per day)
102+
- Vouches last 45 epochs (~45 days)
103+
- Required for sending transactions
104+
105+
### 4. Verify Success
106+
107+
```bash
108+
libra query view 0x1::reauthorization::is_v8_authorized <your-address>
109+
```
110+
Returns **true** when fully authorized.
111+
112+
113+
## Common Questions
114+
115+
### Do I need a vouch for coins to unlock?
116+
**No.** Unlocking begins automatically after re-join at the next epoch. Vouches are only required for *sending* transactions.
117+
118+
### Why are my coins locked after re-join?
119+
FILO resets your unlocked balance to 0. The first unlock happens at the next epoch boundary (~24h), regardless of vouch status.
120+
121+
### Can I re-join multiple times?
122+
**Yes.** The system safely ignores duplicate re-joins.
123+
124+
### What happens when my vouch expires?
125+
- Your balance continues unlocking normally
126+
- Outgoing transactions fail with `EU_NO_VOUCHER`
127+
- Simply request a new vouch to resume sending
128+
129+
### Can I vouch for myself?
130+
**No.** Self-vouching is blocked with error `EU_SELF_VOUCH`.
131+
132+
133+
## Troubleshooting
134+
135+
| Error | Cause | Solution |
136+
|-------|-------|----------|
137+
| `ENOT_MIGRATED_FROM_V7` | Haven't run re-join | Execute `libra txs user re-join` |
138+
| `EFOUNDER_HAS_NO_FRIENDS` | Founder without valid vouch | Get vouched by an active user |
139+
| `EU_NO_VOUCHER` | No valid vouch found | Request a vouch from a friend |
140+
| `EU_ACCOUNT_NOT_INITIALIZED` | Voucher hasn't migrated | Voucher must run re-join first |
141+
| `EU_SELF_VOUCH` | Attempted self-vouch | Ask someone else |
142+
| `EU_ALREADY_VOUCHED` | Duplicate vouch exists | Already vouched - no action needed |
143+
| `EU_VOUCH_LIMIT_EPOCH` | Voucher's daily limit reached | Wait 24h or find another voucher |
144+
| `EU_REVOKE_COOLDOWN` | Revoked too recently | Wait 3 epochs before new actions |
145+
| Balance shows `0 / X` unlocked | FILO reset | Wait one epoch for first unlock |
146+
| Lost mnemonic | No recovery possible | Mnemonic required - treat like hardware wallet seed |
147+
148+
149+
## Technical Deep Dive
150+
151+
<details>
152+
<summary>🔧 Advanced Implementation Details</summary>
153+
154+
### Core Functions
155+
156+
**Re-join Migration** (`filo_migration::maybe_migrate`):
157+
- `activity::migrate` - Marks account as v8 active
158+
- `founder::migrate` - Handles founder-specific setup
159+
- `slow_wallet::filo_migration_reset` - Resets unlock schedule to 0
160+
- `vouch::init` - Creates vouch data structures
161+
- `page_rank_lazy::maybe_initialize_trust_record` - Initializes trust scoring
162+
163+
**Authorization Check** (`reauthorization::assert_v8_authorized`):
164+
- Verifies migration status via `activity::is_initialized`
165+
- For founders: requires `founder::has_friends` (valid vouches)
166+
- For community wallets: requires donor authorization
167+
168+
**Vouch System** (`vouch` module):
169+
- Vouches stored in `ReceivedVouches` and `GivenVouches` resources
170+
- 45-epoch expiration via `EXPIRATION_ELAPSED_EPOCHS`
171+
- Automatic garbage collection of expired vouches
172+
- Anti-sybil protections via ancestry checks
173+
174+
### Validator-Specific Requirements
175+
176+
Validators need enhanced social proof:
177+
- Required vouches: `sqrt(validator_count) + 1`
178+
- Calculated by `proof_of_fee::calculate_min_vouches_required`
179+
- Blocks validator actions if threshold not met
180+
181+
### Module Interaction Flow
182+
183+
```
184+
User → re-join → filo_migration::maybe_migrate
185+
↓
186+
[Migrates 5 systems]
187+
↓
188+
User → get vouched → vouch::vouch_for
189+
↓
190+
[Creates vouch edge]
191+
↓
192+
Any transaction → reauthorization::assert_v8_authorized
193+
↓
194+
[Checks migration + vouches]
195+
```
196+
197+
</details>
198+
199+

‎sidebars.js‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -97,6 +97,13 @@ const sidebars = {
9797
'guides/community-wallet-ops/send-coins',
9898
],
9999
},
100+
{
101+
type: 'category',
102+
label: 'Founder',
103+
items: [
104+
'guides/founder/migrate-to-v8',
105+
],
106+
},
100107
{
101108
type: 'category',
102109
label: 'Integrations',

0 commit comments

Comments
 (0)