{"id":15287632,"url":"https://github.com/elkrem/koyn","last_synced_at":"2025-05-06T21:08:20.468Z","repository":{"id":134248511,"uuid":"131600765","full_name":"elkrem/koyn","owner":"elkrem","description":"A trustless and decentralized Bitcoin library for Arduino compatible boards","archived":false,"fork":false,"pushed_at":"2019-05-31T21:38:56.000Z","size":385,"stargazers_count":66,"open_issues_count":1,"forks_count":19,"subscribers_count":13,"default_branch":"master","last_synced_at":"2025-05-06T21:08:13.378Z","etag":null,"topics":["arduino","bitcoin","electrum","esp32","esp8266","library","spv"],"latest_commit_sha":null,"homepage":null,"language":"C++","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/elkrem.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2018-04-30T13:42:40.000Z","updated_at":"2025-02-09T05:10:36.000Z","dependencies_parsed_at":"2023-05-24T10:00:32.070Z","dependency_job_id":null,"html_url":"https://github.com/elkrem/koyn","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elkrem%2Fkoyn","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elkrem%2Fkoyn/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elkrem%2Fkoyn/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elkrem%2Fkoyn/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/elkrem","download_url":"https://codeload.github.com/elkrem/koyn/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252769423,"owners_count":21801378,"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":["arduino","bitcoin","electrum","esp32","esp8266","library","spv"],"created_at":"2024-09-30T15:33:43.202Z","updated_at":"2025-05-06T21:08:20.435Z","avatar_url":"https://github.com/elkrem.png","language":"C++","funding_links":[],"categories":["Libraries"],"sub_categories":["Others"],"readme":"# Koyn: Bitcoin Library For Arduino [![Build Status](https://travis-ci.org/elkrem/koyn.svg?branch=master)](https://travis-ci.org/elkrem/koyn)\n\n## Overview\n\nA fully decentralized and trustless Bitcoin light (aka SPV) client implementation for the Arduino platform based on Electrum protocol.\n\nWith its simple and easy-to-use API, it allows you to interface Arduino boards to the Bitcoin network. The sky is the limit, you can either do a physical action when a transaction is made or send transactions based on hardware events.\n\n## Readiness\n\nThe library should be working but it is still rough around the edges. It is considered to be a **work-in-progress**. It is by all means far from being production ready. It hasn't been thoroughly tested or gone through security reviews.\n\nCurrently, it can only works with Bitcoin testnet **(no mainnet support yet)**. Be advised not to use real Bitcoins. We are not responsible for any loss of funds so use it at your own risk.\n\nArduino boards support is initially limited as well, please check below for more info.\n\nAlso, the public interface hasn't been finalized yet, it can be changed a bit during the initial releases.\n\n## Light Clients\n\nLight Bitcoin clients (nodes) doesn't store the full transaction history (blockchain) of the network (unlike full clients). They only download the headers (80 bytes every ~10 minutes) of the created blocks to be able to verify that a particular transaction was indeed included and accepted by the network. The concept is often referred to by the term *SPV* (Simplified Payment Verification).\n\nThere are two popular protocols for SPV clients. Bitcoin Core and Electrum, they pretty much have the same concept. The core protocol works with raw bytes and Electrum is JSON based. This library supports only Electrum protocol for now, thus it only works with Electrum servers.\n\n## Hardware Requirements\n\nThe library requires an ESP8266 or ESP32 based board connected with an SPI microSD card module to work.\n\nThe microSD card needs to be a single partition, FAT formatted, fast (class 10) and has at least 1GB of space. It doesn't need to be empty as we create a new directory on its root named `koyn`.\n\n## Boards Support\n\nThese boards have been tested and are known to work:\n\n**ESP8266**\n- Adafruit Huzzah ESP8266\n- Wemos D1\n- SparkFun ESP8266 Thing\n- NodeMCU\n\n**ESP32**\n- DOIT ESP32 DEVKIT V1\n- ESPDUINO-32\n- SparkFun ESP32 Thing\n\nThese microSD card boards has been tested and known to work:\n\n- Wemos Micro SD Card Shield\n- SparkFun microSD Shield\n\n## Installation\n\nMake sure you have the latest version of [Arduino IDE](https://www.arduino.cc/en/Main/Software) with either [ESP8266](https://github.com/esp8266/Arduino#installing-with-boards-manager) or [ESP32](https://github.com/espressif/arduino-esp32#installation-instructions) cores installed.\n\n\n**Using Library Manager (Recommended)**\n\nOpen the Arduino IDE, go to Sketch \u003e Include Library \u003e Manage Libraries.\n\nAnd then, search for our library in the list, pick the latest version and click install.\n\n**Manual Method**\n\nDownload the latest version of the library from the [releases page](https://github.com/Elkrem/Koyn/releases). Unzip it in a new directory named *Koyn* inside your Arduino's libraries directory.\n\n**PlatformIO**\n\nIf you are using PlatformIO, the library can be installed from their library manager as well, just search for `Koyn`.\n\n## Blockchain Headers Syncing\n\nYou can choose to sync and validate the headers on the board directly starting from the genesis block, but it can take from tens of minutes to hours depending on your sketch and network conditions.\n\nSo it is advised to preload the microSD card with the latest headers on a host machine before hand using one of the methods below, then rename it to `blkhdrs` and place it in `/koyn` directory on the microSD.\n\n**Using Our Tool (Recommended)**\n\nWe developed a command line tool based on [BitcoinJ](https://github.com/bitcoinj/bitcoinj) library that validates and downloads the Bitcoin blockchain headers to a file on your local machine.\n\nFirst make sure you have a [Java Runtime Environment](https://java.com/en/download/) installed on your host machine and accessible from your `PATH`. Then download the latest [release](https://github.com/elkrem/koyn-sync/releases) of our tool. Then run the executable or call `java -jar koyn-sync-VERSION.jar` from a command line terminal. (Make sure you are connected to the Internet, and the working directory is writable)\n\nThe tool will download the headers to your working directory and create either `./koyn/mainnet/blkhdrs` or `./koyn/testnet/blkhdrs` depending on the supplied [flags](https://github.com/elkrem/koyn-sync#optional-flags). (Logging messages will show its progress)\n\n**From Electrum Website**\n\nIf you trust Electrum.org, you can download the headers directly from their website and the library will sync the rest of the headers when started.\n\n- Bitcoin [Testnet Headers](https://download.electrum.org/testnet_headers) (till August, 2017)\n- Bitcoin [Mainnet Headers](https://download.electrum.org/blockchain_headers) (till August, 2017)\n\n**From Electrum App**\n\nInstall Electrum client on your machine if you don't have it, run it, let it sync.\n\nYou may need to supply `--testnet` parameter before running the Electrum executable if you need to sync the **testnet** headers.\n\nOn Windows, the headers file is located in `%APPDATA%\\Electrum\\blockchain_headers` or `%APPDATA%\\Electrum\\testnet\\blockchain_headers` if you are using the testnet. On Mac and Linux, the headers file is located in `~/.electrum/blockchain_headers` or `~/.electrum/testnet/blockchain_headers` if you are using the testnet.\n\nNote: Electrum versions \u003e=3.1.0 **does not** sync the headers from the genesis block and rely on the concept of checkpoints. So to sync using Electrum please use version below 3.1.0.\n\n## Usage\n\nWe tried to make our API as simple as possible, here are some samples.\n\n**Bare Minimum**\n\n```\n#include \"Koyn.h\"\n\nvoid setup() {\n  Koyn.begin();\n}\n\nvoid loop() {\n  Koyn.run();\n}\n```\n\n**Transaction Signing and Broadcasting**\n\n```\nBitcoinAddress myAddress(\"PRIVATE_KEY\", KEY_PRIVATE);\nKoyn.trackAddress(\u0026myAddress);\nBitcoinAddress myFriendAddress(\"BITCOIN_ADDRESS\", ADDRESS_ENCODED);\nKoyn.spend(\u0026myAddress, \u0026myFriendAddress, 100000000, 100000);\n```\n\n**Transactions Tracking**\n\n```\nvoid paymentCallback(BitcoinTransaction tx){\n\n}\n```\n\n```\nKoyn.onNewTransaction(\u0026paymentCallback);\nif(Koyn.isSynced()){\n    Koyn.trackAddress(\u0026myAddress);\n}\n```\n\n**Complete Example: Flash a light bulb with Bitcoin**\n\n```\n#include \u003cKoyn.h\u003e\n\n#define LIGHT_BULB 13\n#define PAYMENT_VALUE 1000000\n\nBitcoinAddress myAddress(\"PRIVATE_KEY\", KEY_PRIVATE);\nBitcoinAddress myFriendAddress(\"BITCOIN_ADDRESS\", ADDRESS_ENCODED);\n\nvoid setup() {\n  pinMode(LIGHT_BULB, OUTPUT);\n  ..\n  .. Connect to WiFi\n  ..\n  Koyn.begin(false);\n  Koyn.onNewTransaction(\u0026paymentCallback);\n}\n\nvoid loop() {\n  if(Koyn.isSynced()){\n    Koyn.trackAddress(\u0026myAddress);\n  }\n  Koyn.run();\n}\n\nvoid paymentCallback(BitcoinTransaction tx){\n  for(int i=0;i\u003ctx.getInputsCount();i++)\n  {\n    BitcoinAddress from;\n    tx.getInput(i, \u0026from);\n    if(from == myFriendAddress){\n      for(int j=0;j\u003ctx.getOutputsCount();j++)\n      {\n        BitcoinAddress to;\n        tx.getOutput(j, \u0026to);\n        if(to == myAddress){\n          if(tx.getOutputAmount(j) == PAYMENT_VALUE){\n              digitalWrite(LIGHT_BULB, HIGH);\n              Koyn.delay(1000);\n              digitalWrite(LIGHT_BULB, LOW);\n          }\n          else{\n              Koyn.spend(\u0026myAddress, \u0026myFriendAddress, tx.getOutputAmount(j), 100000);\n          }\n        break;          \n        }\n      }\n      break;\n    }\n  }\n}\n```\n\n## Supported Networks\n\n- [x] Bitcoin Testnet\n- [ ] Bitcoin Mainnet\n- [ ] Bitcoin Cash\n\n## Examples\n\nExamples that cover most of our APIs can be found [here](examples).\n\n\u003c!--## microSD Card Structure--\u003e\n\n## Documentation\n\nDocumentation for all of the usable public methods, classes and configuration can be found in our [Wiki](https://github.com/elkrem/koyn/wiki/Docs).\n\n## Configuration And Defaults\n\nMost of the hardcoded library defaults and configuration parameters can be edited [here](src/Config.h).\n\nDebug messages can be enabled on the default Serial interface through the same file as well by uncommenting `#define ENABLE_DEBUG_MESSAGES` line.\n\n## Status and Roadmap\n\n- [x] Connects to multiple Electrum servers.\n- [x] Validates the headers one by one starting from the genesis block.\n- [x] Downloads (syncs) the latest blockchain headers and validates them.\n- [x] Track transactions to user's addresses.\n- [x] Validates incoming transactions and making sure they were accepted by the network.\n- [x] Sign and send transactions (from user's addresses) to the network.\n- [ ] Support headers checkpoints.\n- [ ] Support Bitcoin mainnet.\n- [ ] Support additional WiFi connected Arduino boards.\n- [ ] Support custom transactions.\n- [ ] Support P2SH transactions.\n- [ ] Support SegWit transactions and addresses.\n- [ ] Support hierarchical deterministic wallets (BIP32).\n- [ ] Support mnemonic seed wallets (BIP39).\n- [ ] Support logical hierarchy for deterministic wallets (BIP44).\n- [ ] Add APIs to ease the workflow of payment channels.\n- [ ] Add APIs to ease the prototyping of hardware wallets.\n\n## Notes and Caveats\n\n- Only P2PKH transactions and addresses are supported.\n- Only non-SegWit transactions and addresses are supported.\n- Only addresses generated from compressed public keys are supported.\n- The library connects to non-TLS Electrum servers only.\n- The library connects to a hardcoded list of bootnodes only for now, the `server.peers.subscribe` call hasn't been implemented yet.\n- The library works with Bitcoin testnet only for now.\n- The library does cache private keys in memory.\n- The library doesn't support true random generators yet (generated private keys and addresses rely on analog pin #0 noise).\n- Due to the limitation of hardware, there are some constraints on transaction sizes, tracked addresses number, transactions number kept in memory and others (Their defaults can be overwritten in `Config.h` file)\n\n## Acquiring Testnet Bitcoins\n\nTestnet bitcoins can be easily acquired using online faucets like [this](https://testnet.manu.backend.hamburg/faucet) and [this](https://testnet.coinfaucet.eu/en/).\n\n## Changelog\n\nTo see what has changed in recent versions of Koyn library, see the [change log](CHANGELOG.md).\n\n## Contributing\n\nWe welcome all contributions from our community. If you've find a bug or can improve the code or want to add a new feature, please follow our [contributions guidelines](CONTRIBUTING.md).\n\n## Learn More\n\nBe the first to know about our future blockchain connected hardware products by subscribing to our mailing list at [Elkrem.io](https://elkrem.io).\n\n## Attributions and Credits\n\n- [aJson](https://github.com/interactive-matter/aJson)\n- [Base58](https://github.com/HsuBokai/base58)\n- [Json Streaming Parser](https://github.com/squix78/json-streaming-parser)\n- [Ripemd160](https://github.com/ARMmbed/mbedtls)\n- [SdFat](https://github.com/greiman/SdFat)\n- [Sha256](https://github.com/Cathedrow/Cryptosuite)\n- [uECC](https://github.com/kmackay/micro-ecc)\n- [ElectrumX](https://github.com/kyuupichan/electrumx)\n- [Electrum Client](https://github.com/spesmilo/electrum)\n\n## License and Copyright\n\n```\nThis code is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General\nPublic License version 3 only, as published by the Free Software Foundation.\n\nThis code is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied\nwarranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public License\nversion 3 for more details (a copy is included in the LICENSE.md file that accompanied this code).\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Felkrem%2Fkoyn","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Felkrem%2Fkoyn","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Felkrem%2Fkoyn/lists"}