fuellabs / fuels-ts

Fuel Network Typescript SDK

fuels-ts is a library for interacting with Fuel v2.

Resources

The documentation site is your main stop for resources.

• Quickstart
• Documentation
  • Wallets
  • Contracts
  • Scripts
  • Predicates
  • ABI Typegen
• Contributing
• The Fuel Forum
• The Fuel Ecosystem

Install

npm install fuels --save

If you are a Windows user, you will need to be running Windows Subsystem for Linux (WSL) to install and use the Fuel toolchain, including the TypeScript SDK. We don't support Windows natively at this time.

Import

Simple example usages.

import { Wallet } from "fuels";

// Random Wallet
console.log(Wallet.generate());

// Using privateKey Wallet
console.log(new Wallet("0x0000...0000"));

CLI

Fuels include some utility commands via built-in CLI tool.

Check the docs for more info.

$ npm add fuels
$ npx fuels --help
Usage: fuels [options] [command]

Options:
  -D, --debug        Enables verbose logging (default: false)
  -S, --silent       Omit output messages (default: false)
  -v, --version      Output the version number
  -h, --help         Display help

Commands:
  init [options]     Create a sample `fuel.config.ts` file
  dev [options]      Start a Fuel node and run build + deploy on every file change
  build [options]    Build Sway programs and generate Typescript for them
  deploy [options]   Deploy contracts to the Fuel network
  typegen [options]  Generate Typescript from Sway ABI JSON files
  versions           Check for version incompatibilities
  core               Wrapper around Fuel Core binary
  forc               Wrapper around Forc binary
  help [command]     Display help for command

The Fuel Ecosystem

Learn more about the Fuel Ecosystem.

• 🌴 Sway — The new language, empowering everyone to build reliable and efficient smart contracts
• 🧰 Forc — The Fuel toolbox: Build, deploy and manage your sway projects
• ⚙️ Fuel Core — The new FuelVM, a blazingly fast blockchain VM
• 🔗 Fuel Specs — The Fuel protocol specifications
• 💼 Fuels Wallet — The Official Fuels Wallet
• 🦀 Rust SDK — A robust SDK in rust
• ⚡ Fuel Network — The project
• 📚 The Fuel Forum — Ask questions, get updates, and contribute to a modular future

License

The primary license for this repo is Apache 2.0, see LICENSE.

fuels-ts's Issues

Add Mnemonic and HDWallet support

• Generate a BIP-039 + BIP-044 wallet from mnemonic deriving path using the wordlist.

Update Typechain and spike on generating structs

Implement structs and enums from `type: contract` Fuel spec

Currently, function is only one supported.

With more custom data types, abi of type contract with struct definitions will be added. https://github.com/FuelLabs/fuel-specs/blob/master/specs/protocol/abi.md#json-abi-format

Implement contract type

Add documentation with jsdoc or typedocs

Update Providers package to use the latest fuel-core

Setup Versioned Releases

We have addressed the issue of publishing packages to NPM on #38, but that doesn't include proper versioning.

We should make proper releases that:

• Are published to the NPM tag latest
• Have proper semver-following versions
• Have changes in a CHANGELOG.md
• Make GH releases with change logs (that will appear here: https://github.com/FuelLabs/fuels-ts/releases)

Update calls creates transactions, and makes a function call -> returns receipts

Human-Readable ABI

Having an ABI format that is human-readable may provide a better experience.
https://blog.ricmoo.com/human-readable-contract-abis-in-ethers-js-141902f4d917

Suggest rename to fuel-ts

I think this repository / module should be renamed fuel-ts. Is there any reason why we went with "fuels-ts"?

Update `contact-v2` dependency to use NPM instead of github

The merkle tree code uses contracts from contract-v2. The repo is private and uses git to pull the dependency. This forces us to set an access token for CI. Once contract-v2 is accessible via NPM, CI and package.json should be updated.

Support default storage when creating contracts

Users should be able to specify default values for contract storage when deploying them.

Blockers:

• FuelLabs/fuel-specs#236

Add `signMessage`

Add signMessage following;

• specs: https://github.com/FuelLabs/fuel-specs/blob/master/specs/protocol/cryptographic_primitives.md#public-key-cryptography
• fuels-rs implementation: FuelLabs/fuels-rs@40d9b6b#diff-dabbabe6828f1fb7638ca0ace7dd311af93e4f83fc42d234246fdef19d086cf0

Add `signTransaction`

Currently it is hard to test/dev against a provider/contract. We should mock it out

Add `sendTransactions`.

Add feature to send signed transactions. Related to #39

Wire up Provider to Contract

Add pre-commit or pre-push hooks to run linter and tests

Use husky and run linting and tests

Encrypt/Decrypt wallet

• Encrypt wallet data using password wallet.lock(password: string) -> Wallet({ locked: true })
• Decrypt wallet data using password wallet.unlock(password: string) -> Wallet({ locked: false })

Implement Tx Coding

Transaction encoding should be implemented according to spec: https://github.com/FuelLabs/fuel-specs/blob/master/specs/protocol/tx_format.md

abigen: exclude first 3 fields instead of name matching

As discussed in FuelLabs/fuels-rs#11 (comment), once the Sway compiler removes the need to have gas, color, and coin amount as mandatory arguments to every ABI method, we should go back to this place in the fuels-ts code and remove the workaround.

Add TransactionRequest to Provider

Add named getters for storage slots

Interface and Contract should have support for accessing storage slots.

Blockers

• Storage API/syntax needs to be decided

Scaffold & Linting

Set up the project structure, add linting, and TS

• Prettier
• TS
• Dir structure
• Modules
• Port over https://github.com/FuelLabs/fuel-v2-contracts/tree/master/protocol
• Perf Benchmarks
• ????
• Profit

Add wallets to sign transactions

Follow https://docs.ethers.io/v5/api/signer/ and implement it

Documentation for how ABI encode/decode

Extract Merkle Tree Code into Own Library

Our MT code should be available as an independent package that isn't Fuel specific so it can be used on other projects.

Set Up CI

Run test, linting, etc

Implement Provider for Fuel Nodes

A Provider should be implemented to communicate with Fuel nodes.

Refactor `Tuple` and `Array` Coders

These coders are called recursively and have input/output types of any. We should refactor this so the types are explicit on these coders.

Contract factory

Support calling contracts with composite inputs and outputs

Update to fuel-core 0.2.0

ABI Encode/Decode

First pass is to create encode and decode functions to match argument encoding specs.

Use https://github.com/ethers-io/ethers.js/blob/master/packages/abi/src.ts/abi-coder.ts as a reference

Add missing operations to Provider

Update `fuels-ts` for `0.2.0`

Update provider tests
Main one is the getCoinsByOwner -> coins update.
ProgramState
coin id update
etc

Merkletree => TS

• Port over https://github.com/FuelLabs/fuel-v2-contracts/tree/master/protocol
• Perf Benchmarks
• ????
• Profit

Add Example Node App

Add an example Node.js app that uses fuels-ts.

• Add example Sway contract
• Add a script to publish the contract
• Add a script that generates TS types/code from contract
  • Blocked by FuelLabs/sway#322
• Add an Express app (80% usage in State of JS 2020 Back-end Frameworks)
• Add Jest tests (68% usage in State of JS 2020 Testing)

Update to latest Forc and fuel-core

We don't actually depend on Forc, but we have files generated by Forc. We should update Forc on our locals and regenerate these files to make sure we are compatible with their latest version.

Changes similar to FuelLabs/fuels-rs#19 will be required.

Setup Package Publishing

Typechain target for Sway ABI

Create a target using this structure and create *.d.ts files and factories for development

Notes:

https://github.com/dethcrypto/TypeChain/blob/7999f466164b7045a8c57e1fd92c667e24c6a71a/packages/typechain/src/typechain/findTarget.ts

Current supported type:

• function

Improve README.md

Implement Interface for contracts (ABI -> TS generator)

Match specs to take in https://github.com/FuelLabs/fuel-specs/blob/master/specs/protocol/abi.md#json-abi-format and encode and decode function and arguments.

Follow patterns from https://github.com/ethers-io/ethers.js/blob/master/packages/abi/src.ts/interface.ts
https://docs.ethers.io/v5/api/utils/abi/interface/

Make the REPO Open source

add the license and magic

Bikeshed Display Name

Just like ethers.js/Ethers and sway/Sway, fuels-ts and fuels-rs should also have capitalized display names.

Encoding and decoding function results

ABI should be able to encode and decode function results on the interface

Flush out other ABI types

Currently function is supported.

What are the other types we should spec out?

Fix `byte[]` Coding

WitnessCoder and anything else that uses byte[] should be checked if they properly pad to 8 bytes when encoding and also consume that padding during decoding.

[SPIKE] Figure out performance/benchmark tests

Metamask intergration

Integrate with metamask

https://docs.metamask.io/guide/rpc-api.html#wallet-addethereumchain

To intergrate we need the following:

interface AddEthereumChainParameter {
  chainId: string; // A 0x-prefixed hexadecimal string
  chainName: string;
  nativeCurrency: {
    name: string;
    symbol: string; // 2-6 characters long
    decimals: 18;
  };
  rpcUrls: string[];
  blockExplorerUrls?: string[];
  iconUrls?: string[]; // Currently ignored.
}

Currently don't have an ethereum json-rpc facade

Enable Provider Tests

ATM Provider tests are being skipped. We should enable them.

Blockers:

• FuelLabs/fuel-core#40
• FuelLabs/fuel-core#41
• Mutation.dryRun needs to use binary tx/receipt format

`Utilites.signMessage` it's not working like `wallet.<signMessage|signTransaction>`

It looks like we have a divergency when finding the public key from a signed message;

Given private key in this case:
0xae78c8b502571dba876742437f8bc78b689cf8518356c0921393d89caaf284ce

We have;

1. When we sign a transaction/message with wallet.<signMessage|signTransaction> and retrieve the public key with utilities.<verifyMessage|verifyTransaction> or just check the wallet.publickKey it has a value
   0xa1ad658fd9b046cb8bc37cba09e1330c859467b235a5c76659000c4577f526c7. Link
2. If we use utilities.signMessage and try to check the publicKey using utilities.verifyMessage it returns the publicKey 0xbafe4b5d65c9efd34390402ca185d4a58a9e5b1d89c5bc52d90d382059296508. Link