{"id":26451174,"url":"https://github.com/jtesta/bitclamp","last_synced_at":"2025-07-07T08:40:15.883Z","repository":{"id":150552484,"uuid":"56806784","full_name":"jtesta/bitclamp","owner":"jtesta","description":"Bitclamp allows arbitrary files to be permanently and anonymously published into the Bitcoin and Dogecoin blockchains.","archived":false,"fork":false,"pushed_at":"2017-01-12T01:59:25.000Z","size":185,"stargazers_count":13,"open_issues_count":0,"forks_count":1,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-04-04T11:37:20.943Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jtesta.png","metadata":{"files":{"readme":"README.txt","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","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}},"created_at":"2016-04-21T21:30:07.000Z","updated_at":"2024-04-01T17:12:49.000Z","dependencies_parsed_at":null,"dependency_job_id":"9615d22a-6144-425e-a2b9-c109d5b69f4a","html_url":"https://github.com/jtesta/bitclamp","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/jtesta/bitclamp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jtesta%2Fbitclamp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jtesta%2Fbitclamp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jtesta%2Fbitclamp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jtesta%2Fbitclamp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jtesta","download_url":"https://codeload.github.com/jtesta/bitclamp/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jtesta%2Fbitclamp/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":264044867,"owners_count":23548829,"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-03-18T16:32:22.933Z","updated_at":"2025-07-07T08:40:15.846Z","avatar_url":"https://github.com/jtesta.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"Bitclamp v0.9\nJoe Testa \u003cjtesta [shift-two] positronsecurity [daht] com\u003e\nPositron Security\nhttp://www.positronsecurity.com/\n\n\nThis tool publishes files into the blockchains of Bitcoin and Dogecoin.  While\nother methods to push data into the blockchain exist, this project is special\nbecause it is much more reasonable in terms of cost (transaction fees), allows\nfor data to be searched, and has no size limits.\n\nIMPORTANT NOTE:  Bitclamp is currently in beta.  DO NOT publish anything of\nvalue until it reaches a stable release (approximately January 2017).  There is\na 100% chance that content published before then will not be easily viewable or\nsearchable due to upcoming changes to the data structures.\n\nRefer to the SETUP.txt file for instructions on how to initialize the bitcoind/\ndogecoind servers.\n\n\n1. Publication of Content\n\n1.1. Quick Example\n\nAssuming bitcoind/dogecoind is not currently running, a quick example is:\n\n    $ python3 bitclamp.py --daemon=spawn --chain=btc --file=SEKRUT_DOC.pdf --txfee=0.0003 --change=mwbsGwGwSmaw6xZPT2G2rxxR63ErR6tjdx\n\nIn the above example, --chain specifies what blockchain to use (\"btc\" or\n\"doge\"), --file is the file to publish, --txfee is the transaction fee rate per\nKB (see section 1.2), and --change specifies where any leftover coins are to be\nsent after publication is complete.\n\n   The program responds with:\n\nAutomatic detection of content type is: document\nAutomatically adding file extension '.lzma' to file name to reflect usage of lzma compression: SEKRUT_DOC.pdf.lzma\nTo begin publication, send 0.06506440 BTC to 2MzquEsJsunGKw5ffrYsMr1jmbAu9WyKGn2\n\n   Just like it says, you must send the specified amount to the listed address\nin order to begin publication.  Once it is received, the program will say:\n\nReceived funds.  Beginning publication...\n\n   Now its just a waiting game.  Depending on how large SEKRUT_DOC.pdf is,\npublication can take anywhere from minutes to years (yes, literally years...).\nSee section 1.4 on how to get an estimate on publication times.\n\n   Eventually, publication will complete, and the program will say:\n\nPublication complete!  Waiting for the transactions to surpass the confirmation threshold.  This phase is optional.\n4 transactions awaiting full confirmation...\n0 transactions awaiting full confirmation...\nAll transactions fully confirmed.\n\n\n1.2. Transaction Fees\n\nTransactions fees are necessary for transactions to be processed.\nInterestingly, fees are calculated with respect to the number of kilobytes a\ntransaction takes, and not based on the amount of coins being sent.  Senders\nof funds choose the rate they wish to use.  A high rate will result in quick\nconfirmation, and a below-average rate causes transactions to be ignored for\na while.\n\nThe fee rate is determined by the open market at any given time.  As such, it\nfluctuates based on current activity.  At the time of this writing, the\nDogecoin network does not experience high volume of transactions; its fee rate\nappears to be very stable at 1 DOGE per KB (this is extremely cheap!).  The\nBitcoin network, however, has a very high volume, yielding high transaction\nfees.\n\nYou can estimate the fee rate you should use in two ways:\n\n   * By asking your local bitcoind node with \"bitcoin-cli estimatefee N\", where\n        N is a number from 1 to 20 (omit this number to see the documentation\n        on the estimatefee function).\n\n   * By examining the current average fee rate.  The following websites can\n     tell you this:\n        - https://www.blocktrail.com/BTC\n        - https://live.blockcypher.com/btc/\n        - https://chain.so/\n\nThe higher the rate you use, the quicker your publication will complete.\nHowever, it will obviously cost more (possibly a LOT more).  Choosing a lower\nrate will save money, but will increase the amount of time required to finish.\nThis is a tradeoff decision you need to make on your own.\n\nBe aware that the fee rate is somewhat cyclical.  There are peak times of\ntransaction volume, and times of low volume.  If the rate during peak times is,\nsay, 0.0003, and the rate during low volume is 0.0002, then using a rate in\nbetween (0.00025) will strike a balance between publication time and cost.\nYour transactions will be ignored when the market demands a higher rate, but\nwill be processed easily during low-volume times.\n\n\n1.3. Daemon Existing Mode\n\nThe quick example in section 1.1 used \"--daemon=spawn\", which tells Bitclamp\nthat bitcoind/dogecoind should be spawned for publication, then shut down\nwhen complete.  If you'd like for bitcoind/dogecoind to remain available\nindependently of the publication, you can run the daemon in \"existing\" mode\n(this is also useful if you'd like to publish multiple files simultaneously):\n\n    $ bitcoind -daemon -txindex -blocknotify=\"python3 /path/to/BlockClient.py /path/to/block_listeners.txt\"\n\n/path/to/BlockClient.py is (obviously) the path to where BlockClient.py exists.\n/path/to/block_listeners.txt is a path to an (initially) empty file.  Later,\nyou will fill this in with information once publication is begun.\n\nOnce the daemon is started, you can start the publication with:\n\n---\n\n    $ python3 bitclamp.py --daemon=existing --chain=btc --file=SEKRUT_DOC.pdf --txfee=0.0003 --change=mwbsGwGwSmaw6xZPT2G2rxxR63ErR6tjdx --regtest\n\n--\u003e BlockListener is now listening on port 4761.  Configure bitcoind to connect back to this port, and publication can begin.  In the file that its BlockClient parses, add the following on a line by itself:\n\n\tlocalhost 4761\n\nDo this BEFORE you send the funds to the publication address!\n\nAutomatic detection of content type is: document\nAutomatically adding file extension '.lzma' to file name to reflect usage of lzma compression: SEKRUT_DOC.pdf.lzma\nTo begin publication, send 0.06506440 BTC to 2N2aNnkW1fZ8qDgfFta8cdU3mTegWiZf5du\nReceived funds.  Beginning publication...\nSending about 0.04330063 in change to mwbsGwGwSmaw6xZPT2G2rxxR63ErR6tjdx...\n\n---\n\nNow place \"localhost 4761\" in /path/to/block_listeners.txt (as set in the\nbitcoind/dogecoind argument, above).  Then send coins to the specified address\nto begin publication.\n\n   Note that multiple publications can be run using the same bitcoind/dogecoind\ninstance with this method by putting multiple lines in block_listeners.txt.\n\n\n1.4. Estimation of Publication Cost \u0026 Time\n\nBecause publication cost and time can vary wildly based on file size and\nspecific blockchain used, the \"--estimate\" option allows the user to get an\nestimate:\n\n---\n\n    $ python3 bitclamp.py --chain=btc --file=SEKRUT_DOC.pdf --estimate\nGetting fee estimate from network...\nFound fee estimate: 0.00022111\nTo publish SEKRUT_DOC.pdf (123.6 KB) on the BTC network with a transaction fee rate of 0.00022111, the amount needed to begin publishing is 0.04810583 BTC.  Of this figure, 0.04133116 will be lost to transaction fees, and 0.00050000 will be sent between transactions.  Based on the size of the file, an extra 15% is added to account for variability in the transaction sizes (larger files will have less added than smaller ones).  Because any and all unused funds are refunded upon completion, the true publication cost should be closer to the transaction fee cost (0.04133116).  With 1 concurrent transactions, and 5 outputs per transaction, publication will require at least 60 blocks, or at least 10 hours, 0 minutes.\n\nNote that this is accurate under optimal network conditions.  Real-world conditions may vary greatly.\n\n---\n\nNote that, as of the time of this writing, the Bitcoin network is known to be\nextremely slow at confirming transactions.  The Dogecoin network, however, is\nquite fast.\n\nThe estimation feature supports the \"--noutputs\" and \"--ntransactions\" options\n(see \"Advanced Publication Features: Number of Outputs \u0026 Concurrent\nTransactions\" in section 1.4.2):\n\n    $ python3 bitclamp.py --chain=doge --file=SEKRUT_DOC.pdf --estimate --txfee=1 --noutputs=7 --ntransactions=10\n[...]\nWith 10 concurrent transactions, and 7 outputs per transaction, publication will require at least 10 blocks, or at least 10 minutes.\n[...]\n\n\n1.5. Advanced Publication Features\n\n1.5.1. Custom Filenames and Descriptions\n\nThe filename of the publication can be changed or obscured with the \"--name\"\noption.  In fact, the filename can be omitted entirely with \"--name=''\".\n\nA custom description (up to 128 bytes) can be set with the \"--description\"\nargument.  This field can be used later for searching content in the\nblockchain (by default, the description field is blank).\n\n\n1.5.2. Number of Outputs \u0026 Concurrent Transactions\n\nBy default, Bitclamp uses 5 outputs per transaction.  Because each output\nallows 448 bytes to be published, this results in roughly 2240 bytes published\nper transaction.  This can be changed through the \"--noutputs\" argument.\n\nAlso, Bitclamp transmits one transaction per block by default.  Multiple\ntransactions can be sent instead with the \"--ntransactions\" argument.\n\nBefore you get too excited, though, know that increasing these values will\nlikely *slow down* publication time on the Bitcoin network due to severe\ncongestion as of the time of this writing.\n\nHowever, the Dogecoin network is quite under-utilized at the moment.  A VERY\nsignificant speed boost can be obtained by setting \"--ntransactions=10\" or so.\nIn fact, 20 or 30 concurrent transactions may also be beneficial...\n\n\n1.5.3. Plaintext Publishing\n\nBy default, publications are encrypted with a temporary, random key that is\ndivulged at the very end of the stream.  Hence, nothing is readable until the\nentire file is fully published.\n\nHowever, under certain circumstances, it may be desirable to publish the file\nin plaintext so that its segments are immediately readable as publication\noccurs.  In that case, use the \"--no-crypto\" option.\n\n\n1.5.4. Deadman Switches\n\nBy default, files are encrypted with a random key before publication begins.\nThe key is normally released after the entire file is published.  However, you\ncan withhold the key in a separate key file to manually publish at a later time.\n\nAn external process can then be set to require you to check-in at regular\nintervals.  If a check-in is missed, the key is automatically published.\nEffectively, this becomes an \"insurance policy\" of sorts to protect yourself\nfrom being arrested or killed.\n\nSee DEADMAN_SWITCH_README.txt for full documentation.\n\n\n2. Explicit Extraction of Content\n\nThere are two ways of extracting content from the blockchain.  The blockchain\ncan be monitored in realtime and any discovered content can be written to an\noutput directory.  See the \"Setup For Passive Monitoring Of New Content\" in\nSETUP.txt for information on how to set this up.\n\nThe second way is to use bitclamp_extracterizer.py to scan through part or all\nof the blockchain.  To extract all content:\n\n    $ python3 bitclamp_extracterizer.py --output=/tmp/btc_output\n    $ ls -al /tmp/btc_output/\n[...]\n-rw-rw-r-- 1 btcwriter btcwriter   30133 Jan  9 10:29 omg.tar.bz2\n-rw-rw-r-- 1 btcwriter btcwriter  126584 Jan  9 10:29 SEKRUT_DOC.pdf\n-rw-rw-r-- 1 btcwriter btcwriter   55438 Jan  9 10:31 haha_im_using_the_internet.jpg\n\nTo extract all content between certain block numbers:\n\n   $ python3 bitclamp_extracterizer.py --chain=doge --output=/tmp/doge_output --start-block=4000 --end-block=5000\n   $ ls -al /tmp/doge_output/\n[...]\n-rw-rw-r-- 1 dogewriter dogewriter   24576 Jan  9 10:58 supercool.exe\n-rw-rw-r-- 1 dogewriter dogewriter  102243 Jan  9 10:58 magic.zip\n\nIts possible to filter based on content type.  To download all documents:\n\n   $ python3 bitclamp_extracterizer.py --output=/tmp/btc_output2 --start-block=6000 --content-type document\n   $ ls -al /tmp/btc_output2/\n[...]\n-rw-rw-r--  1 btcwriter btcwriter 126584 Jan  9 11:02 SEKRUT_DOC.pdf\n-rw-rw-r--  1 btcwriter btcwriter 102955 Jan  9 11:03 roflcopter.docx\n\nA filename filter can be applied as well:\n\n   $ python3 bitclamp_extracterizer.py --output=/tmp/btc_output3 --start-block=6000 --filename=SEKRUT* --regtest\n   $ ls -al /tmp/btc_output3/\n[...]\n-rw-rw-r--  1 btcwriter btcwriter 126584 Jan  9 11:14 SEKRUT_DOC.pdf\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjtesta%2Fbitclamp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjtesta%2Fbitclamp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjtesta%2Fbitclamp/lists"}