Wormhole Solidity SDK Smart Contract Audit

</nav>
<article class="report">
<h1 id="introduction">Introduction</h1>
<p>iosiro was commissioned by Wormhole to perform a smart contract audit of their Solidity SDK library. Two auditors conducted the audit between 09 December 2025 and 06 January 2026, over 11 audit days.</p>
<h4 id="overview">Overview</h4>
<p>The assessment focused on several core library and utility components intended to be consumed by other projects. Integrators should exercise caution when consuming these components and ensure that the security and functional considerations documented in the comments (particularly around unchecked parsing and hashing helpers) are strictly adhered to.</p>
<p>The audit identified one critical issue and seven informational findings. All issues were either resolved through code changes or closed as acceptable design trade-offs, and there were no open findings at the conclusion of the engagement.</p>
<p>Most findings were related to design and robustness concerns rather than exploitable vulnerabilities that would directly put funds at risk. With these considerations addressed, the reviewed library components are well-positioned for safe integration, provided that the documented usage constraints are respected by downstream consumers.</p>
<table class="findings-count">
<thead>
<tr>
<th> </th>
<th>Critical</th>
<th>High</th>
<th>Medium</th>
<th>Low</th>
<th>Informational</th>
</tr>
</thead>
<tbody>
<tr>
<td>Open</td>
<td>0</td>
<td>0</td>
<td>0</td>
<td>0</td>
<td>0</td>
</tr>
<tr>
<td>Resolved</td>
<td>1</td>
<td>0</td>
<td>0</td>
<td>0</td>
<td>4</td>
</tr>
<tr>
<td>Closed</td>
<td>0</td>
<td>0</td>
<td>0</td>
<td>0</td>
<td>3</td>
</tr>
</tbody>
</table>
<h4 id="scope">Scope</h4>
<p>The assessment focused on the source files listed below, with all other files considered out of scope. Any out-of-scope code interacting with the assessed code was presumed to operate correctly without introducing functional or security vulnerabilities.</p>
<ul>
<li><strong>Project name:</strong> <a href="https://github.com/wormhole-foundation/wormhole-solidity-sdk/tree/main">wormhole-solidity-sdk</a></li>
<li><strong>Initial audit commit:</strong> <a href="https://github.com/wormhole-foundation/wormhole-solidity-sdk/tree/97ca219eb34af71b80678cbf7bb10ff0cbb0f5bd">97ca219</a></li>
<li><strong>Final review commit:</strong> <a href="https://github.com/wormhole-foundation/wormhole-solidity-sdk/tree/b4a904ec8c807f9d01c5eacfb975c89dc40012a3">b4a904e</a></li>
<li><strong>Files:</strong>
<ul>
<li><a href="https://github.com/wormhole-foundation/wormhole-solidity-sdk/blob/97ca219eb34af71b80678cbf7bb10ff0cbb0f5bd/src/libraries/BytesParsing.sol">src/libraries/BytesParsing.sol</a></li>
<li><a href="https://github.com/wormhole-foundation/wormhole-solidity-sdk/blob/97ca219eb34af71b80678cbf7bb10ff0cbb0f5bd/src/libraries/VaaLib.sol">src/libraries/VaaLib.sol</a></li>
<li><a href="https://github.com/wormhole-foundation/wormhole-solidity-sdk/blob/97ca219eb34af71b80678cbf7bb10ff0cbb0f5bd/src/libraries/ReplayProtection.sol">src/libraries/ReplayProtection.sol</a></li>
<li><a href="https://github.com/wormhole-foundation/wormhole-solidity-sdk/tree/97ca219eb34af71b80678cbf7bb10ff0cbb0f5bd/src/proxy">src/proxy</a></li>
<li><a href="https://github.com/wormhole-foundation/wormhole-solidity-sdk/blob/97ca219eb34af71b80678cbf7bb10ff0cbb0f5bd/src/utils/Keccak.sol">src/utils/Keccak.sol</a></li>
<li><a href="https://github.com/wormhole-foundation/wormhole-solidity-sdk/blob/97ca219eb34af71b80678cbf7bb10ff0cbb0f5bd/src/libraries/PermitParsing.sol">src/libraries/PermitParsing.sol</a></li>
<li><a href="https://github.com/wormhole-foundation/wormhole-solidity-sdk/blob/97ca219eb34af71b80678cbf7bb10ff0cbb0f5bd/src/libraries/Percentage.sol">src/libraries/Percentage.sol</a></li>
</ul>
</li>
</ul>
<p>A specification is available in the <a href="#specification">Specification section</a> of this report.</p>
<h1 id="disclaimer">Disclaimer</h1>
<p>This report aims to provide an overview of the assessed smart contracts’ risk exposure and a guide to improving their security posture by addressing identified issues. The audit, limited to specific source code at the time of review, sought to:</p>
<ul>
<li>Identify potential security flaws.</li>
<li>Verify that the smart contracts’ functionality aligns with their documentation.</li>
</ul>
<p>Off-chain components, such as backend web application code, keeper functionality, and deployment scripts, were explicitly not in scope of this audit.</p>
<p>Given the unregulated nature and ease of cryptocurrency transfers, operations involving these assets face a high risk from cyber attacks. Maintaining the highest security level is crucial, necessitating a proactive and adaptive approach that accounts for the experimental and rapidly evolving nature of blockchain technology. To encourage secure code development, developers should:</p>
<ul>
<li>Integrate security throughout the development lifecycle.</li>
<li>Employ defensive programming to mitigate the risks posed by unexpected events.</li>
<li>Adhere to current best practices wherever possible.</li>
</ul>
<h1 id="methodology">Methodology</h1>
<p>The audit was conducted using the techniques described below.</p>
<dl>
<dt>Code review</dt>
<dd>The source code was manually inspected to identify potential security flaws. Code review is a useful approach for detecting security flaws, discrepancies between the specification and implementation, design improvements, and high-risk areas of the system.</dd>
<dt>Dynamic analysis</dt>
<dd>The contracts were compiled, deployed, and tested in a test environment, both manually and through the test suite provided. Dynamic analysis was used to identify additional edge cases, confirm that the code was functional, and validate the reported issues.</dd>
<dt>Automated analysis</dt>
<dd>Automated tooling was used to detect the presence of various types of security vulnerabilities. Static analysis results were reviewed manually, any false positives were removed. Any true positive results are included in this report.</dd>
</dl>
<h1 id="audit-findings">Audit findings</h1>
<p>The table below provides an overview of the audit’s findings. Detailed write-ups are provided below.</p>
<table class="findings">
<thead>
<tr>
<th>ID</th>
<th>Issue</th>
<th>Risk</th>
<th>Status</th>
</tr>
</thead>
<tbody>
<tr>
<td><a href="#IO-WRM-SDK-001">IO-WRM-SDK-001</a></td>
<td>Incorrect offset used</td>
<td class="rating-critical">Critical</td>
<td class="status-resolved">Resolved</td>
</tr>
<tr>
<td><a href="#IO-WRM-SDK-002">IO-WRM-SDK-002</a></td>
<td>Rename return variable</td>
<td class="rating-informational">Informational</td>
<td class="status-resolved">Resolved</td>
</tr>
<tr>
<td><a href="#IO-WRM-SDK-003">IO-WRM-SDK-003</a></td>
<td>Unnecessary cast</td>
<td class="rating-informational">Informational</td>
<td class="status-resolved">Resolved</td>
</tr>
<tr>
<td><a href="#IO-WRM-SDK-004">IO-WRM-SDK-004</a></td>
<td>Missing warnings for Keccak functions</td>
<td class="rating-informational">Informational</td>
<td class="status-resolved">Resolved</td>
</tr>
<tr>
<td><a href="#IO-WRM-SDK-005">IO-WRM-SDK-005</a></td>
<td>Unused Constants</td>
<td class="rating-informational">Informational</td>
<td class="status-resolved">Resolved</td>
</tr>
<tr>
<td><a href="#IO-WRM-SDK-006">IO-WRM-SDK-006</a></td>
<td>Sequence-based replay protection griefing</td>
<td class="rating-informational">Informational</td>
<td class="status-closed">Closed</td>
</tr>
<tr>
<td><a href="#IO-WRM-SDK-007">IO-WRM-SDK-007</a></td>
<td>Recalculate envelope size</td>
<td class="rating-informational">Informational</td>
<td class="status-closed">Closed</td>
</tr>
<tr>
<td><a href="#IO-WRM-SDK-008">IO-WRM-SDK-008</a></td>
<td>Free memory space access assumptions</td>
<td class="rating-informational">Informational</td>
<td class="status-closed">Closed</td>
</tr>
</tbody>
</table>
<p>Each issue identified during the audit has been assigned a risk rating. The rating is determined based on the criteria outlined below.</p>
<dl>
<dt>Critical risk</dt>
<dd>The issue could result in the theft of funds from the contract or its users.</dd>
<dt>High risk</dt>
<dd>The issue could result in the loss of funds for the contract owner or its users.</dd>
<dt>Medium risk</dt>
<dd>The issue resulted in the code being dysfunctional or the specification being implemented incorrectly.</dd>
<dt>Low risk</dt>
<dd>A design or best practice issue that could affect the ordinary functioning of the contract.</dd>
<dt>Informational</dt>
<dd>An improvement related to best practice or a suboptimal design pattern.</dd>
</dl>
<p>In addition to a risk rating, each issue is assigned a status:</p>
<dl>
<dt>Open</dt>
<dd>The issue remained present in the code as of the final commit reviewed and may still pose a risk.</dd>
<dt>Resolved</dt>
<dd>The issue was identified during the audit and has since been satisfactorily addressed, removing the risk it posed.</dd>
<dt>Closed</dt>
<dd>The issue was identified during the audit and acknowledged by the developers as an acceptable risk without actioning any change.</dd>
</dl>
<a name="IO-WRM-SDK-001"></a><h2 id="io-wrm-sdk-001-incorrect-offset-used" class="break-before"><strong>IO-WRM-SDK-001</strong> Incorrect offset used</h2>
<table class="metadata">

