{"id":16484370,"url":"https://github.com/nugaon/bicyclechain","last_synced_at":"2025-09-02T12:34:00.223Z","repository":{"id":40734627,"uuid":"186825030","full_name":"nugaon/bicyclechain","owner":"nugaon","description":"Unified Blockchain API for financial use. ","archived":false,"fork":false,"pushed_at":"2023-01-07T05:30:46.000Z","size":2480,"stargazers_count":8,"open_issues_count":23,"forks_count":6,"subscribers_count":1,"default_branch":"master","last_synced_at":"2024-10-12T13:16:51.863Z","etag":null,"topics":["bitcoin","bitcoin-wallet","blockchain","blockchain-api","ethereum","ripple"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nugaon.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"license","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-05-15T12:47:29.000Z","updated_at":"2021-09-24T04:15:42.000Z","dependencies_parsed_at":"2023-02-06T12:46:31.135Z","dependency_job_id":null,"html_url":"https://github.com/nugaon/bicyclechain","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nugaon%2Fbicyclechain","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nugaon%2Fbicyclechain/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nugaon%2Fbicyclechain/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nugaon%2Fbicyclechain/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nugaon","download_url":"https://codeload.github.com/nugaon/bicyclechain/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":221812743,"owners_count":16884699,"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":["bitcoin","bitcoin-wallet","blockchain","blockchain-api","ethereum","ripple"],"created_at":"2024-10-11T13:16:55.424Z","updated_at":"2024-10-28T09:35:05.640Z","avatar_url":"https://github.com/nugaon.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"```\no--o                        o         o-o  o               \n|   |                       |        /     |               \nO--o   O   o-o  o  o   o-o  |  o-o  O      O--o   oo  O  o-o  \n|   |  |  |     |  |  |     |  |-'   \\     |  |  | |  |  |  |\no--o   o   o-o  o--O   o-o  o  o-o    o-o  o  o  o-o- o  o  o\n                   |                                  \n                o--o                                 \n```\n# Description\nThe goal of the project is to make unified API for more types of cryptocurrencies for financial use.\nCoins and Tokens must be handled in the same way when the client wants to make transaction from one account to another, ask for balance of an account or create one.\nThe common use-case when a coin exchange platform wants to integrate new digital assets for new markets or\na regular user would like to handle his/her distinct cryptocurrencies in a same way on its local nodes.\nThere is also opportunity to make notifications about wallet balance changes at the most coins/tokens.\n\n## Terminology\nBecause the same words and expressions are used differently in the blockchain world, clear definitions are provided to help to understand the application:\n- ** address ** blockchain address which is able to receive cryptocurrency.\n- ** account ** it would be always blockchain address or the account, which equals to its usage and definition on the specified blockchain network.\nIt means if you call Bitcoin endpoint, you can pass account name, which could contain several addresses instead of a single BTC address for the account parameter.\n- ** wallet ** contains accounts that the application can handle directly.\n- ** withdraw ** send cryptocurrency from one address to another on the specified blockchain.\n- ** transaction ** you can retrieve a \"native\" transaction by transactionID and it is an equivalent of the blockhain transaction representation.\nAlso you can list all transactions of a specified address, which may contain the 'from', 'to' directions in the transaction, the confirmations and the type of the transaction (RECEIVE, SEND, OTHER).\n- ** block number ** The sequence number of the block in the blockchain.\n- ** token ** similar to coin, except that it does not have its own transport layer but it depends on an existent and independent blockchain technology.\n- ** confirmation ** difference between the last synced block number of the configured blockchain node server and the block number of the transaction.\n\n## File structure\n```\n│\n├── src/ - Main source code base of the project\n│   ├── application/ - Application codebase\n│   │   ├── cryptoCurrencies/ - source code for the cryptoCurrency EPs and make interfaces for tokens and coins for its implementation\n│   │   ├── generic/ - common used helper functions\n│   │   └── localnodes/ - implementations for different blockchain technologies\n│   │       └── {BlockchainTechnologyName}/ - contains all configuration, interfaces, API calls, functions of the {BlockchainTechnologyName}\n│   │           ├── tokens/ - if the {BlockchainTechnologyName} able to transfer tokens it cointains its implementation. Its controller also implements the ICryptoCurrency interface like the coins.\n│   │           ├── uniqueEndpoints/ - if the {BlockchainTechnologyName} has implementation for specific tasks, it contains its routes and controllers.\n│   │           ├── {BlockchainTechnologyName}Controller.ts - implements ICryptoCurrency interface and only contains the input/output handling.\n│   │           ├── {BlockchainTechnologyName}Service.ts - business logic, the controller directly calls its functions.\n│   │           └── ILocalNodeConfig.ts - configuration interface for its API\n│   ├── engine/ - Framework engine codebase\n│   ├── environments/ - Environment configuration files\n│   └── server/ - Server codebase\n├── logs/ - logs from Winston\n├── dist/ - Distributable bundle (native javascript files)\n└── node_modules/ - Node modules [requires $npm install]\n```\n\n## API documentation\nIf the application runs, you can reach the API documentation at http://127.0.0.1:3000/documentation or you can check the endpoints directly %via src/application/cryptoCurrencies/CryptoCurrencyRoutes.ts\n\n\u003e get /api/v1/cryptocurrency/{cryptocurrency}/account/{account}/balance\n\nQuery balance of the given account. At Bitcoin (and forks) you can pass the account name instead of the address.\n\n\u003e get /api/v1/cryptocurrency/{cryptocurrency}/account/{account}/deposits\n\nGet depsoit transactions of an account\n\n\u003e post /api/v1/cryptocurrency/{cryptocurrency}/account/{account}/deposits\n\nGet all deposits of an account with pagination, by pass in the post payload\n```\n{\n  \"page\": 1,\n  \"offset\": 100\n}\n```\nyou get the first maximum 100 entries.\n\n\u003e get /api/v1/cryptocurrency/{cryptocurrency}/account/{account}/transactions\n\nGet transactions of an account\n\n\u003e post /api/v1/cryptocurrency/{cryptocurrency}/account/{account}/transactions\n\nGet transactions of an account in a limited list\n\n\u003e get /api/v1/cryptocurrency/{cryptocurrency}/account/{account}/transaction\n\nGet transaction of an account, which shows the state of the account, changed by the transaction and if yes, how\n\n\u003e get /api/v1/cryptocurrency/{cryptocurrency}/accounts\n\nGet accounts that the keystore/wallet/application contains\n\n\u003e get /api/v1/cryptocurrency/{cryptocurrency}/address/{address}/check\n\nCheck if the address is valid\n\n\u003e get /api/v1/cryptocurrency/{cryptocurrency}/spendableBalance\n\nGet the spendable amount of coin/token on the main account.\n\n\u003e get /api/v1/cryptocurrency/{cryptocurrency}/transaction/{txid}\n\nGet transaction by ID and set type label (RECEIVE, SENT, OTHER) from viewpoint of your wallet.\nFor example if the transaction's 'to' value equals to one of your accounts', then the label can be \"RECEIVE\" (or \"OTHER\" if it is in the 'from' property as well).\n\n\u003e get /api/v1/cryptocurrency/{cryptocurrency}/nativeTransaction/{txid}\n\nGet native transaction details from the blockchain\n\n\u003e post /api/v1/cryptocurrency/{cryptocurrency}/account\n\nCreate account in the blockchain.\nFor bitcoin and its forks should pass * \"additionalParams\": { \"account\": \"accountName\" } * payload for the account generation.\n\n\u003e post /api/v1/cryptocurrency/{cryptocurrency}/withdraw\n\nMake transaction from the main account or a specified account to the given address. You maybe should pass password or any other options if you specify sendFrom address (for example at Ethereum).\nFor some cryptocurrency it is obligatory to define an additional parameter in the additionalParams object.\nPayload:\n```\n{\n  \"sendTo\": \"string\",\n  \"sendFrom\": \"string\",\n  \"amount\": \"string\",\n  \"additionalParams\": {}\n}\n```\n\n# Usage\nThe application is designed for internal network usage, do not run on public server.\n\n## Wallet Change Callback\nWhen the state of the handled accounts changes, the application makes a GET request to an arbitrary API endpoint with the transaction ID which caused the change itself.\nTo configure this EP you must set the API URI in your environment.ts file at the configuration of the used coin. Design this EP in the way that nothing else can call it except the BicycleChain\nand when it is called do useful things with the transaction id, for example:\n- log your transaction history,\n- call getNativeTransaction to get all information about the transaction,\n- make a request to the BicycleChain getTransaction method to figure out it was a received or a sent transaction, then you can check this account transactions with confirmations with listTransactions.\nFor BTC and its forks have a native client defined flag -walletnotify at the client start where you can set this feature, so the application has no built-in feature for these coins.  \n\n## Environment configuration\nSet your active configuration to *src/environments/environment.ts* . You can start from the example configuration in *src/environments/environment.example.ts*.\nThe environment configuration has to implement the *src/engine/interfaces/AppConfiguration.ts* interface.\n\nYou can define cryptocurrency params at the endpoints in your environment file, for instance if you would like to handle Ethereum set the following:\n```\nlocalnodes: [\n    {\n        route: \"eth\",\n        class: \"Ethereum\"\n    },\n    (...)\n]\n```  \nThe \"route\" will be the {cryptocurrency} param at the API endpoints. The class maps this route to the appropriate controller/service in the source code.\nYou can find this mapping in the *src/engine/configuration/LocalNodeControllerRegistry.ts*. The blockchain nodes configuration place in the localnodeConfigs section.\nEmit those coins that you don't want to use, the application won't load those parts. For tokens you must configure its blockchain node configuration in the similar way (if it has it)\n```\nlocalnodeConfigs: {\n    Ethereum: {\n        (...)\n        withContracts: [\n            {\n                address: \"0x5f3856E40105316EEF244Ea43714A03E04d209CA\",\n                route: \"petty\",\n                type: \"ERC20\"\n            }\n        ]\n    },\n    (...)\n```\nThe blockchain nodes configuration can differ from one another. You can find the exact structure for the correct setup one-by-one in the *src/application/localnodes/{localnode}/ILocalNodeConfig.ts*.\n\n## Run the application\nInstall lib dependencies that the node packages use\n\u003e sudo apt-get install -y python build-essential\n\nInstall Nodejs (version 10 is supported), suggested install with [NVM](https://github.com/nvm-sh/nvm)\n\u003e curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.34.0/install.sh | bash\n\n\u003e source ~/.bashrc\n\n\u003e nvm i 10\n\nRun the application with PM2 (or with any other alternative which can build NodeJS Typescript code).\n\u003e npm i -g pm2\n\nFor PM2 you should install the typescript module with\n\u003e pm2 install typescript ts-node\n\nInstall node packages\n\u003e npm i\n\nSet your own environment configuration file (in src/environments/environment.ts), then you can start the BicycleChain with PM2\n\u003e pm2 start src/init.ts --name BicycleChain\n\n## Unique Routes\nAt some localnode config set, some particular routes can appear (if it has, in the {BlockchainTechnologyName} folder contains uniqueEndpoints folder).\nThese routes offer specific actions on the configured blockhain network.\n\n### Ethereum\n\n\u003e post /api/v1/ethereum/callContractMethod\n\nInvoke a contract's function with the passed parameters.\nPayload:\n\n```json\n{\n    \"methodName\": \"sampleMethodName\", /* the functon name that you want to call */\n    \"methodType\": \"send\", /* at send will change on the contract state and send transaction to the blockchain, call methodtype only runs in EVM, not change the contract state */\n    \"contractAddress\": \"0xe1f45817c10a07fc7bb137a317f65b371d36af42\", /* The contract hash address */\n    \"contractAbi\": [{\"constant\":true,\"inputs\":[],\"name\":\"owner\",\"outputs\":[{\"name\":\"\",\"type\":\"address\"}]}], /* JSON ABI objects in array */\n    \"additionalParams\": { /* optional */\n        \"callFrom\": \"0x0E18C1e20DD1A03a41548dA76C736Fe1C4cD1FE3\", /* default is the main address which set in the configuration */\n        \"callFromPassword\": \"testpassword\", /* password if the callFrom */\n        \"gas\": 50000,\n        \"gasPrice\": \"2000000000\",\n        \"functionParams\": [\"something\", 123] /* parameters in correct order for the function call */\n    }\n}\n```\n\n\u003e post /api/v1/ethereum/deployContract\n\nDeploy contract to the Ethereum Blockchain\nPayload:\n\n```json\n{\n    \"bytecode\": \"60556023600b82828239805160001a607314601657fe5b30600052607381538281f3fe73000000000000000000000000000000000000000030146080604052600080f\", /* bytecode generated by solc */\n    \"abi\": [{\"constant\":true,\"inputs\":[],\"name\":\"owner\",\"outputs\":[{\"name\":\"\",\"type\":\"address\"}]}], /* JSON ABI objects in array */\n    \"additionalParams\": { /* optional */\n        \"callFrom\": \"0x0E18C1e20DD1A03a41548dA76C736Fe1C4cD1FE3\", /* default is the main address which set in the configuration */\n        \"callFromPassword\": \"testpassword\", /* password if the callFrom */\n        \"gas\": 50000,\n        \"gasPrice\": \"2000000000\",\n        \"functionParams\": [\"something\", 123] /* parameters in correct order for the function call */\n    }\n}\n```\n\n### TRON\n\n\u003e post /api/v1/trx/createTRC10Token\n\nCreate TRC10 token on the TRON Network\nPayload:\n\n```json\n{\n    \"name\": \"Petty\", /* Name of the token */\n    \"abbreviation\": \"PEY\", /* The short acronym of the token */\n    \"description\": \"Everyone deserves a Petty.\", /* Description of the asset */\n    \"url\": \"https://pettytoken.network\", /* Official webpage of the asset */\n    \"totalSupply\": 1000000, /* The all available token for the asset (in case of use decimals, it remains the same amount like without that)* /\n    \"trxRatio\": 1, /* How much TRX will tokenRatio cost? */\n    \"tokenRatio\": 1 , /* How many tokens will trxRatio afford? */\n    \"saleStart\": 1580437783000, / * Timestamp. When the token ICO starts. Default is the current time */\n    \"saleEnd\": 1580437783, /* Timestamp. When the token ICO ends. Default is the current time + 60 seconds */\n    \"freeBandwidth\": 10000, /* The creator's donated bandwidth for use by token holders. Default 0 */\n    \"freeBandwidthLimit\":  1000000, /* Out of totalFreeBandwidth; the amount each token holder get. Default 0 */\n    \"frozenAmount\":  100000, /* How many token will locked. Default 1 */\n    \"frozenDuration\": 1, /* Number of days. How much time token will locked. Default 1 */\n    \"precision\": 8, /* Precision of the token values. */\n    \"additionalParams\": { /* optional */\n        \"callFromPrivateKey\": \"e5b30d0ebd5fd3ea24e0a07fc3b697f550c6ed5cf4895034ee9f379711aefb10\" /* The private key that will be used to sign the transaction */\n    }\n}\n```\n\n# Notes for Local Nodes\nTo running this API with full functionalities for some local nodes MongoDB needed to have. You can run a simple MongoDB instance with Docker\n\u003e docker run -d -v bicycle-data:/data/db --name bicyclechain-mongo -p 127.0.0.1:27017:27017 mongo\n\nCall its CLI with\n\u003e docker exec -ti bicyclechain-mongo mongo\n\nListing account transactions in most of the cases only work with * owned accounts * .\n\n## TRON\nFor TRON network suggested to set up an MongoDB database in the interest of account handling (the application save the generated accounts into the database).\nWith MongoDB usage, the application utilize this resource for its own explorer and save transactions at transaction events into the database.\nIt is useful for listing transactions for a given user, also necessary for token usage\n(in the case of the ERC20 tokens transaction value which is received at Transfer events, so it required at getTransaction methods).\n\nAt withdraw you can pass the privateKey of the sender by attend * additionalParams.privateKey * to your payload, if the MongoDB doesn't have the private key of the given address.\n\n## EOSIO\nThe Bicyclechain supports only transactions which contains one action at `getTransaction` and `getAccountTransaction` endpoints. For further information call `nativeTransaction`.\n\nFor account creation the `additionalInfo.account` has to be specified and optional `additionalInfo.pubKey` can be added to the payload.\nIf you omit the latter, the application will use public key of your main account.\n\nThe balance change tracking only watch the main account's balance changes.\n\nThe `listAccountTransactions` and the `listAccountDeposits` only check the \"Transfer\" methods in the token contracts, by the original action ordinal.\n\n# Contribution\nOn a separated branch you can make pull request for your cryptocurrency integration.\nThe condition for a coin pull request is that the Dockerfile of the used blockchain node server has to be on the repository main branch of the [Cointainer](https://github.com/nugaon/cointainer) project.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnugaon%2Fbicyclechain","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnugaon%2Fbicyclechain","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnugaon%2Fbicyclechain/lists"}