safe_chainid

<!doctype html> <html class="default no-js"> <head> <meta charset="utf-8"> <meta http-equiv="X-UA-Compatible" content="IE=edge"> <title>safe_chainid</title> <meta name="description" content=""> <meta name="viewport" content="width=device-width, initial-scale=1"> <link rel="stylesheet" href="assets/css/main.css"> <script async src="assets/js/search.js" id="search-script"></script> </head> <body> <header> <div class="tsd-page-toolbar"> <div class="container"> <div class="table-wrap"> <div class="table-cell" id="tsd-search" data-index="assets/js/search.json" data-base="."> <div class="field"> <label for="tsd-search-field" class="tsd-widget search no-caption">Search</label> <input id="tsd-search-field" type="text" /> </div> <ul class="results"> <li class="state loading">Preparing search index...</li> <li class="state failure">The search index is not available</li> </ul> <ul class="results-priority" style="display:none"> </ul> <a href="index.html" class="title">safe_chainid</a> </div> <div class="table-cell" id="tsd-widgets"> <div id="tsd-filter"> <a href="#" class="tsd-widget options no-caption" data-toggle="options">Options</a> <div class="tsd-filter-group"> <div class="tsd-select" id="tsd-filter-visibility"> All <ul class="tsd-select-list"> <li data-value="public">Public</li> <li data-value="protected">Public/Protected</li> <li data-value="private" class="selected">All</li> </ul> </div> <input type="checkbox" id="tsd-filter-inherited" checked /> <label class="tsd-widget" for="tsd-filter-inherited">Inherited</label> <input type="checkbox" id="tsd-filter-externals" checked /> <label class="tsd-widget" for="tsd-filter-externals">Externals</label> <input type="checkbox" id="tsd-filter-only-exported" /> <label class="tsd-widget" for="tsd-filter-only-exported">Only exported</label> </div> </div> <a href="#" class="tsd-widget menu no-caption" data-toggle="menu">Menu</a> </div> </div> </div> </div> <div class="tsd-page-title"> <div class="container"> <ul class="tsd-breadcrumb"> </ul> </div> </div> </header> <div class="container container-main"> <div class="row"> <div class="col-3 col-menu menu-sticky-wrap menu-highlight"> <nav class="tsd-navigation primary"> <ul> <li class=" "> <a href="modules.html">Exports</a> </li> </ul> </nav> </div> <div class="col-7 offset-3 col-content"> <h1>Project safe_chainid</h1> <div class="tsd-panel tsd-typography"> <a href="#safe-chainid" id="safe-chainid" style="color: inherit; text-decoration: none;"> <h1>Safe ChainId</h1> </a> <blockquote> Note @remarks originally wrote this in a gist. </blockquote> <a href="#summary" id="summary" style="color: inherit; text-decoration: none;"> <h2>Summary</h2> </a> MetaMask can only handle chain IDs of a certain size. Specifically: <pre><code class="language-javascript">MAX_SAFE_CHAIN_ID = 4503599627370476; </code></pre> MetaMask (and any program that consumes the same cryptographic libraries that we do) should reject any chain IDs greater than <code>MAX_SAFE_CHAIN_ID</code>, and validate chain IDs as follows, after successfully parsing them as <code>number</code> values: <pre><code class="language-javascript">const MAX_SAFE_CHAIN_ID = 4503599627370476; function isSafeChainId(chainId) { return ( Number.isSafeInteger(chainId) && chainId > 0 && chainId <= MAX_SAFE_CHAIN_ID ); } </code></pre> <a href="#justification" id="justification" style="color: inherit; text-decoration: none;"> <h2>Justification</h2> </a> <a href="#problem-statement" id="problem-statement" style="color: inherit; text-decoration: none;"> <h3>Problem Statement</h3> </a> At the time of writing, the chain ID is effectively the GUID of Ethereum chains, and a critical component of transaction signing. See <a href="https://eips.ethereum.org/EIPS/eip-155">EIP-155</a> for details. We are about to complete efforts to require chain IDs for all chains in MetaMask and enforce their use in transaction signing. (We were already doing this, but there were some edge cases remaining.) However, you'll notice that EIP-155 says nothing about the size of the chain ID. Per <a href="https://eips.ethereum.org/EIPS/eip-695">EIP-695</a>, the chain ID is a <code>QUANTITY</code>, which can be (with some possible caveats) any number in the <code>0</code> to <code>2**256</code> range. Because JavaScript <code>number</code> values are <a href="https://en.wikipedia.org/wiki/IEEE_754">IEEE 754</a> double-precision floating point numbers, they can only safely represent values in the <code>-(2**53 - 1) <= 2**53 - 1</code> range. (We call the upper end of this range the <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/MAX_SAFE_INTEGER"><code>MAX_SAFE_INTEGER</code></a>.) This means that a chain could specify a chain ID that isn't safely representable as a native JavaScript <code>number</code>. In the extension, we've tried to mitigate this by using <code>bignumber.js</code> to validate chain IDs before converting them to hex, but this is also unsafe because of the signing libraries we use. Consider the following <code>ethereumjs-tx</code> implementations: <ul> <li><a href="https://github.com/ethereumjs/ethereumjs-tx/blob/e3fc21467ecb997090f63f154b1407094f173bf2/index.js#L120-L127"><code>ethereumjs-tx@1.3.7</code>, used by the extension</a></li> <li><a href="https://github.com/ethereumjs/ethereumjs-vm/blob/5184804b6652056183babb47ef254d98765c9b8c/packages/tx/src/transaction.ts#L368-L383"><code>ethereumjs-tx@3.0.0</code>, the latest version</a></li> </ul> Whether we use <code>bignumber.js</code> or something else, our signing libraries expect <code>number</code> chain IDs. The formula they used we get from <code>ethereumjs-tx@3.0.0</code>, which we also find in EIP-155: <pre><code class="language-javascript">const isValidEIP155V = vInt === this.getChainId() * 2 + 35 || vInt === this.getChainId() * 2 + 36; </code></pre> In addition, in <a href="https://github.com/ethereumjs/ethereumjs-util/blob/c5dca47d1ec983edd3b00b559088f9b56e16bc01/src/signature.ts#L16-28">the <code>ecsign</code> implementation</a> of <code>ethereumjs-util@7.0.5</code> (the latest version), we find the following: <pre><code class="language-javascript">const sig = ecdsaSign(msgHash, privateKey); const recovery: number = sig.recid; const ret = { r: Buffer.from(sig.signature.slice(0, 32)), s: Buffer.from(sig.signature.slice(32, 64)), v: chainId ? recovery + (chainId * 2 + 35) : recovery + 27, }; </code></pre> We don't know what will happen if we provide an unsafe chain ID to a signing method, but presumably, nothing good. Let's not find out; let's establish a <code>MAX_SAFE_CHAIN_ID</code> and enforce it. Now, <code>sig.recid</code> is the ECDSA signature's "recovery id", which per the following sources is a number in the <code>0 <= 3</code> range: <ul> <li><a href="https://ethereum.stackexchange.com/a/53182">Ethereum StackExchange</a></li> <li><a href="https://pycoin.readthedocs.io/en/latest/source/pycoin.ecdsa.html">The <code>pycoin</code> (a Bitcoin library) documentation</a></li> </ul> In summary: <ul> <li>The chain ID is used to compute the <code>v</code> parameter in various Ethereum signing operations</li> <li>Our signing libraries expect the chain ID to be a primitive <code>JavaScript</code> number</li> <li>The chain ID must not exceed the JavaScript <code>MAX_SAFE_INTEGER</code> (<code>2**53 - 1</code>) in size</li> </ul> <a href="#calculations" id="calculations" style="color: inherit; text-decoration: none;"> <h3>Calculations</h3> </a> Given the above signing implementations, we can calculate the largest chain ID, <code>MAX_SAFE_CHAIN_ID</code>, we can safely handle in MetaMask: <pre><code class="language-text">From ethereumjs-util@7.0.5, we have that: v = recovery + (chainId * 2 + 35) Per the above discussion, we also have that: int_max = 2**53 - 1 recovery_max = 3 chainId_max = ? Therefore: v_max = 3 + (chainId * 2 + 35) = chainId * 2 + 38 && v_max <= int_max -> 2**53 - 1 = MAX_SAFE_CHAIN_ID * 2 + 38 -> // Since we're dealing with integers, we round down. MAX_SAFE_CHAIN_ID = floor( ( 2**53 - 39 ) / 2 ) = 4503599627370476 </code></pre> Given the value of the safe chain ID, we can validate all incoming chain IDs as follows, once they're converted to integers: <pre><code class="language-javascript">const MAX_SAFE_CHAIN_ID = 4503599627370476; function isSafeChainId(chainId) { return ( Number.isSafeInteger(chainId) && chainId > 0 && chainId <= MAX_SAFE_CHAIN_ID ); } </code></pre> </div>  </div> <div class="col-2 col-menu secondary-menu"> <nav class="tsd-navigation secondary menu-sticky"> <ul class="before-current"> <li class=" tsd-kind-enum root"> <a href="enums/SafeChainId.html" class="tsd-kind-icon">SafeChainId</a> </li> <li class=" tsd-kind-variable root"> <a href="modules.html#MAX_SAFE_CHAIN_ID" class="tsd-kind-icon">MAX_SAFE_CHAIN_ID</a> </li> <li class=" tsd-kind-variable root"> <a href="modules.html#MAX_SAFE_CHAIN_ID_HEX" class="tsd-kind-icon">MAX_SAFE_CHAIN_ID_HEX</a> </li> <li class=" tsd-kind-function root"> <a href="modules.html#isSafeChainId" class="tsd-kind-icon">isSafeChainId</a> </li> <li class=" tsd-kind-function root"> <a href="modules.html#normalizeChainId" class="tsd-kind-icon">normalizeChainId</a> </li> </ul> </nav> </div> </div> </div> <footer class="with-border-bottom"> </footer> <div class="container tsd-generator"> Generated using <a href="http://typedoc.org/" target="_blank">TypeDoc</a> </div> <div class="overlay"></div> <script src="assets/js/main.js"></script> </body> </html>