<tbody>
<tr>
<td class="rating-critical">Critical</td>
<td class="status-resolved">Resolved</td>
<td><a href="https://github.com/wormhole-foundation/wormhole-solidity-sdk/blob/97ca219eb34af71b80678cbf7bb10ff0cbb0f5bd/src/libraries/VaaLib.sol#L430">VaaLib.sol#L430</a></td>
</tr>
</tbody>
</table>
<p>In <code>VaaLib::decodeVaaBodyStructMem()</code>, an offset of 0 was passed to <code>VaaLib::decodeVaaBodyMemUnchecked()</code>. This was incorrect because the decode function expects an offset at the end of the header and beginning of the envelope. Given an offset of 0, the function attempts to decode the envelope from within the header, producing incorrect data.</p>
<h3 id="recommendation">Recommendation</h3>
<p>The correct approach, as used in other functions, is to calculate the offset that skips the header by calling <code>VaaLib::skipVaaHeaderMemUnchecked(encodedVaa, 0)</code> and pass that offset to <code>VaaLib::decodeVaaBodyMemUnchecked()</code>.</p>
<h3 id="client-response">Client response</h3>
<p>This issue was resolved in <a href="https://github.com/wormhole-foundation/wormhole-solidity-sdk/pull/113/commits/109135d7370151008a0935588aaf2c1aa8ff9848">109135d</a>, where <code>VaaLib::decodeVaaBodyStructMem()</code> was updated to call <code>VaaLib::decodeVaaBodyMem()</code>, which handles the offset calculation correctly.</p>
<a name="IO-WRM-SDK-002"></a><h2 id="io-wrm-sdk-002-rename-return-variable" class="break-before"><strong>IO-WRM-SDK-002</strong> Rename return variable</h2>
<table class="metadata">

