Add new host APIs set_storage_or_clear and get_storage_or_zero

[castillax]

Description

This PR introduces two new storage API functions—set_storage_or_clear and get_storage_or_zero—which provide fixed‑size (32‑byte) storage operations. These APIs are an attempt to match Ethereum’s SSTORE semantics. These APIs provide additional functionality for setting and retrieving storage values and clearing storage when a zero value is provided and returning zero bytes when a key does not exist.

Fixes #6944

Review Notes

• Changes in runtime.rs
  Added the set_storage_or_clear function to set storage at a fixed 256-bit key with a fixed 256-bit value. If the provided value is all zeros, the key is cleared.
  Added the get_storage_or_zero function to read storage at a fixed 256-bit key and write back a fixed 256-bit value. If the key does not exist, 32 bytes of zero are written back.
• Changes in storage.rs
  Added test cases to cover the new set_storage_or_clear and get_storage_or_zero APIs.
  .

// Example usage of the new set_storage_or_clear function
let existing = api::set_storage_or_clear(StorageFlags::empty(), &KEY, &VALUE_A);
assert_eq!(existing, None);

// Example usage of the new get_storage_or_zero function
let mut stored: [u8; 32] = [0u8; 32];
let _ = api::get_storage_or_zero(StorageFlags::empty(), &KEY, &mut stored);
assert_eq!(stored, VALUE_A);

All existing tests pass

Checklist

• My PR includes a detailed description as outlined in the "Description" and its two subsections above.
• My PR follows the labeling requirements of this project (at minimum one label for T required)
  • External contributors: ask maintainers to put the right label on your PR.
• I have made corresponding changes to the documentation (if applicable)
• I have added tests that prove my fix is effective or that my feature works (if applicable)

[xermicus]

You need to write benchmarks and charge weights. Additionally we should consider transient storage for the new host functions too.

To minimize code duplication I'd probably factor out the logic from set_storage and get_storage into one or more internal methods and add a boolean flag or something similar to specify whether the clearing / zero-ing is wanted. The exposed runtime APIs are then just thin wrappers around those.

[castillax]

/cmd prdoc --audience runtime_dev --bump minor

[athei]

Yeah a separate test would be nice. Will give the test code more on depth review when the other comments are resolved.

[paritytech-workflow-stopper]

All GitHub workflows were cancelled due to failure one of the required jobs.
Failed workflow url: https://github.com/paritytech/polkadot-sdk/actions/runs/13854589336
Failed job name: check-runtime-migration

[athei]

I know it seems pedantic. But please spent some time to come up with useful docs and names.

[athei]

Looks good. But before we can merge new stable functions we need to make use of them in revive. So we need to wait until @xermicus has time to implement that in revive or we merge as unstable.

[athei]

We verified that it works in revive.

[xermicus]

The revive test suite passes against this branch. Modulo some unrelated test somehow failing and that for external observers there is a semantic difference visible between a storage key holding zero vs. no storage key. Which will no longer be observable. I think this is fine because for the contract it isn't observable.

[pgherveou]

Would the new variants influence the benchmarks?
right now the set_storage benchmark always use the storageValue::Memory variant
and the get_storage the StorageReadMode::Standard

[athei]

All storage access is benchmarked with the maximum key length. So we are still safe here since we are using smaller keys. The maximum for keys is only 128 bytes. It is negligible. We won't gain much by benchmarking with the exact key size.