{"id":18557987,"url":"https://github.com/zh/bcp-js","last_synced_at":"2025-04-10T01:32:32.150Z","repository":{"id":52238453,"uuid":"348234729","full_name":"zh/bcp-js","owner":"zh","description":"BlockChain Payloads - OP_RETURN saved pointers to data","archived":false,"fork":false,"pushed_at":"2021-05-04T02:14:28.000Z","size":294,"stargazers_count":4,"open_issues_count":0,"forks_count":5,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-24T14:38:14.608Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","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/zh.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":"2021-03-16T06:13:40.000Z","updated_at":"2024-03-24T08:25:49.000Z","dependencies_parsed_at":"2022-08-30T19:51:27.462Z","dependency_job_id":null,"html_url":"https://github.com/zh/bcp-js","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/zh%2Fbcp-js","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zh%2Fbcp-js/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zh%2Fbcp-js/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zh%2Fbcp-js/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zh","download_url":"https://codeload.github.com/zh/bcp-js/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248124010,"owners_count":21051576,"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":[],"created_at":"2024-11-06T21:38:35.480Z","updated_at":"2025-04-10T01:32:27.136Z","avatar_url":"https://github.com/zh.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# BlockChain Payloads (BCP)\n\nImmutable pointers to digital data, saved on the BCH blockchain\n\n## Objectives\n\nThere are already a lot of projects, working with NFT on BCH blockchain (SLP\ntokens), but they all choose their own way to connect these tokens to the related\ncontent.\n\nit is difficult for the wallets and exchanges developers to support these projects, because it requires individual changes for every additional project.\n\nWith the increased usage of NFT tokens on the BCH blockchain, there is a need to unify the way these tokens connect to the tokenized data - audio, video, images etc.\n\nCurrent repository contains **bcp-js** JavaScript Library for building transactions for the [BlockChain Payloads (BCP) Protocol](docs/bcp-protocol-spec.md).\n\n## BCP Protocol Reference\n\nThis library is a reference code for the [BlockChain Payloads (BCP) Protocol](docs/bcp-protocol-spec.md). The [examples in this repository](examples/) contain the full code necessary for the BCP message types and sources described in the protocol specification. Please reference these examples when building or testing your own applications.\n\n\n## Used libraries and services\n\n* [bignumber.js](https://mikemcl.github.io/bignumber.js/) - A JavaScript library for arbitrary-precision arithmetic\n\n## Installation\n\n* for *node.js*\n\n```sh\nnpm install bcp-js\n```\n\n* for browser\n\n```html\n\u003cscript src=\"https://unpkg.com/bcp-js\"\u003e\u003c/script\u003e\n```\n\nfor a specific version:\n\n```html\n\u003cscript src=\"https://unpkg.com/bcp-js@1.0.1/dist/bcp.min.js\"\u003e\u003c/script\u003e\n```\n\n\n## Development\n\nThe easiest way is to download the library sources from the GitHub repository and rebuild them for your project:\n\n```sh\ngit clone https://github.com/zh/bcp-js.git\ncd bcp-js\nnpm install\nnpm run build\n```\n\n## Testing\n\nThere are some basic tests implemented. More will be added.\n\n```sh\nnpm test\n```\n\n## Usage\n\n### Library instantiation\n\n```js\nconst { BCP } = require('bcp-js')\nconst bcp = new BCP()\n```\n\n### BCP types and sources\n\nThe library provides definitions for all BCP types and sources, mentioned in the [protocol specification](docs/bcp-protocol-spec.md):\n\n* **1.) BCP Types**\n\n * *`BCP_TYPE_GENERIC`* - Generic type. Can be any content\n * *`BCP_TYPE_TEXT`* - Simple string (UTF-8 encoded)\n * *`BCP_TYPE_IMAGE`* - *.png*, *.gif* etc. images\n * *`BCP_TYPE_AUDIO`* - *.mp3*, *.ogg* etc. audio files\n * *`BCP_TYPE_VIDEO`* - *.mpv*, *.mp4* etc. video files\n * *`BCP_TYPE_JSON`* - JSON formated data - *still not implemented*\n\n* **2.) BCP Sources**\n\n * *`BCP_SRC_NONE`* - data is inside the *OP_RETURN* itself\n * *`BCP_SRC_TXID`* - on-chain data, represented by transaction ID\n * *`BCP_SRC_URL`* - URL, off-chain storage - *https://...*, *ipfs://...* etc.\n * *`BCP_SRC_IPFS`* - IPFS, represented by IPFS hash of the data (*depricated, use BCP_SRC_URL instead*)\n * *`BCP_SRC_ADDR`* - BCH (*bitcoincash:*) or SLP (*simpleledger:*) address\n\n To use these definitions you need to import them in your sources:\n\n ```js\n const { BCP, BCP_TYPE_IMAGE, BCP_SRC_IPFS } = require('bcp-js')\n ```\n\n### Methods for BCP creation\n\n* *`create(type, source, data)`* - Need to explicitly specify BCP type and source. All methods below using this method.\n* *`createChainText(data)`* - on-chain string data, inside the *OP_RETURN* itself\n* *`createText(source, data)`* - off-chain UFT-8 encoded string (is this needed?)\n* *`createAudio(source, data)`* - points to audio file (*.mp3*, *.ogg* etc.)\n* *`createImage(source, data)`* - points to an image file (*.png*, *.gif* etc.)\n* *`createState(address, type = BCP_TYPE_GENERIC)`* - points to BCH or SLP address (*bitcoincash:*, *simpleledger:*)\n* *`createFromString(str)`* - automatically detects source from the string - TxID, IPFS etc.\n\n#### Create BCP for a simple blockchain saved text\n\nSimple text message, similar to the `memo.cash` ones (text is in the *OP_RETURN* itself):\n\n```js\nconst opReturn = bcp.createChainText('Hello BCP')\nconsole.log(opReturn.toString('hex')) // 6a0442435000010201010948656c6c6f20424350\n```\n\n#### Create BCP for an audio file on  IPFS\n\nShort *.mp3* file with rain drops, hosted on IPFS - BCP points to the IPFS hash\n\nUse a general method, which allow BCP type argument:\n\n```js\nconst { BCP_TYPE_AUDIO, BCP_SRC_IPFS } = require('bcp-js')\nconst ipfsHash = 'QmZmqLskJmghru919cvU4qSy3L5vc1S2JdzsUXrM17ZqT9'\nconst opReturn = bcp.create(BCP_TYPE_AUDIO, BCP_SRC_IPFS, ipfsHash)\nconsole.log(opReturn.toString('hex'))\n// 6a0442435000010401042e516d5a6d714c736b4a6d6768727539313963765534715379334c3576633153324a647a735558724d31375a715439\n```\n\nor use specific method for the given BCP type\n\n```js\nconst ipfsHash = 'QmZmqLskJmghru919cvU4qSy3L5vc1S2JdzsUXrM17ZqT9'\nconst opReturn = bcp.createAudio(BCP_SRC_IPFS, ipfsHash)\n```\n\n#### Create BCP to SLP address\n\nCreating a pointer to BCH or SLP address allow simulatiion of mutable (changable) objects, for example tracking the state of some game player etc. The BCP itself is immutable, saved on the blockchaain, but changes in the object can be tracked by sending transaction to the address, encoded in the BCP. Like items a game player owns, payments for given contract etc.\n\n```js\nconst { BCP_SRC_ADDR } = require('bcp-js')\nconst slpAddress = 'simpleledger:qq2fg599ysqvfefr2ur0z34n2dk6f0aszg5pskpe06'\nconst opReturn = bcp.createState(slpAddress)\nconsole.log(opReturn.toString('hex'))\n// 6a0442435000010101053773696d706c656c65646765723a71713266673539397973717666656672327572307a33346e32646b36663061737a673570736b70653036\n```\n\nIf you know the type of transactions, that will be send to the address above, you can also add it to the parameters. For example changable image gallery on IPFS: on adding/changing images, just **send a transaction to the provided address** with the new image IPFS hash (*Qm...*)\n\n```js\nconst opReturn = bcp.createState(slpAddress, BCP_TYPE_IMAGE)\n```\n\n### Methods for parsing BCP\n\n* *`parse(payload)`* - parse *OP_RETURN* with BCP and return JS object\n\n#### Parse IPFS save audio file\n\nUsing the audio-file on IPFS *OP_RETURN* from the creation example above.\n\n```js\nconst op = '6a0442435000010401042e516d5a6d714c736b4a6d6768727539313963765534715379334c3576633153324a647a735558724d31375a715439'\nparsed = bcp.parse(op)\nconsole.log(JSON.stringify(parsed, null,2))\n```\n```js\n{\n  \"type\": 4,   // BCP_TYPE_AUDIO\n  \"source\": 4, // BCP_SOURCE_IPFS\n  \"data\": {\n    \"hash\": {  // QmZmqLskJmghru919cvU4qSy3L5vc1S2JdzsUXrM17ZqT9\n      \"type\": \"Buffer\",\n      \"data\": [\n      ...\n\n```\n\nYou can see more usage examples in the [examples directory](examples/).\n\n## Future plans\n\nSLP on BCH blockchain providing pretty mature infrastrucure for working with NFT tokens - grouping (parent+children), indexing etc. There is no need to invite the same for the BCPs. Just **create NFT with documentUri pointing to BCP** and all these services can be used for working with the data, pointed by BCP. This will also provide ownership prove of the digital content.\n\nThere is already a [proposal for adding several OP_RETURN data to one transaction](https://bitcoincashresearch.org/t/multiple-op-returns-this-time-for-real/315). This will make connecting NFT to the BCP pointed data even easier - one *OP_RETURN* for the SLP and one for the BCP!\n\nSome real code for create/view NFTs with BCP pointed data will be added.\n\nHope more wallets and exchanges developers agree on the current proposal, so more implementations will be done - other languages etc.\n\n## Donations\n\nEvery amount of BCH will help the future development\n\n* BCH: `bitcoincash:qq3t709lskk7tpg5nl8xdfvu8rx4v66ys5cwlxw3ac`\n\n![BCH address](https://gateway.pinata.cloud/ipfs/QmPz1Knaxj5UhJ4jrQjpr6LK9uA5em26NVmC2eX7W4D29D)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzh%2Fbcp-js","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzh%2Fbcp-js","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzh%2Fbcp-js/lists"}