<tbody>
<tr>
<td class="rating-informational">Informational</td>
<td class="status-resolved">Resolved</td>
<td><a href="https://github.com/wormhole-foundation/wormhole-solidity-sdk/blob/97ca219eb34af71b80678cbf7bb10ff0cbb0f5bd/src/libraries/VaaLib.sol#L1089">VaaLib.sol#L1089</a></td>
</tr>
</tbody>
</table>
<p>The returned offset from <code>VaaLib::decodeGuardianSignatureMemUnchecked()</code> should be renamed from <code>envelopeOffset</code> to <code>newOffset</code>, similar to <code>VaaLib::decodeGuardianSignatureCdUnchecked()</code>. This is because this function will likely be called in a loop, meaning only the last call would actually be the <code>envelopeOffset</code>.</p>
<h3 id="client-response-1">Client response</h3>
<p>The return variable was renamed in <a href="https://github.com/wormhole-foundation/wormhole-solidity-sdk/pull/113/commits/109135d7370151008a0935588aaf2c1aa8ff9848">109135d</a>.</p>
<a name="IO-WRM-SDK-003"></a><h2 id="io-wrm-sdk-003-unnecessary-cast" class="break-before"><strong>IO-WRM-SDK-003</strong> Unnecessary cast</h2>
<table class="metadata">

