188 lines
16 KiB
HTML
188 lines
16 KiB
HTML
<!DOCTYPE html>
|
|
<html class="paged">
|
|
<head>
|
|
<title>Assembler</title>
|
|
<link rel="stylesheet" type="text/css" href="/v5/static/style.css">
|
|
</head>
|
|
<body>
|
|
<div class="sidebar">
|
|
<div class="header">
|
|
<div class="logo"><a href="/v5/"><div class="image"></div><div class="name">ethers</div><div class="version">v5.0</div></a></div>
|
|
</div>
|
|
<div class="toc"><div>
|
|
<div class="link title"><a href="/v5/">Documentation</a></div><div class="base show link depth-1"><a href="/v5/getting-started/">Getting Started</a></div><div class="base show link depth-1"><a href="/v5/concepts/">Ethereum Basics</a></div><div class="hide link depth-2"><a href="/v5/concepts/events/">Events</a></div><div class="hide link depth-2"><a href="/v5/concepts/gas/">Gas</a></div><div class="hide link depth-2"><a href="/v5/concepts/security/">Security</a></div><div class="base show link depth-1"><a href="/v5/api/">Application Programming Interface</a></div><div class="hide link depth-2"><a href="/v5/api/contract/">Contract Interaction</a></div><div class="hide link depth-3"><a href="/v5/api/contract/contract/">Contract</a></div><div class="hide link depth-3"><a href="/v5/api/contract/contract-factory/">ContractFactory</a></div><div class="hide link depth-3"><a href="/v5/api/contract/example/">Example: ERC-20 Contract</a></div><div class="hide link depth-2"><a href="/v5/api/signer/">Signers</a></div><div class="hide link depth-2"><a href="/v5/api/providers/">Providers</a></div><div class="hide link depth-3"><a href="/v5/api/providers/provider/">Provider</a></div><div class="hide link depth-3"><a href="/v5/api/providers/jsonrpc-provider/">JsonRpcProvider</a></div><div class="hide link depth-3"><a href="/v5/api/providers/api-providers/">API Providers</a></div><div class="hide link depth-3"><a href="/v5/api/providers/other/">Other Providers</a></div><div class="hide link depth-3"><a href="/v5/api/providers/types/">Types</a></div><div class="hide link depth-2"><a href="/v5/api/utils/">Utilities</a></div><div class="hide link depth-3"><a href="/v5/api/utils/abi/">Application Binary Interface</a></div><div class="hide link depth-4"><a href="/v5/api/utils/abi/coder/">AbiCoder</a></div><div class="hide link depth-4"><a href="/v5/api/utils/abi/formats/">ABI Formats</a></div><div class="hide link depth-4"><a href="/v5/api/utils/abi/fragments/">Fragments</a></div><div class="hide link depth-4"><a href="/v5/api/utils/abi/interface/">Interface</a></div><div class="hide link depth-3"><a href="/v5/api/utils/address/">Addresses</a></div><div class="hide link depth-3"><a href="/v5/api/utils/bignumber/">BigNumber</a></div><div class="hide link depth-3"><a href="/v5/api/utils/bytes/">Byte Manipulation</a></div><div class="hide link depth-3"><a href="/v5/api/utils/constants/">Constants</a></div><div class="hide link depth-3"><a href="/v5/api/utils/display-logic/">Display Logic and Input</a></div><div class="hide link depth-3"><a href="/v5/api/utils/encoding/">Encoding Utilities</a></div><div class="hide link depth-3"><a href="/v5/api/utils/fixednumber/">FixedNumber</a></div><div class="hide link depth-3"><a href="/v5/api/utils/hashing/">Hashing Algorithms</a></div><div class="hide link depth-3"><a href="/v5/api/utils/hdnode/">HD Wallet</a></div><div class="hide link depth-3"><a href="/v5/api/utils/logger/">Logging</a></div><div class="hide link depth-3"><a href="/v5/api/utils/properties/">Property Utilities</a></div><div class="hide link depth-3"><a href="/v5/api/utils/signing-key/">Signing Key</a></div><div class="hide link depth-3"><a href="/v5/api/utils/strings/">Strings</a></div><div class="hide link depth-3"><a href="/v5/api/utils/transactions/">Transactions</a></div><div class="hide link depth-3"><a href="/v5/api/utils/web/">Web Utilities</a></div><div class="hide link depth-3"><a href="/v5/api/utils/wordlists/">Wordlists</a></div><div class="hide link depth-2"><a href="/v5/api/other/">Other Libraries</a></div><div class="hide link depth-3"><a href="/v5/api/other/assembly/">Assembly</a></div><div class="hide link depth-4"><a href="/v5/api/other/assembly/dialect/">Ethers ASM Dialect</a></div><div class="hide link depth-4"><a href="/v5/api/other/assembly/api/">Utilities</a></div><div class="hide link depth-4"><a href="/v5/api/other/assembly/ast/">Abstract Syntax Tree</a></div><div class="hide link depth-3"><a href="/v5/api/other/hardware/">Hardware Wallets</a></div><div class="hide link depth-2"><a href="/v5/api/experimental/">Experimental</a></div><div class="base ancestor show link depth-1"><a href="/v5/cli/">Command Line Interfaces</a></div><div class="show link depth-2"><a href="/v5/cli/ethers/">Sandbox Utility</a></div><div class="myself ancestor ancestor show link depth-2"><a href="/v5/cli/asm/">Assembler</a></div><div class="show link depth-2"><a href="/v5/cli/ens/">Ethereum Naming Service</a></div><div class="show link depth-2"><a href="/v5/cli/typescript/">TypeScript</a></div><div class="show link depth-2"><a href="/v5/cli/plugin/">Making Your Own</a></div><div class="base show link depth-1"><a href="/v5/cookbook/">Cookbook</a></div><div class="base show link depth-1"><a href="/v5/migration/">Migration Guide</a></div><div class="hide link depth-2"><a href="/v5/migration/web3/">Migration: From Web3.js</a></div><div class="hide link depth-2"><a href="/v5/migration/ethers-v4/">Migration: From Ethers v4</a></div><div class="base show link depth-1"><a href="/v5/testing/">Testing</a></div><div class="base show link depth-1"><a href="/v5/contributing/">Contributing and Hacking</a></div><div class="base show link depth-1"><a href="/v5/documentation/">Flatworm Docs</a></div><div class="base show link depth-1"><a href="/v5/license/">License and Copyright</a></div>
|
|
</div></div>
|
|
</div>
|
|
<div class="content">
|
|
<div class="breadcrumbs"><a href="/v5/">Documentation</a> » <a href="/v5/cli/">Command Line Interfaces</a> » <span class="current">Assembler</span></div>
|
|
|
|
<a name="cli-asm"></a><a name="cli-asm"></a><h1 class="show-anchors"><div>Assembler<div class="anchors"><a class="self" href="/v5/cli/asm/#cli-asm"></a></div></div></h1><p>The assembler Command-Line utility allows you to assemble the <a href="/v5/api/other/assembly/dialect/">Ethers ASM Dialect</a> into deployable EVM bytecode and disassemle EVM bytecode into human-readable mnemonics.</p>
|
|
|
|
<a name="cli-asm--help"></a><h2 class="show-anchors"><div>Help<div class="anchors"><a class="self" href="/v5/cli/asm/#cli-asm--help"></a></div></div></h2>
|
|
<div class="code">Usage:
|
|
ethers-asm [ FILENAME ] [ OPTIONS ]
|
|
|
|
OPTIONS
|
|
--define KEY=VALUE provide assembler defines
|
|
--disassemble Disassemble input bytecode
|
|
--ignore-warnings Ignore warnings
|
|
--pic generate position independent code
|
|
--target LABEL output LABEL bytecode (default: _)
|
|
|
|
OTHER OPTIONS
|
|
--debug Show stack traces for errors
|
|
--help Show this usage and exit
|
|
--version Show this version and exit</div><a name="cli-asm--example-input-files"></a><h2 class="show-anchors"><div>Example Input Files<div class="anchors"><a class="self" href="/v5/cli/asm/#cli-asm--example-input-files"></a></div></div></h2>
|
|
<div class="code-title"><div>SimpleStore.asm</div></div><div class="code">; SimpleStore (uint)
|
|
|
|
; Set the inital value of 42
|
|
sstore(0, 42)
|
|
|
|
; Init code to deploy myContract
|
|
codecopy(0, $myContract, #myContract)
|
|
return(0, #myContract)
|
|
|
|
@myContract {
|
|
; Non-payable
|
|
jumpi($error, callvalue)
|
|
|
|
; Get the Sighash
|
|
shr({{= 256 - 32 }}, calldataload(0))
|
|
|
|
; getValue()
|
|
dup1
|
|
{{= sighash("getValue()") }}
|
|
jumpi($getValue, eq)
|
|
|
|
; setValue(uint)
|
|
dup1
|
|
{{= sighash("setValue(uint)") }}
|
|
jumpi($setValue, eq)
|
|
|
|
; No matching signature
|
|
@error:
|
|
revert(0, 0)
|
|
|
|
@getValue:
|
|
mstore(0, sload(0))
|
|
return (0, 32)
|
|
|
|
@setValue:
|
|
; Make sure we have exactly a uint
|
|
jumpi($error, iszero(eq(calldatasize, 36)))
|
|
|
|
; Store the value
|
|
sstore(0, calldataload(4))
|
|
return (0, 0)
|
|
|
|
; There is no *need* for the PUSH32, it just makes
|
|
; decompiled code look nicer
|
|
@checksum[
|
|
{{= (defines.checksum ? concat([
|
|
Opcode.from("PUSH32"),
|
|
id(myContract.source)
|
|
]): "0x")
|
|
}}
|
|
]
|
|
}</div><div class="code-title"><div>SimpleStore.bin</div></div><div class="code">0x602a6000556044601160003960446000f334601e5760003560e01c8063209652
|
|
0x5514602457806355241077146030575b60006000fd5b60005460005260206000
|
|
0xf35b6024361415601e5760043560005560006000f3</div><div class="definition container-box note"><div class="term">Note: Bytecode File Syntax</div><div class="body"><p>A bin file may be made up of multiple blocks of bytecode, each may optionally begin with a <code class="inline">0x</code> prefix, all of which <b>must</b> be of even length (since bytes are required, with 2 nibbles per byte)</p>
|
|
|
|
<p>All whitespace is ignored.</p>
|
|
|
|
</div></div><a name="cli-asm--assembler-examples"></a><h2 class="show-anchors"><div>Assembler Examples<div class="anchors"><a class="self" href="/v5/cli/asm/#cli-asm--assembler-examples"></a></div></div></h2><p>The assembler converts an <a href="/v5/api/other/assembly/dialect/">Ethers ASM Dialect</a> into bytecode by running multiple passes of an assemble stage, each pass more closely approximating the final result.</p>
|
|
|
|
<p>This allows small portions of the bytecode to be massaged and tweaked until the bytecode stablizes. This allows for more compact jump destinations and for code to be include more advanced meta-programming techniques.</p>
|
|
|
|
<div class="code">/home/ethers> ethers-asm SimpleStore.asm
|
|
0x602a6000556044601160003960446000f334601e5760003560e01c80632096525514602457806355241077146030575b60006000fd5b60005460005260206000f35b6024361415601e5760043560005560006000f3
|
|
|
|
# Piping in ASM source code
|
|
/home/ethers> cat SimpleStore.asm | ethers-asm
|
|
# Same as above
|
|
|
|
# Setting a define which the ASM file checks and adds a checksum
|
|
/home/ethers> ethers-asm --define checksum SimpleStore.asm
|
|
0x602a6000556065601160003960656000f334601e5760003560e01c80632096525514602457806355241077146030575b60006000fd5b60005460005260206000f35b6024361415601e5760043560005560006000f37f10358310d664c9aeb4bf4ce7a10a6a03176bd23194c8ccbd3160a6dac90774d6</div><a name="cli-asm--assembler-examples--options"></a><h3 class="show-anchors"><div>Options<div class="anchors"><a class="self" href="/v5/cli/asm/#cli-asm--assembler-examples--options"></a></div></div></h3>
|
|
<div class="definition"><div class="term"><b>--define KEY=VALUE</b> <i>or</i> <b>--define FLAG</b></div><div class="body"><p>This allows key/value pairs (where the value is a string) and flags (which the value is <code class="inline">true</code>) to be passed along to the assembler, which can be accessed in <a href="/v5/api/other/assembly/dialect/#asm-dialect-scripting">Scripting Blocks</a>, such as <code class="inline">{{= defined.someKey }}</code>.</p>
|
|
|
|
</div></div><div class="definition"><div class="term"><b>--ignore-warnings</b></div><div class="body"><p>By default any warning will be treated like an error. This enabled by-passing warnings.</p>
|
|
|
|
</div></div><div class="definition"><div class="term"><b>--pic</b></div><div class="body"><p>When a program is assembled, the labels are usually given as an absolute byte position, which can be jumped to for loops and control flow. This means that a program must be installed at a specific location.</p>
|
|
|
|
<p>Byt specifying the <b>Position Independent Code</b> flag, code will be generated in a way such that all offsets are relative, allowing the program to be moved without any impact to its logic.</p>
|
|
|
|
<p>This does incur an additional gsas cost of 8 gas per offset access though.</p>
|
|
|
|
</div></div><div class="definition"><div class="term"><b>--target LABEL</b></div><div class="body"><p>All programs have a root scope named <code class="inline">_</code> which is by default assembled. This option allows another labelled target (either a <a href="/v5/api/other/assembly/dialect/#asm-dialect-scope">Scopes</a> or a <a href="/v5/api/other/assembly/dialect/#asm-dialect-datasegment">Data Segment</a> to be assembled instead. The entire program is still assembled per usual, so this only impacts which part of the program is output.</p>
|
|
|
|
</div></div><a name="cli-asm--disassembler-examples"></a><h2 class="show-anchors"><div>Disassembler Examples<div class="anchors"><a class="self" href="/v5/cli/asm/#cli-asm--disassembler-examples"></a></div></div></h2><p>A disassembled program shows offsets and mnemonics for the given bytecode. This format may change in the future to be more human-readable.</p>
|
|
|
|
<div class="code">/home/ethers> ethers-asm --disassemble SimpleStore.bin
|
|
0000 : 0x2a ; #1
|
|
0002 : 0x00 ; #1
|
|
0004 : SSTORE
|
|
0005 : 0x44 ; #1
|
|
0007 : 0x11 ; #1
|
|
0009 : 0x00 ; #1
|
|
000b : CODECOPY
|
|
000c : 0x44 ; #1
|
|
000e : 0x00 ; #1
|
|
0010 : RETURN
|
|
0011 : CALLVALUE
|
|
0012 : 0x1e ; #1
|
|
0014 : JUMPI
|
|
0015 : 0x00 ; #1
|
|
0017 : CALLDATALOAD
|
|
0018 : 0xe0 ; #1
|
|
001a : SHR
|
|
001b : DUP1
|
|
001c : 0x20965255 ; #4
|
|
0021 : EQ
|
|
0022 : 0x24 ; #1
|
|
0024 : JUMPI
|
|
0025 : DUP1
|
|
0026 : 0x55241077 ; #4
|
|
002b : EQ
|
|
002c : 0x30 ; #1
|
|
002e : JUMPI
|
|
002f*: JUMPDEST
|
|
0030 : 0x00 ; #1
|
|
0032 : 0x00 ; #1
|
|
0034 : REVERT
|
|
0035*: JUMPDEST
|
|
0036 : 0x00 ; #1
|
|
0038 : SLOAD
|
|
0039 : 0x00 ; #1
|
|
003b : MSTORE
|
|
003c : 0x20 ; #1
|
|
003e : 0x00 ; #1
|
|
0040 : RETURN
|
|
0041*: JUMPDEST
|
|
0042 : 0x24 ; #1
|
|
0044 : CALLDATASIZE
|
|
0045 : EQ
|
|
0046 : ISZERO
|
|
0047 : 0x1e ; #1
|
|
0049 : JUMPI
|
|
004a : 0x04 ; #1
|
|
004c : CALLDATALOAD
|
|
004d : 0x00 ; #1
|
|
004f : SSTORE
|
|
0050 : 0x00 ; #1
|
|
0052 : 0x00 ; #1
|
|
0054 : RETURN
|
|
|
|
/home/ethers> cat SimpleStore.bin | ethers-asm --disassemble
|
|
# Same as above</div>
|
|
|
|
<div class="footer">
|
|
<div class="nav previous"><a href="/v5/cli/ethers/"><span class="arrow">←</span>Sandbox Utility</a></div>
|
|
<div class="nav next"><a href="/v5/cli/ens/">Ethereum Naming Service<span class="arrow">→</span></a></div>
|
|
</div>
|
|
<div class="copyright">The content of this site is licensed under the <a href="https://choosealicense.com/licenses/cc-by-4.0/">Creative Commons License</a>. Generated on July 5, 2020, 12:0am.</div>
|
|
</div>
|
|
<script src="/v5/static/script.js" type="text/javascript"></script>
|
|
</body>
|
|
</html>
|