# Wasm\_memory\_persistence backwards compatibility

**URL:** <https://forum.dfinity.org/t/wasm-memory-persistence-backwards-compatibility/33816>\
**Category:** Developers\
**Created:** [August 2, 2024, 11:51am UTC](https://forum.dfinity.org/t/wasm-memory-persistence-backwards-compatibility/33816 "2024-08-02T11:51:41Z")\
**Posts on this page:** 12\
**Page:** 1

<div class="post-metadata">

**Author:** ![peterparker](https://avatars.discourse-cdn.com/v4/letter/p/b9bd4f/32.png) [@peterparker](https://forum.dfinity.org/u/peterparker)\
**Post date:** [August 2, 2024, 11:51am UTC](https://forum.dfinity.org/t/wasm-memory-persistence-backwards-compatibility/33816/1 "2024-08-02T11:51:41Z")

</div>

Updating the IC types in TypeScript leads to having to resolve a breaking change given that `wasm_memory_persistence` is a mandatory optional types.

I found an entry about it in this [CHANGELOG](https://github.com/dfinity/interface-spec/blob/2b479115c064b82f551815aac000dfd33d2beb2d/spec/_attachments/interface-spec-changelog.md?plain=1#L9) and a brief explanation in the [documentation](https://internetcomputer.org/docs/current/references/ic-interface-spec/#system-api-upgrades) but, nowhere it is explained how to migrate - i.e. what’s the backwards compatibility value to use?

```auto
// Mode used to be typed as
mode: {reinstall: null} | {upgrade: [] | [{skip_pre_upgrade: [] | [boolean]}]} | {install: null};

// New type
mode: {reinstall: null}
  | {
      upgrade:
        | []
        | [
            {
              wasm_memory_persistence: [] | [{keep: null} | {replace: null}];
              skip_pre_upgrade: [] | [boolean];
            }
          ];
    }
  | {install: null};

// So given the following
mode: {upgrade: [{skip_pre_upgrade: [false]}]}

// What should be the backwards compatible parameter?
mode: {upgrade: [{skip_pre_upgrade: [false], wasm_memory_persistence: [????????????]}]}

```

Side note: `wasm_memory_persistence` relates to what is commonly referred as “heap” memory?

---

<div class="post-metadata">

**Author:** ![mraszyk](https://sea1.discourse-cdn.com/flex023/user_avatar/forum.dfinity.org/mraszyk/32/7945_2.png) [@mraszyk](https://forum.dfinity.org/u/mraszyk)\
**Post date:** [August 23, 2024, 9:15am UTC](https://forum.dfinity.org/t/wasm-memory-persistence-backwards-compatibility/33816/2 "2024-08-23T09:15:21Z")

</div>

I’d recommend you to use `wasm_memory_persistence: [] ` assuming this corresponds to `wasm_memory_persistence` being set to `null`.

> `wasm_memory_persistence` relates to what is commonly referred as “heap” memory

indeed

---

<div class="post-metadata">

**Author:** ![peterparker](https://avatars.discourse-cdn.com/v4/letter/p/b9bd4f/32.png) [@peterparker](https://forum.dfinity.org/u/peterparker)\
**Post date:** [August 23, 2024, 9:31am UTC](https://forum.dfinity.org/t/wasm-memory-persistence-backwards-compatibility/33816/3 "2024-08-23T09:31:02Z")

</div>

> [@mraszyk](#):
>
> I’d recommend you to use `wasm_memory_persistence: []`

Thanks. So `[]` equals `keep` or `replace`? I assumed `keep` but, never too sure.

---

<div class="post-metadata">

**Author:** ![mraszyk](https://sea1.discourse-cdn.com/flex023/user_avatar/forum.dfinity.org/mraszyk/32/7945_2.png) [@mraszyk](https://forum.dfinity.org/u/mraszyk)\
**Post date:** [August 23, 2024, 9:42am UTC](https://forum.dfinity.org/t/wasm-memory-persistence-backwards-compatibility/33816/4 "2024-08-23T09:42:48Z")

</div>

`[]` corresponds to `replace` which is the behavior you’d get before the persistence feature was introduced (the heap memory would be reset as the canister would by default not be able to make sense of the old heap memory, e.g., created by code compiled by a different version of the compiler)

---

<div class="post-metadata">

**Author:** ![peterparker](https://avatars.discourse-cdn.com/v4/letter/p/b9bd4f/32.png) [@peterparker](https://forum.dfinity.org/u/peterparker)\
**Post date:** [August 23, 2024, 10:36am UTC](https://forum.dfinity.org/t/wasm-memory-persistence-backwards-compatibility/33816/5 "2024-08-23T10:36:56Z")

</div>

I’m a bit confused now. If I understand correctly, the default behavior remains the same, the heap memory is wiped during a canister upgrade. This corresponds to the `[replace]` or `[]` option.

If the above is correct, what’s the use case for the `keep` option? Is it the opposite, where the heap memory is preserved? Is there an explanation somewhere that details when to use each behavior (I mean in practice, in real life)? Also, is there a sample repository available assuming pre and post upgrade should be coded differently?

---

<div class="post-metadata">

**Author:** ![mraszyk](https://sea1.discourse-cdn.com/flex023/user_avatar/forum.dfinity.org/mraszyk/32/7945_2.png) [@mraszyk](https://forum.dfinity.org/u/mraszyk)\
**Post date:** [August 23, 2024, 10:53am UTC](https://forum.dfinity.org/t/wasm-memory-persistence-backwards-compatibility/33816/6 "2024-08-23T10:53:17Z")

</div>

> If the above is correct, what’s the use case for the `keep` option? Is it the opposite, where the heap memory is preserved?

The main use case is Motoko orthogonal persistence which wants to reuse the heap memory of the old canister after a canister upgrade and thus the heap memory must be preserved across the upgrade.

> Is there an explanation somewhere that details when to use each behavior (I mean in practice, in real life)?

You should use this for Motoko canisters which expose a custom section with the name `enhanced-orthogonal-persistence`. Note that the execution environment [checks](https://github.com/dfinity/ic/blob/160eeef7dd69b603d89c91f410d8f2ba5cba5a76/rs/execution_environment/src/execution/upgrade.rs#L879) for that, too.

> Also, is there a sample repository available assuming pre and post upgrade should be coded differently?

It isn’t just about a pre- and post-upgrade. It requires careful support from the language runtime which is what the Motoko orthogonal persistence feature is about.

---

<div class="post-metadata">

**Author:** ![peterparker](https://avatars.discourse-cdn.com/v4/letter/p/b9bd4f/32.png) [@peterparker](https://forum.dfinity.org/u/peterparker)\
**Post date:** [August 23, 2024, 10:58am UTC](https://forum.dfinity.org/t/wasm-memory-persistence-backwards-compatibility/33816/7 "2024-08-23T10:58:57Z")

</div>

Thanks for the details. I think I’ve got it now. It would be helpful to include this type of information in the CHANGELOG.

As for me, to maintain backwards compatibility and answer the main question of the thread, I’ll migrate to `wasm_memory_persistence: [{replace: null}]`.

---

<div class="post-metadata">

**Author:** ![mraszyk](https://sea1.discourse-cdn.com/flex023/user_avatar/forum.dfinity.org/mraszyk/32/7945_2.png) [@mraszyk](https://forum.dfinity.org/u/mraszyk)\
**Post date:** [August 23, 2024, 2:12pm UTC](https://forum.dfinity.org/t/wasm-memory-persistence-backwards-compatibility/33816/8 "2024-08-23T14:12:55Z")

</div>

> [@peterparker](#):
>
> wasm\_memory\_persistence: [{replace: null}]

Could you please check with the Motoko team what implications this would have for Motoko orthogonal persistence. @luc-blaeser

---

<div class="post-metadata">

**Author:** ![mraszyk](https://sea1.discourse-cdn.com/flex023/user_avatar/forum.dfinity.org/mraszyk/32/7945_2.png) [@mraszyk](https://forum.dfinity.org/u/mraszyk)\
**Post date:** [August 23, 2024, 2:14pm UTC](https://forum.dfinity.org/t/wasm-memory-persistence-backwards-compatibility/33816/9 "2024-08-23T14:14:38Z")

</div>

> [@peterparker](#):
>
> It would be helpful to include this type of information in the CHANGELOG.

Please feel free the open a PR with your suggested changes.

---

<div class="post-metadata">

**Author:** ![peterparker](https://avatars.discourse-cdn.com/v4/letter/p/b9bd4f/32.png) [@peterparker](https://forum.dfinity.org/u/peterparker)\
**Post date:** [August 23, 2024, 2:25pm UTC](https://forum.dfinity.org/t/wasm-memory-persistence-backwards-compatibility/33816/10 "2024-08-23T14:25:04Z")

</div>

> [@mraszyk](#):
>
> Please feel free the open a PR with your suggested changes.

A suggestion for the future CHANGELOGs.

---

<div class="post-metadata">

**Author:** ![luc-blaeser](https://sea1.discourse-cdn.com/flex023/user_avatar/forum.dfinity.org/luc-blaeser/32/7410_2.png) [@luc-blaeser](https://forum.dfinity.org/u/luc-blaeser)\
**Post date:** [August 23, 2024, 2:51pm UTC](https://forum.dfinity.org/t/wasm-memory-persistence-backwards-compatibility/33816/11 "2024-08-23T14:51:07Z")

</div>

Thanks for reaching out, @peterparker

`wasm_memory_persistence` is indeed a Motoko-specific feature, that is used by enhanced orthogonal persistence. More information can be found here: [Enhanced Orthogonal Persistence (Complete Integration) by luc-blaeser · Pull Request #4488 · dfinity/motoko · GitHub](https://github.com/dfinity/motoko/pull/4488)  
We plan to beta-release it soon, but still need to wait for some support of other components, e.g. `dfx`.

I strongly recommend to use `wasm_memory_persistence: []` which is the default behavior. As mentioned, this is dropping Wasm main memory (including the heap). This setting makes sense for all non-Motoko canisters.  
For Motoko, the IC checks whether the `keep` is accidentally missing with that configuration, so reminds you to use `keep` when needed.

However, if you specify `wasm_memory_persistence: [{replace: null}]` you will lose the persistent data of future Motoko canisters, as it forces to erase main memory which is the new place where Motoko keeps the persistent data.

I am happy to provide more information or answer questions.

---

<div class="post-metadata">

**Author:** ![peterparker](https://avatars.discourse-cdn.com/v4/letter/p/b9bd4f/32.png) [@peterparker](https://forum.dfinity.org/u/peterparker)\
**Post date:** [August 23, 2024, 3:13pm UTC](https://forum.dfinity.org/t/wasm-memory-persistence-backwards-compatibility/33816/12 "2024-08-23T15:13:32Z")

</div>

Thanks for the detailed explanation, Luc, it’s interesting and appreciated!

I don’t use Motoko. Relying on the default value in Juno’s tooling feels less future-proof than ensuring the expected behavior is met by being verbose. That’s why I mentionned I’ll use the the explicit argument.