<tbody>
<tr>
<td class="rating-informational">Informational</td>
<td class="status-resolved">Resolved</td>
<td><a href="https://github.com/wormhole-foundation/wormhole-solidity-sdk/blob/97ca219eb34af71b80678cbf7bb10ff0cbb0f5bd/src/libraries/BytesParsing.sol#L381-L384">BytesParsing.sol#L381-L384</a></td>
</tr>
</tbody>
</table>
<p>A cast from <code>uint8</code> to <code>uint256</code> was used in <code>BytesParsing::asBoolCdUnchecked()</code>. This may be unnecessary as booleans are equivalent to <code>uint8</code>. As such, the final <code>val</code> value could be assigned to <code>ret</code> directly.</p>
<h3 id="client-response-2">Client response</h3>
<p>The cast was used to clear the upper 31 bytes. However, an improvement was implemented in <a href="https://github.com/wormhole-foundation/wormhole-solidity-sdk/pull/113/commits/abf970684cde19650fbf4f3d3f71ac015ce432c3">abf9706</a> to reorder the cleaning step to avoid two extra 0xff masking operations.</p>
<a name="IO-WRM-SDK-004"></a><h2 id="io-wrm-sdk-004-missing-warnings-for-keccak-functions" class="break-before"><strong>IO-WRM-SDK-004</strong> Missing warnings for Keccak functions</h2>
<table class="metadata">

<tbody>
<tr>
<td class="rating-informational">Informational</td>
<td class="status-resolved">Resolved</td>
<td><a href="https://github.com/wormhole-foundation/wormhole-solidity-sdk/blob/97ca219eb34af71b80678cbf7bb10ff0cbb0f5bd/src/utils/Keccak.sol#L14">Keccak.sol#L14</a></td>
</tr>
</tbody>
</table>
<p>A warning explaining the risks of unchecked functions, similar to the format at the top of the <code>BytesParsing.sol</code> library, was not present for the Keccak free functions. This was especially true for the <code>Keccak::keccak256SliceUnchecked()</code> function since an invalid <code>offset</code> or <code>length</code> value would hash invalid data, creating an invalid hash.</p>
<h3 id="client-response-3">Client response</h3>
<p>A comment with the necessary warnings was added above the function in <a href="https://github.com/wormhole-foundation/wormhole-solidity-sdk/pull/113/commits/57ad49bf459a423b7a01dcae90a9fea96d8b3fb6">57ad49b</a>.</p>
<a name="IO-WRM-SDK-005"></a><h2 id="io-wrm-sdk-005-unused-constants" class="break-before"><strong>IO-WRM-SDK-005</strong> Unused Constants</h2>
<table class="metadata">

