{"id":20065910,"url":"https://github.com/reshiadavan/catena","last_synced_at":"2026-05-03T22:32:28.705Z","repository":{"id":169188099,"uuid":"636326512","full_name":"ReshiAdavan/Catena","owner":"ReshiAdavan","description":"simple, lightweight, actor-based distributed blockchain","archived":false,"fork":false,"pushed_at":"2024-01-05T17:30:53.000Z","size":273,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-09-23T23:36:26.834Z","etag":null,"topics":["actor-model","akka","blockchain","docker","docker-compose","functional-programming","scala"],"latest_commit_sha":null,"homepage":"","language":"Scala","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ReshiAdavan.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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":"2023-05-04T15:37:54.000Z","updated_at":"2025-02-04T19:37:26.000Z","dependencies_parsed_at":null,"dependency_job_id":"81cd3675-c837-42dd-ac4a-56a1037060bc","html_url":"https://github.com/ReshiAdavan/Catena","commit_stats":null,"previous_names":["reshiadavan/catena"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/ReshiAdavan/Catena","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ReshiAdavan%2FCatena","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ReshiAdavan%2FCatena/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ReshiAdavan%2FCatena/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ReshiAdavan%2FCatena/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ReshiAdavan","download_url":"https://codeload.github.com/ReshiAdavan/Catena/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ReshiAdavan%2FCatena/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32587817,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-03T22:12:39.696Z","status":"ssl_error","status_checked_at":"2026-05-03T22:09:10.534Z","response_time":103,"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":["actor-model","akka","blockchain","docker","docker-compose","functional-programming","scala"],"created_at":"2024-11-13T13:53:17.200Z","updated_at":"2026-05-03T22:32:28.675Z","avatar_url":"https://github.com/ReshiAdavan.png","language":"Scala","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Catena\n\nA Simple, Lightweight, Actor-Based Distributed Blockchain built in Scala, using functional programming concepts and the actor model, in the Akka Framework.\n\n### Inspiration\n\nAfter [CryptGO](https://github.com/ReshiAdavan/CryptGO), I wanted to look into web3.0, blockchain, decentralized systems, etc. So I decided to implement a round robin algorithm to decide between the many projects I could choose and it gave me a blockchain (haha just kidding).\n\nI thought the first thing I could tackle was a blockchain as it was similar in architecture to some of the projects that I have created before. As with any project I gave it my best shot!\n\nThe design decision of choosing Scala originated from an interview and take home assessment I received over Summer 2022. They asked me to complete a take home assessment, entirely in Scala, and if I knew the functional programming paradigm.\n\nNeedless to say I was curious and decided to learn it for myself.\n\nVoila! Catena!\n\n### Topics\n\n- **Languages**: Scala\n- **Paradigm**: Functional (pure and higher order functions, lazy evaluation, currying, etc)\n- **Frameworks**: Akka\n- **Architectures**: Distributed Ledger, Actor-Based Blockchain\n- **Concepts**: PoW Algorithm, Transactions, Chains, Nodes\n\n### Use It Yourself\n\nRun the Project following these steps:\n\n1.  Build the Docker image through the following breakdown:\n\n#### Docker image\n\nThe Dockerfile lets you build the Docker Image of a catena node. In details, the Dockerfile:\n\n- you need a ssh private key to pull from the repo\n- download the [sbt](https://www.scala-sbt.org/) version specified through the image `build-arg` parameter\n- install git and openssh\n- checkout the project\n- run the project and `EXPOSE` port 8080 correctly\n\nThe image can be built using the command (given the right configuration on your end):\n\n`docker build --build-arg SBT_VERSION=\"1.2.7\" -t \u003cyour_user\u003e/\u003cproject_name\u003e .`\n\nThen you can upload the docker image on Dockerhub and go from there\n\n##### Run the docker container\n\nThe docker container compiles the source code and run the catena node. For this reason, when running the container it is required to pass an argument as per when you run the source code.\n\nTo run a branch of the remote repo simply pass the name of the branch as the argument. e.g.:\n\n`docker run --name \u003cwhatever_name_you_choose\u003e -p 8000:8000 \u003cyour_user\u003e/\u003cproject_name\u003e \u003cbranch_name\u003e`\n\nThis will run the code of the branch `\u003cbranch_name\u003e`.\n\nTo run the local source code mounting the local folder to the container `\u003cbranch_name\u003e` one, use the `-v /your/source/folder:/\u003cbranch_name\u003e` and pass `local` as an argument. You can optionally specify a folder inside the container where the source in the volume should be mounted. The source will be automatically copied inside the `/\u003cbranch_name\u003e` folder. This is useful when you are running multiple containers in the same machine.\n\nWhen you stop the container and start it again, the code may need to be manually updated from the repo in case you are running a remote branch, or will compile the local code in case you are running in local mode. Of course a script on your end can automate this (I may or may not have done this).\n\n2.  Run the cluster of 3 nodes using the `docker-compose up` command in the root folder of the project.\n3.  You will need to host the API on any API platform (Postman, Insomnia, etc) and run the respective endpoints to interact with Catena nodes (it should just take time to play around with).\n\n### Architectures (In Detail)\n\nThe blockchain is a distributed ledger: it registers some transaction of values b/w a sender \u0026 receiver. What differs blockchain from a database is the decentralized nature of the blockchain; it is distributed among several communicating nodes that guarantee the validity of the transactions registered.\n\nThe blockchain stores transactions in blocks, that are created (mined) by nodes investing computational power. Every block is created by solving a puzzle that is hard to solve, but easy to verify. Following this light, every block represents the work needed to solve the grand puzzle. This is the reason why the puzzle is called the \"Proof of Work\"; the solution of the puzzle is the proof that a node spent a certain amount of work to solve it and mine the block.\n\nBlock Architecture:\n\n\u003cimg src=\"https://github.com/ReshiAdavan/Catena/blob/master/imgs/blockchain-architecture.PNG\" /\u003e\n\nThe main components of our blockchain model are the Transaction, the Chain, the Proof of Work (PoW) algorithm, and the Node. The transactions are stored inside the blocks of the chain, that are mined using the PoW. The node is the server that runs the blockchain.\n\nSolution Architecture:\n\n\u003cimg src=\"https://github.com/ReshiAdavan/Catena/blob/master/imgs/solution-architecture.PNG\" /\u003e\n\n#### Transaction\n\nTransactions register the movement of our currency between two entities. Every transaction is composed by a sender, a recipient, and an amount of said currency. Transactions will be registered inside the blocks of our blockchain.\n\n#### Chain\n\nThe chain is a linked list (LL) of blocks containing a list of transactions. Every block of the chain has an index, the proof that validates it, the list of transactions, the hash of the previous block, the list of previous blocks, and a timestamp. Every block is chained to the previous one by its hash, that is computed converting the block to a JSON string and then hashing it through a SHA-256 hashing function.\n\n#### PoW\n\nThe PoW algorithm is required to mine the blocks composing the blockchain. The idea is to solve a puzzle that is hard to solve, but easy to verify having the proof. The PoW algorithm that is implemented in Catena is similar to the Bitcoin one (based on Hashcash). It consists in finding a hash with N leading zeros, that is computed starting from the hash of the last block and a number, that is the proof of our algorithm (I have NOT implemented the hashing function myself).\n\n#### Node\n\nThe Node is the server running our blockchain. It provides some REST API to interact with it and perform basic operations such as send a new transaction, get the list of pending transactions, mine a block, and get the current status of the blockchain.\n\n#### The Actor Model\n\nCatena has been implemented using the actor model through the use of the [Akka Framework](https://akka.io/).\n\nHierarchy of actors:\n\n\u003cimg src=\"https://github.com/ReshiAdavan/Catena/blob/master/imgs/actor-hierarchy.PNG\" /\u003e\n\nOverall design:\n\n\u003cimg src=\"https://github.com/ReshiAdavan/Catena/blob/master/imgs/actor-design.PNG\" /\u003e\n\nP.S: I cannot conclude this blockchain was made from 100% purely functional code because there is some state managed in the blockchain and FP requires that functions are stateless. It would be a mix of functional and conventional code we are mostly familar with.\n\nThe detailed designs follows:\n\n\u003cimg src=\"https://github.com/ReshiAdavan/Catena/blob/master/imgs/actor-detailed.png\" /\u003e\n\n- **Broker Actor** is responsible of managing the transactions. It can add a new transaction, read the pending transactions (the ones that are not yet included in a block), and clear the list of pending transactions.\n- **Miner Actor** is responsible of the mining process. It validates the proof of added nodes and executes the PoW algorithm to mine a new block. It is implemented as a state machine composed of two states (ready and busy) in order to handle mining concurrency - If the node is mining a block, it cannot start to mine a new one.\n- **Blockchain Actor** is responsible of managing the chain. It manages the addition of new blocks, and provides information about the chain: the last index, the last hash, and the status of the chain itself. This is a _Persistent Actor_, so it keeps a journal of events and saves a snapshot of the state of the chain when a new block is added. If the node goes down, when it is up again the Blockchain Actor can restore the status of the chain loading the last snapshot.\n- **Node Actor** is on the top of the hierarchy of actors: it manages all the operations executed by the other actors, and it is the junction point between the API and the business logic implemented inside the actors.\n- **ClusterManager Actor** is the manager of the cluster. Its in charge of everything cluster related, such as return the current active members of the cluster.\n- **ClusterListener Actor** listens to the events that happen in the cluster - a member is up/down, etc. - and logs it for debugging purpose.\n\n---\n\nIf you made it this far, congrats! That concludes Catena's README.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Freshiadavan%2Fcatena","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Freshiadavan%2Fcatena","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Freshiadavan%2Fcatena/lists"}