flex-contract
Advanced tools
A modern, flexible Ethereum smart contract abstraction that:
If you want a simple library for working with more general (ether) transactions, check out the flex-ether package, upon which this library is based.
npm install flex-contract
# or
yarn install flex-contract
const FlexContract = require('flex-contract');
// May be a plain ABI or a truffle artifact.
const ABI = require('./MyContract.ABI.json');
// Should be the hex-encoded binary output of solc/truffle.
const BYTECODE = require('./MyContract.bytecode.bin');
// Previously deployed contract address. Can also be an ENS address.
const DEPLOYED_AT = '0xf6fb5b73987d6d9a139e23bab97be6fc89e0dcd1';
// A self-signing wallet key for transactions.
const PRIVATE_KEY = '0xb3734ec890893585330c71ece72afb05058192b6be47bee2b99714e6bb5696ab';
// Define a contract interface on the mainnet.
let contract = new FlexContract(ABI);
// Deploy it, signed by an private key.
const tx = contract.new({key: PRIVATE_KEY, bytecode: BYTECODE}).send();
// Wait for the transaction hash.
await tx.txId;
// Wait for the receipt, you can also just wait on the `tx` object itself.
await tx.receipt;
// Wait for the receipt after 3 confirmations.
await tx.confirmed(3);
// Call a constant function and wait for the result(s).
await contract.myConstantFn().call();
// Make a transaction call to the contract, signed by an
// private key, and wait for the receipt.
let receipt = await contract.myTransactionFn('1234').send({ key: PRIVATE_KEY });
// Find some transaction events in the receipt.
let events = receipt.findEvents('MyEvent');
// Find all contract events named 'MyEvent' from the last 16 blocks.
events = await contract.MyEvent().since({ fromBlock: -16 });
// Track events as they happen.
const watcher = contract.MyEvent().watch();
watcher.on('data', event => {
// Handle event.
});
The only requirement for creating an instance is the ABI, which can be a plain ABI outputted by solc, or a Truffle artifact produced by the truffle suite.
By default, the instance will create an Infura provider to
talk to the main network. You can modify this behavior with the options
network, infuraKey, web3, eth, provider, or providerURI.
Some options can be overridden in method calls.
contract = new FlexContract(
// Contract ABI object. May also be a truffle artifact.
ABI: object | Array,
// Deployed address of contract. May be an ENS address (e.g., 'ethereum.eth').
// May omitted.
address: string,
// Options object. May be omitted.
{
// Network to use with Infura provider.
// May be 'main', 'ropsten', 'rinkeby', or 'kovan'.
// Defaults to 'main'
network: string,
// Your Infura project ID, if not passing a custom provider.
infuraKey: string,
// Whether to use a websocket connection instead of an HTTPS connection
// when using Infura.
ws: boolean,
// Connect to an existing provider at a URI
// (e.g., http://localhost:8545 or https://mainnet.infura.io/v3/PROJECT_ID).
// The 'net' option is required is using an IPC path.
providerURI: string,
// net instance, from require('net'), if using IPC path in providerURI
net: object,
// Use a custom provider instance (e.g., web3.currentProvider for metamask).
// Overrides all provider options.
provider: object,
// Use a custom web3 instance (that will be wrapped in a FlexEther).
// Overrides all provider options.
web3: object,
// Use a custom FlexEther (web3 wrapper) instance.
// Overrides all provider options.
// See https://github.com/merklejerk/flex-ether
eth: FlexEther,
// Hex-encoded string output of solc --bin.
// If the ABI passed as the first argument is a truffle artifact,
// the bytecode will already be defined.
bytecode: string,
// Fractional bonus to apply to gas price when making transactions.
// 0.01 = +1%. May be negative to under-price.
// Defaults to -0.005.
// Can be overridden in method calls.
gasPriceBonus: string,
// Fractional bonus to apply to gas limit estimates when making transactions.
// 0.01 = +1%. May be negative, but probably not a good idea.
// Defaults to 0.66
// Can be overridden in method calls.
gasBonus: string
});
The contract instance is automatically populated with the contract functions. Arguments can be passed in positionally or by name through a single dictionary object:
const contract = new FlexContract(ABI, DEPLOYED_ADDRESS);
// Create a call object to `myContractFn(uint256 a, bytes32 b)`
// on the contract with positional arguments.
const call1 = contract.myContractFn(
1337,
'0xebca483a47b9ef4817ecf0b6d326833020a1e21ba067a25bf089e47ba634f87c',
);
// Create a call object to `myContractFn(uint256 a, bytes32 b)`
// on the contract with named arguments.
const call2 = contract.myContractFn({
a: 1337,
b: `0xebca483a47b9ef4817ecf0b6d326833020a1e21ba067a25bf089e47ba634f87c`
});
Calling the function will return a bound function call object, which allows you to do 3 things:
gas(): Estimate the gas cost of the function call.call(): Simulate a call to the function, without modifying the blockchain state. This is the only way to get the return value of a contract function.send(): Send the call as a transaction, which modifies the blockchain state.See Encoding/Decoding Rules for information on how function arguments and return values are encoded and decoded.
Calling gas() on a bound function call will simulate the call and estimate the gas used.
// Estimate the gas used by calling `myContractFn()`. This resolves to a single
// `number`.
const gasUsed = await contract.myContractFn(...args).gas(/* opts */);
gas() accepts a single options object with the following optional fields:
{
// Address of caller. May be an ENS address.
// Defaults to the provider's default account.
from: string,
// Hex-encoded private key.
// Makes the call from the address derived from this private key.
// Overrides the `from` option.
key: string,
// Address of contract to call. May be an ENS address.
// Defaults to contract.address.
address: string,
// Amount of ether (in wei) to send with the call.
// Can be a hex or base-10 string.
value: string,
// Make the call against the blockchain's state at a specific block number.
// Can be a previously mined block number, a negative number, or the string
// 'latest'.
// If the number is negative, it represents a backwards offset from the
// last block mined, where -1 is the last block mined, -2 is the second to
// last, etc.
// Defaults to -1.
block: string,
// Override the generated (hex) call data to be sent.
data: string,
}
Calling call() on a bound function call will simulate the function call without modifying the blockchain state. This is the only way to get the return value from a contract function, as transactions resolve to receipts, not return values.
// Simulate a call to `myContractFn()`, which resolves to its return value(s).
const result = await contract.myContractFn(...args).call(/* opts */);
call() can accept a single options object with the following optional fields:
{
// Address of caller. May be an ENS address.
// Defaults to the provider's default account.
from: string,
// Hex-encoded private key.
// Makes the call from the address derived from this private key.
// Overrides the `from` option.
key: string,
// Address of contract to call. May be an ENS address.
// Defaults to contract.address.
address: string,
// Amount of ether (in wei) to send with the call.
// Can be a hex or base-10 string.
value: string,
// Make the call against the blockchain's state at a specific block number.
// Can be a previously mined block number, a negative number, or the string
// 'latest'.
// If the number is negative, it represents a backwards offset from the
// last block mined, where -1 is the last block mined, -2 is the second to
// last, etc.
// Defaults to -1.
block: string,
// The gas limit of the call.
gas: number,
// Override the generated (hex) call data to be sent.
data: string,
// geth `eth_call` state overrides object.
// See https://geth.ethereum.org/docs/rpc/ns-eth
overrides: object,
}
For some advanced applications you may find yourself handling ABI-encoded, hex result data. Bound functions also have a decodeCallResult() method which can decode these results into more conventional values. For this use, the parameters passed into the bound function do not matter. You can either re-use an existing instance of the bound function or create a new one with dummy values.
const MY_CONSTANT_FN_HEX_RESULT = '0x...';
// Just use dummy values to create a bound function that matches its function signature: myConstantFn(uint256,string).
const reuslt = contract.myConstantFn(1337, 'foo').decodeCallResult(MY_CONSTANT_FN_HEX_RESULT);
To actually modify the blockchain, you can execute a contract function call as a transaction by calling send() on a bound function object. This resolves to a receipt object once the transaction is successfully mined.
send() returns an augmented Promise object with the following fields:
txId: A Promise that resolves once the transaction hash of the call is available.receipt: A Promise that resolves to a receipt once the transaction is mined. Same as waiting on the container Promise object.confirmed(count): A Promise that rsolves to a receipt once the transaction is mind and has been confirmed by count blocks.// Execute a call to `myContractFn()`, which resolves to a receipt when
// successfully mined.
const receipt = await contract.myContractFn(...args).send(/* opts */);
// This also resolves to a transaction receipt.
const receipt = await contract.myContractFn(...args).send(/* opts */).receipt;
// This resolves to the transaction hash once it's available.
const txHash = await contract.myContractFn(...args).send(/* opts */).txId;
// This resolves to the receipt after 4 confirmations.
const receipt = await contract.myContractFn(...args).send(/* opts */).confirmed(4);
send() can accept a single options object with the following optional fields:
{
// Address of caller. May be an ENS address.
// Defaults to the provider's default account.
from: string,
// Hex-encoded private key.
// Makes the call from the address derived from this private key.
// Overrides the `from` option.
key: string,
// Address of contract to call. May be an ENS address.
// Defaults to contract.address.
address: string,
// Amount of ether (in wei) to send with the call.
// Can be a hex or base-10 string.
value: string,
// The gas limit of the call.
gas: number,
// Gas price to use, as a hex or base-10 string, in wei.
// If not specified, it will be calculated from network gas price with bonus.
gasPrice: string,
// Bonus to apply to gas price calculations.
// Should be a positive or negative string, where 0.01 = +1%.
// If omitted, `contract.gasPriceBonus` will be used.
gasPriceBonus: string,
// Bonus to apply to gas limit calculations.
// Should be a positive or negative string, where 0.01 = +1%.
// If omitted, `contract.gasBonus` will be used.
gasBonus: string,
// Override the generated (hex) call data to be sent.
data: string,
A contract can be deployed via new() which, like normal function calls, returns a bound function object with gas(), call(), and send() functions.
const FlexContract = require('flex-contract');
const ABI = require('./MyContract.ABI.json');
// Should be the hex-encoded binary output of solc/truffle.
const BYTECODE = require('./MyContract.bytecode.bin');
// Create a contract with bytecode data.
const contract = FlexContract(ABI, {bytecode: BYTECODE});
// Deploy a new instance of the contract, passing two positional arguments
// to the constructor, signed by default provider account and wait for the receipt.
const receipt = await contract.new(arg1, arg2).send();
// contract.address is now set to the deployed address.
contract.address; // '0x059AFFF592bCF0CD2dDaAF83CeC2dbeEDA6f71D5'
// receipt also has deployed contract address.
receipt.address; // '0x059AFFF592bCF0CD2dDaAF83CeC2dbeEDA6f71D5'
Calling encode() on a bound function call will return the encoded call data.
// Return the encoded call data to `myContractFn()`.
const encoded = await contract.myContractFn(...args).encode(/* opts */);
Receipts resolved from transaction calls follow the format of web3 transaction receipts, augmented with a few extra fields:
events: array of parsed event objects.findEvent(name, args): method to find the first event matching a provided arguments object.findEvents(name, args): method to find all events matching a provided arguments object.Event objects follow the format:
{
// Transaction hash of the transaction that triggered it.
transactionHash: '0x1234...',
// Block number of the block it occured in.
blockNumber: 1234,
// Index against all other logs raised in the transaction.
logIndex: 1234,
// Address of the contract where the event was raised.
address: '0x1234...',
// Name of the event.
name: 'MyEventName',
// Arguments of the event.
// Keys are for both the positional index of the argument and its name.
args: {
'0': FIRST_VALUE,
'FIRST_VALUE_NAME': FIRST_VALUE,
'1': SECOND_VALUE,
'SECOND_VALUE_NAME': SECOND_VALUE,
...
}
}
const receipt = await contract.someTransactionFn(...args).send();
// List events.
receipt.events; // [{name:..., args:...}, ... etc.]
// Find an event named 'MyEvent' matching certain argument values.
// Returns one event.
receipt.findEvent('MyEvent', {argName0: argValue0, ...});
// Find all events named 'MyEvent' matching certain argument values.
// Returns a list of events.
receipt.findEvents('MyEvent', {argName0: argValue0, ...});
Internal events are events that are raised in other contracts during a transaction. The library will attempt to decode these events only if a flex-contract had been previously instantiated to that address, from construction, deployment, or by explicitly setting a contract's address field.
Past events can be retrieved by calling a method on the contract instance sharing the same name as the event, then calling since() on the returned object. Arguments passed into the method will filter results to only those whose arguments match. You may pass null for arguments that should match any value. Event objects follow the format defined in
receipt objects.
The range of blocks to search for events can be set through the fromBlock and toBlock options. Possible values are all mined block numbers. Negative numbers can also be used to specify a backwards offset from the last block, where -1 is the last block, -2 is the second to last block, and so on.
// Get all events named 'MyEvent', which takes two arguments, that occurred in
// the last block. `events` is an array of event objects.
let events = await contract.MyEvent(null, null).since();
// Get all events named 'MyEvent' with the first argument matching `1234` that
// occurred in the last 10 blocks.
events = await contract.MyEvent(1234, null).since({
fromBlock: -10,
toBlock: -1,
});
// Get events named 'MyEvent' matching the named arguments passed that occurred
// in the last block.
events = await contract.MyEvent({
arg1Name: 1234,
arg2Name: null,
});
since() can take the an options object with the following optional fields:
{
// Block number to start the search.
// Negative values are backwards offsets from the last block.
// Defaults to -1.
fromBlock: string,
// Block number to start the search.
// Negative values are backwards offsets from the last block.
// Defaults to -1.
toBlock: string,
// Address of contract. May be an ENS address.
// Defaults to contract.address.
address: string,
}
Events can be monitored as they happen by calling a method with the same name as the event then calling watch() on returned object. This will create an EventEmitter object. Filters are defined as in past events,
but you cannot specify a block range, since watches always scan the current block.
Internally, watches are implemented as polled versions of past events and you can configure the poll rate via the pollRate option. When you no longer need a watcher, you should call its close() method to avoid memory leaks and network
congestion.
// Watch for all events named 'MyEvent' that matches `1234` as the first
// argument and any second argument.
let watcher = contract.MyEvent(1234, null).watch();
// a 'data' event is raised whenever a new matching event is seen.
watcher.on('data', function(event) => {
// Handle the event.
// ...
// Done with watcher.
this.close();
});
// Watch for events named 'MyEvent' matching some arguments by name, and poll
// every 15 seconds.
watcher = contract.MyEvent({arg1Name: 1234, arg2Name: null})
.watch({ pollRate: 15000 });
// Stop polling.
watcher.close();
watch() can take the following options:
{
// How often to scan new blocks, in milliseconds.
// defaults to 15000 (15 seconds).
pollRate: string,
// Address of contract. May be an ENS address.
// Defaults to contract.address.
address: string,
// Named arguments values to filter events by.
// e.g., {ARG_NAME_0: ARG_VALUE_0, ARG_NAME_1: ARG_VALUE_1, ... }
// Do not pass positional arguments if used.
args: object
}
There are a few rules to follow when passing values into contract methods and event filters, and how to expect them.
number type or
converted to base-10 or base-16 string (.e.g, '1234' or '0x04d2').'1234').'0x1337b33f...').'ethereum.eth').'0x1337b33f...').// Solidity definition:
function myConstantFn() pure returns (uint256 a, address b, bytes32 c) {
return (1024,
0x0420DC92A955e3e139b52142f32Bd54C6D46c023,
0x3dffba3b7f99285cc73642eac5ac7110ec7da4b4618d99f3dc9f9954a3dacf27);
}
// flex-contract call
await contract.myConstantFn();
// Output:
// {
// '0': '1024',
// '1': '0x0420DC92A955e3e139b52142f32Bd54C6D46c023',
// '2': '0x3dffba3b7f99285cc73642eac5ac7110ec7da4b4618d99f3dc9f9954a3dacf27A',
// 'a': '1024',
// 'b': '0x0420DC92A955e3e139b52142f32Bd54C6D46c023',
// 'c': '0x3dffba3b7f99285cc73642eac5ac7110ec7da4b4618d99f3dc9f9954a3dacf27A'
// }
Anywhere you can pass an address, you can instead pass an
ENS address, such as
'thisismyensaddress.eth'. If an ENS address cannot be resolved, an
exception will be raised. For event watchers, it will be emitted
in an 'error' event.
ENS is only available on the main, ropsten, and rinkeby networks. The ENS address will also have to be set up with the ENS contract on the respective network to properly resolve.
Once an address is resolved, the address will be cached for future calls.
Each address has a TTL, or time-to-live, defined, which specifies how long
the cache should be retained. However, many ENS registrations unintentionally
leave the TTL at the default of 0, which would imply no caching.
So, by default, cache TTLs are clamped to be at least one hour. You can
configure this behavior yourself by setting the
FlexContract.ens.minTTL property to the minimum number of milliseconds to
keep a cache entry.
You can clone an existing flex-contract instance with the clone() method.
This method accepts an options object that overrides certain properties of the
original instance.
cloned = conract.clone(
// Optional overrides.
{
// Set the deployed address.
address: string,
// Set the contract's bytecode, used in `new()`.
bytecode: string,
// Set the gas price bonus.
// Should be a number, where 0.01 = +1%.
gasPriceBonus: string,
// Set the gas limit bonus.
// Should be a number, where 0.01 = +1%.
gasBonus: string,
// Provide a web3 instance.
web3: object,
// Provide a provider instance.
provider: object,
// Connect to a different providerURI (.e.g, 'http://localhost:8545').
providerURI: string,
// Connect to a different network ('main', 'rinkeby', 'ropsten', 'kovan').
network: string,
// Your Infura project ID. You should provide the `network` option as well
// if you pass this, or else the network will default to `main`.
infuraKey: string
});
A contract instance exposes a few properties, most of which you are free to change. Many of these can also be overridden in individual call options.
address (string) Address the contract is deployed to (may be ENS).gasBonus (string) Gas limit estimate bonus for transactions, where 0.01 = +1%. May be negative.gasPriceBonus (string) Gas price bonus for transactions, where 0.01 = +1%. May be negative.bytecode Bytecode of the contract (if available), used for deployment with new().web3 (Web3) The wrapped Web3 instance used.eth (FlexEther) The flex-ether instance used.abi (Read-only) The ABI defining the contract.FAQs
A modern, flexible Ethereum smart contract abstraction.
The npm package flex-contract receives a total of 0 weekly downloads. As such, flex-contract popularity was classified as not popular.
We found that flex-contract demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Ransomware negotiators share how modern cybercriminals operate like corporations, using specialized teams, negotiation tactics, and reputation management.
Security News
PyPI confirms no security flaws were exploited in the Ultralytics supply chain attack and highlights improvements for safer package publishing.
Security News
Research
The Socket Research Team breaks down a malicious wrapper package that uses obfuscation to harvest credentials and exfiltrate sensitive data.