This project provides a thin shim between FireFly and an ERC1155 contract exposed via ethconnect or evmconnect.
This service is entirely stateless - it maps incoming REST operations directly to blockchain calls, and maps blockchain events to outgoing websocket events.
This connector is designed to interact with ERC1155 smart contracts on an Ethereum blockchain which conform to a specific pattern. The repository includes a sample Solidity contract that may be used to get up and running with simple token support, and may provide a starting point for developing production contracts that can be used with this connector.
To be usable by this connector, an ERC1155 contract should do all of the following:
- Conform to IERC1155MixedFungible.
- Group tokens into clear fungible and non-fungible pools by partitioning the token ID space via the split bit implementation detailed in the comments in ERC1155MixedFungible.
This connector may also be used as a starting point to build a custom connector that interacts with ERC1155 contracts conforming to some other pattern.
The most flexible and robust token functionality is achieved by teaching FireFly about your token contract, then allowing it to teach the token connector. This is optional in the sense that there are additional methods used by the token connector to guess at the contract ABI (detailed later), but is the preferred method for most use cases.
To leverage this capability in a running FireFly environment, you must:
- Upload the token contract ABI to FireFly as a contract interface.
- Include the
interfaceparameter when creating the pool on FireFly.
This will cause FireFly to parse the interface and provide ABI details to this connector, so it can determine the best methods from the ABI to be used for each operation. When this procedure is followed, the connector can find and call any variant of mint/burn/transfer/approval that is listed in the source code for erc1155.ts. Due to strong assumptions in the source code, these are mostly the signatures from IERC1155MixedFungible, with a few other variants for some methods from the OpenZeppelin Wizard.
In the absence of being provided with ABI details, the token connector will attempt to guess the contract
ABI in use. It does this by using ERC165 supportsInterface() to query the contract's support for
IERC1155MixedFungible, as defined in this repository. If the query succeeds, the connector will leverage
the methods on that interface to perform token operations. Therefore it is possible to use these
contracts without the extra step of teaching FireFly about the contract interface first.
The APIs of this connector conform to the FireFly fftokens standard, and are designed to be called by FireFly. They should generally not be called directly by anything other than FireFly.
Below are some of the specific considerations and extra requirements enforced by this connector on top of the fftokens standard.
If config.address is specified, the connector will invoke the create() method of the ERC1155 token
contract at the specified address.
If config.address is not specified, and CONTRACT_ADDRESS is set in the connector's
environment, the create() method of that contract will be invoked.
Any name and symbol provided from FireFly are ignored by this connector.
For fungible token pools, tokenIndex and uri will be ignored.
For non-fungible token pools, tokenIndex will be ignored, as an index will be auto-generated.
amount may be any integer that can be represented by a JavaScript number, and will cause that
amount of unique tokens to be minted.
For non-fungible token pools, tokenIndex is required, and amount must be 1.
For non-fungible token pools, tokenIndex is required, and amount must be 1.
All approvals are global and will apply to all tokens across all pools on a particular ERC1155 contract.
The following APIs are not part of the fftokens standard, but are exposed under /api/v1:
GET /balance- Get token balanceGET /receipt/:id- Get receipt for a previous request
The easiest way to run this service is as part of a stack created via firefly-cli.
To run manually, you first need to run an Ethereum blockchain node and an instance of firefly-ethconnect, and deploy the ERC1155 smart contract.
Then, adjust your configuration to point at the deployed contract by editing .env or by setting the environment values directly in your shell.
Install and run the application using npm:
# install
$ npm install
# run in development mode
$ npm run start
# run in watch mode
$ npm run start:dev
# run in production mode
$ npm run start:prodView the Swagger UI at http://localhost:3000/api
View the generated OpenAPI spec at http://localhost:3000/api-json
# unit tests
$ npm run test
# e2e tests
$ npm run test:e2e
# lint
$ npm run lint
# formatting
$ npm run formatMost short-term outages should be handled by the blockchain connector. For example if the blockchain node returns HTTP 429 due to rate limiting
it is the blockchain connector's responsibility to use appropriate back-off retries to attempt to make the required blockchain call successfully.
There are cases where the token connector may need to perform its own back-off retry for a blockchain action. For example if the blockchain connector microservice has crashed and is in the process of restarting just as the token connector is trying to query an NFT token URI to enrich a token event, if the token connector doesn't perform a retry then the event will be returned without the token URI populated.
The token connector has configurable retry behaviour for all blockchain related calls. By default the connector will perform up to 15 retries with a back-off
interval between each one. The default first retry interval is 100ms and doubles up to a maximum of 10s per retry interval. Retries are only performed where
the error returned from the REST call matches a configurable regular expression retry condition. The default retry condition is .*ECONN.* which ensures
retries take place for common TCP errors such as ECONNRESET and ECONNREFUSED.
The configurable retry settings are:
RETRY_BACKOFF_FACTOR(default2)RETRY_BACKOFF_LIMIT_MS(default10000)RETRY_BACKOFF_INITIAL_MS(default100)RETRY_CONDITION(default.*ECONN.*)RETRY_MAX_ATTEMPTS(default15)
Setting RETRY_CONDITION to "" disables retries. Setting RETRY_MAX_ATTEMPTS to -1 causes it to retry indefinitely.
Note, the token connector will make a total of RETRY_MAX_ATTEMPTS + 1 calls for a given retryable call (1 original attempt and RETRY_MAX_ATTEMPTS retries)
Mutual TLS can be enabled by providing three environment variables:
TLS_CATLS_CERTTLS_KEY
Each should be a path to a file on disk. Providing all three environment variables will result in a token connector running with TLS enabled, and requiring all clients to provide client certificates signed by the certificate authority.