Skip to content

Commit 394b9f6

Browse files
ElliotFriendElliotFriend
committed
re-arrange content on the page. add a warning before anti-patterns
1 parent 53af14e commit 394b9f6

1 file changed

Lines changed: 129 additions & 120 deletions

File tree

‎docs/build/guides/storage/migrate-contract-storage.mdx‎

Lines changed: 129 additions & 120 deletions
Original file line numberDiff line numberDiff line change
@@ -4,73 +4,147 @@ hide_table_of_contents: true
44
description: Use the version marker pattern to safely read and migrate stored data when a contract upgrade changes a data structure
55
---
66

7-
When a contract is upgraded and a stored data structure gains new fields, the data already written to the ledger still uses the old layout. Naively reading those old entries with the new type causes the host to trap. This guide explains why that happens, introduces the version marker pattern as the correct solution, and covers lazy versus eager migration strategies and how to test them.
7+
When a contract is upgraded and a stored data structure gains new fields, the data already written to the ledger still uses the old layout. Naively reading those old entries with the new type causes the host to trap. This guide introduces the version marker pattern as the correct solution, covers lazy versus eager migration strategies and how to test them, and explains why the "intuitive" approach fails.
88

9-
## Why intuitive approaches fail
9+
## Versioned Enum Pattern
1010

1111
Suppose a contract stores `DataV1` entries and is upgraded to use `DataV2`, which adds an optional field `c`:
1212

1313
```rust
1414
#[contracttype]
15-
pub struct Data { a: i64, b: i64 }
15+
pub struct DataV1 { a: i64, b: i64 }
1616

1717
#[contracttype]
1818
pub struct DataV2 { a: i64, b: i64, c: Option<i64> }
1919
```
2020

21-
### Approach 1: Read old entries directly with the new type
21+
The recommended approach in this circumstance is to implement a versioned enum that can hold either a `V1` or `V2` data struct.
22+
23+
```rust
24+
#[contracttype]
25+
pub enum Data {
26+
V1(DataV1),
27+
V2(DataV2),
28+
}
29+
30+
#[contracttype]
31+
pub enum DataKey {
32+
Data(u64),
33+
}
34+
```
2235

23-
The most natural approach is to read the stored bytes directly as `DataV2` and expect `c` to default to `None`:
36+
### Migration Logic
37+
38+
The migration logic enumerates the two data formats and converts `V1` data to `V2` format, and passes `V2` format through. If it's already `V1`, it maps fields `a` and `b` over and sets the new `c` field to `None` (the field that was added in `V2`). If it's already `V2`, it passes through unchanged. This is a lazy migration - old data is upgraded on read, not in a bulk migration.
2439

2540
```rust
26-
// Reading a DataV1 entry with the DataV2 type.
27-
// A developer might expect c = None for old entries — but this traps.
28-
let data: DataV2 = env.storage().persistent().get(&key).unwrap();
29-
// Error(Object, UnexpectedSize)
41+
impl Data {
42+
pub fn into_v2(self) -> DataV2 {
43+
match self {
44+
Data::V1(v1) => DataV2 { a: v1.a, b: v1.b, c: None },
45+
Data::V2(v2) => v2,
46+
}
47+
}
48+
}
3049
```
3150

32-
This traps with `Error(Object, UnexpectedSize)`. The Soroban host validates the field count of the XDR-encoded value against the type definition before returning anything to the contract. Because `DataV1` has two fields and `DataV2` has three, the host rejects the entry before the SDK can handle it.
51+
### Reading with version awareness
3352

34-
### Approach 2: Use `try_from_val` as a fallback
53+
The value is read from storage and then `into_v2()` ensures that the returned value is in the `V2` format.
3554

36-
Another approach is to use `try_from_val` expecting to catch a deserialization error and recover:
55+
```rust
56+
pub fn read_data(e: Env, id: u32) -> Option<DataV2> {
57+
let data_enum: Data = e.storage().persistent().get(&DataKey::Data(id))?;
58+
Some(data_enum.into_v2())
59+
}
60+
```
61+
62+
### Writing always uses the current version
63+
64+
The write function `write_data()` takes a data argument in the `DataV2` format.
3765

3866
```rust
39-
let raw: Val = env.storage().persistent().get(&key).unwrap();
40-
if let Ok(v2) = DataV2::try_from_val(&env, &raw) {
41-
v2
42-
} else {
43-
// This branch is never reached — the host traps before returning Err.
44-
let v1 = DataV1::try_from_val(&env, &raw).unwrap();
45-
DataV2 { a: v1.a, b: v1.b, c: None }
67+
pub fn write_data(e: Env, id: u32, data: DataV2) {
68+
e.storage().persistent().set(&DataKey::Data(id), &Data::V2(data));
4669
}
4770
```
4871