<tbody>
<tr>
<td class="rating-informational">Informational</td>
<td class="status-resolved">Resolved</td>
<td><a href="https://github.com/wormhole-foundation/wormhole-solidity-sdk/blob/97ca219eb34af71b80678cbf7bb10ff0cbb0f5bd/src/libraries/VaaLib.sol#L249">VaaLib.sol#L249</a>, <a href="https://github.com/wormhole-foundation/wormhole-solidity-sdk/blob/97ca219eb34af71b80678cbf7bb10ff0cbb0f5bd/src/libraries/VaaLib.sol#L263">VaaLib.sol#L263</a>, <a href="https://github.com/wormhole-foundation/wormhole-solidity-sdk/blob/97ca219eb34af71b80678cbf7bb10ff0cbb0f5bd/src/libraries/VaaLib.sol#L286">VaaLib.sol#L286</a>, <a href="https://github.com/wormhole-foundation/wormhole-solidity-sdk/blob/97ca219eb34af71b80678cbf7bb10ff0cbb0f5bd/src/libraries/Percentage.sol#L26">Percentage.sol#L26</a>, <a href="https://github.com/wormhole-foundation/wormhole-solidity-sdk/blob/97ca219eb34af71b80678cbf7bb10ff0cbb0f5bd/src/libraries/Percentage.sol#L29">Percentage.sol#L29</a></td>
</tr>
</tbody>
</table>
<p>The following constants were unused in <code>VaaLib.sol</code>. These could be removed unless the intention is to allow contracts that derive from this library access to these constants:</p>
<ul>
<li><code>MULTISIG_SIGNATURE_ARRAY_OFFSET</code></li>
<li><code>MULTISIG_SIGNATURE_V_OFFSET</code></li>
<li><code>SCHNORR_ENVELOPE_OFFSET</code></li>
</ul>
<p>Similarly, the following constants were unused in <code>Percentage.sol</code>.</p>
<ul>
<li><code>BYTE_SIZE</code></li>
<li><code>EXPONENT_BASE</code></li>
</ul>
<h3 id="client-response-4">Client response</h3>
<p><code>EXPONENT_BASE</code>, which had no utility, was removed in <a href="https://github.com/wormhole-foundation/wormhole-solidity-sdk/pull/113/commits/0fd4257562122410adb251fba8eb9b4d0bd5447e">0fd4257</a>. The rest of the constants were kept for reference for consuming contracts.</p>
<a name="IO-WRM-SDK-006"></a><h2 id="io-wrm-sdk-006-sequence-based-replay-protection-griefing" class="break-before"><strong>IO-WRM-SDK-006</strong> Sequence-based replay protection griefing</h2>
<table class="metadata">

<tbody>
<tr>
<td class="rating-informational">Informational</td>
<td class="status-closed">Closed</td>
<td><a href="https://github.com/wormhole-foundation/wormhole-solidity-sdk/blob/97ca219eb34af71b80678cbf7bb10ff0cbb0f5bd/src/libraries/ReplayProtection.sol#L65">ReplayProtection.sol#L65</a></td>
</tr>
</tbody>
</table>
<p>When determining the base slot for a given emitter address and chain, the values are XORed instead of encoded and packed. Due to XOR involution, an attacker could attempt to derive an emitter address that satisfies <code>attacker_emitter == target_emitter XOR target_chain_id XOR attacker_chain_id</code>. This would allow them to access the same base slot and set the replay protection flags for sequence numbers not yet reached by the valid emitter.</p>
<p>While theoretically possible, it would require the attacker to be able to deploy an emitter at a specific address on their attack chain. Currently, it is infeasible to do this on existing chains.</p>
<p>A more robust approach would be to derive the base slot using <code>abi.encodePacked</code> instead of using XOR.</p>
<h3 id="client-response-5">Client response</h3>
<p>The team acknowledged this as a theoretical design consideration and opted to leave the implementation unchanged.</p>
<a name="IO-WRM-SDK-007"></a><h2 id="io-wrm-sdk-007-recalculate-envelope-size" class="break-before"><strong>IO-WRM-SDK-007</strong> Recalculate envelope size</h2>
<table class="metadata">

