{"id":15698814,"url":"https://github.com/jeffdecola/jeffcoin","last_synced_at":"2025-05-09T02:12:55.909Z","repository":{"id":56014996,"uuid":"209333637","full_name":"JeffDeCola/jeffCoin","owner":"JeffDeCola","description":"My cryptocurrency using a distributed decentralized public ledger in a blockchain (i.e. bitcoin).","archived":false,"fork":false,"pushed_at":"2025-02-04T19:04:50.000Z","size":3943,"stargazers_count":6,"open_issues_count":0,"forks_count":3,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-02-26T10:51:20.328Z","etag":null,"topics":["api-rest","bitcoin","blockchain","blockchain-transactions","cryptocurrency-mining","cryptocurrency-wallet","crytocurrency","ecdsa-key-pair","ecdsa-signature","proof-of-work","sha256-hash","tcp-server","unspent-output","wallet"],"latest_commit_sha":null,"homepage":"","language":"Go","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/JeffDeCola.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}},"created_at":"2019-09-18T14:47:31.000Z","updated_at":"2025-02-04T19:04:54.000Z","dependencies_parsed_at":"2023-12-05T16:10:51.249Z","dependency_job_id":"f0244778-1649-4c97-8667-4cc3471177ac","html_url":"https://github.com/JeffDeCola/jeffCoin","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JeffDeCola%2FjeffCoin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JeffDeCola%2FjeffCoin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JeffDeCola%2FjeffCoin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JeffDeCola%2FjeffCoin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/JeffDeCola","download_url":"https://codeload.github.com/JeffDeCola/jeffCoin/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243141286,"owners_count":20242815,"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":["api-rest","bitcoin","blockchain","blockchain-transactions","cryptocurrency-mining","cryptocurrency-wallet","crytocurrency","ecdsa-key-pair","ecdsa-signature","proof-of-work","sha256-hash","tcp-server","unspent-output","wallet"],"created_at":"2024-10-03T19:34:19.496Z","updated_at":"2025-05-09T02:12:55.902Z","avatar_url":"https://github.com/JeffDeCola.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# jeffCoin\n\n[![Tag Latest](https://img.shields.io/github/v/tag/jeffdecola/jeffCoin)](https://github.com/JeffDeCola/jeffCoin/tags)\n[![jeffdecola.com](https://img.shields.io/badge/website-jeffdecola.com-blue)](https://jeffdecola.com)\n[![MIT License](https://img.shields.io/:license-mit-blue.svg)](https://jeffdecola.mit-license.org)\n[![Go Reference](https://pkg.go.dev/badge/github.com/JeffDeCola/jeffCoin.svg)](https://pkg.go.dev/github.com/JeffDeCola/jeffCoin)\n[![Go Report Card](https://goreportcard.com/badge/github.com/JeffDeCola/jeffCoin)](https://goreportcard.com/report/github.com/JeffDeCola/jeffCoin)\n[![codeclimate Maintainability](https://api.codeclimate.com/v1/badges/0c7cf619a01dd65fc06b/maintainability)](https://codeclimate.com/github/JeffDeCola/jeffCoin/maintainability)\n[![codeclimate Issue Count](https://codeclimate.com/github/JeffDeCola/jeffCoin/badges/issue_count.svg)](https://codeclimate.com/github/JeffDeCola/jeffCoin/issues)\n\n```text\n*** THE REPO IS UNDER CONSTRUCTION - CHECK BACK SOON ***\n```\n\n_A cryptocurrency (transaction based data) built on distributed decentralized\nmulti-node P2P open Network using a sha256 Proof of Work (PoW) **blockchain**\nwith a REST JSON API and a TCP Server to communicate between\nthe Nodes over IP. Or more simply, **a distributed decentralized public ledger.**_\n\nDive In\n\n* Head down to [RUN](https://github.com/JeffDeCola/jeffCoin#run)\n\nTable of Contents\n\n* [PREREQUISITES](https://github.com/JeffDeCola/jeffCoin#prerequisites)\n* [BUILDING BLOCKS](https://github.com/JeffDeCola/jeffCoin#building-blocks)\n* [OVERVIEW](https://github.com/JeffDeCola/jeffCoin#overview)\n* [SOFTWARE ARCHITECTURE](https://github.com/JeffDeCola/jeffCoin#software-architecture)\n* [YOUR PASSWORD \u0026 KEYS](https://github.com/JeffDeCola/jeffCoin#your-password--keys)\n* [RUN](https://github.com/JeffDeCola/jeffCoin#run)\n  * [GENESIS NODE](https://github.com/JeffDeCola/jeffCoin#genesis-node)\n  * [ADDING NEW NODES](https://github.com/JeffDeCola/jeffCoin#adding-new-nodes)\n  * [LOGGING](https://github.com/JeffDeCola/jeffCoin#logging)\n  * [WEBSERVER \u0026 REST API](https://github.com/JeffDeCola/jeffCoin#webserver--rest-api)\n  * [PLAY AROUND](https://github.com/JeffDeCola/jeffCoin#play-around)\n  * [SWITCHES (REFERENCE)](https://github.com/JeffDeCola/jeffCoin#switches-reference)\n* [RUN (WALLET ONLY)](https://github.com/JeffDeCola/jeffCoin#run-wallet-only)\n* [RUN (OPTIONAL)](https://github.com/JeffDeCola/jeffCoin#run-optional)\n  * [CONNECT USING TCP](https://github.com/JeffDeCola/jeffCoin#connect-using-tcp)\n  * [TEST MOCK TRANSACTIONS](https://github.com/JeffDeCola/jeffCoin#test-mock-transactions)\n  * [RUN ON GOOGLE COMPUTE ENGINE (GCE)](https://github.com/JeffDeCola/jeffCoin#run-on-google-compute-engine-gce)\n\nDocumentation and Reference\n\n* [blockchain-cheat-sheet](https://github.com/JeffDeCola/my-cheat-sheets/tree/master/software/development/software-architectures/blockchain/blockchain-cheat-sheet)\n* I got a lot of inspiration\n  [here](https://github.com/nosequeldeebee/blockchain-tutorial)\n* software architecture is located in\n  [architecture.md](https://github.com/JeffDeCola/jeffCoin/blob/master/architecture.md)\n* This repos\n  [github webpage](https://jeffdecola.github.io/jeffCoin/)\n  _built with\n  [concourse](https://github.com/JeffDeCola/jeffCoin/blob/master/ci-README.md)_\n\n## PREREQUISITES\n\n```bash\ngo get -v -u github.com/btcsuite/btcutil/base58\ngo get -v -u golang.org/x/crypto/ripemd160\ngo get -u -v github.com/gorilla/mux\ngo get -u -v github.com/sirupsen/logrus\ngo get -u -v github.com/pkg/errors\ngo get -u -v github.com/satori/go.uuid\ngo get -u -v golang.org/x/crypto/bcrypt\n```\n\n## SOFTWARE STACK\n\n* **GUI**\n  _golang net/http package_\n* **Routing \u0026 REST API framework**\n  _golang gorilla/mux package_\n* **Inter Node Communication**\n  _golang TCP package_\n* **Backend**\n  _golang_\n* **Database**\n  _N/A_\n\n## BUILDING BLOCKS\n\nThis project was built from some of my other projects,\n\n* **BLOCKCHAIN**\n  * The blockchain built from my\n    [single-node-blockchain-with-REST](https://github.com/JeffDeCola/my-go-examples/tree/master/blockchain/single-node-blockchain-with-REST)\n  * **BLOCKCHAIN TRANSACTIONS** are built from my\n    [bitcoin-ledger](https://github.com/JeffDeCola/my-go-examples/tree/master/blockchain/bitcoin-ledger)\n  * The ECDSA signature verification built from my\n    [ecdsa-digital-signature](https://github.com/JeffDeCola/my-go-examples/tree/master/cryptography/asymmetric-cryptography/ecdsa-digital-signature)\n* **ROUTINGNODE**\n  * The TCP Server built from my\n    [simple-tcp-ip-server](https://github.com/JeffDeCola/my-go-examples/tree/master/api/simple-tcp-ip-server)\n* **WALLET**\n  * Generating keys and creating the jeffCoin address\n    is built from my\n    [create-bitcoin-address-from-ecdsa-publickey](https://github.com/JeffDeCola/my-go-examples/tree/master/blockchain/create-bitcoin-address-from-ecdsa-publickey)\n  * The Wallet Private Key is encrypted using\n    [aes-256-gcm](https://github.com/JeffDeCola/my-go-examples/tree/master/cryptography/symmetric-cryptography/aes-256-gcm)\n* **WEBSERVER**\n  * The GUI \u0026 REST JSON API is built from my\n    [simple-webserver-with-REST](https://github.com/JeffDeCola/my-go-examples/tree/master/api/simple-webserver-with-REST)\n  * The password is hashed and checked using\n    [bcrypt-password-hashing](https://github.com/JeffDeCola/my-go-examples/tree/master/cryptography/hashing/bcrypt-password-hashing)\n* **OTHER**\n  * I also use my\n    [errors](https://github.com/JeffDeCola/my-go-examples/tree/master/packages/errors),\n    [logrus](https://github.com/JeffDeCola/my-go-examples/tree/master/packages/logrus),\n    and\n    [flag](https://github.com/JeffDeCola/my-go-examples/tree/master/packages/flag)\n    projects\n\n## OVERVIEW\n\n`jeffCoin` (JEFF) is my interpretation of a transaction based (ledger) using a blockchain.\nThis is a work in progress I feel can be used as a foundation for\nbuilding bigger and better things.\n\nThe following illustration shows the jeffCoin Network of Nodes,\n\n![IMAGE - the-jeffcoin-network - IMAGE](docs/pics/the-jeffcoin-network.svg)\n\nCoins (a.k.a jeffCoins) are minted as follows,\n\n* A grand total of **1,000,000 jeffCoins**\n* The blockchain will not store jeffCoins but **addies** which are\n  1/1000 of a jeffCoin (.001 JEFF)\n* The founders wallet will start with **100,000 jeffCoins (100,000,000 addies)**\n  (10% of all jeffCoins)\n* Rewards **1 jeffCoin (1000 addies) every 10 minutes**\n  _(144 jeffCoins/day or 52,560 jeffCoins/year)_\n* Will take **17.12 years to mint all the jeffCoins**\n  _(900,000/52,560 = 17.12)_\n\njeffCoin uses the following technology,\n\n* Written in golang\n* Implements a blockchain using a sha256 hash\n* A distributed decentralized multi-node P2P architecture maintaining\n  a Network of Nodes\n* A Webserver with both a GUI and a REST API\n* A TCP Server for inter-node communication\n* ECDSA Private \u0026 Public Key generation\n* Private Key AES-256 encryption for storage\n* Creates a jeffCoin Address from the ECDSA Public Key\n  _(Just like bitcoin)_ currently not being used\n* ECDSA Digital Signature Verification\n* Mining uses Proof of Work (PoW)\n* Transaction as stored using an unspent transaction output model\n* Password hashing and storage using bcrypt\n\nWhat jeffCoin does not have,\n\n* No database, so if the entire Network dies, the chain dies\n* Rigorous testing of all corner cases\n\n## SOFTWARE ARCHITECTURE\n\nThis readme got too big so I moved my software explanation to\n[architecture.md](https://github.com/JeffDeCola/jeffCoin/blob/master/architecture.md).\n\nI divided the software into 5 sections,\n\n* [1. BLOCKCHAIN](https://github.com/JeffDeCola/jeffCoin/blob/master/architecture.md#1-blockchain)\n  * [1.1 BLOCKCHAIN](https://github.com/JeffDeCola/jeffCoin/blob/master/architecture.md#11-blockchain)\n  * [1.2 TRANSACTIONS](https://github.com/JeffDeCola/jeffCoin/blob/master/architecture.md#12-transactions)\n* [2. MINER](https://github.com/JeffDeCola/jeffCoin/blob/master/architecture.md#2-miner)\n* [3. ROUTINGNODE](https://github.com/JeffDeCola/jeffCoin/blob/master/architecture.md#3-routingnode)\n  * [3.1 NODELIST](https://github.com/JeffDeCola/jeffCoin/blob/master/architecture.md#31-nodelist)\n  * [3.2 TCP REQUESTS \u0026 HANDLERS](https://github.com/JeffDeCola/jeffCoin/blob/master/architecture.md#32-tcp-requests--handlers)\n* [4. WALLET](https://github.com/JeffDeCola/jeffCoin/blob/master/architecture.md#4-wallet)\n* [5. WEBSERVER](https://github.com/JeffDeCola/jeffCoin/blob/master/architecture.md#5-webserver)\n  * [5.1 GUI](https://github.com/JeffDeCola/jeffCoin/blob/master/architecture.md#51-gui)\n  * [5.2 REST API](https://github.com/JeffDeCola/jeffCoin/blob/master/architecture.md#52-rest-api)\n\n## YOUR PASSWORD \u0026 KEYS\n\nYour secrets are kept in `/credentials` in .json files.\nThese file are `.gitignored`.\nBut if they did make there way onto git you are still protected as follows,\n\n* **Password File**\n  * Stores your password hash\n  * Password hashing using bcrypt\n* **Wallet File**\n  * Stores your Private and Public ECDSA Key\n  * The Private Key is Encrypted using AES-256 with your password as your key\n\nThis illustration may help,\n\n![IMAGE - password-and-key-flow - IMAGE](docs/pics/password-and-key-flow.svg)\n\n## RUN\n\nIf this is you first time running and you want to create your own private\nNetwork, you need to create your first Node (Genesis Node).\nYou only do this once. You can also set the log level (info, debug, trace)\nto cut down on the amount of logging.\n\n### GENESIS NODE\n\n```bash\ngo run jeffCoin.go \\\n       -genesis \\\n       -loglevel debug \\\n       -nodehttpport 2000 \\\n       -nodeip 127.0.0.1 \\\n       -nodename Founders \\\n       -nodetcpport 3000 \\\n       -nodepassword fpw\n```\n\nThis will created the first Node (the Founders Node) in the Network.\nIt will also create a wallet and password file and save the credentials\nin `/wallet` and `/password` respectively.  Not to worry, the password\nis password hashed with bcrypt and your Wallet Private Key is encrypted\nusing AES-256. I also `.gitignore` them.\n\nNote that the node has an IP address and port for both HTTP and TCP.\nFor this example I use the localhost or 127.0.0.1. But obviously,\nyou can pick anything you want for your rig.\n\n**But having one node is boring so lets create more.**\n\n### ADDING NEW NODES\n\nTo hook up to the Network you need the IP of any\nworking Network Node. If you have the above running Node\non `127.0.0.1:3000`, adding a second Node\n\"Jeff\" in your network could look like,\n\n```bash\ngo run jeffCoin.go \\\n       -loglevel debug \\\n       -networkip 127.0.0.1 \\\n       -networktcpport 3000 \\\n       -nodehttpport 2001 \\\n       -nodeip 127.0.0.1 \\\n       -nodename Jeff \\\n       -nodetcpport 3001 \\\n       -nodepassword jpw\n```\n\nWhy stop, might as well add a third Node,\n\n```bash\ngo run jeffCoin.go \\\n       -loglevel debug \\\n       -networkip 127.0.0.1 \\\n       -networktcpport 3000 \\\n       -nodehttpport 2002 \\\n       -nodeip 127.0.0.1 \\\n       -nodename Matt \\\n       -nodetcpport 3002 \\\n       -nodepassword mpw\n```\n\n### LOGGING\n\nYou will notice logging is set to `-debug`. You can be more explicit\nand set to `-trace` or less wordy and set to `-info`.\n\n### WEBSERVER \u0026 REST API\n\nThe GUI for the three nodes you just created are,\n\n[127.0.0.1:2000](http://127.0.0.1:2000/)\n**/**\n[127.0.0.1:2001](http://127.0.0.1:2001/)\n**/**\n[127.0.0.1:2002](http://127.0.0.1:2002/)\n\nThe API page will list the various API commands.\nFor example, to show a particular block,\n\n[127.0.0.1:2000/showblock/0](http://127.0.0.1:2000/showblock/0)\n\n### PLAY AROUND\n\nEach Node has it's own wallet, so now you can send jeffCoins/Value.\nTo do this, use the Webserver and API.\nYou will notice only the Founders have jeffCoins to send.\nSo Jeff or Matt will not be able to send coins until the\nFounder gives them some.\n\nSend some coins from the Founders to Jeff or Matt and note they are pending.\nThat's because they are not validated.  Like bitcoin, you will need\nto wait 10 minutes for a miner to solve the nonce and then for\nthe Network to validate the transactions and reach consensus.\n\n### SWITCHES (REFERENCE)\n\n**`-h`** prints the following,\n\n* **`-gce`**\n  Is this Node on Google Compute Engine _(See below)_\n* **`-genesis`**\n  Create your first Node\n* **`-loglevel`** _string_\n  LogLevel (info, debug or trace) (default \"info\")\n* **`-networkip`** _string_\n  Network IP (default \"127.0.0.1\")\n* **`-networktcpport`** _string_\n  Network TCP Port (default \"3000\")\n* **`-nodehttpport`** _string_\n  Node Web Port (default \"2001\")\n* **`-nodeip`** string\n  Node IP (default \"127.0.0.1\")\n* **`-nodename`** _string_\n  Node Name (default \"Jeff\")\n* **`-nodepassword`** _string_\n  Set/Reset your Password\n* **`-nodetcpport`** _string_\n  Node TCP Port (default \"3001\")\n* **`-testblockchain`**\n  Loads the blockchain with test data _(See below)_\n* **`-v`**\n  prints current version\n* **-`wallet`**\n  Only the wallet and webserver GUI/API _(See below)_\n\n## RUN (WALLET ONLY)\n\nIf you just want to have a wallet, use the `-wallet` switch.\nYou will not be part of the Network since there is no blockchain\nor miner.  But you can always restart and become part of the Node.\n\nYou will need to hook up to a Node, so the following could work,\n\n```bash\ngo run jeffCoin.go \\\n       -loglevel debug \\\n       -networkip 127.0.0.1 \\\n       -networktcpport 3000 \\\n       -nodehttpport 2005 \\\n       -nodeip 127.0.0.1 \\\n       -nodename Jills-Wallet \\\n       -nodetcpport 3005 \\\n       -nodepassword jpw \\\n       -wallet\n```\n\nThe Node and Wallet name are the same.\n\n## RUN (OPTIONAL)\n\nHere are some optional things you can do.\n\n### CONNECT USING TCP\n\nYou can also bypass the Webserver REST API and just open\na connection to the TCP server itself,\n\n```txt\nnetcat -q -1 127.0.0.1 3000\n```\n\nAnd request commands such as,\n\n```txt\n--- Waiting for command: SBC, BANN, SNL, BVB, BC, BTR, SAB, TR, EOF\nSNL\n[...nodeList...]\nthank you\n```\n\nNote you will need to handshake it with a `thank you` at the end.\n\nThere is a complete list of commands in the architecture readme\n[TCP REQUESTS \u0026 HANDLERS](https://github.com/JeffDeCola/jeffCoin/blob/master/architecture.md#32-tcp-requests--handlers).\n\n### TEST MOCK TRANSACTIONS\n\nIf you add the `-test` switch you will run some mock transactions from mock wallets.\nThose wallets are located in `/wallets` and just used for testing.\n\nYou must use the **MockFounders** nodename,\n\n```bash\ngo run jeffCoin.go \\\n       -genesis \\\n       -loglevel debug \\\n       -nodehttpport 2000 \\\n       -nodeip 127.0.0.1 \\\n       -nodename MockFounders \\\n       -nodetcpport 3000 \\\n       -nodepassword mfpw \\\n       -testblockchain\n```\n\nThese transactions are the same I used in my\n[bitcoin-ledger](https://github.com/JeffDeCola/my-go-examples/tree/master/blockchain/bitcoin-ledger)\nexample.\n\nSo your blockchain and pendingBlock should look similar to\n[blockchain-output.txt](https://github.com/JeffDeCola/my-go-examples/blob/master/blockchain/bitcoin-ledger/blockchain-output.txt).\n\nAnd the balances in the blockchain should be,\n\n```txt\nThe balance for MockFounders PubKey (Address) is 99657000\nThe balance for MockJeffs PubKey (Address) is 42500\nThe balance for MockMatts PubKey (Address) is 265000\nThe balance for MockJills PubKey (Address) is 35000\nThe balance for MockCoinVaults PubKey (Address) is 500\n```\n\nRemember, the pendingBlock is pending, so it's not part of this calculation.\nTransaction do not have value until they are part of the blockchain.\n\n### RUN ON GOOGLE COMPUTE ENGINE (GCE)\n\nMake sure your create a firewall rule and have your instance use\nit as a network tag,\n\n```bash\ngcloud compute firewall-rules create jeffs-firewall-settings-rule \\\n    --action allow \\\n    --rules tcp:1234,tcp:3334 \\\n    --priority 1000 \\\n    --source-ranges 0.0.0.0/0 \\\n    --target-tags \"jeffs-firewall-settings\" \\\n    --description \"Jeffs firewall rules\"\n```\n\nThe IP `0.0.0.0` gets forwarded to your external IP, hence I added a\n`-gce switch` to deal with this,\n\n```bash\ngo run jeffCoin.go \\\n       -gce \\\n       -genesis \\\n       -loglevel debug \\\n       -nodehttpport 1234 \\\n       -nodeip 35.203.189.193 \\\n       -nodename Founders \\\n       -nodetcpport 3334 \\\n       -nodepassword fpw\n```\n\nAdd another node (not at gce) is as simple as connecting to it,\n\n```bash\ngo run jeffCoin.go \\\n       -loglevel debug \\\n       -networkip 35.203.189.193 \\\n       -networktcpport 3334 \\\n       -nodehttpport 2003 \\\n       -nodeip 127.0.0.1 \\\n       -nodename Jill \\\n       -nodetcpport 3003 \\\n       -nodepassword jpw\n```\n\nI have a gce build example\n[here](https://github.com/JeffDeCola/my-packer-image-builds#jeffs-gce-ubuntu-1904-xxxx).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjeffdecola%2Fjeffcoin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjeffdecola%2Fjeffcoin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjeffdecola%2Fjeffcoin/lists"}