49-
This also traps at the host level. The field count validation happens in the host environment during deserialization — it does not produce a Rust `Err` that the SDK can intercept. There is no way to catch or recover from the mismatch at the contract level.
72+
### Testing migrations
5073

51-
The root issue is that a contract cannot determine which type an existing storage entry was written as just by reading it. That information must be stored explicitly.
74+
Testing data migration requires simulating state written by an old contract version and verifying that the new contract reads it correctly.
75+
76+
In this test data in the `V1` format is first stored. Then it's read using the `read_data` function, which converts data in the `V1` format to V2 format with `into_v2()` before returning the result. The result is tested with `assert_eq!()`, and stored with the same `id` as it was stored with, which means the `V1` formatted data is overwritten with the same data in `V2` format.
77+
78+
Then the data is read from storage to verify it's stored in the `V2` format, and finally the data is read using the `read_data()` function to verify that the data is also returned in the `V2` format by the read function.
79+
80+
```rust
81+
#[test]
82+
fn test_write_upgrades_v1_entry_to_v2_1() {
83+
let env = Env::default();
84+
let id: u32 = 7;
85+
let contract_id = env.register(Contract, ());
86+
let client = ContractClient::new(&env, &contract_id);
87+
88+
// Inject a V1 entry directly, simulating legacy on-chain state.
89+
env.as_contract(&contract_id, || {
90+
env.storage()
91+
.persistent()
92+
.set(&DataKey::Data(id), &Data::V1(DataV1 { a: 5, b: 6 }));
93+
});
94+
95+
// Read it - into_v2() migrates lazily; c must be None.
96+
let migrated = client.read_data(&id).unwrap();
97+
assert_eq!(migrated.a, 5);
98+
assert_eq!(migrated.b, 6);
99+
assert_eq!(migrated.c, None);
100+
101+
// Write it back - write_data always stores Data::V2(...).
102+
client.write_data(&id, &migrated);
103+
104+
// Confirm the stored enum variant is now V2, not V1.
105+
let stored: Data = env.as_contract(&contract_id, || {
106+
env.storage().persistent().get(&DataKey::Data(id))
107+
})
108+
.unwrap();
109+
110+
match stored {
111+
Data::V2(v2) => {
112+
assert_eq!(v2.a, 5);
113+
assert_eq!(v2.b, 6);
114+
assert_eq!(v2.c, None);
115+
}
116+
Data::V1(_) => panic!("expected Data::V2 after write_data, found Data::V1"),
117+
}
118+
119+
// Subsequent reads go through the V2 branch and return identical values.
120+
let result = client.read_data(&id).unwrap();
121+
assert_eq!(result.a, 5);
122+
assert_eq!(result.b, 6);
123+
assert_eq!(result.c, None);
124+
}
125+
```
52126

53127
## Version Marker Pattern
54128

55-
The solution is to store a version number alongside each data entry, keyed by the same identifier. The contract reads the version first, then branches on the result to decode the payload with the correct type.
129+
An alternative solution is to store a version number alongside each data entry, keyed by the same identifier. The contract reads the version first, then branches on the result to decode the payload with the correct type.
56130

57131
### Key layout
58132

59-
Define two variants in your key enum — one for the version marker and one for the payload — both keyed by the same `id`:
133+
Define two variants in your key enum - one for the version marker and one for the payload - both keyed by the same `id`:
60134

61135
```rust
62136
#[contracttype]
63137
pub enum DataKey {
64-
DataVersion(u32), // version marker keyed by id
65-
Data(u32), // data keyed by id
138+
DataVersion(u32), // version marker, keyed by id
139+
Data(u32), // data, keyed by the same id
66140
}
67141
```
68142

69143
Each logical record occupies two storage slots. Because the version is stored per-record rather than globally, each entry is independently versioned. There is no all-or-nothing upgrade requirement.
70144

71145
### Reading with version awareness
72146

73-
Before decoding a storage entry, read its version marker. Use `unwrap_or(1)` to handle entries that were written before versioning was introduced — the absence of a version key is itself a signal that the entry is version 1:
147+
Before decoding a storage entry, read its version marker. Use `unwrap_or(1)` to handle entries that were written before versioning was introduced. The absence of a version key is itself a signal that the entry is version 1:
74148

