pezkuwichain/pezkuwi-fellows
1
0
Fork 0
mirror of https://github.com/pezkuwichain/pezkuwi-fellows.git synced 2026-04-22 05:37:57 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
6a912b1a65b806904e8ba78aed3451afbfc24f6a
pezkuwi-fellows/proposed/0145-remove-unnecessary-allocator-usage.html
T
paritytech-rfc-bot[bot] 6a912b1a65 deploy: 072e255c1a
2025-12-01 00:13:02 +00:00

970 lines
98 KiB
HTML
Raw Blame History

<!DOCTYPE HTML>
<html lang="en" class="polkadot" dir="ltr">
<head>
<!-- Book generated using mdBook -->
<meta charset="UTF-8">
<title>RFC-0145: Remove the host-side runtime memory allocator - Polkadot Fellowship RFCs</title>
<!-- Custom HTML head -->
<meta name="description" content="An online book of RFCs approved or proposed within the Polkadot Fellowship.">
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta name="theme-color" content="#ffffff">
<link rel="icon" href="../favicon.svg">
<link rel="shortcut icon" href="../favicon.png">
<link rel="stylesheet" href="../css/variables.css">
<link rel="stylesheet" href="../css/general.css">
<link rel="stylesheet" href="../css/chrome.css">
<link rel="stylesheet" href="../css/print.css" media="print">
<!-- Fonts -->
<link rel="stylesheet" href="../FontAwesome/css/font-awesome.css">
<link rel="stylesheet" href="../fonts/fonts.css">
<!-- Highlight.js Stylesheets -->
<link rel="stylesheet" href="../highlight.css">
<link rel="stylesheet" href="../tomorrow-night.css">
<link rel="stylesheet" href="../ayu-highlight.css">
<!-- Custom theme stylesheets -->
<link rel="stylesheet" href="../theme/polkadot.css">
</head>
<body class="sidebar-visible no-js">
<div id="body-container">
<!-- Provide site root to javascript -->
<script>
var path_to_root = "../";
var default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? "polkadot" : "polkadot";
</script>
<!-- Work around some values being stored in localStorage wrapped in quotes -->
<script>
try {
var theme = localStorage.getItem('mdbook-theme');
var sidebar = localStorage.getItem('mdbook-sidebar');
if (theme.startsWith('"') && theme.endsWith('"')) {
localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
}
if (sidebar.startsWith('"') && sidebar.endsWith('"')) {
localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
}
} catch (e) { }
</script>
<!-- Set the theme before any content is loaded, prevents flash -->
<script>
var theme;
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
if (theme === null || theme === undefined) { theme = default_theme; }
var html = document.querySelector('html');
html.classList.remove('polkadot')
html.classList.add(theme);
var body = document.querySelector('body');
body.classList.remove('no-js')
body.classList.add('js');
</script>
<input type="checkbox" id="sidebar-toggle-anchor" class="hidden">
<!-- Hide / unhide sidebar before it is displayed -->
<script>
var body = document.querySelector('body');
var sidebar = null;
var sidebar_toggle = document.getElementById("sidebar-toggle-anchor");
if (document.body.clientWidth >= 1080) {
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
sidebar = sidebar || 'visible';
} else {
sidebar = 'hidden';
}
sidebar_toggle.checked = sidebar === 'visible';
body.classList.remove('sidebar-visible');
body.classList.add("sidebar-" + sidebar);
</script>
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
<div class="sidebar-scrollbox">
<ol class="chapter"><li class="chapter-item expanded affix "><a href="../introduction.html">Introduction</a></li><li class="spacer"></li><li class="chapter-item expanded affix "><li class="part-title">Newly Proposed</li><li class="spacer"></li><li class="chapter-item expanded affix "><li class="part-title">Proposed</li><li class="chapter-item expanded "><a href="../proposed/0145-remove-unnecessary-allocator-usage.html" class="active">RFC-0145: Remove the host-side runtime memory allocator</a></li><li class="chapter-item expanded "><a href="../proposed/0154-multi-slot-aura.html">RFC-0154: AURA Multi-Slot Collation </a></li><li class="chapter-item expanded "><a href="../proposed/0156-bls-signatures.html">RFC-0156: Add BLS12-381 Host Functions</a></li><li class="spacer"></li><li class="chapter-item expanded affix "><li class="part-title">Approved</li><li class="chapter-item expanded "><a href="../approved/0001-agile-coretime.html">RFC-1: Agile Coretime</a></li><li class="chapter-item expanded "><a href="../approved/0005-coretime-interface.html">RFC-5: Coretime Interface</a></li><li class="chapter-item expanded "><a href="../approved/0007-system-collator-selection.html">RFC-0007: System Collator Selection</a></li><li class="chapter-item expanded "><a href="../approved/0008-parachain-bootnodes-dht.html">RFC-0008: Store parachain bootnodes in relay chain DHT</a></li><li class="chapter-item expanded "><a href="../approved/0009-improved-net-light-client-requests.html">RFC-0009: Improved light client requests networking protocol</a></li><li class="chapter-item expanded "><a href="../approved/0010-burn-coretime-revenue.html">RFC-0010: Burn Coretime Revenue</a></li><li class="chapter-item expanded "><a href="../approved/0012-process-for-adding-new-collectives.html">RFC-0012: Process for Adding New System Collectives</a></li><li class="chapter-item expanded "><a href="../approved/0013-prepare-blockbuilder-and-core-runtime-apis-for-mbms.html">RFC-0013: Prepare Core runtime API for MBMs</a></li><li class="chapter-item expanded "><a href="../approved/0014-improve-locking-mechanism-for-parachains.html">RFC-0014: Improve locking mechanism for parachains</a></li><li class="chapter-item expanded "><a href="../approved/0017-coretime-market-redesign.html">RFC-0017: Coretime Market Redesign</a></li><li class="chapter-item expanded "><a href="../approved/0022-adopt-encointer-runtime.html">RFC-0022: Adopt Encointer Runtime</a></li><li class="chapter-item expanded "><a href="../approved/0026-sassafras-consensus.html">RFC-0026: Sassafras Consensus Protocol</a></li><li class="chapter-item expanded "><a href="../approved/0032-minimal-relay.html">RFC-0032: Minimal Relay</a></li><li class="chapter-item expanded "><a href="../approved/0042-extrinsics-state-version.html">RFC-0042: Add System version that replaces StateVersion on RuntimeVersion</a></li><li class="chapter-item expanded "><a href="../approved/0043-storage-proof-size-hostfunction.html">RFC-0043: Introduce storage_proof_size Host Function for Improved Parachain Block Utilization</a></li><li class="chapter-item expanded "><a href="../approved/0045-nft-deposits-asset-hub.html">RFC-0045: Lowering NFT Deposits on Asset Hub</a></li><li class="chapter-item expanded "><a href="../approved/0047-assignment-of-availability-chunks.html">RFC-0047: Assignment of availability chunks to validators</a></li><li class="chapter-item expanded "><a href="../approved/0048-session-keys-runtime-api.html">RFC-0048: Generate ownership proof for SessionKeys</a></li><li class="chapter-item expanded "><a href="../approved/0050-fellowship-salaries.html">RFC-0050: Fellowship Salaries</a></li><li class="chapter-item expanded "><a href="../approved/0056-one-transaction-per-notification.html">RFC-0056: Enforce only one transaction per notification</a></li><li class="chapter-item expanded "><a href="../approved/0059-nodes-capabilities-discovery.html">RFC-0059: Add a discovery mechanism for nodes based on their capabilities</a></li><li class="chapter-item expanded "><a href="../approved/0078-merkleized-metadata.html">RFC-0078: Merkleized Metadata</a></li><li class="chapter-item expanded "><a href="../approved/0084-general-transaction-extrinsic-format.html">RFC-0084: General transactions in extrinsic format</a></li><li class="chapter-item expanded "><a href="../approved/0091-dht-record-creation-time.html">RFC-0091: DHT Authority discovery record creation time</a></li><li class="chapter-item expanded "><a href="../approved/0097-unbonding_queue.html">RFC-0097: Unbonding Queue</a></li><li class="chapter-item expanded "><a href="../approved/0099-transaction-extension-version.html">RFC-0099: Introduce a transaction extension version</a></li><li class="chapter-item expanded "><a href="../approved/0100-xcm-multi-type-asset-transfer.html">RFC-0100: New XCM instruction: InitiateAssetsTransfer</a></li><li class="chapter-item expanded "><a href="../approved/0101-xcm-transact-remove-max-weight-param.html">RFC-0101: XCM Transact remove require_weight_at_most parameter</a></li><li class="chapter-item expanded "><a href="../approved/0103-introduce-core-index-commitment.html">RFC-0103: Introduce a CoreIndex commitment and a SessionIndex field in candidate receipts</a></li><li class="chapter-item expanded "><a href="../approved/0105-xcm-improved-fee-mechanism.html">RFC-0105: XCM improved fee mechanism</a></li><li class="chapter-item expanded "><a href="../approved/0107-xcm-execution-hints.html">RFC-0107: XCM Execution hints</a></li><li class="chapter-item expanded "><a href="../approved/0108-xcm-remove-testnet-ids.html">RFC-0108: Remove XCM testnet NetworkIds</a></li><li class="chapter-item expanded "><a href="../approved/0122-alias-origin-on-asset-transfers.html">RFC-0122: Asset transfers can alias XCM origin on destination to original origin</a></li><li class="chapter-item expanded "><a href="../approved/0123-pending-code-as-storage-location-for-runtime-upgrades.html">RFC-0123: Introduce :pending_code as intermediate storage key for the runtime code</a></li><li class="chapter-item expanded "><a href="../approved/0125-xcm-asset-metadata.html">RFC-0125: XCM Asset Metadata</a></li><li class="chapter-item expanded "><a href="../approved/0126-introduce-pvq.html">RFC-0126: Introduce PVQ (PolkaVM Query)</a></li><li class="chapter-item expanded "><a href="../approved/0135-compressed-blob-prefixes.html">RFC-0135: Compressed Blob Prefixes</a></li><li class="chapter-item expanded "><a href="../approved/0139-faster-erasure-coding.html">RFC-0139: Faster Erasure Coding</a></li><li class="chapter-item expanded "><a href="../approved/0146-deflationary-fee-proposal.html">RFC-0146: Deflationary Transaction Fee Model for the Relay Chain and its System Parachains</a></li><li class="chapter-item expanded "><a href="../approved/0149-rfc-1-renewal-adjustment.html">RFC-0149: Renewal Adjustment</a></li><li class="chapter-item expanded "><a href="../approved/0150-voting-while-delegating.html">RFC-150: Allow Voting While Delegating</a></li><li class="spacer"></li><li class="chapter-item expanded affix "><li class="part-title">Stale</li><li class="chapter-item expanded "><a href="../stale/0000-pre-elves_soft.html">RFC-0000: Pre-ELVES soft concensus</a></li><li class="chapter-item expanded "><a href="../stale/0000-rewards.html">RFC-0000: Validator Rewards</a></li><li class="chapter-item expanded "><a href="../stale/0004-remove-unnecessary-allocator-usage.html">RFC-0004: Remove the host-side runtime memory allocator</a></li><li class="chapter-item expanded "><a href="../stale/0006-dynamic-pricing-for-bulk-coretime-sales.html">RFC-0006: Dynamic Pricing for Bulk Coretime Sales</a></li><li class="chapter-item expanded "><a href="../stale/0034-xcm-absolute-location-account-derivation.html">RFC-34: XCM Absolute Location Account Derivation</a></li><li class="chapter-item expanded "><a href="../stale/0035-conviction-voting-delegation-modifications.html"> RFC-0035: Conviction Voting Delegation Modifications</a></li><li class="chapter-item expanded "><a href="../stale/0044-rent-based-registration.html">RFC-0044: Rent based registration model</a></li><li class="chapter-item expanded "><a href="../stale/0054-remove-heap-pages.html">RFC-0054: Remove the concept of "heap pages" from the client</a></li><li class="chapter-item expanded "><a href="../stale/0070-x-track-kusamanetwork.html">RFC-0070: X Track for @kusamanetwork</a></li><li class="chapter-item expanded "><a href="../stale/0073-referedum-deposit-track.html">RFC-0073: Decision Deposit Referendum Track</a></li><li class="chapter-item expanded "><a href="../stale/0074-stateful-multisig-pallet.html">RFC-0074: Stateful Multisig Pallet</a></li><li class="chapter-item expanded "><a href="../stale/0077-increase-max-length-of-identity-pgp-fingerprint-value.html">RFC-0077: Increase maximum length of identity PGP fingerprint values from 20 bytes</a></li><li class="chapter-item expanded "><a href="../stale/0088-broker-pallet-slashable-deposit-purchaser-reputation-reserved-cores.html">RFC-0088: Add slashable locked deposit, purchaser reputation, and reserved cores for on-chain identities to broker pallet</a></li><li class="chapter-item expanded "><a href="../stale/00xx-secondary-marketplace-for-regions.html">RFC-0001: Secondary Market for Regions</a></li><li class="chapter-item expanded "><a href="../stale/00xx-smart-contracts-coretime-chain.html">RFC-0002: Smart Contracts on the Coretime Chain</a></li><li class="chapter-item expanded "><a href="../stale/0102-offchain-parachain-runtime-upgrades.html">RFC-0000: Feature Name Here</a></li><li class="chapter-item expanded "><a href="../stale/0106-xcm-remove-fees-mode.html">RFC-0106: Remove XCM fees mode</a></li><li class="chapter-item expanded "><a href="../stale/0111-pure-proxy-replication.html">RFC-0111: Pure Proxy Replication</a></li><li class="chapter-item expanded "><a href="../stale/0112-compress-state-response-message-in-state-sync.html">RFC-0112: Compress the State Response Message in State Sync</a></li><li class="chapter-item expanded "><a href="../stale/0114-secp256r1-hostfunction.html">RFC-0114: Introduce secp256r1_ecdsa_verify_prehashed Host Function to verify NIST-P256 elliptic curve signatures</a></li><li class="chapter-item expanded "><a href="../stale/0117-unbrick-collective.html">RFC-0117: The Unbrick Collective</a></li><li class="chapter-item expanded "><a href="../stale/0120-referenda-confirmation-by-candle-mechanism.html">RFC-0120: Referenda Confirmation by Candle Mechanism</a></li><li class="chapter-item expanded "><a href="../stale/0124-extrinsic-version-5.html">RFC-0124: Extrinsic version 5</a></li><li class="chapter-item expanded "><a href="../stale/0138-invulnerable-collator-election.html">RFC-0138: Election mechanism for invulnerable collators on system chains</a></li><li class="chapter-item expanded "><a href="../stale/0152-decentralized-convex-preference-coretime-market-for-polkadot.html">RFC-0152: Decentralized Convex-Preference Coretime Market for Polkadot</a></li><li class="chapter-item expanded "><a href="../stale/0155-pUSD.html">RFC-0155: pUSD (Polkadot USD over-collateralised debt token)</a></li><li class="chapter-item expanded "><a href="../stale/RFC-114 Adjust Tipper Track Confirmation Periods.html">RFC-114: Adjust Tipper Track Confirmation Periods</a></li><li class="chapter-item expanded "><a href="../stale/TODO-stale-nomination-reward-curve.html">RFC-TODO: Stale Nomination Reward Curve</a></li><li class="chapter-item expanded "><a href="../stale/xxxx-improve-the-security-of-proof-of-possession.html">RFC-XXXX: Adding customized mandatory context to proof of possession statement</a></li></ol>
</div>
<div id="sidebar-resize-handle" class="sidebar-resize-handle"></div>
</nav>
<!-- Track and set sidebar scroll position -->
<script>
var sidebarScrollbox = document.querySelector('#sidebar .sidebar-scrollbox');
sidebarScrollbox.addEventListener('click', function(e) {
if (e.target.tagName === 'A') {
sessionStorage.setItem('sidebar-scroll', sidebarScrollbox.scrollTop);
}
}, { passive: true });
var sidebarScrollTop = sessionStorage.getItem('sidebar-scroll');
sessionStorage.removeItem('sidebar-scroll');
if (sidebarScrollTop) {
// preserve sidebar scroll position when navigating via links within sidebar
sidebarScrollbox.scrollTop = sidebarScrollTop;
} else {
// scroll sidebar to current active section when navigating via "next/previous chapter" buttons
var activeSection = document.querySelector('#sidebar .active');
if (activeSection) {
activeSection.scrollIntoView({ block: 'center' });
}
}
</script>
<div id="page-wrapper" class="page-wrapper">
<div class="page">
<div id="menu-bar-hover-placeholder"></div>
<div id="menu-bar" class="menu-bar sticky">
<div class="left-buttons">
<label id="sidebar-toggle" class="icon-button" for="sidebar-toggle-anchor" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
<i class="fa fa-bars"></i>
</label>
<button id="theme-toggle" class="icon-button" type="button" title="Change theme" aria-label="Change theme" aria-haspopup="true" aria-expanded="false" aria-controls="theme-list">
<i class="fa fa-paint-brush"></i>
</button>
<ul id="theme-list" class="theme-popup" aria-label="Themes" role="menu">
<li role="none"><button role="menuitem" class="theme" id="polkadot">Polkadot</button></li>
<li role="none"><button role="menuitem" class="theme" id="light">Light</button></li>
<li role="none"><button role="menuitem" class="theme" id="rust">Rust</button></li>
<li role="none"><button role="menuitem" class="theme" id="coal">Coal</button></li>
<li role="none"><button role="menuitem" class="theme" id="navy">Navy</button></li>
<li role="none"><button role="menuitem" class="theme" id="ayu">Ayu</button></li>
</ul>
<button id="search-toggle" class="icon-button" type="button" title="Search. (Shortkey: s)" aria-label="Toggle Searchbar" aria-expanded="false" aria-keyshortcuts="S" aria-controls="searchbar">
<i class="fa fa-search"></i>
</button>
</div>
<h1 class="menu-title">Polkadot Fellowship RFCs</h1>
<div class="right-buttons">
<a href="../print.html" title="Print this book" aria-label="Print this book">
<i id="print-button" class="fa fa-print"></i>
</a>
</div>
</div>
<div id="search-wrapper" class="hidden">
<form id="searchbar-outer" class="searchbar-outer">
<input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
</form>
<div id="searchresults-outer" class="searchresults-outer hidden">
<div id="searchresults-header" class="searchresults-header"></div>
<ul id="searchresults">
</ul>
</div>
</div>
<!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
<script>
document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) {
link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
});
</script>
<div id="content" class="content">
<main>
<p><a href="https://github.com/polkadot-fellows/RFCs/pull/145">(source)</a></p>
<p><strong>Table of Contents</strong></p>
<ul>
<li><a href="#rfc-0145-remove-the-host-side-runtime-memory-allocator">RFC-0145: Remove the host-side runtime memory allocator</a>
<ul>
<li><a href="#summary">Summary</a></li>
<li><a href="#prior-art">Prior Art</a>
<ul>
<li><a href="#changes-from-rfc-4">Changes from RFC-4</a></li>
</ul>
</li>
<li><a href="#motivation">Motivation</a></li>
<li><a href="#stakeholders">Stakeholders</a></li>
<li><a href="#explanation">Explanation</a>
<ul>
<li><a href="#new-definitions">New definitions</a></li>
<li><a href="#memory-safety">Memory safety</a></li>
<li><a href="#changes-to-host-functions">Changes to host functions</a></li>
<li><a href="#other-changes">Other changes</a></li>
</ul>
</li>
</ul>
</li>
</ul>
<h1 id="rfc-0145-remove-the-host-side-runtime-memory-allocator"><a class="header" href="#rfc-0145-remove-the-host-side-runtime-memory-allocator">RFC-0145: Remove the host-side runtime memory allocator</a></h1>
<div class="table-wrapper"><table><thead><tr><th></th><th></th></tr></thead><tbody>
<tr><td><strong>Start Date</strong></td><td>2025-05-16</td></tr>
<tr><td><strong>Description</strong></td><td>Update the runtime-host interface to no longer make use of a host-side allocator</td></tr>
<tr><td><strong>Authors</strong></td><td>Pierre Krieger, Someone Unknown</td></tr>
<tr><td></td><td></td></tr>
</tbody></table>
</div>
<h2 id="summary"><a class="header" href="#summary">Summary</a></h2>
<p>Update the runtime-host interface so that it no longer uses the host-side allocator.</p>
<h2 id="prior-art"><a class="header" href="#prior-art">Prior Art</a></h2>
<p>The API of these new functions was heavily inspired by the API used by the C programming language.</p>
<p>This RFC is mainly based on <a href="https://github.com/polkadot-fellows/RFCs/pull/4">RFC-4</a> by @tomaka, which was never adopted, and this RFC supersedes it.</p>
<h3 id="changes-from-rfc-4"><a class="header" href="#changes-from-rfc-4">Changes from RFC-4</a></h3>
<ul>
<li>The original RFC required checking if an output buffer address provided to a host function is inside the VM address space range and to stop the runtime execution if that's not the case. That requirement has been removed in this version of the RFC, as in the general case, the host doesn't have exhaustive information about the VM's memory organization. Thus, attempting to write to an out-of-bounds region will result in a &quot;normal&quot; runtime panic.</li>
<li>Function signatures introduced by <a href="https://github.com/w3f/PPPs/pull/7">PPP#7</a> have been used in this RFC, as the PPP has already been <a href="https://github.com/paritytech/substrate/pull/11490">properly implemented</a> and <a href="https://github.com/w3f/polkadot-spec/pull/592/files">documented</a>. However, it has never been officially adopted, nor have its functions been in use.</li>
<li>Return values were harmonized to <code>i64</code> everywhere where they represent either a positive outcome as a positive integer or a negative outcome as a negative error code.</li>
<li><code>ext_offchain_network_peer_id_version_1</code> now returns a result code instead of silently failing if the network status is unavailable.</li>
<li>Added new versions of <code>ext_misc_runtime_version</code> and <code>ext_offchain_random_seed</code>.</li>
<li>Addressed discussions from the original RFC-4 discussion thread.</li>
</ul>
<h2 id="motivation"><a class="header" href="#motivation">Motivation</a></h2>
<p>The heap allocation of the runtime is currently controlled by the host using a memory allocator on the host side.</p>
<p>The API of many host functions contains buffer allocations. For example, when calling <code>ext_hashing_twox_256_version_1</code>, the host allocates a 32-byte buffer using the host allocator, and returns a pointer to this buffer to the runtime. The runtime later has to call <code>ext_allocator_free_version_1</code> on this pointer to free the buffer.</p>
<p>Even though no benchmark has been done, it is pretty obvious that this design is very inefficient. To continue with the example of <code>ext_hashing_twox_256_version_1</code>, it would be more efficient to instead write the output hash to a buffer allocated by the runtime on its stack and passed by pointer to the function. Allocating a buffer on the stack, in the worst case, consists simply of decreasing a number; in the best case, it is free. Doing so would save many VM memory reads and writes by the allocator, and would save a function call to <code>ext_allocator_free_version_1</code>.</p>
<p>Furthermore, the existence of the host-side allocator has become questionable over time. It is implemented in a very naive way: every allocation is rounded up to the next power of two, and once a piece of memory is allocated it can only be reused for allocations which also round up to the exactly the same size. So in theory it's possible to end up in a situation where we still technically have plenty of free memory, but our allocations will fail because all of that memory is reserved for differently sized buckets. That behavior is de-facto hardcoded into the current protocol and for determinism and backwards compatibility reasons, it needs to be implemented exactly identically in every client implementation. </p>
<p>In addition to that, runtimes make substantial use of heap memory allocations, and each allocation needs to go through the runtime &lt;-&gt; host boundary twice (once for allocating and once for freeing). Moving the allocator to the runtime side would be a good idea, although it would increase the runtime size. But before the host-side allocator can be deprecated, all the host functions that use it must be updated to avoid using it.</p>
<h2 id="stakeholders"><a class="header" href="#stakeholders">Stakeholders</a></h2>
<p>Runtime developers, who will benefit from the improved performance and more deterministic behavior of the runtime code.</p>
<h2 id="explanation"><a class="header" href="#explanation">Explanation</a></h2>
<h3 id="new-definitions"><a class="header" href="#new-definitions">New definitions</a></h3>
<h4 id="new-definition-i-runtime-optional-positive-integer"><a class="header" href="#new-definition-i-runtime-optional-positive-integer"><a name="new-def-i"></a>New Definition I: Runtime Optional Positive Integer</a></h4>
<p>By a Runtime Optional Positive Integer we refer to an abstract value $r \in \mathcal{R}$ where $\mathcal{R} := {\bot} \cup {0, 1, \dots, 2^{32} - 1},$ and where $\bot$ denotes the <em>absent</em> value.</p>
<p>At the Host-Runtime interface this type is represented by a signed 64-bit integer $x \in \mathbb{Z}$ (thus $\mathbb{Z} := {-2^{63}, \dots, 2^{63} - 1}$).</p>
<p>We define the encoding function $\mathrm{Enc}<em>{\mathrm{ROP}} : \mathcal{R} \to \mathbb{Z}$ and decoding function $\mathrm{Dec}</em>{\mathrm{ROP}} : \mathbb{Z} \to \mathcal{R} \cup {\mathrm{error}}$ as follows.</p>
<p>For $r \in \mathcal{R}$,</p>
<p>$$
\mathrm{Enc}_{\mathrm{ROP}}(r) :=
\begin{cases}
-1 &amp; \text{if } r = \bot, \
r &amp; \text{if } r \in {0, 1, \dots, 2^{32} - 1}.
\end{cases}
$$</p>
<p>For a signed 64-bit integer $x$,</p>
<p>$$
\mathrm{Dec}_{\mathrm{ROP}}(x) :=
\begin{cases}
\bot &amp; \text{if } x = -1, \
x &amp; \text{if } 0 \le x &lt; 2^{32}, \
\mathrm{error} &amp; \text{otherwise.}
\end{cases}
$$</p>
<p>A valid Runtime Optional Positive Integer at the Host-Runtime boundary is any 64-bit signed integer $x$ such that $x \in {-1} \cup {0, 1, \dots, 2^{32} - 1}$. All other 64-bit integer values are invalid for this type.</p>
<p>Conforming implementations must not produce invalid values when encoding. Receivers must abort execution if decoding results in $\mathrm{error}$.</p>
<h4 id="new-definition-ii-runtime-optional-pointer-size"><a class="header" href="#new-definition-ii-runtime-optional-pointer-size"><a name="new-def-ii"></a>New Definition II: Runtime Optional Pointer-Size</a></h4>
<p>The Runtime optional pointer-size has exactly the same definition as Runtime pointer-size (<a href="https://spec.polkadot.network/chap-host-api#defn-runtime-pointer-size">Definition 216</a>) with the value of 2⁶⁴-1 representing a non-existing value (an <em>absent</em> value).</p>
<h3 id="memory-safety"><a class="header" href="#memory-safety">Memory safety</a></h3>
<p>Pointers to input parameters passed to the host must reference readable memory regions. The host must abort execution if the memory region referenced by the pointer cannot be read, unless explicitly stated otherwise.</p>
<p>Pointers to output parameters passed to the host must reference writeable memory regions. The host must abort execution if the memory region referenced by the pointer cannot be written, in case it is performing the actual write, unless explicitly stated otherwise.</p>
<h3 id="changes-to-host-functions"><a class="header" href="#changes-to-host-functions">Changes to host functions</a></h3>
<h4 id="ext_storage_get"><a class="header" href="#ext_storage_get">ext_storage_get</a></h4>
<h5 id="existing-prototype"><a class="header" href="#existing-prototype">Existing prototype</a></h5>
<pre><code class="language-wat">(func $ext_storage_get_version_1
(param $key i64) (result i64))
</code></pre>
<h5 id="changes"><a class="header" href="#changes">Changes</a></h5>
<p>Considered obsolete in favor of <code>ext_storage_read_version_2</code>. Cannot be used in a runtime using the new-style of entry-point.</p>
<h4 id="ext_storage_read"><a class="header" href="#ext_storage_read">ext_storage_read</a></h4>
<h5 id="existing-prototype-1"><a class="header" href="#existing-prototype-1">Existing prototype</a></h5>
<pre><code class="language-wat">(func $ext_storage_read_version_1
(param $key i64) (param $value_out i64) (param $offset i32) (result i64))
</code></pre>
<h5 id="changes-1"><a class="header" href="#changes-1">Changes</a></h5>
<p>The function was returning a SCALE-encoded <code>Option</code>-wrapped 32-bit integer representing the number of bytes left at supplied <code>offset</code>. It was using a host-allocated buffer to return it. It is changed to always return the full length of the value directly as a primitive value.</p>
<h5 id="new-prototype"><a class="header" href="#new-prototype">New prototype</a></h5>
<pre><code class="language-wat">(func $ext_storage_read_version_2
(param $key i64) (param $value_out i64) (param $value_offset i32) (result i64))
</code></pre>
<h5 id="arguments"><a class="header" href="#arguments">Arguments</a></h5>
<ul>
<li><code>key</code> is a pointer-size (<a href="https://spec.polkadot.network/chap-host-api#defn-runtime-pointer-size">Definition 216</a>) to the storage key being read;</li>
<li><code>value_out</code> is a pointer-size (<a href="https://spec.polkadot.network/chap-host-api#defn-runtime-pointer-size">Definition 216</a>) to a buffer where the value read should be stored. The value is actually stored only if the buffer is large enough. Otherwise, the buffer is not written into and its contents are unchanged;</li>
<li><code>value_offset</code> is an unsigned 32-bit offset from which the value reading should start.</li>
</ul>
<h5 id="result"><a class="header" href="#result">Result</a></h5>
<p>The result is an optional positive integer (<a href="#new-def-i">New Definition I</a>), representing either the full length of the value in storage or the <em>absence</em> of such a value in storage.</p>
<h4 id="ext_storage_clear_prefix"><a class="header" href="#ext_storage_clear_prefix">ext_storage_clear_prefix</a></h4>
<h5 id="existing-prototype-2"><a class="header" href="#existing-prototype-2">Existing prototype</a></h5>
<pre><code class="language-wat">(func $ext_storage_clear_prefix_version_2
(param $prefix i64) (param $limit i64) (result i64))
</code></pre>
<h5 id="changes-2"><a class="header" href="#changes-2">Changes</a></h5>
<p>The function used to accept only a prefix and a limit and return a SCALE-encoded <code>enum</code> representing the number of iterations performed, wrapped into a discriminator to differentiate if all the keys were removed. It was using a host-allocated buffer to return the value. As <a href="https://github.com/w3f/polkadot-spec/issues/588">discussed</a>, such implementation was suboptimal, and a better implementation was proposed in <a href="https://github.com/w3f/PPPs/pull/7">PPP#7</a>, but the PPP has never been adopted. The new version adopts the PPP, providing a means of returning much more exhaustive information about the work performed, and also accepts an optional input cursor and makes the limit optional as well. It always returns the full length of the continuation cursor.</p>
<h5 id="new-prototype-1"><a class="header" href="#new-prototype-1">New prototype</a></h5>
<pre><code class="language-wat">(func $ext_storage_clear_prefix_version_3
(param $maybe_prefix i64) (param $maybe_limit i64) (param $maybe_cursor_in i64)
(param $maybe_cursor_out i64) (param $counters i32) (result i32))
</code></pre>
<h5 id="arguments-1"><a class="header" href="#arguments-1">Arguments</a></h5>
<ul>
<li><code>maybe_prefix</code> is a pointer-size (<a href="https://spec.polkadot.network/chap-host-api#defn-runtime-pointer-size">Definition 216</a>) containing a (possibly empty) storage prefix being cleared;</li>
<li><code>maybe_limit</code> is an optional positive integer (<a href="#new-def-i">New Definition I</a>) representing either the maximum number of backend deletions which may happen, or the <em>absence</em> of such a limit. The number of backend iterations may surpass this limit by no more than one;</li>
<li><code>maybe_cursor_in</code> is an optional pointer-size (<a href="#new-def-ii">New Definition II</a>) representing the cursor returned by the previous (unfinished) call to this function. It should be <em>absent</em> on the first call;</li>
<li><code>maybe_cursor_out</code> is a pointer-size (<a href="https://spec.polkadot.network/chap-host-api#defn-runtime-pointer-size">Definition 216</a>) to a buffer where the continuation cursor will optionally be written (see also the Result section). The value is actually stored only if the buffer is large enough. Whenever the value is not written into the buffer, the buffer contents are unmodified;</li>
<li><code>counters</code> is a pointer (<a href="https://spec.polkadot.network/chap-host-api#defn-runtime-pointer">Definition 215</a>) to a 12-byte buffer where three low-endian 32-bit integers will be stored one after another, representing the counters, respectively:
<ul>
<li>Of items removed from the backend database will be written;</li>
<li>Of unique keys removed, taking into account both the backend and the overlay;</li>
<li>Of iterations (each requiring a storage seek/read) which were done.</li>
</ul>
</li>
</ul>
<h5 id="result-1"><a class="header" href="#result-1">Result</a></h5>
<p>The result represents the length of the continuation cursor which might have been written to the buffer provided in <code>maybe_cursor_out</code>. A zero value represents the absence of such a cursor and no need for continuation (the prefix has been completely cleared).</p>
<h4 id="ext_storage_root"><a class="header" href="#ext_storage_root">ext_storage_root</a></h4>
<h5 id="existing-prototype-3"><a class="header" href="#existing-prototype-3">Existing prototype</a></h5>
<pre><code class="language-wat">(func $ext_storage_root_version_2
(param $version i32) (result i64))
</code></pre>
<h5 id="changes-3"><a class="header" href="#changes-3">Changes</a></h5>
<p>The old version accepted the state version as an argument and returned a SCALE-encoded trie root hash through a host-allocated buffer. The new version adopts <a href="https://github.com/w3f/PPPs/pull/6">PPP#6</a> getting rid of the argument that used to represent the state version. It accepts a pointer to a runtime-allocated buffer and fills it with the output value. The length of the encoded result is returned.</p>
<h5 id="new-prototype-2"><a class="header" href="#new-prototype-2">New prototype</a></h5>
<pre><code class="language-wat">(func $ext_storage_root_version_3
(param $out i64) (result i32))
</code></pre>
<h5 id="arguments-2"><a class="header" href="#arguments-2">Arguments</a></h5>
<ul>
<li><code>out</code> is a pointer-size (<a href="https://spec.polkadot.network/chap-host-api#defn-runtime-pointer-size">Definition 216</a>) to a buffer where the SCALE-encoded storage root, calculated after committing all the existing operations, will be stored. The value is actually stored only if the buffer is large enough. Otherwise, the buffer is not written into and its contents are unchanged.</li>
</ul>
<h5 id="results"><a class="header" href="#results">Results</a></h5>
<p>The result is the full length of the output that might have been stored in the buffer provided in <code>out</code>.</p>
<h4 id="ext_storage_next_key"><a class="header" href="#ext_storage_next_key">ext_storage_next_key</a></h4>
<h5 id="existing-prototype-4"><a class="header" href="#existing-prototype-4">Existing prototype</a></h5>
<pre><code class="language-wat">(func $ext_storage_next_key_version_1
(param $key i64) (result i64))
</code></pre>
<h5 id="changes-4"><a class="header" href="#changes-4">Changes</a></h5>
<p>The old version accepted the key and returned the SCALE-encoded next key in a host-allocated buffer. The new version additionally accepts a runtime-allocated output buffer and returns full next key length.</p>
<h5 id="new-prototype-3"><a class="header" href="#new-prototype-3">New prototype</a></h5>
<pre><code class="language-wat">(func $ext_storage_next_key_version_2
(param $key_in i64) (param $key_out i64) (result i32))
</code></pre>
<h5 id="arguments-3"><a class="header" href="#arguments-3">Arguments</a></h5>
<ul>
<li><code>key_in</code> is a pointer-size (<a href="https://spec.polkadot.network/chap-host-api#defn-runtime-pointer-size">Definition 216</a>) to a buffer containing a storage key;</li>
<li><code>key_out</code> is a pointer-size (<a href="https://spec.polkadot.network/chap-host-api#defn-runtime-pointer-size">Definition 216</a>) to an output buffer where the next key in the storage in the lexicographical order will be written. The value is actually stored only if the buffer is large enough. Otherwise, the buffer is not written into and its contents are unchanged.</li>
</ul>
<h5 id="result-2"><a class="header" href="#result-2">Result</a></h5>
<p>The result is the full length of the output key that might have been stored in <code>key_out</code>, or zero if no next key was found.</p>
<h4 id="ext_default_child_storage_get"><a class="header" href="#ext_default_child_storage_get">ext_default_child_storage_get</a></h4>
<h5 id="existing-prototype-5"><a class="header" href="#existing-prototype-5">Existing prototype</a></h5>
<pre><code class="language-wat">(func $ext_default_child_storage_get_version_1
(param $child_storage_key i64) (param $key i64) (result i64))
</code></pre>
<h5 id="changes-5"><a class="header" href="#changes-5">Changes</a></h5>
<p>Considered obsolete in favor of <code>ext_default_child_storage_read_version_2</code>. Cannot be used in a runtime using the new-style of entry-point.</p>
<h4 id="ext_default_child_storage_read"><a class="header" href="#ext_default_child_storage_read">ext_default_child_storage_read</a></h4>
<h5 id="existing-prototype-6"><a class="header" href="#existing-prototype-6">Existing prototype</a></h5>
<pre><code class="language-wat">(func $ext_default_child_storage_read_version_1
(param $child_storage_key i64) (param $key i64) (param $value_out i64) (param $offset i32)
(result i64))
</code></pre>
<h5 id="changes-6"><a class="header" href="#changes-6">Changes</a></h5>
<p>The function was returning a SCALE-encoded <code>Option</code>-wrapped 32-bit integer representing the number of bytes left at supplied <code>offset</code>. It was using a host-allocated buffer to return it. It is changed to always return the full length of the value directly as a primitive value.</p>
<h5 id="new-prototype-4"><a class="header" href="#new-prototype-4">New prototype</a></h5>
<pre><code class="language-wat">(func $ext_default_child_storage_read_version_2
(param $storage_key i64) (param $key i64) (param $value_out i64) (param $value_offset i32)
(result i64))
</code></pre>
<h5 id="arguments-4"><a class="header" href="#arguments-4">Arguments</a></h5>
<ul>
<li><code>storage_key</code> is a pointer-size (<a href="https://spec.polkadot.network/chap-host-api#defn-runtime-pointer-size">Definition 216</a>) to the child storage key (<a href="https://spec.polkadot.network/chap-host-api#defn-child-storage-type">Definition 219</a>);</li>
<li><code>key</code> is the storage key being read;</li>
<li><code>value_out</code> is a pointer-size (<a href="https://spec.polkadot.network/chap-host-api#defn-runtime-pointer-size">Definition 216</a>) to a buffer where the value read should be stored. The value is actually stored only if the buffer is large enough. Otherwise, the buffer is not written into and its contents are unchanged;</li>
<li><code>value_offset</code> is an unsigned 32-bit offset from which the value reading should start.</li>
</ul>
<h5 id="result-3"><a class="header" href="#result-3">Result</a></h5>
<p>The result is an optional positive integer (<a href="#new-def-i">New Definition I</a>), representing either the full length of the value in storage or the <em>absence</em> of such a value in storage.</p>
<h4 id="ext_default_child_storage_storage_kill"><a class="header" href="#ext_default_child_storage_storage_kill">ext_default_child_storage_storage_kill</a></h4>
<h5 id="existing-prototype-7"><a class="header" href="#existing-prototype-7">Existing prototype</a></h5>
<pre><code class="language-wat">(func $ext_default_child_storage_storage_kill_version_3
(param $child_storage_key i64) (param $limit i64)
(result i64))
</code></pre>
<h5 id="changes-7"><a class="header" href="#changes-7">Changes</a></h5>
<p>The function used to accept only a child storage key and a limit and return a SCALE-encoded <code>enum</code> representing the number of iterations performed, wrapped into a discriminator to differentiate if all the keys were removed. It was using a host-allocated buffer to return the value. As <a href="https://github.com/w3f/polkadot-spec/issues/588">discussed</a>, such implementation was suboptimal, and a better implementation was proposed in <a href="https://github.com/w3f/PPPs/pull/7">PPP#7</a>, but the PPP has never been adopted. The new version adopts the PPP, providing a means of returning much more exhaustive information about the work performed, and also accepts an optional input cursor and makes the limit optional as well. It always returns the full length of the continuation cursor.</p>
<h5 id="new-prototype-5"><a class="header" href="#new-prototype-5">New prototype</a></h5>
<pre><code class="language-wat">(func $ext_default_child_storage_storage_kill_version_4
(param $storage_key i64) (param $maybe_limit i64) (param $maybe_cursor_in i64)
(param $maybe_cursor_out i64) (param $counters i32) (result i32))
</code></pre>
<h5 id="arguments-5"><a class="header" href="#arguments-5">Arguments</a></h5>
<ul>
<li><code>storage_key</code> is a pointer-size (<a href="https://spec.polkadot.network/chap-host-api#defn-runtime-pointer-size">Definition 216</a>) to the child storage key (<a href="https://spec.polkadot.network/chap-host-api#defn-child-storage-type">Definition 219</a>);</li>
<li><code>maybe_limit</code> is an optional positive integer representing either the maximum number of backend deletions which may happen, or the absence of such a limit. The number of backend iterations may surpass this limit by no more than one;</li>
<li><code>maybe_cursor_in</code> is an optional pointer-size representing the cursor returned by the previous (unfinished) call to this function. It should be <em>absent</em> on the first call;</li>
<li><code>maybe_cursor_out</code> is a pointer-size (<a href="https://spec.polkadot.network/chap-host-api#defn-runtime-pointer-size">Definition 216</a>) to a buffer where the continuation cursor will optionally be written (see also the Result section). The value is actually stored only if the buffer is large enough. Whenever the value is not written into the buffer, the buffer contents are unmodified;</li>
<li><code>counters</code> is a pointer (<a href="https://spec.polkadot.network/chap-host-api#defn-runtime-pointer">Definition 215</a>) to a 12-byte buffer where three low-endian 32-bit integers will be stored one after another, representing the counters, respectively:
<ul>
<li>Of items removed from the backend database will be written;</li>
<li>Of unique keys removed, taking into account both the backend and the overlay;</li>
<li>Of iterations (each requiring a storage seek/read) which were done.</li>
</ul>
</li>
</ul>
<h5 id="result-4"><a class="header" href="#result-4">Result</a></h5>
<p>The result represents the length of the continuation cursor which might have been written to the buffer provided in <code>maybe_cursor_out</code>. A zero value represents the absence of such a cursor and no need for continuation (the prefix has been completely cleared).</p>
<h4 id="ext_default_child_storage_clear_prefix"><a class="header" href="#ext_default_child_storage_clear_prefix">ext_default_child_storage_clear_prefix</a></h4>
<h5 id="existing-prototype-8"><a class="header" href="#existing-prototype-8">Existing prototype</a></h5>
<pre><code class="language-wat">(func $ext_default_child_storage_clear_prefix_version_2
(param $child_storage_key i64) (param $prefix i64) (param $limit i64)
(result i64))
</code></pre>
<h5 id="changes-8"><a class="header" href="#changes-8">Changes</a></h5>
<p>The function used to accept (along with the child storage key) only a prefix and a limit and return a SCALE-encoded <code>enum</code> representing the number of iterations performed, wrapped into a discriminator to differentiate if all the keys were removed. It was using a host-allocated buffer to return the value. As <a href="https://github.com/w3f/polkadot-spec/issues/588">discussed</a>, such implementation was suboptimal, and a better implementation was proposed in <a href="https://github.com/w3f/PPPs/pull/7">PPP#7</a>, but the PPP has never been adopted. The new version adopts the PPP, providing a means of returning much more exhaustive information about the work performed, and also accepts an optional input cursor and makes the limit optional as well. It always returns the full length of the continuation cursor.</p>
<h5 id="new-prototype-6"><a class="header" href="#new-prototype-6">New prototype</a></h5>
<pre><code class="language-wat">(func $ext_default_child_storage_clear_prefix_version_3
(param $storage_key i64) (param $prefix i64) (param $maybe_limit i64)
(param $maybe_cursor_in i64) (param $maybe_cursor_out i64) (param $counters i32)
(result i32))
</code></pre>
<h5 id="arguments-6"><a class="header" href="#arguments-6">Arguments</a></h5>
<ul>
<li><code>storage_key</code> is a pointer-size (<a href="https://spec.polkadot.network/chap-host-api#defn-runtime-pointer-size">Definition 216</a>) to the child storage key (<a href="https://spec.polkadot.network/chap-host-api#defn-child-storage-type">Definition 219</a>);</li>
<li><code>prefix</code> is a pointer-size (<a href="https://spec.polkadot.network/chap-host-api#defn-runtime-pointer-size">Definition 216</a>) containing a storage prefix being cleared;</li>
<li><code>maybe_limit</code> is an optional positive integer representing either the maximum number of backend deletions which may happen, or the absence of such a limit. The number of backend iterations may surpass this limit by no more than one;</li>
<li><code>maybe_cursor_in</code> is an optional pointer-size representing the cursor returned by the previous (unfinished) call to this function. It should be <em>absent</em> on the first call;</li>
<li><code>maybe_cursor_out</code> is a pointer-size (<a href="https://spec.polkadot.network/chap-host-api#defn-runtime-pointer-size">Definition 216</a>) to a buffer where the continuation cursor will optionally be written (see also the Result section). The value is actually stored only if the buffer is large enough. Whenever the value is not written into the buffer, the buffer contents are unmodified;</li>
<li><code>counters</code> is a pointer (<a href="https://spec.polkadot.network/chap-host-api#defn-runtime-pointer">Definition 215</a>) to a 12-byte buffer where three low-endian 32-bit integers will be stored one after another, representing the counters, respectively:
<ul>
<li>Of items removed from the backend database will be written;</li>
<li>Of unique keys removed, taking into account both the backend and the overlay;</li>
<li>Of iterations (each requiring a storage seek/read) which were done.</li>
</ul>
</li>
</ul>
<h5 id="result-5"><a class="header" href="#result-5">Result</a></h5>
<p>The result represents the length of the continuation cursor which might have been written to the buffer provided in <code>maybe_cursor_out</code>. A zero value represents the absence of such a cursor and no need for continuation (the prefix has been completely cleared).</p>
<h4 id="ext_default_child_storage_root"><a class="header" href="#ext_default_child_storage_root">ext_default_child_storage_root</a></h4>
<h5 id="existing-prototype-9"><a class="header" href="#existing-prototype-9">Existing prototype</a></h5>
<pre><code class="language-wat">(func $ext_default_child_storage_root_version_2
(param $child_storage_key i64) (param $version i32) (result i64))
</code></pre>
<h5 id="changes-9"><a class="header" href="#changes-9">Changes</a></h5>
<p>The old version accepted (along with the child storage key) the state version as an argument and returned a SCALE-encoded trie root hash through a host-allocated buffer. The new version adopts <a href="https://github.com/w3f/PPPs/pull/6">PPP#6</a> getting rid of the argument that used to represent the state version. It accepts a pointer to a runtime-allocated buffer and fills it with the output value. The length of the encoded result is returned.</p>
<h5 id="new-prototype-7"><a class="header" href="#new-prototype-7">New prototype</a></h5>
<pre><code class="language-wat">(func $ext_default_child_storage_root_version_3
(param $storage_key i64) (param $out i64) (result i32))
</code></pre>
<h5 id="arguments-7"><a class="header" href="#arguments-7">Arguments</a></h5>
<ul>
<li><code>storage_key</code> is a pointer-size (<a href="https://spec.polkadot.network/chap-host-api#defn-runtime-pointer-size">Definition 216</a>) to the child storage key (<a href="https://spec.polkadot.network/chap-host-api#defn-child-storage-type">Definition 219</a>);</li>
<li><code>out</code> is a pointer-size (<a href="https://spec.polkadot.network/chap-host-api#defn-runtime-pointer-size">Definition 216</a>) to a buffer where the SCALE-encoded storage root, calculated after committing all the existing operations, will be stored. The value is actually stored only if the buffer is large enough. Otherwise, the buffer is not written into and its contents are unchanged.</li>
</ul>
<h5 id="results-1"><a class="header" href="#results-1">Results</a></h5>
<p>The result is the length of the output that mught have been stored in the buffer provided in <code>out</code>.</p>
<h4 id="ext_default_child_storage_next_key"><a class="header" href="#ext_default_child_storage_next_key">ext_default_child_storage_next_key</a></h4>
<h5 id="existing-prototype-10"><a class="header" href="#existing-prototype-10">Existing prototype</a></h5>
<pre><code class="language-wat">(func $ext_default_child_storage_next_key_version_1
(param $child_storage_key i64) (param $key i64) (result i64))
</code></pre>
<h5 id="changes-10"><a class="header" href="#changes-10">Changes</a></h5>
<p>The old version accepted (along with the child storage key) the key and returned the SCALE-encoded next key in a host-allocated buffer. The new version additionally accepts a runtime-allocated output buffer and returns full next key length.</p>
<h5 id="new-prototype-8"><a class="header" href="#new-prototype-8">New prototype</a></h5>
<pre><code class="language-wat">(func $ext_default_child_storage_next_key_version_2
(param $storage_key i64) (param $key_in i64) (param $key_out i64) (result i32))
</code></pre>
<h5 id="arguments-8"><a class="header" href="#arguments-8">Arguments</a></h5>
<ul>
<li><code>storage_key</code> is a pointer-size (<a href="https://spec.polkadot.network/chap-host-api#defn-runtime-pointer-size">Definition 216</a>) to the child storage key (<a href="https://spec.polkadot.network/chap-host-api#defn-child-storage-type">Definition 219</a>);</li>
<li><code>key_in</code> is a pointer-size (<a href="https://spec.polkadot.network/chap-host-api#defn-runtime-pointer-size">Definition 216</a>) to a buffer containing a storage key;</li>
<li><code>key_out</code> is a pointer-size (<a href="https://spec.polkadot.network/chap-host-api#defn-runtime-pointer-size">Definition 216</a>) to an output buffer where the next key in the storage in the lexicographical order will be written. The value is actually stored only if the buffer is large enough. Otherwise, the buffer is not written into and its contents are unchanged.</li>
</ul>
<h5 id="result-6"><a class="header" href="#result-6">Result</a></h5>
<p>The result is the length of the output key that might have been written into <code>key_out</code>, or zero if no next key was found.</p>
<h4 id="ext_trie_blake2keccak_256_ordered_root"><a class="header" href="#ext_trie_blake2keccak_256_ordered_root">ext_trie_{blake2|keccak}_256_[ordered_]root</a></h4>
<h5 id="existing-prototypes"><a class="header" href="#existing-prototypes">Existing prototypes</a></h5>
<pre><code class="language-wat">(func $ext_trie_{blake2|keccak}_256_[ordered_]root_version_2
(param $data i64) (param $version i32) (result i32))
</code></pre>
<h5 id="changes-11"><a class="header" href="#changes-11">Changes</a></h5>
<p>The following functions share the same signatures and set of changes:</p>
<ul>
<li><code>ext_trie_blake2_256_root</code></li>
<li><code>ext_trie_blake2_256_ordered_root</code></li>
<li><code>ext_trie_keccak_256_root</code></li>
<li><code>ext_trie_keccak_256_ordered_root</code></li>
</ul>
<p>The functions used to return the root in a 32-byte host-allocated buffer. They now accept a runtime-allocated output buffer as an argument, and doesn't return anything.</p>
<h5 id="new-prototypes"><a class="header" href="#new-prototypes">New prototypes</a></h5>
<pre><code class="language-wat">(func $ext_trie_{blake2|keccak}_256_[ordered_]root_version_3
(param $input i64) (param $version i32) (param $out i32))
</code></pre>
<h5 id="arguments-9"><a class="header" href="#arguments-9">Arguments</a></h5>
<ul>
<li><code>input</code> is a pointer-size (<a href="https://spec.polkadot.network/chap-host-api#defn-runtime-pointer-size">Definition 216</a>) to the SCALE-encoded vector of the trie key-value pairs;</li>
<li><code>version</code> is the state version, where <code>0</code> denotes V0 and <code>1</code> denotes V1 state version. Other state versions may be introduced in the future;</li>
<li><code>out</code> is a pointer (<a href="https://spec.polkadot.network/chap-host-api#defn-runtime-pointer">Definition 215</a>) to a 32-byte buffer, where the calculated trie root will be stored.</li>
</ul>
<h4 id="ext_misc_runtime_version"><a class="header" href="#ext_misc_runtime_version">ext_misc_runtime_version</a></h4>
<h5 id="existing-prototype-11"><a class="header" href="#existing-prototype-11">Existing prototype</a></h5>
<pre><code class="language-wat">(func $ext_misc_runtime_version_version_1
(param $data i64) (result i64))
</code></pre>
<h5 id="changes-12"><a class="header" href="#changes-12">Changes</a></h5>
<p>The function used to return the SCALE-encoded runtime version information in a host-allocated buffer. It is changed to accept a runtime-allocated buffer as an arguments and to return the length of the SCALE-encoded result.</p>
<h5 id="new-prototype-9"><a class="header" href="#new-prototype-9">New prototype</a></h5>
<pre><code class="language-wat">(func $ext_misc_runtime_version_version_2
(param $wasm i64) (param $out i64) (result i64))
</code></pre>
<h5 id="arguments-10"><a class="header" href="#arguments-10">Arguments</a></h5>
<ul>
<li><code>wasm</code> is a pointer-size (<a href="https://spec.polkadot.network/chap-host-api#defn-runtime-pointer-size">Definition 216</a>) to the Wasm blob from which the version information should be extracted;</li>
<li><code>out</code> is a pointer-size (<a href="https://spec.polkadot.network/chap-host-api#defn-runtime-pointer-size">Definition 216</a>) to the buffer where the SCALE-encoded extracted version information will be stored. The value is actually stored only if the buffer is large enough. Otherwise, the buffer is not written into and its contents are unchanged.</li>
</ul>
<h5 id="result-7"><a class="header" href="#result-7">Result</a></h5>
<p>The result is an optional positive integer (<a href="#new-def-i">New Definition I</a>) representing the length of the output data that might have been stored in <code>out</code>. An <em>absent</em> value represents the absence of the version information in the Wasm blob or a failure to read one.</p>
<h4 id="ext_misc_last_cursor"><a class="header" href="#ext_misc_last_cursor">ext_misc_last_cursor</a></h4>
<h5 id="changes-13"><a class="header" href="#changes-13">Changes</a></h5>
<p>A new function is introduced to make it possible to fetch a cursor produced by <code>ext_storage_clear_prefix</code>, <code>ext_default_child_storage_clear_prefix</code>, and <code>ext_default_child_storage_kill_prefix</code> even if a buffer initially provided to those functions wasn't large enough to accommodate the cursor.</p>
<h5 id="new-prototype-10"><a class="header" href="#new-prototype-10">New prototype</a></h5>
<pre><code class="language-wat">(func $ext_misc_last_cursor_version_1
(param $out i64) (result i64))
</code></pre>
<h5 id="arguments-11"><a class="header" href="#arguments-11">Arguments</a></h5>
<ul>
<li><code>out</code> is a pointer-size (<a href="https://spec.polkadot.network/chap-host-api#defn-runtime-pointer-size">Definition 216</a>) to the buffer where the last cached cursor will be stored, if one exists. The value is actually stored only if the buffer is large enough. Otherwise, the buffer is not written into and its contents are unchanged.</li>
</ul>
<h5 id="result-8"><a class="header" href="#result-8">Result</a></h5>
<p>The result is an optional positive integer (<a href="#new-def-i">New Definition I</a>) representing the length of the cursor that might have been stored in <code>out</code>. An <em>absent</em> value represents the absence of the cached cursor.</p>
<p>If the buffer had enough capacity and the cursor was stored successfully, the cursor cache is cleared and the same cursor cannot be retrieved once again using this function.</p>
<h4 id="ext_crypto_ed25519sr25519ecdsa_public_keys"><a class="header" href="#ext_crypto_ed25519sr25519ecdsa_public_keys">ext_crypto_{ed25519|sr25519|ecdsa}_public_keys</a></h4>
<h5 id="existing-prototypes-1"><a class="header" href="#existing-prototypes-1">Existing prototypes</a></h5>
<pre><code class="language-wat">(func $ext_crypto_ed25519_public_keys_version_1
(param $key_type_id i32) (result i64))
(func $ext_crypto_sr25519_public_keys_version_1
(param $key_type_id i32) (result i64))
(func $ext_crypto_ecdsa_public_keys_version_1
(param $key_type_id i32) (result i64))
</code></pre>
<h5 id="changes-14"><a class="header" href="#changes-14">Changes</a></h5>
<p>The following functions are considered obsolete in favor of the new <code>*_num_public_keys</code> and <code>*_public_key</code> counterparts:</p>
<ul>
<li><code>ext_crypto_ed25519_public_keys_version_1</code></li>
<li><code>ext_crypto_sr25519_public_keys_version_1</code></li>
<li><code>ext_crypto_ecdsa_public_keys_version_1</code></li>
</ul>
<p>They cannot be used in a runtime using the new-style of entry-point.</p>
<h4 id="ext_crypto_ed25519sr25519ecdsa_num_public_keys"><a class="header" href="#ext_crypto_ed25519sr25519ecdsa_num_public_keys">ext_crypto_{ed25519|sr25519|ecdsa}_num_public_keys</a></h4>
<h5 id="changes-15"><a class="header" href="#changes-15">Changes</a></h5>
<p>New functions, all sharing the same signature and logic, are introduced:</p>
<ul>
<li><code>ext_crypto_ed25519_num_public_keys_version_1</code></li>
<li><code>ext_crypto_sr25519_num_public_keys_version_1</code></li>
<li><code>ext_crypto_ecdsa_num_public_keys_version_1</code></li>
</ul>
<p>They are intended to replace the obsolete <code>ext_crypto_{ed25519|sr25519|ecdsa}_public_keys</code> with a new iterative approach.</p>
<h5 id="new-prototypes-1"><a class="header" href="#new-prototypes-1">New prototypes</a></h5>
<pre><code class="language-wat">(func $ext_crypto_{ed25519|sr25519|ecdsa}_num_public_keys
(param $id i32) (result i32))
</code></pre>
<h5 id="arguments-12"><a class="header" href="#arguments-12">Arguments</a></h5>
<ul>
<li><code>id</code> is a pointer (<a href="https://spec.polkadot.network/chap-host-api#defn-runtime-pointer">Definition 215</a>) to the key type identifier (<a href="https://spec.polkadot.network/chap-host-api#defn-key-type-id">Definition 220</a>).</li>
</ul>
<h5 id="result-9"><a class="header" href="#result-9">Result</a></h5>
<p>The result represents a (possibly zero) number of keys of the given type known to the keystore.</p>
<h4 id="ext_crypto_ed25519sr25519ecdsa_public_key"><a class="header" href="#ext_crypto_ed25519sr25519ecdsa_public_key">ext_crypto_{ed25519|sr25519|ecdsa}_public_key</a></h4>
<h5 id="changes-16"><a class="header" href="#changes-16">Changes</a></h5>
<p>New functions, all sharing the same signature and logic, are introduced:</p>
<ul>
<li><code>ext_crypto_ed25519_public_key_version_1</code></li>
<li><code>ext_crypto_sr25519_public_key_version_1</code></li>
<li><code>ext_crypto_ecdsa_public_key_version_1</code></li>
</ul>
<p>They are intended to replace the obsolete <code>ext_crypto_{ed25519|sr25519|ecdsa}_public_keys</code> with a new iterative approach.</p>
<h5 id="new-prototypes-2"><a class="header" href="#new-prototypes-2">New prototypes</a></h5>
<pre><code class="language-wat">(func $ext_crypto_{ed25519|sr25519|ecdsa}_public_key
(param $id i32) (param $index i32) (param $out))
</code></pre>
<h5 id="arguments-13"><a class="header" href="#arguments-13">Arguments</a></h5>
<ul>
<li><code>id</code> is a pointer (<a href="https://spec.polkadot.network/chap-host-api#defn-runtime-pointer">Definition 215</a>) to the key type identifier (<a href="https://spec.polkadot.network/chap-host-api#defn-key-type-id">Definition 220</a>).</li>
<li><code>index</code> is the index of the key in the keystore. If the index is out of bounds (determined by the value returned by the respective <code>_num_public_keys</code> function) the function will panic;</li>
<li><code>out</code> is a pointer (<a href="https://spec.polkadot.network/chap-host-api#defn-runtime-pointer">Definition 215</a>) to the output buffer of the respective size (depending on key type) where the key will be written.</li>
</ul>
<h4 id="ext_crypto_ed25519sr25519ecdsa_generate"><a class="header" href="#ext_crypto_ed25519sr25519ecdsa_generate">ext_crypto_{ed25519|sr25519|ecdsa}_generate</a></h4>
<h5 id="existing-prototypes-2"><a class="header" href="#existing-prototypes-2">Existing prototypes</a></h5>
<pre><code class="language-wat">(func $ext_crypto_{ed25519|sr25519|ecdsa}_generate_version_1
(param $key_type_id i32) (param $seed i64) (result i32))
</code></pre>
<h5 id="changes-17"><a class="header" href="#changes-17">Changes</a></h5>
<p>The following functions share the same signatures and set of changes:</p>
<ul>
<li><code>ext_crypto_ed25519_generate</code></li>
<li><code>ext_crypto_sr25519_generate</code></li>
<li><code>ext_crypto_ecdsa_generate</code></li>
</ul>
<p>The functions used to return a host-allocated buffer containing the key of the corresponding type. They are changed to accept a runtime-allocated buffer as an argument and to return no value, as the length of keys is known and the operation cannot fail.</p>
<h5 id="new-prototypes-3"><a class="header" href="#new-prototypes-3">New prototypes</a></h5>
<pre><code class="language-wat">(func $ext_crypto_{ed25519|sr25519|ecdsa}_generate_version_2
(param $id i32) (param $seed i64) (param $out i32))
</code></pre>
<h5 id="arguments-14"><a class="header" href="#arguments-14">Arguments</a></h5>
<ul>
<li><code>id</code> is a pointer (<a href="https://spec.polkadot.network/chap-host-api#defn-runtime-pointer">Definition 215</a>) to the key type identifier (<a href="https://spec.polkadot.network/chap-host-api#defn-key-type-id">Definition 220</a>). The function will panic if the identifier is invalid;</li>
<li><code>seed</code> is a pointer-size (<a href="https://spec.polkadot.network/chap-host-api#defn-runtime-pointer-size">Definition 216</a>) to the SCALE-encoded Option value (<a href="https://spec.polkadot.network/id-cryptography-encoding#defn-option-type">Definition 200</a>) containing the BIP-39 seed which must be valid UTF-8. The function will panic if the seed is not valid UTF-8;</li>
<li><code>out</code> is a pointer (<a href="https://spec.polkadot.network/chap-host-api#defn-runtime-pointer">Definition 215</a>) to the output buffer of the respective size (depending on key type) where the generated key will be written.</li>
</ul>
<h4 id="ext_crypto_ed25519sr25519ecdsa_sign_prehashed"><a class="header" href="#ext_crypto_ed25519sr25519ecdsa_sign_prehashed">ext_crypto_{ed25519|sr25519|ecdsa}_sign[_prehashed]</a></h4>
<h5 id="existing-prototypes-3"><a class="header" href="#existing-prototypes-3">Existing prototypes</a></h5>
<pre><code class="language-wat">(func $ext_crypto_{ed25519|sr25519|ecdsa}_sign{_prehashed|}_version_1
(param $id i32) (param $pub_key i32) (param $msg i64) (result i64))
</code></pre>
<h5 id="changes-18"><a class="header" href="#changes-18">Changes</a></h5>
<p>The following functions share the same signatures and set of changes:</p>
<ul>
<li><code>ext_crypto_ed25519_sign</code></li>
<li><code>ext_crypto_sr25519_sign</code></li>
<li><code>ext_crypto_ecdsa_sign</code></li>
<li><code>ext_crypto_ecdsa_sign_prehashed</code></li>
</ul>
<p>The functions used to return a host-allocated SCALE-encoded value representing the result of signature application. They are changed to accept a pointer to a runtime-allocated buffer of a known size (dependent on the signature type) and to return a result code.</p>
<h4 id="new-prototypes-4"><a class="header" href="#new-prototypes-4">New prototypes</a></h4>
<pre><code class="language-wat">(func $ext_crypto_{ed25519|sr25519|ecdsa}_sign{_prehashed|}_version_2
(param $id i32) (param $pub_key i32) (param $msg i64) (param $out i64) (result i64))
</code></pre>
<h5 id="arguments-15"><a class="header" href="#arguments-15">Arguments</a></h5>
<ul>
<li><code>id</code> is a pointer (<a href="https://spec.polkadot.network/chap-host-api#defn-runtime-pointer">Definition 215</a>) to the key type identifier (<a href="https://spec.polkadot.network/chap-host-api#defn-key-type-id">Definition 220</a>). The function will panic if the identifier is invalid;</li>
<li><code>pub_key</code> is a pointer (<a href="https://spec.polkadot.network/chap-host-api#defn-runtime-pointer">Definition 215</a>) to the public key bytes (as returned by the respective <code>_public_key</code> function);</li>
<li><code>msg</code> is a pointer-size (<a href="https://spec.polkadot.network/chap-host-api#defn-runtime-pointer-size">Definition 216</a>) to the message that is to be signed;</li>
<li><code>out</code> is a pointer (<a href="https://spec.polkadot.network/chap-host-api#defn-runtime-pointer">Definition 215</a>) to the output buffer of the respective size (depending on key type) where the signature will be written.</li>
</ul>
<h5 id="result-10"><a class="header" href="#result-10">Result</a></h5>
<p>The function returns <code>0</code> on success. On error, <code>-1</code> is returned and the output buffer should be considered uninitialized.</p>
<h4 id="ext_crypto_secp256k1_ecdsa_recover_compressed"><a class="header" href="#ext_crypto_secp256k1_ecdsa_recover_compressed">ext_crypto_secp256k1_ecdsa_recover[_compressed]</a></h4>
<h5 id="existing-prototypes-4"><a class="header" href="#existing-prototypes-4">Existing prototypes</a></h5>
<pre><code class="language-wat">(func $ext_crypto_secp256k1_ecdsa_recover\[_compressed]_version_2
(param $sig i32) (param $msg i32) (result i64))
</code></pre>
<h5 id="changes-19"><a class="header" href="#changes-19">Changes</a></h5>
<p>The following functions share the same signatures and set of changes:</p>
<ul>
<li><code>ext_crypto_secp256k1_ecdsa_recover</code></li>
<li><code>ext_crypto_secp256k1_ecdsa_recover_compressed</code></li>
</ul>
<p>The functions used to return a host-allocated SCALE-encoded value representing the result of the key recovery. They are changed to accept a pointer to a runtime-allocated buffer of a known size and to return a result code. The return error encoding, defined under <a href="https://spec.polkadot.network/chap-host-api#defn-ecdsa-verify-error">Definition 221</a>, is changed to promote the unification of host function result reporting (zero and positive values are for success, and the negative values are for failure codes).</p>
<h5 id="new-prototypes-5"><a class="header" href="#new-prototypes-5">New prototypes</a></h5>
<pre><code class="language-wat">(func $ext_crypto_secp256k1_ecdsa_recover\[_compressed]_version_3
(param $sig i32) (param $msg i32) (param $out i32) (result i64))
</code></pre>
<h5 id="arguments-16"><a class="header" href="#arguments-16">Arguments</a></h5>
<ul>
<li><code>sig</code> is a pointer (<a href="https://spec.polkadot.network/chap-host-api#defn-runtime-pointer">Definition 215</a>) to the buffer containing the 65-byte signature in RSV format. V must be either 0/1 or 27/28;</li>
<li><code>msg</code> is a pointer (<a href="https://spec.polkadot.network/chap-host-api#defn-runtime-pointer">Definition 215</a>) to the buffer containing the 256-bit Blake2 hash of the message;</li>
<li><code>out</code> is a pointer (<a href="https://spec.polkadot.network/chap-host-api#defn-runtime-pointer">Definition 215</a>) to the output buffer of the respective size (depending on key type) where the recovered public key will be written.</li>
</ul>
<h5 id="result-11"><a class="header" href="#result-11">Result</a></h5>
<p>The function returns <code>0</code> on success. On error, it returns a negative ECDSA verification error code, where <code>-1</code> stands for incorrect R or S, <code>-2</code> stands for invalid V, and <code>-3</code> stands for invalid signature.</p>
<h4 id="ext_hashing_keccaksha2blake2twox_"><a class="header" href="#ext_hashing_keccaksha2blake2twox_">ext_hashing_{keccak|sha2|blake2|twox}_</a></h4>
<h5 id="existing-prototypes-5"><a class="header" href="#existing-prototypes-5">Existing prototypes</a></h5>
<pre><code class="language-wat">(func $ext_hashing_{keccak|sha2|blake2|twox}_{64|128|256|512}_version_1
(param $data i64) (result i32))
</code></pre>
<h5 id="changes-20"><a class="header" href="#changes-20">Changes</a></h5>
<p>The following functions share the same signatures and set of changes:</p>
<ul>
<li><code>ext_hashing_keccak_256</code></li>
<li><code>ext_hashing_keccak_512</code></li>
<li><code>ext_hashing_sha2_256</code></li>
<li><code>ext_hashing_blake2_128</code></li>
<li><code>ext_hashing_blake2_256</code></li>
<li><code>ext_hashing_twox_64</code></li>
<li><code>ext_hashing_twox_128</code></li>
<li><code>ext_hashing_twox_256</code></li>
</ul>
<p>The functions used to return a host-allocated buffer containing the hash. They are changed to accept a runtime-allocated buffer of a known size (depedent on the hash type) and to return no value, as the operation cannot fail.</p>
<h5 id="new-prototypes-6"><a class="header" href="#new-prototypes-6">New prototypes</a></h5>
<pre><code class="language-wat">(func $ext_hashing_{keccak|sha2|blake2|twox}_{64|128|256|512}_version_2
(param $data i64) (param $out i32))
</code></pre>
<h5 id="arguments-17"><a class="header" href="#arguments-17">Arguments</a></h5>
<ul>
<li><code>data</code> is a pointer-size (<a href="https://spec.polkadot.network/chap-host-api#defn-runtime-pointer-size">Definition 216</a>) to the data to be hashed.</li>
<li><code>out</code> is a pointer (<a href="https://spec.polkadot.network/chap-host-api#defn-runtime-pointer">Definition 215</a>) to the output buffer of the respective size (depending on hash type) where the calculated hash will be written.</li>
</ul>
<h4 id="ext_offchain_submit_transaction"><a class="header" href="#ext_offchain_submit_transaction">ext_offchain_submit_transaction</a></h4>
<h5 id="existing-prototype-12"><a class="header" href="#existing-prototype-12">Existing prototype</a></h5>
<pre><code class="language-wat">(func $ext_offchain_submit_transaction_version_1
(param $data i64) (result i64))
</code></pre>
<h5 id="changes-21"><a class="header" href="#changes-21">Changes</a></h5>
<p>The old version returned a SCALE-encoded result in a host-allocated buffer. That is changed to return the result as a primitive value.</p>
<h5 id="new-prototype-11"><a class="header" href="#new-prototype-11">New prototype</a></h5>
<pre><code class="language-wat">(func $ext_offchain_submit_transaction_version_2
(param $data i64) (result i64))
</code></pre>
<h5 id="arguments-18"><a class="header" href="#arguments-18">Arguments</a></h5>
<ul>
<li><code>data</code> is a pointer-size (<a href="https://spec.polkadot.network/chap-host-api#defn-runtime-pointer-size">Definition 216</a>) to the byte array storing the encoded extrinsic.</li>
</ul>
<h5 id="result-12"><a class="header" href="#result-12">Result</a></h5>
<p>The result is <code>0</code> for success or <code>-1</code> for failure.</p>
<h4 id="ext_offchain_network_state"><a class="header" href="#ext_offchain_network_state">ext_offchain_network_state</a></h4>
<h5 id="existing-prototype-13"><a class="header" href="#existing-prototype-13">Existing prototype</a></h5>
<pre><code class="language-wat">(func $ext_offchain_network_state_version_1
(result i64))
</code></pre>
<h5 id="changes-22"><a class="header" href="#changes-22">Changes</a></h5>
<p>Considered obsolete in favor of <code>ext_offchain_network_peer_id_version_1</code>. Cannot be used in a runtime using the new-style of entry-point.</p>
<h4 id="ext_offchain_network_peer_id"><a class="header" href="#ext_offchain_network_peer_id">ext_offchain_network_peer_id</a></h4>
<h5 id="changes-23"><a class="header" href="#changes-23">Changes</a></h5>
<p>A new function is introduced to replace <code>ext_offchain_network_state</code>. It fills the output buffer with an opaque peer id of a known size.</p>
<h5 id="new-prototype-12"><a class="header" href="#new-prototype-12">New prototype</a></h5>
<pre><code class="language-wat">(func $ext_offchain_submit_transaction_version_2
(param $out i32) (result i64))
</code></pre>
<h5 id="arguments-19"><a class="header" href="#arguments-19">Arguments</a></h5>
<ul>
<li><code>out</code> is a pointer (<a href="https://spec.polkadot.network/chap-host-api#defn-runtime-pointer">Definition 215</a>) to the output buffer, 38 bytes long, where the network peer ID will be written.</li>
</ul>
<h5 id="result-13"><a class="header" href="#result-13">Result</a></h5>
<p>The result is <code>0</code> for success or <code>-1</code> for failure.</p>
<h4 id="ext_offchain_random_seed"><a class="header" href="#ext_offchain_random_seed">ext_offchain_random_seed</a></h4>
<h5 id="existing-prototype-14"><a class="header" href="#existing-prototype-14">Existing prototype</a></h5>
<pre><code class="language-wat">(func $ext_offchain_random_seed_version_1
(result i32))
</code></pre>
<h5 id="changes-24"><a class="header" href="#changes-24">Changes</a></h5>
<p>The function used to return a host-allocated buffer containing the random seed. It is changed to accept a pointer to a runtime-allocated buffer where the random seed is written and to return no value as the operation cannot fail.</p>
<h5 id="new-prototype-13"><a class="header" href="#new-prototype-13">New prototype</a></h5>
<pre><code class="language-wat">(func $ext_offchain_random_seed_version_2
(param $out i32))
</code></pre>
<h5 id="arguments-20"><a class="header" href="#arguments-20">Arguments</a></h5>
<ul>
<li><code>out</code> is a pointer (<a href="https://spec.polkadot.network/chap-host-api#defn-runtime-pointer">Definition 215</a>) to the output buffer, 32 bytes long, where the random seed will be written.</li>
</ul>
<h4 id="ext_offchain_local_storage_get"><a class="header" href="#ext_offchain_local_storage_get">ext_offchain_local_storage_get</a></h4>
<h5 id="existing-prototype-15"><a class="header" href="#existing-prototype-15">Existing prototype</a></h5>
<pre><code class="language-wat">(func $ext_offchain_local_storage_get_version_1
(param $kind i32) (param $key i64) (result i64))
</code></pre>
<h5 id="changes-25"><a class="header" href="#changes-25">Changes</a></h5>
<p>Considered obsolete in favor of <code>ext_offchain_local_storage_read_version_1</code>. Cannot be used in a runtime using the new-style of entry-point.</p>
<h4 id="ext_offchain_local_storage_read"><a class="header" href="#ext_offchain_local_storage_read">ext_offchain_local_storage_read</a></h4>
<h5 id="changes-26"><a class="header" href="#changes-26">Changes</a></h5>
<p>A new function is introduced to replace <code>ext_offchain_local_storage_get</code>. The name has been changed to better correspond to the family of the same-functionality functions in <code>ext_storage_*</code> group.</p>
<h5 id="new-prototype-14"><a class="header" href="#new-prototype-14">New prototype</a></h5>
<pre><code class="language-wat">(func $ext_offchain_local_storage_read_version_1
(param $kind i32) (param $key i64) (param $value_out i64) (param $offset i32) (result i64))
</code></pre>
<h5 id="arguments-21"><a class="header" href="#arguments-21">Arguments</a></h5>
<ul>
<li><code>kind</code> is an offchain storage kind, where <code>0</code> denotes the persistent storage (<a href="https://spec.polkadot.network/chap-host-api#defn-offchain-persistent-storage">Definition 222</a>), and <code>1</code> denotes the local storage (<a href="https://spec.polkadot.network/chap-host-api#defn-offchain-persistent-storage">Definition 223</a>);</li>
<li><code>key</code> is a pointer-size (<a href="https://spec.polkadot.network/chap-host-api#defn-runtime-pointer-size">Definition 216</a>) to the storage key being read;</li>
<li><code>value_out</code> is a pointer-size (<a href="https://spec.polkadot.network/chap-host-api#defn-runtime-pointer-size">Definition 216</a>) to a buffer where the value read should be stored. The value is actually stored only if the buffer is large enough. Otherwise, the buffer is not written into and its contents are unchanged;</li>
<li><code>offset</code> is a 32-bit offset from which the value reading should start.</li>
</ul>
<h5 id="result-14"><a class="header" href="#result-14">Result</a></h5>
<p>The result is an optional positive integer (<a href="#new-def-i">New Definition I</a>), representing either the full length of the value in storage or the <em>absence</em> of such a value in storage.</p>
<h4 id="ext_offchain_http_request_start"><a class="header" href="#ext_offchain_http_request_start">ext_offchain_http_request_start</a></h4>
<h5 id="existing-prototype-16"><a class="header" href="#existing-prototype-16">Existing prototype</a></h5>
<pre><code class="language-wat">(func $ext_offchain_http_request_start_version_1
(param $method i64) (param $uri i64) (param $meta i64) (result i64))
</code></pre>
<h5 id="changes-27"><a class="header" href="#changes-27">Changes</a></h5>
<p>The function used to return a SCALE-encoded <code>Result</code> value in a host-allocated buffer. That is changed to return a primitive value denoting the operation result. The result interpretation has been changed to promote the unification of host function result returning (zero and positive values are for success, and the negative values are for failure codes).</p>
<h5 id="new-prototype-15"><a class="header" href="#new-prototype-15">New prototype</a></h5>
<pre><code class="language-wat">(func $ext_offchain_http_request_start_version_2
(param $method i64) (param $uri i64) (param $meta i64) (result i64))
</code></pre>
<h5 id="arguments-22"><a class="header" href="#arguments-22">Arguments</a></h5>
<p><code>method</code> is a pointer-size (<a href="https://spec.polkadot.network/chap-host-api#defn-runtime-pointer-size">Definition 216</a>) to the HTTP method. Possible values are “GET” and “POST”;
<code>uri</code> is a pointer-size (<a href="https://spec.polkadot.network/chap-host-api#defn-runtime-pointer-size">Definition 216</a>) to the URI;
<code>meta</code> is a future-reserved field containing additional, SCALE-encoded parameters. Currently, its value is ignored. Passing a pointer to non-readable memory shall not result in execution abortion.</p>
<h5 id="result-15"><a class="header" href="#result-15">Result</a></h5>
<p>On success, a positive request identifier is returned. On error, <code>-1</code> is returned.</p>
<h4 id="ext_offchain_http_request_add_header"><a class="header" href="#ext_offchain_http_request_add_header">ext_offchain_http_request_add_header</a></h4>
<h5 id="existing-prototype-17"><a class="header" href="#existing-prototype-17">Existing prototype</a></h5>
<pre><code class="language-wat">(func $ext_offchain_http_request_add_header_version_1
(param $request_id i32) (param $name i64) (param $value i64) (result i64))
</code></pre>
<h5 id="changes-28"><a class="header" href="#changes-28">Changes</a></h5>
<p>The function used to return a SCALE-encoded <code>Result</code> value in a host-allocated buffer. That is changed to return a primitive value denoting the operation result. The result interpretation has been changed to promote the unification of host function result returning (zero and positive values are for success, and the negative values are for failure codes).</p>
<h5 id="new-prototype-16"><a class="header" href="#new-prototype-16">New prototype</a></h5>
<pre><code class="language-wat">(func $ext_offchain_http_request_add_header_version_2
(param $request_id i32) (param $name i64) (param $value i64) (result i64))
</code></pre>
<h5 id="arguments-23"><a class="header" href="#arguments-23">Arguments</a></h5>
<ul>
<li><code>request_id</code> is an i32 integer indicating the ID of the started request, as returned by <code>ext_offchain_http_request_start</code>;</li>
<li><code>name</code> is a pointer-size (<a href="https://spec.polkadot.network/chap-host-api#defn-runtime-pointer-size">Definition 216</a>) to the HTTP header name;</li>
<li><code>value</code> is a pointer-size (<a href="https://spec.polkadot.network/chap-host-api#defn-runtime-pointer-size">Definition 216</a>) to the HTTP header value.</li>
</ul>
<h5 id="result-16"><a class="header" href="#result-16">Result</a></h5>
<p>The result is <code>0</code> for success or <code>-1</code> for failure.</p>
<h4 id="ext_offchain_http_request_write_body"><a class="header" href="#ext_offchain_http_request_write_body">ext_offchain_http_request_write_body</a></h4>
<h5 id="existing-prototype-18"><a class="header" href="#existing-prototype-18">Existing prototype</a></h5>
<pre><code class="language-wat">(func $ext_offchain_http_request_write_body_version_1
(param $request_id i32) (param $chunk i64) (param $deadline i64) (result i64))
</code></pre>
<h5 id="changes-29"><a class="header" href="#changes-29">Changes</a></h5>
<p>The function used to return a SCALE-encoded <code>Result</code> value in a host-allocated buffer. That is changed to return a primitive value denoting the operation result. The result interpretation has been changed to promote the unification of host function result returning (zero and positive values are for success, and the negative values are for failure codes).</p>
<h5 id="new-prototype-17"><a class="header" href="#new-prototype-17">New prototype</a></h5>
<pre><code class="language-wat">(func $ext_offchain_http_request_write_body_version_2
(param $request_id i32) (param $chunk i64) (param $deadline i64) (result i64))
</code></pre>
<h5 id="arguments-24"><a class="header" href="#arguments-24">Arguments</a></h5>
<ul>
<li><code>request_id</code> is an i32 integer indicating the ID of the started request, as returned by <code>ext_offchain_http_request_start</code>;</li>
<li><code>chunk</code> is a pointer-size (<a href="https://spec.polkadot.network/chap-host-api#defn-runtime-pointer-size">Definition 216</a>) to the chunk of bytes. Writing an empty chunk finalizes the request;</li>
<li><code>deadline</code> is a pointer-size (<a href="https://spec.polkadot.network/chap-host-api#defn-runtime-pointer-size">Definition 216</a>) to the SCALE-encoded Option value (<a href="https://spec.polkadot.network/id-cryptography-encoding#defn-option-type">Definition 200</a>) containing the UNIX timestamp (<a href="https://spec.polkadot.network/id-cryptography-encoding#defn-unix-time">Definition 191</a>). Passing <code>None</code> blocks indefinitely.</li>
</ul>
<h5 id="result-17"><a class="header" href="#result-17">Result</a></h5>
<p>On success, <code>0</code> is returned. On failure, a negative error code is returned, where <code>-1</code> denotes the deadline was reached, <code>-2</code> denotes that an I/O error occurred, and <code>-3</code> denotes that the request ID provided was invalid.</p>
<h4 id="ext_offchain_http_response_wait"><a class="header" href="#ext_offchain_http_response_wait">ext_offchain_http_response_wait</a></h4>
<h5 id="existing-prototype-19"><a class="header" href="#existing-prototype-19">Existing prototype</a></h5>
<pre><code class="language-wat">(func $ext_offchain_http_response_wait_version_1
(param $ids i64) (param $deadline i64) (result i64))
</code></pre>
<h5 id="changes-30"><a class="header" href="#changes-30">Changes</a></h5>
<p>The function used to return a SCALE-encoded array of request statuses in a host-allocated buffer. It is changed to accept the output buffer of a known size and fill it with request statuses.</p>
<h5 id="new-prototype-18"><a class="header" href="#new-prototype-18">New prototype</a></h5>
<pre><code class="language-wat">(func $ext_offchain_http_response_wait_version_2
(param $ids i64) (param $deadline i64) (param $out i64))
</code></pre>
<h5 id="arguments-25"><a class="header" href="#arguments-25">Arguments</a></h5>
<ul>
<li><code>ids</code> is a pointer-size (<a href="https://spec.polkadot.network/chap-host-api#defn-runtime-pointer-size">Definition 216</a>) to the SCALE-encoded array of started request IDs, as returned by <code>ext_offchain_http_request_start</code>;</li>
<li><code>deadline</code> is a pointer-size (<a href="https://spec.polkadot.network/chap-host-api#defn-runtime-pointer-size">Definition 216</a>) to the SCALE-encoded Option value (<a href="https://spec.polkadot.network/id-cryptography-encoding#defn-option-type">Definition 200</a>) containing the UNIX timestamp (<a href="https://spec.polkadot.network/id-cryptography-encoding#defn-unix-time">Definition 191</a>). Passing <code>None</code> blocks indefinitely;</li>
<li><code>out</code> is a pointer-size (<a href="https://spec.polkadot.network/chap-host-api#defn-runtime-pointer-size">Definition 216</a>) to the buffer of <code>i32</code> integers where the request statuses will be stored. The number of elements of the buffer must be strictly equal to the number of elements in the <code>ids</code> array; otherwise, the function panics.</li>
</ul>
<h4 id="ext_offchain_http_response_headers"><a class="header" href="#ext_offchain_http_response_headers">ext_offchain_http_response_headers</a></h4>
<h5 id="existing-prototype-20"><a class="header" href="#existing-prototype-20">Existing prototype</a></h5>
<pre><code class="language-wat">(func $ext_offchain_http_response_headers_version_1
(param $request_id i32) (result i64))
</code></pre>
<h5 id="changes-31"><a class="header" href="#changes-31">Changes</a></h5>
<p>Considered obsolete in favor of <code>ext_offchain_http_response_header_name</code> and <code>ext_offchain_http_response_header_value</code>. Cannot be used in a runtime using the new-style of entry-point.</p>
<h4 id="ext_offchain_http_response_header_name"><a class="header" href="#ext_offchain_http_response_header_name">ext_offchain_http_response_header_name</a></h4>
<h5 id="changes-32"><a class="header" href="#changes-32">Changes</a></h5>
<p>New function to replace functionality of <code>ext_offchain_http_response_headers</code> with iterative approach. Reads a header name at a given index into a runtime-allocated buffer provided.</p>
<h5 id="new-prototype-19"><a class="header" href="#new-prototype-19">New prototype</a></h5>
<pre><code class="language-wat">(func $ext_offchain_http_response_header_name_version_1
(param $request_id i32) (param $header_index i32) (param $out i64) (result i64))
</code></pre>
<h5 id="arguments-26"><a class="header" href="#arguments-26">Arguments</a></h5>
<ul>
<li><code>request_id</code> is an i32 integer indicating the ID of the started request, as returned by <code>ext_offchain_http_request_start</code>;</li>
<li><code>header_index</code> is an i32 integer indicating the index of the header requested, starting from zero;</li>
<li><code>out</code> is a pointer-size (<a href="https://spec.polkadot.network/chap-host-api#defn-runtime-pointer-size">Definition 216</a>) to the buffer where the header name will be stored. The value is actually stored only if the buffer is large enough. Otherwise, the buffer is not written into and its contents are unchanged.</li>
</ul>
<h5 id="result-18"><a class="header" href="#result-18">Result</a></h5>
<p>The result is an optional positive integer (<a href="#new-def-i">New Definition I</a>), representing either the full length of the header name or the <em>absence</em> of the header with such index.</p>
<h4 id="ext_offchain_http_response_header_value"><a class="header" href="#ext_offchain_http_response_header_value">ext_offchain_http_response_header_value</a></h4>
<h5 id="changes-33"><a class="header" href="#changes-33">Changes</a></h5>
<p>New function to replace functionality of <code>ext_offchain_http_response_headers</code> with iterative approach. Reads a header value at a given index into a runtime-allocated buffer provided.</p>
<h5 id="new-prototype-20"><a class="header" href="#new-prototype-20">New prototype</a></h5>
<pre><code class="language-wat">(func $ext_offchain_http_response_header_value_version_1
(param $request_id i32) (param $header_index i32) (param $out i64) (result i64))
</code></pre>
<h5 id="arguments-27"><a class="header" href="#arguments-27">Arguments</a></h5>
<ul>
<li><code>request_id</code> is an i32 integer indicating the ID of the started request, as returned by <code>ext_offchain_http_request_start</code>;</li>
<li><code>header_index</code> is an i32 integer indicating the index of the header requested, starting from zero;</li>
<li><code>out</code> is a pointer-size (<a href="https://spec.polkadot.network/chap-host-api#defn-runtime-pointer-size">Definition 216</a>) to the buffer where the header value will be stored. The value is actually stored only if the buffer is large enough. Otherwise, the buffer is not written into and its contents are unchanged.</li>
</ul>
<h5 id="result-19"><a class="header" href="#result-19">Result</a></h5>
<p>The result is an optional positive integer (<a href="#new-def-i">New Definition I</a>), representing either the full length of the header value or the <em>absence</em> of the header with such index.</p>
<h4 id="ext_offchain_http_response_read_body"><a class="header" href="#ext_offchain_http_response_read_body">ext_offchain_http_response_read_body</a></h4>
<h5 id="existing-prototype-21"><a class="header" href="#existing-prototype-21">Existing prototype</a></h5>
<pre><code class="language-wat">(func $ext_offchain_http_response_read_body_version_1
(param $request_id i32) (param $buffer i64) (param $deadline i64) (result i64))
</code></pre>
<h5 id="changes-34"><a class="header" href="#changes-34">Changes</a></h5>
<p>The function has already been using a runtime-allocated buffer to return its value. However, the result of the operation was returned as a host-allocated SCALE-encoded <code>Result</code>. It is changed to return a primitive indicating either the length written or an error.</p>
<h5 id="new-prototype-21"><a class="header" href="#new-prototype-21">New prototype</a></h5>
<pre><code class="language-wat">(func $ext_offchain_http_response_read_body_version_2
(param $request_id i32) (param $buffer i64) (param $deadline i64) (result i64))
</code></pre>
<h5 id="arguments-28"><a class="header" href="#arguments-28">Arguments</a></h5>
<ul>
<li><code>request_id</code> is an i32 integer indicating the ID of the started request, as returned by <code>ext_offchain_http_request_start</code>;</li>
<li><code>buffer</code> is a pointer-size (<a href="https://spec.polkadot.network/chap-host-api#defn-runtime-pointer-size">Definition 216</a>) to the buffer where the body is written;</li>
<li><code>deadline</code> is a pointer-size (<a href="https://spec.polkadot.network/chap-host-api#defn-runtime-pointer-size">Definition 216</a>) to the SCALE-encoded Option value (<a href="https://spec.polkadot.network/id-cryptography-encoding#defn-option-type">Definition 200</a>) containing the UNIX timestamp (<a href="https://spec.polkadot.network/id-cryptography-encoding#defn-unix-time">Definition 191</a>). Passing <code>None</code> blocks indefinitely.</li>
</ul>
<h5 id="result-20"><a class="header" href="#result-20">Result</a></h5>
<p>On success, the number of bytes written to the buffer is returned. A value of <code>0</code> means the entire response was consumed and no further calls to the function are needed for the provided request ID. On failure, a negative error code is returned, where <code>-1</code> denotes the deadline was reached, <code>-2</code> denotes that an I/O error occurred, and <code>-3</code> denotes that the request ID provided was invalid.</p>
<h4 id="ext_allocator_"><a class="header" href="#ext_allocator_">ext_allocator_</a></h4>
<h5 id="existing-prototype-22"><a class="header" href="#existing-prototype-22">Existing prototype</a></h5>
<pre><code class="language-wat">(func $ext_allocator_malloc_version_1 (param $size i32) (result i32))
(func $ext_allocator_free_version_1 (param $ptr i32))
</code></pre>
<p>The functions are considered obsolete and cannot be used in a runtime using the new-style of entry-point.</p>
<h4 id="ext_input_read"><a class="header" href="#ext_input_read">ext_input_read</a></h4>
<h5 id="changes-35"><a class="header" href="#changes-35">Changes</a></h5>
<p>A new function providing means of passing input data from the host to the runtime. Previously, the host allocated a buffer and passed a pointer to it to the runtime. With the runtime allocator, it's not possible anymore, so the input data passing protocol changed (see &quot;Other changes&quot; section below). This function is required to support that change.</p>
<h5 id="new-prototype-22"><a class="header" href="#new-prototype-22">New prototype</a></h5>
<pre><code class="language-wat">(func $ext_input_read_version_1
(param $buffer i64))
</code></pre>
<h5 id="arguments-29"><a class="header" href="#arguments-29">Arguments</a></h5>
<ul>
<li><code>buffer</code> is a pointer-size (<a href="https://spec.polkadot.network/chap-host-api#defn-runtime-pointer-size">Definition 216</a>) to the buffer where the input data will be written. If the buffer is not large enough to accommodate the input data, the function will panic.</li>
</ul>
<h3 id="other-changes"><a class="header" href="#other-changes">Other changes</a></h3>
<p>Currently, all runtime entrypoints have the following identical Wasm function signatures:</p>
<pre><code class="language-wat">(func $runtime_entrypoint (param $data i32) (param $len i32) (result i64))
</code></pre>
<p>After this RFC is implemented, such entrypoints are only supported for the legacy runtimes using the host-side allocator. All the new runtimes, using runtime-side allocator, must use new entry point signature:</p>
<pre><code class="language-wat">(func $runtime_entrypoint (param $len i32) (result i64))
</code></pre>
<p>A runtime function called through such an entrypoint gets the length of SCALE-encoded input data as its only argument. After that, the function must allocate exactly the amount of bytes it is requested, and call the <code>ext_input_read</code> host function to obtain the encoded input data.</p>
<p>If a runtime happens to import both functions that allocate on the host side and functions that allocate on the runtime side, the host must not proceed with execution of such a runtime, aborting before the execution takes place.</p>
</main>
<nav class="nav-wrapper" aria-label="Page navigation">
<!-- Mobile navigation buttons -->
<a rel="prev" href="../introduction.html" class="mobile-nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
<i class="fa fa-angle-left"></i>
</a>
<a rel="next prefetch" href="../proposed/0154-multi-slot-aura.html" class="mobile-nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
<i class="fa fa-angle-right"></i>
</a>
<div style="clear: both"></div>
</nav>
</div>
</div>
<nav class="nav-wide-wrapper" aria-label="Page navigation">
<a rel="prev" href="../introduction.html" class="nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
<i class="fa fa-angle-left"></i>
</a>
<a rel="next prefetch" href="../proposed/0154-multi-slot-aura.html" class="nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
<i class="fa fa-angle-right"></i>
</a>
</nav>
</div>
<script>
window.playground_copyable = true;
</script>
<script src="../elasticlunr.min.js"></script>
<script src="../mark.min.js"></script>
<script src="../searcher.js"></script>
<script src="../clipboard.min.js"></script>
<script src="../highlight.js"></script>
<script src="../book.js"></script>
<!-- Custom JS scripts -->
</div>
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink