{"id":37428173,"url":"https://github.com/dcdpr/libtxref","last_synced_at":"2026-01-16T06:32:37.168Z","repository":{"id":45150961,"uuid":"163809264","full_name":"dcdpr/libtxref","owner":"dcdpr","description":null,"archived":false,"fork":false,"pushed_at":"2022-08-09T18:03:30.000Z","size":2299,"stargazers_count":1,"open_issues_count":0,"forks_count":2,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-04-19T19:04:20.799Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dcdpr.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-01-02T07:35:12.000Z","updated_at":"2022-01-04T23:12:15.000Z","dependencies_parsed_at":"2022-09-10T11:41:14.819Z","dependency_job_id":null,"html_url":"https://github.com/dcdpr/libtxref","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/dcdpr/libtxref","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dcdpr%2Flibtxref","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dcdpr%2Flibtxref/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dcdpr%2Flibtxref/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dcdpr%2Flibtxref/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dcdpr","download_url":"https://codeload.github.com/dcdpr/libtxref/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dcdpr%2Flibtxref/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28477808,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-16T06:30:42.265Z","status":"ssl_error","status_checked_at":"2026-01-16T06:30:16.248Z","response_time":107,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":"2026-01-16T06:32:37.086Z","updated_at":"2026-01-16T06:32:37.155Z","avatar_url":"https://github.com/dcdpr.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# libtxref\n\nThis is a library for converting between bitcoin transaction IDs (TxIDs), bitcoin transaction\ncoordinates (blockHeight, transactionIndex, and txoIndex),\nand \"Bech32 Encoded Tx Position References\" (TxRefs). TxRefs are\ndescribed in [BIP 0136](https://github.com/bitcoin/bips/blob/master/bip-0136.mediawiki).\n\n## Usage Examples\n\n### C++ Encoding Examples\n\nSee [the full code for the following examples](examples/cpp_other_examples.cpp).\n\n#### Create a txref for a mainnet transaction, with only a blockHeight and transactionIndex:\n\n```cpp\n    int blockHeight = 10000;\n    int transactionIndex = 2;\n\n    std::string txref = txref::encode(blockHeight, transactionIndex);\n\n    assert(txref == \"tx1:rq3n-qqzq-qk8k-mzd\");\n```\n\n#### Create a txref for a testnet transaction, with only a blockHeight and transactionIndex:\n\n```cpp\n    int blockHeight = 10000;\n    int transactionIndex = 4;\n\n    std:string txref = txref::encodeTestnet(blockHeight, transactionIndex);\n\n    assert(txref == \"txtest1:xq3n-qqyq-qhrg-gy3\");\n```\n\n#### Create an extended txref for a mainnet transaction, with a blockHeight, transactionIndex, and txoIndex:\n\n```cpp\n    int blockHeight = 10000;\n    int transactionIndex = 2;\n    int txoIndex = 3;\n\n    std::string txref = txref::encode(blockHeight, transactionIndex, txoIndex);\n\n    assert(txref == \"tx1:yq3n-qqzq-qrqq-9z4d-2n\");\n```\n\n#### Create an extended txref for a testnet transaction, with a blockHeight, transactionIndex, and txoIndex\n\n```cpp\n    int blockHeight = 10000;\n    int transactionIndex  = 4;\n    int txoIndex = 6;\n\n    std::string txref = txref::encodeTestnet(blockHeight, transactionIndex, txoIndex);\n\n    assert(txref == \"txtest1:8q3n-qqyq-qxqq-v3x4-ze\");\n```\n\n### C++ Decoding Examples\n\nSee [the full code for the following examples](examples/cpp_other_examples.cpp).\n\n#### Decode a txref\n\n```cpp\n    txref::DecodedResult decodedResult = txref::decode(\"tx1:yq3n-qqzq-qrqq-9z4d-2n\");\n\n    assert(decodedResult.hrp == \"tx\");\n    assert(decodedResult.magicCode == txref::MAGIC_CODE_MAIN_EXTENDED);\n    assert(decodedResult.blockHeight == 10000);\n    assert(decodedResult.transactionIndex == 2);\n    assert(decodedResult.txoIndex == 3);\n    assert(decodedResult.encoding == txref::Encoding::Bech32m);\n```\n\n#### Decode an \"original\" txref\n\nThis txref has been encoded with the original bech32 internal constant. The\ndecoding will still succeed, but the library will also return a commentary\nstring that contains an explanatory message along with the txref that should\nbe used instead.\n\n```cpp\n    txref::DecodedResult decodedResult = txref::decode(\"txtest1:xjk0-uqay-zat0-dz8\");\n\n    assert(decodedResult.hrp == \"txtest\");\n    assert(decodedResult.magicCode == txref::MAGIC_CODE_TEST);\n    assert(decodedResult.blockHeight == 466793);\n    assert(decodedResult.transactionIndex == 2205);\n    assert(decodedResult.txoIndex == 0);\n    assert(decodedResult.encoding == txref::Encoding::Bech32); // note: Bech32 rather than Bech32m\n\n    std::cout \u003c\u003c decodedResult.commentary \u003c\u003c \"\\n\";\n    // prints:\n    // \"The txref txtest1:xjk0-uqay-zat0-dz8 uses an old encoding scheme and should be updated to txtest1:xjk0-uqay-zghl-p89 See https://github.com/dcdpr/libtxref#regarding-bech32-checksums for more information.\"\n```\n\n### C Encoding Example\n\nSee [the full code for the following example](examples/c_usage_encoding_example.c).\n\n#### Create a txref for a mainnet transaction\n\n```C\n    int blockHeight = 10000;\n    int transactionIndex = 2;\n    int txoIndex = 3;\n    char main_hrp[] = \"tx\";\n    \n    txref_tstring * tstring = txref_create_tstring();\n    if(!tstring)\n        return E_TXREF_NO_MEMORY;\n\n    txref_error err = txref_encode(tstring, blockHeight, transactionIndex, txoIndex, false, main_hrp);\n    if(err != E_TXREF_SUCCESS) {\n        txref_free_tstring(tstring);\n        return err;\n    }\n    \n    assert(strcmp(tstring-\u003estring, \"tx1:yq3n-qqzq-qrqq-9z4d-2n\") == 0);\n    \n    txref_free_tstring(tstring);\n```\n\n### C Decoding Example\n\nSee [the full code for the following example](examples/c_usage_decoding_example.c).\n\n#### Decode a txref\n\n```C\n    char txref[] = \"tx1:yq3n-qqzq-qrqq-9z4d-2n\";\n\n    txref_DecodedResult *decodedResult = txref_create_DecodedResult();\n    if(!decodedResult)\n        return E_TXREF_NO_MEMORY;\n    \n    txref_error err = txref_decode(decodedResult, txref);\n    if(err != E_TXREF_SUCCESS) {\n        txref_free_DecodedResult(decodedResult);\n        return err;\n    }\n    \n    assert(decodedResult-\u003eblockHeight == 10000);\n    assert(decodedResult-\u003etransactionIndex == 2);\n    assert(decodedResult-\u003etxoIndex == 3);\n\n    txref_free_DecodedResult(decodedResult);\n```\n\n## Building libtxref\n\nTo build libtxref, you will need:\n\n* cmake\n* g++, clang or Visual Studio (community edition)\n\nlibtxref uses a pretty standard cmake build system:\n\n```\nmkdir build\ncd build\ncmake ..\nmake\n```\n\nYou can also run all the tests:\n\n```\nmake test\n```\n\n### Installing prerequisites\n\nIf the above doesn't work, you probably need to install some\nprerequisites. For example, on a fresh Debian 12 (\"bookworm\") system:\n\n```\nsudo apt-get update\nsudo apt-get install make cmake git g++\n```\n\nNow you can again try to build libtxref.\n\n### libbech32\n\nIf you got this code by cloning the github repo:\n\n```\ngit clone https://github.com/dcdpr/libtxref.git\n```\n\nthen you will need to do a few extra steps to make sure you have everything:\n\n```\ncd libbech32\ngit submodule init\ngit submodule update\n```\n\nThere is another way to do this which is a little simpler, however. If\nyou pass --recurse-submodules to the git clone command, it will\nautomatically initialize and update each submodule in the repository:\n\n```\ngit clone --recurse-submodules https://github.com/dcdpr/libtxref.git\n```\n\n## Regarding bech32 checksums\n\nThe Bech32 data encoding format was first proposed by Pieter Wuille in early 2017 in\n[BIP 0173](https://github.com/bitcoin/bips/blob/master/bip-0173.mediawiki). Later, in November 2019, Pieter published\nsome research that a constant used in the bech32 checksum algorithm (value = 1) may not be\noptimal for the error detecting properties of bech32. In February 2021, Pieter published\n[BIP 0350](https://github.com/bitcoin/bips/blob/master/bip-0350.mediawiki) reporting that \"exhaustive analysis\" showed the best possible constant value is\n0x2bc830a3. This improved variant of Bech32 is called \"Bech32m\".\n\nWhen decoding a txref, libtxref returns an enum value showing whether bech32m or bech32\nwas used to encode. If the original bech32 variant is detected, libtxref also returns a\ncommentary string that can be shown to the user. This commentary will contain a new txref that represents\nthe same transaction data, but using the new bech32m variant. This can be seen in the examples above.\n\nWhen encoding data, libtxref will only use the new constant value of 0x2bc830a3.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdcdpr%2Flibtxref","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdcdpr%2Flibtxref","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdcdpr%2Flibtxref/lists"}