web3dart 1.1.1+1

web3dart #

A dart library that connects to interact with the Ethereum blockchain. It connects to an Ethereum node to send transactions, interact with smart contracts and much more!

Features #

  • Connect to an Ethereum node with the rpc-api, call common methods
  • Send signed Ethereum transactions
  • Generate private keys, setup new Ethereum addresses
  • Call functions on smart contracts and listen for contract events

TODO #

  • Code generation based on smart contract ABI for easier interaction
  • Encode all supported solidity types, although only (u)fixed, which are not commonly used, are not supported at the moment.

Usage #

Credentials and Wallets #

In order to send transactions on the Ethereum network, some credentials are required. The library supports raw private keys and v3 wallet files.

import 'dart:math'; //used for the random number generator

import 'package:web3dart/web3dart.dart';
// You can create Credentials from private keys
Credentials fromHex = EthPrivateKey.fromHex("c87509a[...]dc0d3");

// Or generate a new key randomly
var rng = new Random.secure();
Credentials random = EthPrivateKey.createRandom(random)(rng);

// In either way, the library can derive the public key and the address
// from a private key:
var address = await credentials.extractAddress();
print(address.hex);

Another way to obtain Credentials which the library uses to sign transactions is the usage of a wallet file. Wallets store a private key securely and require a password to unlock. The library has experimental support for version 3 wallets commonly generated by other Ethereum clients:

import 'dart:io';
import 'package:web3dart/web3dart.dart';

String content = new File("wallet.json").readAsStringSync();
Wallet wallet = Wallet.fromJson(content, "testpassword");

Credentials unlocked = wallet.privateKey;
// You can now use these credentials to sign transactions or messages

You can also create Wallet files with this library. To do so, you first need the private key you want to encrypt and a desired password. Then, create your wallet with

Wallet wallet = Wallet.createNew(credentials, "password", random);
print(wallet.toJson());

You can also write wallet.toJson() into a file which you can later open with MyEtherWallet (select Keystore / JSON File) or other Ethereum clients like geth.

Custom credentials #

If you want to integrate web3dart with other wallet providers, you can implement Credentials and override the appropriate methods.

Connecting to an RPC server #

The library won't send signed transactions to miners itself. Instead, it relies on an RPC client to do that. You can use a public RPC API like infura, setup your own using geth or, if you just want to test things out, use a private testnet with truffle and ganache. All these options will give you an RPC endpoint to which the library can connect.

import 'package:http/http.dart'; //You can also import the browser version
import 'package:web3dart/web3dart.dart';

var apiUrl = "http://localhost:7545"; //Replace with your API

var httpClient = new Client();
var ethClient = new Web3Client(apiUrl, httpClient);

var credentials = ethClient.credentialsFromPrivateKey("0x...");

// You can now call rpc methods. This one will query the amount of Ether you own
EtherAmount balance = ethClient.getBalance(credentials.address);
print(balance.getValueInUnit(EtherUnit.ether));

Sending transactions #

Of course, this library supports creating, signing and sending Ethereum transactions:

import 'package:web3dart/web3dart.dart';

/// [...], you need to specify the url and your client, see example above
var ethClient = new Web3Client(apiUrl, httpClient);

var credentials = ethClient.credentialsFromPrivateKey("0x...");

await client.sendTransaction(
  credentials,
  Transaction(
    to: EthereumAddress.fromHex('0xC91...3706'),
    gasPrice: EtherAmount.inWei(BigInt.one),
    maxGas: 100000,
    value: EtherAmount.fromUnitAndValue(EtherUnit.ether, 1),
  ),
);

Missing data, like the gas price, the sender and a transaction nonce will be obtained from the connected node when not explicitly specified. If you only need the signed transaction but don't intend to send it, you can use client.signTransaction.

Smart contracts #

The library can parse the abi of a smart contract and send data to it. It can also listen for events emitted by smart contracts. See this file for an example.

Feature requests and bugs #

Please file feature requests and bugs at the issue tracker. If you want to contribute to this libary, please submit a Pull Request.

Changelog #

1.1.1, 1.1.1+1 #

  • Fix parsing transaction receipts when the block number is not yet available. Thanks to @chart21 for the fix.
  • Fix a typo that made it impossible to load the coinbase address. Thanks to @modulovalue for the fix.

1.1.0 #

  • Added getTransactionReceipt to get more detailed information about a transaction, including whether it was executed successfully or not.

1.0.0 #

Basically a complete rewrite of the library - countless bug fixes, a more fluent and consistent api and more features:

  • experimental api to perform expensive operations in a background isolate. Set enableBackgroundIsolate to true when creating a Web3Client to try it out.
  • Events! Use addedBlocks, pendingTransactions and events for auto-updating streams.
  • The client now has a dispose() method which should be called to stop the background isolate and terminate all running streams.