75149
```rust
76150
fn read_data(env: &Env, id: u32) -> DataV2 {
@@ -105,7 +179,7 @@ Once version-aware read/write logic is in place, there are two strategies for co
105179

106180
#### Lazy migration (convert on read)
107181

108-
In lazy migration, old entries are left untouched on the ledger. When a record is read, its version is detected and it is up-converted in memory. When that record is later written back, it is stamped with the new version. No explicit migration step is needed — conversion happens as records are accessed in normal contract use.
182+
In lazy migration, old entries are left untouched on the ledger. When a record is read, its version is detected and it is up-converted in memory. When that record is later written back, it is stamped with the new version. No explicit migration step is needed - conversion happens as records are accessed in normal contract use.
109183

110184
Lazy migration is generally preferred on blockchains. Leaving old entries untouched has no upfront cost and no risk of hitting instruction or ledger-entry limits at upgrade time. Records that are never accessed again are never migrated, which is usually acceptable.
111185

@@ -133,7 +207,7 @@ pub fn migrate_all(env: &Env, ids: Vec<u32>) {
133207
}
134208
```
135209

136-
Eager migration is rarely practical for large datasets on Soroban. Each rewrite consumes fees and burns instructions, and a single transaction cannot migrate an unbounded number of records — the contract will hit instruction or ledger-entry limits. If the batch must span multiple transactions, the contract is in a mixed-version state throughout the window, which means version-aware read logic is still required anyway.
210+
Eager migration is rarely practical for large datasets on Soroban. Each rewrite consumes fees and burns instructions, and a single transaction cannot migrate an unbounded number of records - the contract will hit instruction or ledger-entry limits. If the batch must span multiple transactions, the contract is in a mixed-version state throughout the window, which means version-aware read logic is still required anyway.
137211

138212
Eager migration is occasionally appropriate when the total number of records is small and known in advance (for example, a fixed registry of a few dozen entries), or when you need to permanently drop old version branches from the read path.
139213

@@ -205,11 +279,11 @@ fn test_write_upgrades_v1_entry_to_v2() {
205279
env.storage().persistent().set(&DataKey::Data(id), &v1_data);
206280
});
207281

208-
// Read it — lazy migration produces a DataV2 in memory.
282+
// Read it - lazy migration produces a DataV2 in memory.
209283
let migrated = read_data(&env, id);
210284
assert_eq!(migrated.c, None);
211285

212-
// Write it back — this stamps the entry as version 2.
286+
// Write it back - this stamps the entry as version 2.
213287
write_data(&env, id, &migrated);
214288

