{"id":19901898,"url":"https://github.com/hyperledger/firefly-tokens-erc1155","last_synced_at":"2025-08-10T20:07:20.644Z","repository":{"id":37075289,"uuid":"392375903","full_name":"hyperledger/firefly-tokens-erc1155","owner":"hyperledger","description":"ERC1155 token integration","archived":false,"fork":false,"pushed_at":"2025-07-20T08:16:15.000Z","size":2682,"stargazers_count":22,"open_issues_count":4,"forks_count":15,"subscribers_count":14,"default_branch":"main","last_synced_at":"2025-08-10T07:56:29.365Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://github.com/hyperledger/firefly-tokens-erc1155","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hyperledger.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-08-03T16:09:37.000Z","updated_at":"2025-07-03T13:47:41.000Z","dependencies_parsed_at":"2024-03-04T18:16:20.374Z","dependency_job_id":"b4e4ca62-6eb8-40ed-8450-876e0fa165a6","html_url":"https://github.com/hyperledger/firefly-tokens-erc1155","commit_stats":null,"previous_names":[],"tags_count":38,"template":false,"template_full_name":null,"purl":"pkg:github/hyperledger/firefly-tokens-erc1155","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyperledger%2Ffirefly-tokens-erc1155","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyperledger%2Ffirefly-tokens-erc1155/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyperledger%2Ffirefly-tokens-erc1155/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyperledger%2Ffirefly-tokens-erc1155/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hyperledger","download_url":"https://codeload.github.com/hyperledger/firefly-tokens-erc1155/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyperledger%2Ffirefly-tokens-erc1155/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":269780617,"owners_count":24474686,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-10T02:00:08.965Z","response_time":71,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-12T20:16:33.334Z","updated_at":"2025-08-10T20:07:20.594Z","avatar_url":"https://github.com/hyperledger.png","language":"TypeScript","readme":"# FireFly Tokens Microservice for ERC1155\n\nThis project provides a thin shim between [FireFly](https://github.com/hyperledger/firefly)\nand an ERC1155 contract exposed via [ethconnect](https://github.com/hyperledger/firefly-ethconnect)\nor [evmconnect](https://github.com/hyperledger/firefly-evmconnect).\n\nBased on [Node.js](http://nodejs.org) and [Nest](http://nestjs.com).\n\nThis service is entirely stateless - it maps incoming REST operations directly to blockchain\ncalls, and maps blockchain events to outgoing websocket events.\n\n## Smart Contracts\n\nThis connector is designed to interact with ERC1155 smart contracts on an Ethereum\nblockchain which conform to a few different patterns. The repository includes sample\n[Solidity contracts](samples/solidity/) that conform to some of the ABIs expected.\n\nAt the very minimum, _all_ contracts must implement the events and methods defined in the\nERC1155 standard, including the optional `uri()` method.\n\nBeyond this, there are a few methods for creating a contract that the connector can utilize.\n\n### FireFly Interface Parsing\n\nThe most flexible and robust token functionality is achieved by teaching FireFly about your token\ncontract, then allowing it to teach the token connector. This is optional in the sense that there\nare additional methods used by the token connector to guess at the contract ABI (detailed later),\nbut is the preferred method for most use cases.\n\nTo leverage this capability in a running FireFly environment, you must:\n\n1. [Upload the token contract ABI to FireFly](https://hyperledger.github.io/firefly/tutorials/custom_contracts/ethereum.html)\n   as a contract interface.\n2. Include the `interface` parameter when [creating the pool on FireFly](https://hyperledger.github.io/firefly/tutorials/tokens).\n\nThis will cause FireFly to parse the interface and provide ABI details\nto this connector, so it can determine the best methods from the ABI to be used for each operation.\nWhen this procedure is followed, the connector can find and call any variant of mint/burn/transfer/approval\nthat is listed in the source code for [erc1155.ts](src/tokens/erc1155.ts).\nThis list includes methods in the base standards, methods in the [IERC1155MixedFungible](samples/solidity/contracts/IERC1155MixedFungible.sol)\ninterface defined in this repository, and common method variants from the\n[OpenZeppelin Wizard](https://wizard.openzeppelin.com). Additional variants can be added to the list\nby building a custom version of this connector or by proposing them via pull request.\n\n### Fallback Functionality (not recommended)\n\nIn the absence of being provided with ABI details, the token connector will assume that the contract\nconforms to the `IERC1155MixedFungible` interface defined in this repository.\n\n## API Extensions\n\nThe APIs of this connector conform to the FireFly fftokens standard, and are designed to be called by\nFireFly. They should generally not be called directly by anything other than FireFly.\n\nBelow are some of the specific considerations and extra requirements enforced by this connector on\ntop of the fftokens standard.\n\n### `/createpool`\n\nIf `config.address`, `config.startId`, and `config.endId` are all specified, the connector will assume\nthat a token pool has already been created on the specified contract, using the specified subset of\ntoken IDs (inclusive). Note: Because ERC1155 defines the token ID as uint256, the range of possible IDs\nis `0x0` to `0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff`.\n\nIf `config.address` is specified, the connector will invoke the `create()` method (as defined in the\n[IERC1155Factory](samples/solidity/contracts/IERC1155Factory.sol) interface) of the ERC1155 token\ncontract at the specified address.\n\nIf `config.address` is not specified, and `CONTRACT_ADDRESS` is set in the connector's\nenvironment, the `create()` method of that contract will be invoked.\n\nAny `name` and `symbol` provided from FireFly are ignored by this connector.\n\n### `/mint`\n\nFor fungible token pools, `tokenIndex` and `uri` will be ignored.\n\nFor non-fungible token pools, `tokenIndex` and `amount` will be handled differently depending on the\nunderlying ABI. The sample contract in this repository uses auto-indexing, so `tokenIndex` must be\nomitted and `amount` may be 1 or greater (to mint 1 or more unique NFTs). The samples generated by\nOpenZeppelin generally use manual indexing, so `tokenIndex` must be specified (as an offset from\nthe pool's `startId`) and `amount` must be 1.\n\n### `/burn`\n\nFor non-fungible token pools, `tokenIndex` is required, and `amount` must be 1.\n\n### `/transfer`\n\nFor non-fungible token pools, `tokenIndex` is required, and `amount` must be 1.\n\n### `/approval`\n\nAll approvals are global and will apply to all tokens across _all_ pools on a particular ERC1155 contract.\n\n## Extra APIs\n\nThe following APIs are not part of the fftokens standard, but are exposed under `/api/v1`:\n\n- `GET /balance` - Get token balance\n- `GET /receipt/:id` - Get receipt for a previous request\n\n## Running the service\n\nThe easiest way to run this service is as part of a stack created via\n[firefly-cli](https://github.com/hyperledger/firefly-cli).\n\nTo run manually, you first need to run an Ethereum blockchain node and an instance of\n[firefly-ethconnect](https://github.com/hyperledger/firefly-ethconnect), and deploy the\n[ERC1155 smart contract](solidity/contracts/ERC1155MixedFungible.sol).\n\nThen, adjust your configuration to point at the deployed contract by editing [.env](.env)\nor by setting the environment values directly in your shell.\n\nInstall and run the application using npm:\n\n```bash\n# install\n$ npm install\n\n# run in development mode\n$ npm run start\n\n# run in watch mode\n$ npm run start:dev\n\n# run in production mode\n$ npm run start:prod\n```\n\nView the Swagger UI at http://localhost:3000/api\u003cbr /\u003e\nView the generated OpenAPI spec at http://localhost:3000/api-json\n\n## Testing\n\n```bash\n# unit tests\n$ npm run test\n\n# e2e tests\n$ npm run test:e2e\n\n# lint\n$ npm run lint\n\n# formatting\n$ npm run format\n```\n\n## Blockchain retry behaviour\n\nMost short-term outages should be handled by the blockchain connector. For example if the blockchain node returns `HTTP 429` due to rate limiting\nit is the blockchain connector's responsibility to use appropriate back-off retries to attempt to make the required blockchain call successfully.\n\nThere 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\nmicroservice 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\nthe token connector doesn't perform a retry then the event will be returned without the token URI populated.\n\nThe 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\ninterval 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\nthe error returned from the REST call matches a configurable regular expression retry condition. The default retry condition is `.*ECONN.*` which ensures\nretries take place for common TCP errors such as `ECONNRESET` and `ECONNREFUSED`.\n\nThe configurable retry settings are:\n\n- `RETRY_BACKOFF_FACTOR` (default `2`)\n- `RETRY_BACKOFF_LIMIT_MS` (default `10000`)\n- `RETRY_BACKOFF_INITIAL_MS` (default `100`)\n- `RETRY_CONDITION` (default `.*ECONN.*`)\n- `RETRY_MAX_ATTEMPTS` (default `15`)\n\nSetting `RETRY_CONDITION` to `\"\"` disables retries. Setting `RETRY_MAX_ATTEMPTS` to `-1` causes it to retry indefinitely.\n\nNote, 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)\n\n## TLS\n\nMutual TLS can be enabled by providing three environment variables:\n\n- `TLS_CA`\n- `TLS_CERT`\n- `TLS_KEY`\n\nEach 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.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhyperledger%2Ffirefly-tokens-erc1155","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhyperledger%2Ffirefly-tokens-erc1155","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhyperledger%2Ffirefly-tokens-erc1155/lists"}