{"id":27429494,"url":"https://github.com/byteball/aa-channels-lib","last_synced_at":"2026-02-07T17:04:58.145Z","repository":{"id":72989771,"uuid":"195729391","full_name":"byteball/aa-channels-lib","owner":"byteball","description":"General purpose library for payment channels","archived":false,"fork":false,"pushed_at":"2020-08-29T13:06:20.000Z","size":563,"stargazers_count":2,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-14T14:18:03.302Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","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/byteball.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2019-07-08T03:21:39.000Z","updated_at":"2023-03-04T16:40:08.000Z","dependencies_parsed_at":null,"dependency_job_id":"a6934d41-11ce-4d9c-a924-bc1e646b3e22","html_url":"https://github.com/byteball/aa-channels-lib","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/byteball/aa-channels-lib","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/byteball%2Faa-channels-lib","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/byteball%2Faa-channels-lib/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/byteball%2Faa-channels-lib/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/byteball%2Faa-channels-lib/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/byteball","download_url":"https://codeload.github.com/byteball/aa-channels-lib/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/byteball%2Faa-channels-lib/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265003609,"owners_count":23696244,"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":"2025-04-14T14:17:57.935Z","updated_at":"2026-02-07T17:04:58.068Z","avatar_url":"https://github.com/byteball.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# aa-channels-lib\n\nThis library handles a bidirectionnal payment channel based on [Autonomous Agents](https://medium.com/obyte/introducing-autonomous-agents-6fe12fb12aa3)\nIt allows free, instant and confirmation-free offchain transactions between two parties.\nExample of use cases: pay-per-call API, pay-per-time streaming...\n\n## How does it work?\n\nThe library can either be included in a Node.js project or as a stand-alone Node.js program controlled with Remote-Procedure-Call (RPC).\nBoth parties willing to transact have to use the library.\nThe library runs an [headless-wallet](https://github.com/byteball/headless-obyte) that has to be funded prior to operation.\n\nThe communication between peers can be handled by the library, in this case two choices are available:\n- Encrypted chat: virtually no setup but has some latency, is not adapted for consequent volume of data and is hub-dependent.\n- HTTPS: a party that wants to receive payment has to setup an Nginx proxy but the communication is direct, very fast and the application can be infinitely scalable (see High Availability node)\n\nThe communication can be external, all you need is a mean to transfer a payment package in JSON. The payment package is obtained with `createPaymentPackage` function and can be verified by receveir with `verifyPaymentPackage`.\n\n## Basic example\nOne peer initiates the creation with:\n```javascript\nchannels.createNewChannel(peer, initial_amount, options, function(error, aa_address, unit){\n\n});\n```\n**peer** is an url or a pairing address, **aa_address** is returned by the function and is to be saved as it will used to identify channel for further operation.\nTransactions can begin immediately if peer accepts unconfirmed payments or after confirmation by the network\n\nOne peer wanting to send an offchain payment uses this function:\n\n```javascript\nchannels.sendMessageAndPay(aa_address, message_to_peer, amount, function(error, response){\n\tif (error)\n\t\treturn console.log(error);\n\telse\n\t\treturn console.log(response);\n});\n```\n**aa_address** is the address of the channel provided during its creation, **message_to_peer** is anything that can be parsed in JSON (string, number or object) and that you want to transmit to your peer, **amount** is the amount of your payment and **function** is a callback that will be returned with **error** or **response** from your peer.\n\nYou can set a function to be executed when you receive an offchain payment:\n```javascript\nchannels.setCallBackForPaymentReceived(function(amount, asset, message, peer_address, handle){\n\tif (message == \"thanks me\")\n\t\treturn handle(null, \"Thank you \" + peer_address + \" I received you payment of \" + amount + \" \" + asset);\n\telse if (message == \"send me an error\")\n\t\treturn handle(\"this is an error\");\n});\n\n```\nThe response can be a number, a string or an object, and will be forwarded to the payer.\n\n\nThe channel can be closed an anytime by one of the party with:\n```javascript\nchannels.close(aa_address, function(error){\n\tif (error)\n\t\tconsole.error(error);\n});\n```\nAfter confirmation by peer or a timeout, you headless wallet will receive a payment calculated as follow:\n**amount received** = **total amount deposited by you to the channel** - **total amount paid to your peer** + **total payment received from your peer**\n\nAll functions and events available are documented there: https://github.com/Papabyte/aa-channels-lib/blob/master/doc/reference.md\n\n## Configuration\nDepending on your needs, different configurations are possible.\n\n#### Vendor configuration\n ![Vendor configuration decision tree](source-doc/vendor-tree.png?raw=true \"Vendor configuration\")\n\n#### Client configuration\n ![Client configuration decision tree](source-doc/client-tree.png?raw=true \"Client configuration\")\n\n\u003cdetails\u003e\u003csummary\u003eInclude module in your node.js project\u003c/summary\u003e\n\n* Add the package to your project:\n`npm install --save https://github.com/Papabyte/aa-channels-lib.git`\n\n* Require the module at the beginning of your code.\n`const channels = require('aa-channels-lib')`\n\nFor events you need also\n`const eventBus = require('ocore/event_bus.js')`\n\nAll library [functions](doc/reference.md#Functions) are available as property, example:\n```javascript\nchannels.setAutoRefill(\"7FLNK5AIWSYU2TVEKRW4CHCQUAKOYGWG\",122000, 300000, function(error){\n\tif (error)\n\t\tconsole.log(error);\n});\n```\n\nAll [events](doc/reference.md#Events) can be subscribed with `eventBus.on(event,function(){})`, example: \n\n```javascript\neventBus.on(\"channel_created_by_peer\", function(peer_address, aa_address){ \n\tconsole.log(\"a peer created a channel, aa address: \" + aa_address + \", peer address: \" + peer_address)\n});\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\u003csummary\u003eRun as RPC server\u003c/summary\u003e\n\n* Install Node.js \u003e version 6\n* clone the library \n`git clone https://github.com/Papabyte/aa-channels-lib.git `\n* Run Rpcify\n`cd aa-channels-lib`\n`node rpcify.js`\n\nBy default port 6333 is accessible through HTTP or websocket, websocket is mandatory if you want to receive events.\nCommands be send in JSON by POST method in http or websocket message, example: \n`curl --data '{\"jsonrpc\":\"2.0\", \"id\":1, \"method\":\"setAutoRefill\", \"params\":[\"7FLNK5AIWSYU2TVEKRW4CHCQUAKOYGWG\",122000, 300000]}'`\n\n`method` is the name of the function you want to use, `params` is an array containing parameters you want to pass.\n\nAll functions and events are available (except `setCallBackForPaymentReceived` function).\n\nLearn more on: https://github.com/byteball/rpcify\n\u003c/details\u003e\n\n\u003cdetails\u003e\u003csummary\u003eIntegrated communication\u003c/summary\u003e\n\n* Set in `enabledReceivers` array as below in your conf.js file as below:\n```javascript\nexports.enabledReceivers = ['http','obyte-messenger'];\n```\n* For HTTP, configure port:\n```javascript\nexports.httpDefaultPort = 6800;\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\u003csummary\u003eExternal communication\u003c/summary\u003e\n\n* Leave `enabledReceivers` array empty in your conf.js file as below:\n```javascript\nexports.enabledReceivers = [];\n```\nCreate channel with `createNewChannel` using peer's payment address as first parameter, obtain payment packages with `createPaymentPackage` and verify them with `verifyPaymentPackage`.\n\u003c/details\u003e\n\n\u003cdetails\u003e\u003csummary\u003eHigh Avaibility mode\u003c/summary\u003e\n\nA node only destinated to receive payment can run in high-availability mode. In this case, the front service that handles the requests from clients is separated from a background service that runs the headless wallet. Several front services can run in parallel to serve clients even when the background goes down for some time (like for being updated). That greatly helps the scalability of your business.\n\nThe exact setup depends of you need but you will likely use:\n* a load balancer that will redirect https requests to different front service instances.\n* an external MySQL database to which front app and background app can connect to.\n\nCheck specific documentation there: https://github.com/Papabyte/aa-channels-lib/blob/master/doc/ha_mode.md\n\u003c/details\u003e\n\n\u003cdetails\u003e\u003csummary\u003eWeb dashboard\u003c/summary\u003e\nA local web dashboard can be enabled to check the states of all channels \n\n* Port configuration:\n```javascript\nexports.webServerPort = 8080;\n```\n\n![web dashboard](source-doc/dashboard.png?raw=true \"Client configuration\")\n\n\u003c/details\u003e","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbyteball%2Faa-channels-lib","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbyteball%2Faa-channels-lib","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbyteball%2Faa-channels-lib/lists"}