215289
env.as_contract(&contract_id, || {
@@ -233,110 +307,45 @@ The three test cases cover the three states a record can be in after an upgrade:
233307
- A `DataV2` entry written by the new contract
234308
- A `DataV1` entry that is read and then written back (the lazy migration round-trip)
235309

236-
## Versioned Enum Pattern
237-
238-
Another approach is to implement a versioned enum that can hold either a `V1` or `V2` data struct.
239-
240-
```rust
241-
#[contracttype]
242-
pub enum Data {
243-
V1(DataV1),
244-
V2(DataV2),
245-
}
310+
## Why intuitive approaches fail
246311

247-
#[contracttype]
248-
pub enum DataKey {
249-
Data(u64),
250-
}
251-
```
312+
The techniques presented here may not immediately seem necessary. The "apparent" obvious solutions may be to programmatically handle the discrepancies in data types, rather than modify any of the underlying data structures, or adjust how the storage entries are read or written.
252313

253-
### Migration Logic
314+
:::warning
254315

255-
The migration logic enumerates the two data formats and converts `V1` data to `V2` format, and passes `V2` format through. If it's already `V1`, it maps fields `a` and `b` over and sets the new `c` field to `None` (the field that was added in `V2`). If it's already `V2`, it passes through unchanged. This is a lazy migration — old data is upgraded on read, not in a bulk migration.
316+
We've outlined a couple of the more "obvious" approaches to this problem, to illustrate _why_ these anti-patterns are not ideal. Please do not use the following code snippets as examples to be emulated. Rather, read the context of them, and learn why to avoid them.
256317

257-
```rust
258-
impl Data {
259-
pub fn into_v2(self) -> DataV2 {
260-
match self {
261-
Data::V1(v1) => DataV2 { a: v1.a, b: v1.b, c: None },
262-
Data::V2(v2) => v2,
263-
}
264-
}
265-
}
266-
```
318+
:::
267319

268-
### Reading with version awareness
320+
### Approach 1: Read old entries directly with the new type
269321

270-
The value is read from storage and then `into_v2()` ensures that the returned value is in the `V2` format.
322+
You may think the most natural approach is to read the stored bytes directly as `DataV2` and expect `c` to default to `None`:
271323

272324
```rust
273-
pub fn read_data(e: Env, id: u32) -> Option<DataV2> {
274-
let data_enum: Data = e.storage().persistent().get(&DataKey::Data(id))?;
275-
Some(data_enum.into_v2())
276-
}
325+
let key = DataKey::DataV2(1u32);
326+
// Reading a DataV1 entry with the DataV2 type.
327+
// A developer might expect c = None for old entries - but this traps.
328+
let data: DataV2 = env.storage().persistent().get(&key).unwrap();
329+
// Error(Object, UnexpectedSize)
277330
```
278331

279-
### Writing always uses the current version
332+
This traps with `Error(Object, UnexpectedSize)`. The Soroban host validates the field count of the XDR-encoded value against the type definition before returning anything to the contract. Because `DataV1` has two fields and `DataV2` has three, the host rejects the entry before the SDK can handle it.
280333

281-
The write function `write_data()` takes a data argument in the `DataV2` format.
334+
### Approach 2: Use `try_from_val` as a fallback
335+
336+
Another approach is to use `try_from_val` expecting to catch a deserialization error and recover:
282337

283338
```rust
284-
pub fn write_data(e: Env, id: u32, data: DataV2) {
285-
e.storage().persistent().set(&DataKey::Data(id), &Data::V2(data));
339+
let raw: Val = env.storage().persistent().get(&key).unwrap();
340+
if let Ok(v2) = DataV2::try_from_val(&env, &raw) {
341+
v2
342+
} else {
343+
// This branch is never reached - the host traps before returning Err.
344+
let v1 = DataV1::try_from_val(&env, &raw).unwrap();
345+
DataV2 { a: v1.a, b: v1.b, c: None }
286346
}
287347
```
288348

289-
### Testing migrations
349+
This also traps at the host level. The field count validation happens in the host environment during deserialization - it does not produce a Rust `Err` that the SDK can intercept. There is no way to catch or recover from the mismatch at the contract level.
290350

291-
Testing data migration requires simulating state written by an old contract version and verifying that the new contract reads it correctly.
292-
293-
In this test data in the `V1` format is first stored. Then it's read using the `read_data` function, which converts data in the `V1` format to V2 format with `into_v2()` before returning the result. The result is tested with `assert_eq!()`, and stored with the same `id` as it was stored with, which means the `V1` formatted data is overwritten with the same data in `V2` format.
294-
295-
Then the data is read from storage to verify it's stored in the `V2` format, and finally the data is read using the `read_data()` function to verify that the data is also returned in the `V2` format by the read function.
296-
297-
```rust
298-
#[test]
299-
fn test_write_upgrades_v1_entry_to_v2_1() {
300-
let env = Env::default();
301-
let id: u32 = 7;
302-
let contract_id = env.register(Contract, ());
303-
let client = ContractClient::new(&env, &contract_id);
304-
305-
// Inject a V1 entry directly, simulating legacy on-chain state.
306-
env.as_contract(&contract_id, || {
307-
env.storage()
308-
.persistent()
309-
.set(&DataKey::Data(id), &Data::V1(DataV1 { a: 5, b: 6 }));
310-
});
311-
312-
// Read it — into_v2() migrates lazily; c must be None.
313-
let migrated = client.read_data(&id).unwrap();
314-
assert_eq!(migrated.a, 5);
315-
assert_eq!(migrated.b, 6);
316-
assert_eq!(migrated.c, None);
317-
318-
// Write it back — write_data always stores Data::V2(...).
319-
client.write_data(&id, &migrated);
320-
321-
// Confirm the stored enum variant is now V2, not V1.
322-
let stored: Data = env.as_contract(&contract_id, || {
323-
env.storage().persistent().get(&DataKey::Data(id))
324-
})
325-
.unwrap();
326-
327-
match stored {
328-
Data::V2(v2) => {
329-
assert_eq!(v2.a, 5);
330-
assert_eq!(v2.b, 6);
331-
assert_eq!(v2.c, None);
332-
}
333-
Data::V1(_) => panic!("expected Data::V2 after write_data, found Data::V1"),
334-
}
335-
336-
// Subsequent reads go through the V2 branch and return identical values.
337-
let result = client.read_data(&id).unwrap();
338-
assert_eq!(result.a, 5);
339-
assert_eq!(result.b, 6);
340-
assert_eq!(result.c, None);
341-
}
342-
```
351+
The root issue is that a contract cannot determine which type an existing storage entry was written as just by reading it. That information must be stored explicitly.

0 commit comments

Comments
 (0)