{"id":21919561,"url":"https://github.com/bosonprotocol/reference-backend","last_synced_at":"2025-04-19T12:33:40.303Z","repository":{"id":40337286,"uuid":"286297618","full_name":"bosonprotocol/reference-backend","owner":"bosonprotocol","description":"[DEPRECATED] An example backend application for Boson Protocol","archived":false,"fork":false,"pushed_at":"2022-12-23T07:21:28.000Z","size":16860,"stargazers_count":10,"open_issues_count":28,"forks_count":0,"subscribers_count":14,"default_branch":"main","last_synced_at":"2023-03-10T01:32:24.575Z","etag":null,"topics":["bosonprotocol","dapp","example-app","reference-app"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"lgpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bosonprotocol.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":".github/CODEOWNERS","security":null,"support":null}},"created_at":"2020-08-09T18:49:53.000Z","updated_at":"2023-02-09T10:29:51.000Z","dependencies_parsed_at":"2023-01-30T18:01:21.494Z","dependency_job_id":null,"html_url":"https://github.com/bosonprotocol/reference-backend","commit_stats":null,"previous_names":[],"tags_count":null,"template":null,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bosonprotocol%2Freference-backend","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bosonprotocol%2Freference-backend/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bosonprotocol%2Freference-backend/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bosonprotocol%2Freference-backend/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bosonprotocol","download_url":"https://codeload.github.com/bosonprotocol/reference-backend/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":226979176,"owners_count":17712574,"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","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":["bosonprotocol","dapp","example-app","reference-app"],"created_at":"2024-11-28T20:08:45.874Z","updated_at":"2024-11-28T20:08:46.648Z","avatar_url":"https://github.com/bosonprotocol.png","language":"JavaScript","readme":"[![banner](docs/assets/banner.png)](https://leptonite.io)\n\n\u003ch1 align=\"center\"\u003eLeptonite - Powered by Boson Protocol\u003c/h1\u003e\n\n[![Gitter chat](https://badges.gitter.im/bosonprotocol.png)](https://gitter.im/bosonprotocol/community)\n\nThis is a reference application which demonstrates how to integrate Boson Protocol into a NodeJS back-end. This repository contains a MongoDB service as well as keeper functions \u0026 event listeners.\n\nThis reference app may be used as a template for building your own marketplace powered by Boson Protocol. Users can connect their wallets and list a set of items as a seller, as well as discover products that can be purchased as a buyer. The application also demonstrates how to the transaction lifecycle can be tracked and co-ordinated by both parties.\n\n---\n**Table of Contents**\n\n- [Design \u0026 Architecture](#design--architecture)\n- [Local Development](#local-development)\n  - [Prerequisites](#prerequisites)\n  - [Build](#build)\n  - [Run](#run)\n  - [Test](#test)\n    - [Unit Tests](#unit-tests)\n    - [Component Tests](#component-tests)\n    - [Persistence Tests](#persistence-tests)\n  - [Code Linting \u0026 Formatting](#code-linting--formatting)\n- [Contributing](#contributing)\n- [License](#license)\n\n---\n## Design \u0026 Architecture\n\nThe application architecture is as depicted below. There are various components to this:\n- `Frontend` (details can be found in the [`reference-frontend`](https://github.com/bosonprotocol/reference-frontend) repository)\n- `Backend`\n    - `Server`\n    - `Database`\n    - `Keepers service` - These are cloud functions which run periodically to trigger certain contract methods such as expiry/finalization. Details can be found [here](https://github.com/bosonprotocol/reference-backend/tree/develop/external/keepers).\n    - `Event Listeners` - This listens for blockchain events and updates the backend accordingly. Details can be found [here](https://github.com/bosonprotocol/reference-backend/tree/develop/external/lambdas).\n- `Smart contracts` (details can be found in the [`contracts`](https://github.com/bosonprotocol/contracts) repository)\n\n[![banner](docs/assets/architecture-diagram.png)](#design-\u0026-architecture)\n\n---\n## Local Development\n\n### Prerequisites\n\nFor local development of the reference-backend, your development machine will need a few\ntools installed. These will allow you to run the ruby scripts (executed as `./go [args]`) to build and test the project.\n\nAt a minimum, you'll need:\n* Node (12.20)\n* NPM (\u003e 6)\n* Ruby (2.7)\n* Bundler (\u003e 2)\n* Git\n* Docker\n* direnv\n  * This easily allows environment variables to be switched when navigating between project directories (e.g. `contracts`, `reference-backend` and `reference-frontend`). You will be prompted to run `direnv allow` to enable this.\n  \nFor instructions on how to get set up with these specific versions:\n* See the [OS X guide](docs/setup/osx.md) if you are on a Mac.\n* See the [Linux guide](docs/setup/linux.md) if you use a Linux distribution.\n\n---\n### Build\nWe have a fully automated local build process to check that your changes are\ngood to be merged. To run the build:\n\n```shell script\n./go\n````\n\nBy default, the build process fetches all dependencies, compiles, lints,\nformats and tests the codebase. There are also tasks for each step. This and\nsubsequent sections provide more details of each of the tasks.\n\nTo fetch dependencies:\n\n```shell script\n./go app:dependencies:install\n```\n\n---\n### Run\nYou will need to:\n - Run a MongoDB database instance (can be local or cloud hosted, like MongoDb Atlas). Be sure the deployed instance is secured with authentication enforced (https://docs.mongodb.com/guides/server/auth/)\n \n * Create a file './.env' on the basis of './.env.example' with the following information:\n    ```\n    DB_CONNECTION_STRING=mongodb://localhost:27017\n    DB_NAME=api\n    DB_USERNAME=admin\n    DB_PASSWORD=secret\n\n    TOKEN_SECRET=1fdd5ab2823e118ee997219330c7abc37a56a5093b753b545ab40e5f216491eec5d400f121e678d6c5b03b01f2e56e1fd14b79afd5c0fdd61477ce469472a8a6\n    GCLOUD_SECRET=1f123ce56aeec5d400b2823e7abc121e6756e1f4b118ee\n\n    VOUCHERS_BUCKET=\"vouchers-upload-images-bucket\"\n    ```\n    Where:\n    * DB_CONNECTION_STRING: the connection string to the DB\n    * DB_NAME: the name of the DB (will be created)\n    * DB_USERNAME/DB_PASSWORD: login/password to access the database\n    * TOKEN_SECRET: see §Configuration above\n    * GCLOUD_SECRET: see §Configuration above\n * Run the API server:\n    ```shell\n    npm install\n    set PORT=3333\n    npm run start\n    ```\n * Create a file './external/keepers/src/.env' on the basis of './external/keepers/src/.env.example' with the following information:\n    ```\n    TOKENS_CONTRACT_ADDRESS=\"0x...\"\n    BOSON_ROUTER_CONTRACT_ADDRESS=\"0x...\"\n    VOUCHER_KERNEL_ADDRESS=\"0x...\"\n    API_URL=\"http://localhost:3333\"\n    GCLOUD_SECRET=\"GENERATED_TOKEN\"\n    ALCHEMY_URL=\"https://eth-desired-network.alchemyapi.io/v2/your-api-key\"\n    ```\n    Where:\n    * TOKENS_CONTRACT_ADDRESS: the address of the ERC1155721 contract\n    * BOSON_ROUTER_CONTRACT_ADDRESS: the address of the BosonRouter contract\n    * VOUCHER_KERNEL_ADDRESS: the address of the VoucherKernel contract\n    * API_URL: the URL of the backend API server (started above)\n    * GCLOUD_SECRET: generated on http://jwtbuilder.jamiekurtz.com with payload = {token: \u003cGCLOUD_SECRET\u003e} and key=\u003cTOKEN_SECRET\u003e, where GCLOUD_SECRET and TOKEN_SECRET values are defined in the env var of the API server\n    * ALCHEMY_URL: URL of the blockchain entry node (Alchemy, Infura, ...). If omitted will fallback to local rpc at port 8545 (default)\n * Run the Keepers service:\n    ```shell\n    npm run start:local:keepers\n    ```\n * Create a file './external/lambdas/.env' on the basis of './external/lambdas/.env.example' with the following information:\n    ```\n    TOKENS_CONTRACT_ADDRESS=\"0x...\"\n    BOSON_ROUTER_CONTRACT_ADDRESS=\"0x...\"\n    CASHIER_ADDRESS=\"0x...\"\n    VOUCHER_KERNEL_ADDRESS=\"0x...\"\n    EXECUTOR_PRIVATE_KEY=\"0x...\"\n    API_URL=\"http://localhost:3333\"\n    GCLOUD_SECRET=\"GENERATED_TOKEN\"\n    PROVIDER_URL=\"https://eth-desired-network.alchemyapi.io/v2/your-api-key\"\n    #If the provider requires a secret authorization field in the request header (like Infura)\n    PROVIDER_SECRET=\n    ```\n    Where:\n    * TOKENS_CONTRACT_ADDRESS: the address of the ERC1155721 contract\n    * BOSON_ROUTER_CONTRACT_ADDRESS: the address of the BosonRouter contract\n    * CASHIER_ADDRESS: the address of the Cashier contract\n    * VOUCHER_KERNEL_ADDRESS: the address of the VoucherKernel contract\n    * EXECUTOR_PRIVATE_KEY: the private key of the wallet to be used to interact with the contracts\n    * API_URL: the URL of the backend API server (started above)\n    * GCLOUD_SECRET: generated on http://jwtbuilder.jamiekurtz.com with payload = {token: \u003cGCLOUD_SECRET\u003e} and key=\u003cTOKEN_SECRET\u003e, where GCLOUD_SECRET and TOKEN_SECRET values are defined in the env var of the API server\n    * PROVIDER_URL: URL of the blockchain entry node (Alchemy, Infura, ...). If omitted will fallback to local rpc at port 8545 (default)\n    * PROVIDER_SECRET: (optional) if the provider requires a secret authorization field in the request header (like Infura)\n * Run the Triggers service:\n    ```shell\n    npm run start:local:triggers\n    ```\n\n---\n### Test\nAll tests are written using\n[Chai's JavaScript testing](https://www.chaijs.com/guide/)\nsupport.\n\n#### Unit Tests\nTo run the unit tests:\n\n```shell script\n./go tests:app:unit\n```\n\n#### Component Tests\nTo run the component tests:\n\n```shell script\n./go tests:app:component\n```\n\n#### Persistence Tests\nTo run the persistence tests:\n\n```shell script\n./go tests:app:persistence\n```\n\n---\n### Code Linting \u0026 Formatting\n\nBoth the app itself and the tests are linted and formatted as part of\nthe build process.\n\nFor the tests, we use:\n* [eslint](https://eslint.org/) for linting\n* [prettier](https://prettier.io/) for formatting\n\nTo lint the app:\n\n```shell script\n./go app:lint\n```\n\nThis will check if the linter is satisfied. If instead you want to attempt to\nautomatically fix any linting issues:\n\n```shell script\n./go app:lint_fix\n```\n\nTo check the formatting of the app:\n\n```shell script\n./go app:format\n```\n\nTo automatically fix formatting issues:\n\n```shell script\n./go app:format_fix\n```\n\nSimilarly, for the tests, to perform the same tasks:\n\n```shell script\n./go tests:app:lint\n./go tests:app:lint_fix\n./go tests:app:format\n./go tests:app:format_fix\n```\n\n---\n## Contributing\n\nWe welcome contributions! Until now, Boson Protocol has been largely worked on by a small dedicated team. However, the ultimate goal is for all of the Boson Protocol repositories to be fully owned by the community and contributors. Issues, pull requests, suggestions, and any sort of involvement are more than welcome.\n\nIf you have noticed a bug, [file an issue](/issues). If you have a large pull request, we recommend filing an issue first; small PRs are always welcome.\n\nQuestions are also welcome, as long as they are tech related. We can use them to improve our documentation.\n\nAll PRs must pass all tests before being merged.\n\nBy being in this community, you agree to the [Code of Conduct](CODE_OF_CONDUCT.md). Take a look at it, if you haven't already.\n\n---\n## License\n\nLicensed under [LGPL v3](LICENSE).\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbosonprotocol%2Freference-backend","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbosonprotocol%2Freference-backend","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbosonprotocol%2Freference-backend/lists"}