diff --git a/content/docs/tools/abigen/index.md b/content/docs/tools/abigen/index.md new file mode 100644 index 0000000000..d8c64a730d --- /dev/null +++ b/content/docs/tools/abigen/index.md @@ -0,0 +1,151 @@ +--- +title: Home +root: .. +--- + +Abigen is a binfing-generator for easily interacting with Ethereum using Go. +Abigen creates easy-to-use, type-safe Go packages from Ethereum smart contract definitions known +as ABIs. This abstracts away a lot of the complexity of handling smart contract deployment +and interaction in Go native applications such as encoding and decoding smart contracts into +EVM bytecode. Abigen comes bundled with Geth. A full Geth installation includes the abigen binary. +Abigen can also be built independently by navigating to `go-ethereum/cmd/abigen` and running +`go build`, or equivalently: + +``` +$ cd $GOPATH/src/github.com/ethereum/go-ethereum +$ go build ./cmd/abigen +``` + +## What is an ABI? + +Ethereum smart contracts have a schema that defines its functions and return types in the form +of a JSON file. This JSON file is known as an *Application Binary Interface*, or ABI. The ABI +acts as a specification for precisely how to encode data sent to a contract and how to +decode the data the contract sends back. The ABI is the only essential piece of information required to +generate Go bindings. Go developers can then use the bindings to interact with the contract +from their Go application without having to deal directly with data encoding and decoding. +An ABI is generated when a contract is compiled. + + +### Generating the bindings + +To demonstrate the binding generator a contract is required. The contract `Storage.sol` implements two +very simple functions: `store` updates a user-defined `uint256` to the contract's storage, and `retrieve` +displays the value stored in the contract to the user. The Solidity code is as follows: + +```solidity +// SPDX-License-Identifier: GPL-3.0 + +pragma solidity >0.7.0 < 0.9.0; +/** +* @title Storage +* @dev store or retrieve variable value +*/ + +contract Storage { + + uint256 value; + + function store(uint256 number) public{ + value = number; + } + + function retrieve() public view returns (uint256){ + return value; + } +} +``` + +This contract can be pasted into a text file and saved as `Storage.sol`. + +The following code snippet shows how an ABI can be generated for `Storage.sol` +using the Solidity compiler `solc`. + +```shell +solc --abi Storage.sol -o build +``` + +The ABI can also be generated in other ways such as using the `compile` commands in development +frameworks such as [Truffle][truffle-link], [Hardhat][hardhat-link] and [Brownie][brownie-link] +or in the online IDE [Remix][remix-link]. ABIs for existing +verified contracts can be downloaded from [Etherscan](etherscan.io). + + +The ABI for `Storage.sol` (`Storage.abi`) looks as follows: + +```json +[{"inputs":[],"name":"retrieve","outputs":[{"internalType":"uint256","name":"","type":"uint256"}],"stateMutability":"view","type":"function"},{"inputs":[{"internalType":"uint256","name":"number","type":"uint256"}],"name":"store","outputs":[],"stateMutability":"nonpayable","type":"function"}] +``` + +The contract binding can then be generated by passing the ABI to `abigen` as follows: + +``` +$ abigen --abi Storage.abi --pkg main --type Storage --out Storage.go +``` + +Where the flags are: + + * `--abi`: Mandatory path to the contract ABI to bind to + * `--pkg`: Mandatory Go package name to place the Go code into + * `--type`: Optional Go type name to assign to the binding struct + * `--out`: Optional output path for the generated Go source file (not set = stdout) + +This will generate a type-safe Go binding for the Storage contract. The generated code will +look something like the snippet below, the full version of which can be viewed +[here](https://gist.github.com/jmcook1186/a78e59d203bb54b06e1b81f2cda79d93). + +```go +// Code generated - DO NOT EDIT. +// This file is a generated binding and any manual changes will be lost. + +package main + +import ( + "errors" + "math/big" + "strings" + + ethereum "github.com/ethereum/go-ethereum" + "github.com/ethereum/go-ethereum/accounts/abi" + "github.com/ethereum/go-ethereum/accounts/abi/bind" + "github.com/ethereum/go-ethereum/common" + "github.com/ethereum/go-ethereum/core/types" + "github.com/ethereum/go-ethereum/event" +) + +// Reference imports to suppress errors if they are not otherwise used. +var ( + _ = errors.New + _ = big.NewInt + _ = strings.NewReader + _ = ethereum.NotFound + _ = bind.Bind + _ = common.Big1 + _ = types.BloomLookup + _ = event.NewSubscription +) + +// StorageMetaData contains all meta data concerning the Storage contract. +var StorageMetaData = &bind.MetaData{ + ABI: "[{\"inputs\":[],\"name\":\"retrieve\",\"outputs\":[{\"internalType\":\"uint256\",\"name\":\"\",\"type\":\"uint256\"}],\"stateMutability\":\"view\",\"type\":\"function\"},{\"inputs\":[{\"internalType\":\"uint256\",\"name\":\"number\",\"type\":\"uint256\"}],\"name\":\"store\",\"outputs\":[],\"stateMutability\":\"nonpayable\",\"type\":\"function\"}]", +} + +// StorageABI is the input ABI used to generate the binding from. +// Deprecated: Use StorageMetaData.ABI instead. +var StorageABI = StorageMetaData.ABI + +// Storage is an auto generated Go binding around an Ethereum contract. +type Storage struct { + StorageCaller // Read-only binding to the contract + StorageTransactor // Write-only binding to the contract + StorageFilterer // Log filterer for contract events +} +... + +``` + +`Storage.go` contains all the bindings required to interact with `Storage.sol` from a Go application. + +For instructions on how to deploy this contract to Ethereum from a Go native application read our +[Go bindings page](/content/docs/developers/dapp-developer/native.md). To browse the Abigen source code +visit the Geth [Github repository](https://github.com/ethereum/go-ethereum/tree/master/cmd/abigen). \ No newline at end of file diff --git a/content/docs/tools/puppeth/index.md b/content/docs/tools/puppeth/index.md new file mode 100644 index 0000000000..73856b26f6 --- /dev/null +++ b/content/docs/tools/puppeth/index.md @@ -0,0 +1,8 @@ +--- +title: puppeth +--- + +Puppeth is a tool for quickly spinning up private development networks. + + +[Github repository](https://github.com/ethereum/go-ethereum/tree/master/cmd/puppeth) \ No newline at end of file