This version contains breaking changes! Here is an overview listing some of them.

BeforeUpdated API
Creating credentials via Credentials.fromPrivateKeyHexUse the EthPrivateKey class or, even better, client.credentialsFromPrivateKey
Sending transactions or calling contract functionsThe api has been changed to just a single methods instead of a transaction builder. See the examples for details.
Low-level cryptographic operations like signing, hashing and converting hex <-> byte array <-> integerNot available in the core library. Import package:web3dart/crypto.dart instead

If you run into problems after updating, please create an issue.

0.4.4 #

  • Added getTransactionByHash method - thank you, maxholman!
  • Allow a different N parameter for scrypt when creating new wallets.

0.4.0 #

  • New APIs allowing for a simpler access to wallets, credentials and addresses
  • More examples in the README

0.2.1 #

  • More solidity types, not with encoding.

0.2 #

  • Send transactions and call messages from smart contracts on the Blockchain.

0.1 #

  • Create new Ethereum accounts

0.0.2 #

  • Send and sign transactions

0.0.1 #

  • Initial version, created by Stagehand

Use this package as a library

1. Depend on it

Add this to your package's pubspec.yaml file:


dependencies:
  web3dart: ^1.1.1+1

2. Install it

You can install packages from the command line:

with pub:


$ pub get

with Flutter:


$ flutter pub get

Alternatively, your editor might support pub get or flutter pub get. Check the docs for your editor to learn more.

3. Import it

Now in your Dart code, you can use:


import 'package:web3dart/web3dart.dart';
  
Popularity:
Describes how popular the package is relative to other packages. [more]
80
Health:
Code health derived from static analysis. [more]
96
Maintenance:
Reflects how tidy and up-to-date the package is. [more]
100
Overall:
Weighted score of the above. [more]
89
Learn more about scoring.

We analyzed this package on Sep 17, 2019, and provided a score, details, and suggestions below. Analysis was completed with status completed using:

  • Dart: 2.5.0
  • pana: 0.12.21

Platforms

Detected platforms: Flutter, other

Primary library: package:web3dart/web3dart.dart with components: isolate.

Health suggestions

Fix lib/src/contracts/abi/abi.dart. (-1.49 points)

Analysis of lib/src/contracts/abi/abi.dart reported 3 hints:

line 143 col 9: DO use curly braces for all flow control structures.

line 145 col 9: DO use curly braces for all flow control structures.

line 222 col 7: DO use curly braces for all flow control structures.

Fix lib/src/core/sync_information.dart. (-1 points)

Analysis of lib/src/core/sync_information.dart reported 2 hints:

line 26 col 7: DO use curly braces for all flow control structures.

line 28 col 7: DO use curly braces for all flow control structures.

Fix lib/src/contracts/abi/arrays.dart. (-0.50 points)

Analysis of lib/src/contracts/abi/arrays.dart reported 1 hint:

line 141 col 7: DO use curly braces for all flow control structures.

Fix additional 3 files with analysis or formatting issues. (-1.50 points)

Additional issues in the following files:

  • lib/src/core/client.dart (1 hint)
  • lib/src/core/transaction_signer.dart (1 hint)
  • lib/src/credentials/wallet.dart (1 hint)

Maintenance suggestions

Maintain an example.

None of the files in the package's example/ directory matches known example patterns.

Common filename patterns include main.dart, example.dart, and web3dart.dart. Packages with multiple examples should provide example/README.md.

For more information see the pub package layout conventions.

Dependencies

Package Constraint Resolved Available
Direct dependencies
Dart SDK >=2.1.0 <3.0.0
convert ^2.1.1 2.1.1
http ^0.12.0 0.12.0+2
isolate ^2.0.0 2.0.2
json_rpc_2 ^2.1.0 2.1.0
meta ^1.1.0 1.1.7
pointycastle ^1.0.1 1.0.1
stream_channel ^2.0.0 2.0.0
typed_data ^1.1.6 1.1.6
uuid ^2.0.0 2.0.2
Transitive dependencies
async 2.3.0
charcode 1.1.2
collection 1.14.12
crypto 2.1.3
http_parser 3.1.3
pedantic 1.8.0+1
source_span 1.5.5
stack_trace 1.9.3
string_scanner 1.0.5
term_glyph 1.1.0
Dev dependencies
coverage ^0.13.0
mockito ^4.0.0
path ^1.6.2 1.6.4
test ^1.5.3
test_api any
test_core any
web_socket_channel ^1.0.0