<tbody>
<tr>
<td class="rating-informational">Informational</td>
<td class="status-closed">Closed</td>
<td><a href="https://github.com/wormhole-foundation/wormhole-solidity-sdk/blob/97ca219eb34af71b80678cbf7bb10ff0cbb0f5bd/src/libraries/VaaLib.sol#L312-L313">VaaLib.sol#L312-L313</a></td>
</tr>
</tbody>
</table>
<p><code>ENVELOPE_SIZE</code> could be calculated based on the sum of its individual element sizes. While the current calculation is correct, it is based on an assumption that the <code>ENVELOPE_TIMESTAMP_OFFSET</code> will always be zero. Should this change in a future refactor, the <code>ENVELOPE_SIZE</code> may become incorrect, and this could be missed in that refactor. Furthermore, calculating it based on the sum of element sizes aligns with the convention used in calculating other <code>*_SIZE</code> constants in the library, such as <code>MULTISIG_GUARDIAN_SIGNATURE_SIZE</code>.</p>
<h3 id="client-response-6">Client response</h3>
<p>The team acknowledged this as a maintainability consideration and opted to leave the implementation unchanged.</p>
<a name="IO-WRM-SDK-008"></a><h2 id="io-wrm-sdk-008-free-memory-space-access-assumptions" class="break-before"><strong>IO-WRM-SDK-008</strong> Free memory space access assumptions</h2>
<table class="metadata">

<tbody>
<tr>
<td class="rating-informational">Informational</td>
<td class="status-closed">Closed</td>
<td><a href="https://github.com/wormhole-foundation/wormhole-solidity-sdk/blob/97ca219eb34af71b80678cbf7bb10ff0cbb0f5bd/src/libraries/BytesParsing.sol#L82">BytesParsing.sol#L82</a>, <a href="https://github.com/wormhole-foundation/wormhole-solidity-sdk/blob/97ca219eb34af71b80678cbf7bb10ff0cbb0f5bd/src/utils/Keccak.sol#L32">Keccak.sol#L32</a></td>
</tr>
</tbody>
</table>
<p>Multiple functions in the SDK access free memory space directly without moving the pointer beyond the data or clearing the data. Hence, for any operations that use this memory space, the data cannot be assumed to be padded with zeros. The offset and size values used should match the data exactly to avoid padding with junk data.</p>
<p>In a similar vein, any data calculated in the free memory space should be returned to the call stack for use and not accessed through the free memory space to prevent corruption.</p>
<h3 id="client-response-7">Client response</h3>
<p>The team acknowledged this as an integration consideration and opted to leave the implementation unchanged.</p>
<h1 id="specification">Specification</h1>
<p>The following section outlines the SDK’s intended functionality at a high level, based on its implementation in the codebase. The assessed components are library and utility building blocks intended to be consumed by other projects. They prioritize gas efficiency (including the use of inline assembly where appropriate), which places additional responsibility on downstream integrators to satisfy the documented preconditions, such as providing correct offsets and lengths to unchecked parsing and hashing helpers.</p>
<h2 id="bytesparsing">BytesParsing</h2>
<p><code>BytesParsing.sol</code> provides the SDK’s low-level byte decoding primitives and serves as the foundation for the higher-level parsing libraries. The implementation prioritizes gas efficiency, using inline assembly where appropriate, and exposes distinct variants for both calldata and memory inputs.</p>
<p>In general, functions are offered in four forms: calldata (<code>Cd</code>) and memory (<code>Mem</code>) variants, each with a bounds-checked version and an <code>Unchecked</code> version. The checked variants protect only against out-of-bounds reads of the provided buffer; they do not protect against arithmetic overflow when computing offsets and lengths.</p>
<p>The intended high-efficiency integration pattern is to parse from calldata where possible and, when using unchecked helpers, to validate correctness at the end by performing a single full-consumption check (e.g., via <code>checkLength</code>) so the decoder consumes the payload exactly. Downstream consumers remain responsible for ensuring offsets and lengths are sensibly bounded, including validating user-controlled inputs, and for preferring encoding formats that constrain attacker-controlled length fields.</p>
<h2 id="vaalib">VaaLib</h2>
<p><code>VaaLib.sol</code> provides gas-efficient VAA parsing utilities built on top of <code>BytesParsing</code>. The library is designed to decode VAAs with minimal overhead and, where possible, to return decoded components directly on the stack rather than requiring memory allocation for a full struct.</p>
<p><code>VaaLib</code> exposes whole-VAA helpers for use cases such as skipping headers and decoding envelopes/bodies, as well as functions that parse individual VAA components and advance offsets to support iterative decoding, for use cases such as decoding guardian signatures in a loop.</p>
<h3 id="function-variants-and-naming-conventions">Function variants and naming conventions</h3>
<dl>
<dt>Data location variants</dt>
<dd>functions are generally provided in calldata (<code>Cd</code>) and memory (<code>Mem</code>) forms.</dd>
<dt>Struct-return variants</dt>
<dd>many decoders have a “struct flavor” that returns the decoded values in an associated in-memory struct, in addition to the stack-returning variants.</dd>
<dt>Parameter naming</dt>
<dd><code>encodedVaa</code> and <code>encodedAttestation</code> are used when the input is expected to contain a single full VAA/attestation; <code>encoded</code> is used for partial inputs or buffers containing multiple items.</dd>
<dt>Unchecked suffix</dt>
<dd><code>Unchecked</code> denotes the absence of bounds checks - it is not Solidity’s <code>unchecked</code> keyword. Arithmetic is performed using unchecked operations as overflows are not expected under the VAA format’s constraints, while underflow conditions are explicitly checked where relevant.</dd>
<dt><code>Vaa</code> tag in function names</dt>
<dd>function names include <code>Vaa</code> to improve clarity and reduce the risk of name collisions when used with <code>using ... for bytes</code>.</dd>
</dl>
<h2 id="replayprotection">ReplayProtection</h2>
<p><code>ReplayProtection.sol</code> provides reusable replay protection primitives intended to prevent a VAA (or message) from being processed more than once. Two replay protection approaches are supported:</p>
<ul>
<li>
<p>Sequence-based replay protection (per chain + emitter)</p>
<ul>
<li>Tracks replay status per <code>(emitterChainId, emitterAddress)</code> using the VAA sequence number.</li>
<li>Must only be used for VAAs published with the finalized consistency level (the default case).</li>
<li>Implemented via a bitmap to reduce gas cost by avoiding writes to clean storage slots wherever possible.</li>
</ul>
</li>
<li>
<p>Hash-based replay protection</p>
<ul>
<li>Can be used for all consistency levels.</li>
<li>Less efficient than sequence-based replay protection because it always writes to a clean storage slot.</li>
<li>Uses the canonical VAA hash. Note that this is not what CoreBridge returns in <code>VM.hash</code> – see the warning box at the top of <code>VaaLib.sol</code> for details.</li>
</ul>
</li>
</ul>
<h2 id="proxy-contracts">Proxy contracts</h2>
<p>The <code>src/proxy</code> components provide a slimmed-down, opinionated implementation of the EIP-1967 proxy pattern (based on the reference implementation) intended for downstream consumers that require upgradeability or call forwarding.</p>
<p>Provision is included for consumers to upgrade from an OpenZeppelin proxy implementation. However, care must be taken during such a migration to ensure that the EIP-1967 proxy admin and implementation storage locations are migrated correctly, as incorrect slot handling can lead to loss of upgrade control or unexpected behavior.</p>
<h2 id="keccak-utilities">Keccak utilities</h2>
<p><code>Keccak.sol</code> provides keccak256 helper functions, including slice-based hashing utilities intended to reduce overhead when hashing sub-regions of an encoded payload. These helpers are designed for performance and include unchecked variants; callers must ensure the <code>offset</code> and <code>length</code> parameters exactly match the intended data region.</p>
<h2 id="permitparsing">PermitParsing</h2>
<p><code>PermitParsing.sol</code> standardizes the encoding and decoding of permit payloads so that consuming contracts can acquire tokens via one of the supported permit mechanisms. It supports:</p>
<ul>
<li>ERC-2612 permit (<code>IERC20Permit.permit</code>)</li>
<li>Uniswap Permit2 “permit” (approval) (<code>IAllowanceTransfer.permit</code>)</li>
<li>Uniswap Permit2 “transfer” (<code>ISignatureTransfer.permitTransferFrom</code>)</li>
</ul>
<p>The library defines a consistent on-wire format for each mechanism:</p>
<ul>
<li><strong>ERC-2612 Permit</strong>: <code>value</code> (uint256), <code>deadline</code> (uint256), <code>r</code> (bytes32), <code>s</code> (bytes32), <code>v</code> (uint8)</li>
<li><strong>Permit2 Permit</strong>: <code>amount</code> (uint160), <code>expiration</code> (uint48), <code>nonce</code> (uint48), <code>sigDeadline</code> (uint256), <code>signature</code> (bytes; 65-byte packed r,s,v)</li>
<li><strong>Permit2 Transfer</strong>: <code>amount</code> (uint256), <code>nonce</code> (uint256), <code>sigDeadline</code> (uint256), <code>signature</code> (bytes; 65-byte packed r,s,v)</li>
</ul>
<p>Decode functions are provided in 2×2 flavors: calldata (<code>Cd</code>) and memory (<code>Mem</code>) inputs, each returning either individual stack values or an associated in-memory struct (<code>Struct</code>). As with <code>BytesParsing</code>, an <code>Unchecked</code> suffix indicates that bounds checks are omitted and unchecked offset arithmetic is used.</p>
<p>The primary decode entry points are <code>decodePermit</code>, <code>decodePermit2Permit</code>, and <code>decodePermit2Transfer</code>. Encoding helpers (<code>encode*</code>) exist primarily to support testing.</p>
<h2 id="percentage">Percentage</h2>
<p><code>Percentage.sol</code> provides a compact representation of percentages using a <code>uint16</code> encoding intended to reduce storage and calldata overhead in consuming projects.</p>
<p>Percentages are represented with up to four decimal digits of precision, or up to a maximum of 1000%. The encoding uses a 14-bit mantissa and a 2-bit decimal exponent:</p>
<p>The <code>uint16</code> value is split into:</p>
<ul>
<li>a 14-bit <strong>mantissa</strong> (m) (the significant digits), and</li>
<li>a 2-bit <strong>decimal exponent</strong> (e) (a base-10 scale factor).</li>
</ul>
<p>The represented percentage is:</p>
<p><span class="math display">\[value(\%) = \frac{m}{10^{(1 + e)}}
\]</span></p>
<p>The exponent shifts the decimal point downwards, enabling a practical range from sub-0.001% values up to 1000.00%. Due to the decimal exponent scheme, some percentages may admit multiple valid representations; consuming code should treat the value as the decoded percentage rather than relying on a unique canonical encoding.</p>
<h1 id="test-coverage-report">Test coverage report</h1>
<p>All tests and fuzz tests executed successfully and were well-written. It was not possible to compile a coverage report because Foundry does not compile fuzz tests successfully when running coverage.</p>

</article>
</main>
</div>

‍

Secure your system.

Request a service

Start Now →