{"id":21952019,"url":"https://github.com/systangotechnologies/rustychain","last_synced_at":"2026-05-09T10:49:34.921Z","repository":{"id":195045493,"uuid":"692128710","full_name":"SystangoTechnologies/rustychain","owner":"SystangoTechnologies","description":"Production ready Starter-kit for RUST based Web applications","archived":false,"fork":false,"pushed_at":"2023-09-15T16:33:52.000Z","size":934,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-02-03T22:40:47.342Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Rust","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/SystangoTechnologies.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-09-15T16:12:36.000Z","updated_at":"2023-09-15T16:32:59.000Z","dependencies_parsed_at":null,"dependency_job_id":"cea4ee5a-d929-48cf-9820-f71137eb70ea","html_url":"https://github.com/SystangoTechnologies/rustychain","commit_stats":null,"previous_names":["systangotechnologies/rustychain"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SystangoTechnologies%2Frustychain","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SystangoTechnologies%2Frustychain/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SystangoTechnologies%2Frustychain/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SystangoTechnologies%2Frustychain/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/SystangoTechnologies","download_url":"https://codeload.github.com/SystangoTechnologies/rustychain/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244999407,"owners_count":20544873,"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":"2024-11-29T06:19:10.684Z","updated_at":"2026-05-09T10:49:34.874Z","avatar_url":"https://github.com/SystangoTechnologies.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003e\n  \u003cbr\u003e\n  \u003ca\u003e\u003cimg src=\"https://github.com/SystangoTechnologies/rustychain/blob/main/docs/images/logo.jpeg\" alt=\"rustychain\"\u003e\u003c/a\u003e\n  \u003cbr\u003e\n  Rust Web Starter-kit\n  \u003cbr\u003e\n\u003c/h1\u003e\n\n\u003ch4 align=\"center\"\u003eProduction ready Starter-kit for RUST based web applications.\u003c/h4\u003e\n\n\u003cp align=\"center\"\u003e\n    \u003ca alt=\"Rust\"\u003e\n        \u003cimg src=\"https://img.shields.io/badge/Rust-v1.72.0-orange.svg\" /\u003e\n    \u003c/a\u003e\n    \u003ca alt=\"Actix\"\u003e\n        \u003cimg src=\"https://img.shields.io/badge/Actix%20Web-v4-brightgreen.svg\" /\u003e\n    \u003c/a\u003e\n    \u003ca alt=\"Diesel\"\u003e\n        \u003cimg src=\"https://img.shields.io/badge/Diesel-v2.0.0-yellowgreen.svg\"\u003e\n    \u003c/a\u003e\n    \u003ca alt=\"r2d2\"\u003e\n        \u003cimg src=\"https://img.shields.io/badge/r2d2-PGSQL-orange.svg\"\u003e  \n    \u003c/a\u003e      \n    \u003ca alt=\"Docker\"\u003e\n        \u003cimg src=\"https://img.shields.io/badge/Docker-v24-yellowgreen.svg\" /\u003e\n    \u003c/a\u003e\n    \u003ca alt=\"Dependencies\"\u003e\n        \u003cimg src=\"https://img.shields.io/badge/dependencies-up%20to%20date-brightgreen.svg\" /\u003e\n    \u003c/a\u003e\n    \u003ca alt=\"Contributions\"\u003e\n        \u003cimg src=\"https://img.shields.io/badge/contributions-welcome-orange.svg\" /\u003e\n    \u003c/a\u003e\n    \u003ca alt=\"License\"\u003e\n        \u003cimg src=\"https://img.shields.io/badge/license-MIT-blue.svg\" /\u003e\n    \u003c/a\u003e\n\u003c/p\u003e\n\n# RustyChain\n\nRustyChain is a standalone blockchain ledger application that supports various transactions for managing fungible tokens. This README.md file provides documentation for the different transaction types and their associated parameters.\n\nThe main features supported in the current version of the application are as follows-\n\n- **Transaction to Initialize Fungible Tokens:**\nUsers can create a transaction for initializing a new Fungible token using an API. They need to provide basic information such as token's name, symbol, decimals and initial supply in order to register the transaction.\n\n- **Transaction to Mint Fungible Tokens:**\nAny token initialized for the first time results in crediting the initial requested supply to the owner's wallet. Owner can now decide to either transfer these tokens to another user's address or simply mint new tokens to him/her. If new tokens are minted, then it will result in the increment of the total_supply of the token and new tokens will get credited to the recipient's address.\n\n- **Transaction to Burn Fungible Tokens:**\nThe opposite of Mint is a Burn transaction. Burn results in reducing the balance of a user's wallet and the overall total supply of the token. Only an owner can burn tokens available in his wallet.\n\n- **Transaction to Transfer Fungible Tokens:**\nUsers can transfer tokens from one wallet to another. If the target wallet doesn't yet exist, then it created first and then credited with the token balance. User can only transfer the amount of tokens which is available in their wallet, if a balance in excess is sent in the transaction then eventually at the time of transaction execution it will result in a failure.\n\n- **Mine Blocks:**\nLast, the application supports mining of blocks with a PoA arrangement. A selected miner gets rights to mine the blocks on ledger, currently a block gets created with at max 2 transactions and at the least 0 transactions too. This limit is configurable and can easily be updated.\n\nMining of a block results in execution of the transactions in raw state. After the execution is done, the transaction moves into either Success or Fail states.\n\n- **Service Maintenance Scheduling:**\nQuite overlooked yet an essential feature of a web application is administered ability to put service on maintenance. This feature allows admin to temporarily put the entire REST APIs on maintenance mode, during this period updates to the backend service can be performed without having to worry about serving client requests. Only an admin can put the service on hold and resume it via an API call.\n\n\nThe main aim behind creating this RUST application was to setup a boilerplate application showing how to use RUST for REST API use cases. We have used the following tools/crates while creating this codebase-\n\n- **Actix** - Server side framework\n- **Diesel** - ORM\n- **r2d2** - Connection pool manager \n- **PostgreSQL** - SQL database \n- **utoipa** - Autogenerated OpenAPI documentation for Rust REST APIs\n- **Docker** - Containerizing framework\n- **Swagger** - API documentation\n- **Redoc** - API documentation\n- **Rapidoc** - API documentation\n\n\n## Onion Architecture\nOnion architecture is a software design pattern that organizes the codebase into concentric layers, with the core layer containing the most fundamental and independent code, and the outer layers containing more specific and dependent code. This separation of concerns makes the codebase more maintainable and scalable, as each layer can be changed without affecting the other layers.\n\nActix web is a popular web framework for Rust that is well-suited for implementing the application layer of the onion architecture. It is built on top of the Actix actor framework, which provides a clear separation of concerns and modularity. Actix web is also high-performance and scalable, making it a good choice for building web applications of all sizes.\n\nIn simpler terms, onion architecture is a way of organizing your code so that it is easier to maintain and update. Actix web is a web framework that can be used to implement onion architecture in Rust.\n\nHere is an analogy:\n\nImagine a cake with multiple layers. Each layer has a different flavor and texture, but they all work together to create a delicious cake. The onion architecture is similar to a cake in that each layer is independent of the other layers. This means that you can change the flavor or texture of one layer without affecting the other layers.\n\nActix web is like the frosting on the cake. It provides a layer of functionality that makes it easy to build web applications. However, Actix web is not necessary for onion architecture. You can use any web framework you want to implement onion architecture.\n\n## RustyChain Architecture Overview\nThe onion architecture is a layered architecture that is based on the onion model. \nWhere each layer in the onion model is used to define the different layers of an application.\n\nFor this rust implementation 4 layers are used. \n* api (app) module: The outermost layer that contains the controllers and the endpoints definition, serialization and deserialization of the data, validation and error handling.\n* infrastructure: Layer that typically include database connections, external APIs calls, logging and configuration management.\n* services: Layer that contains the application's services, which encapsulate the core business logic and provide a higher-level abstraction for the application to interact with the domain entities.\n* domain: The innermost layer that contains the core business logic and entities of the application.\n\n\nFolder structure:\n```\n.\n├── migrations\n├── scripts\n│   └── run_postgres.sh # Run postgres in docker locally\n├── src\n│   ├── api\n│   │   ├── controllers\n│   │   │   └── ...  # controllers for the api\n│   │   ├── dto # Data transfer objects  \n│   │   │   └── ... # Individual DTOs\n│   │   └── errors.py\n│   ├── infrastructure\n│   │   ├── services\n│   │   │   └── ...  # Services that use third party libraries or services (e.g. email service)\n│   │   ├── databases\n│   │   │   └── ...  # Database adapaters and initialization\n│   │   ├── repositories\n│   │   │   └── ...  # Repositories for interacting with the databases\n│   │   └── models\n│   │       └── ...  # Database models\n│   ├── domain\n│   │   ├── mod.rs\n│   │   ├── constants.rs\n│   │   ├── errors.rs\n│   │   ├── models\n│   │   │   └── ...  # Business logic models traits or structs\n│   │   ├── services\n│   │   │   └── ...  # Service traits\n│   │   └── repositories\n│   │       └── ...  # Repository traits \n│   ├── services\n│   │   └── ...  # Concrete service implementation for interacting with the domain (business logic)\n│   ├── container.rs\n│   ├── create_app.rs # app factory \n│   ├── lib.rs \n│   └── main.rs\n```\n\n* migrations: Alembic's migration scripts are stored here.\n* scripts: contains the application's configuration settings.\n\n\n## Database Schema ##\nThe current schema looks as follows:\n\n\u003cimg src=\"https://github.com/SystangoTechnologies/rustychain/blob/main/docs/images/schema.png\" alt=\"rustychain db schema\"\u003e\u003c/a\u003e\n\n\n## REST API Calls \n\n### Transactions\n\n#### 1. Initialize Fungible Token (InitFt)\n\nInitialize a new fungible token.\n\n**Parameters:**\n\n- `from_address`: Token owner's wallet address.\n- `to_address`: System contract address.\n- `transaction_type`: INIT_FT (TransactionType::InitFt).\n- `value`: Initial supply of tokens.\n- `symbol`: Token symbol.\n- `name`: Token name.\n- `decimals`: Token's allowed decimals.\n\nExample Usage:\n```\nPOST API Endpoint : http://localhost:8080/api/transactions\n```\nJSON Payload:\n\n```json\n{\n    \"from_address\": \"0x00000000000000000000000000000000000ARPIT\",\n    \"to_address\": \"0x00000000000000000000000000SYSTEMCONTRACT\",\n    \"transaction_type\": \"INIT_FT\",\n    \"value\": 10000000000,\n    \"data\": {\n        \"symbol\": \"APPL\",\n        \"name\": \"Apple\",\n        \"decimals\": 0\n    }\n}\n```\n\n#### 2. Mint Fungible Tokens (MintFt)\n\nMint fresh tokens of the initialized fungible token.\n\n**Parameters:**\n\n- `from_address`: Token owner's wallet address.\n- `to_address`: Address to which tokens need to be minted.\n- `transaction_type`: MINT_FT (TransactionType::MintFt).\n- `value`: Number of tokens to be minted.\n- `token_address`: Address of the token to be minted, owned by the `from_address`.\n\nExample Usage:\n```\nPOST API Endpoint : http://localhost:8080/api/transactions\n```\nJSON Payload:\n\n```json\n{\n    \"from_address\": \"0x00000000000000000000000000000000000ARPIT\",\n    \"to_address\": \"0x742d35Cc6634C0532925a3b844Bc454e4430JOHN\",    \n    \"transaction_type\": \"MINT_FT\",\n    \"value\": 200,\n    \"data\": {\n        \"token_address\": \"0x8de21e962545c8622a9139387160405a8cee49f5\"\n    }\n}\n```\n\n#### 3. Burn Fungible Tokens (BurnFt)\n\nBurn existing tokens in the fungible token contract.\n\n**Parameters:**\n\n- `from_address`: Wallet address of the user who has tokens to burn.\n- `to_address`: NULL address (can be left empty or set to NULL).\n- `transaction_type`: BURN_FT (TransactionType::BurnFt).\n- `value`: Amount of tokens to be burnt (should be less than or equal to the `from_address`'s balance).\n- `token_address`: Address of the token to be burned.\n\nExample Usage:\n```\nPOST API Endpoint : http://localhost:8080/api/transactions\n```\nJSON Payload:\n\n```json\n{\n  \"from_address\": \"0xUserAddress\",\n  \"to_address\": \"\",\n  \"transaction_type\": \"BURN_FT\",\n  \"value\": 500,\n  \"data\": {\n        \"token_address\": \"0x8de21e962545c8622a9139387160405a8cee49f5\"\n  }\n}\n```\n\n#### 4. Transfer Fungible Tokens (TransferFt)\n\nTransfer owned tokens from one wallet address to another.\n\n**Parameters:**\n\n- `from_address`: Sender's wallet address (user who has tokens).\n- `to_address`: Receiver's wallet address.\n- `transaction_type`: TRANSFER_FT (TransactionType::TransferFt).\n- `value`: Amount of tokens to be transferred (should be less than or equal to sender's balance).\n- `token_address`: Address of the token to be transferred.\n\nExample Usage:\n```\nPOST API Endpoint : http://localhost:8080/api/transactions\n```\nJSON Payload:\n\n```json\n{\n  \"from_address\": \"0xSenderAddress\",\n  \"to_address\": \"0xReceiverAddress\",\n  \"transaction_type\": \"TRANSFER_FT\",\n  \"value\": 200,\n  \"data\": {\n        \"token_address\": \"0x8de21e962545c8622a9139387160405a8cee49f5\"\n  }\n}\n```\n\n#### 5. Get All Transactions\n\nRetrieve all transactions in paginated manner\n\nExample Usage:\n```\nGET API Endpoint : http://localhost:8080/api/transactions\n```\n\n#### 6. Get a Transaction by its Hash\n\nRetrieve a transaction by its hash\n\n**Parameters:**\n\n- `txn_hash`: Transaction Hash.\n\nExample Usage:\n```\nGET API Endpoint : http://localhost:8080/api/transactions/{txn_hash}\n```\n\n### Blocks\n\n#### 1. Mine a new Block\n\nCreates a new block\n\n**Parameters:**\n\n- `miner_address`: Miner's wallet address.\n\nExample Usage:\n```\nPOST API Endpoint : http://localhost:8080/api/blocks\n```\nJSON Payload:\n\n```json\n{\n  \"miner_address\": \"string\"\n}\n```\n\n#### 2. Get All Blocks\n\nRetrieve all blocks in paginated manner\n\nExample Usage:\n```\nGET API Endpoint : http://localhost:8080/api/blocks\n```\n\n#### 3. Get a Block by its number\n\nRetrieve a block in by its number\n\n**Parameters:**\n\n- `id`: Block Number.\n\nExample Usage:\n```\nGET API Endpoint : http://localhost:8080/api/blocks/{id}\n```\n\n### Fungible Tokens\n\n#### 1. Get all Fungible Tokens\n\nRetrieve all the fungible tokens in paginated manner\n\nExample Usage:\n```\nGET API Endpoint : http://localhost:8080/api/fts\n```\n\n#### 2. Get a Fungible Token by its address\n\nRetrieve a fungible token by its hex address\n\n**Parameters:**\n\n- `token_address`: Address of the Fungible Token.\n\nExample Usage:\n```\nGET API Endpoint : http://localhost:8080/api/fts/{token_address}\n```\n\n### Wallets\n\n#### 1. Get all Wallets\n\nRetrieve all the wallets in paginated manner\n\nExample Usage:\n```\nGET API Endpoint : http://localhost:8080/api/wallets\n```\n\n#### 2. Get a Wallet by its Address and the associated Token's Address\n\nRetrieve a wallet by its address and the associated token\n\n**Parameters:**\n\n- `wallet_address`: Address of the User's Wallet.\n- `token_address`: Address of the Fungible Token.\n\nExample Usage:\n```\nGET API Endpoint : http://localhost:8080/api/wallets/{wallet_address}/{token_address}\n```\n\n### Service Context\n\n#### 1. Get Status\n\nRetrieve the maintenance status of the backend\n\nExample Usage:\n```\nGET API Endpoint : http://localhost:8080/admin/maintenance/status\n```\n\n#### 2. Update Status\n\nUpdate the maintenance status of the backend\n\n**Parameters:**\n\n- `maintenance`: Set to true/false.\n\nExample Usage:\n```\nPOST API Endpoint : http://localhost:8080/admin/maintenance/status\n```\n\nJSON Payload:\n\n```json\n{\n  \"maintenance\": false\n}\n```\n\n## How to setup the application locally?\n\n1. Take a git pull on your local machine\n2. Ensure a postgreSQL instance is running locally/remotely\n3. Rename .env.sample to .env\n3. Set DATABASE_URL env variable in the .env file\n4. Set MAX_DB_SESSIONS_PER_WORKER to a realistic number (1/2/3 should be fine for local usage)\n5. Run 'diesel setup' command to setup the database\n6. Run 'diesel migration run' command to run all the migrations\n7. Run 'cargo watch -x run' to run with hot reloading enabled or simply 'cargo run'\n8. To try the integration tests, run 'sh scripts/test.sh'\n\n## Commands\n\n# Start local PG Instance\n``` bash\n/usr/local/opt/postgresql@14/bin/postgres -D /usr/local/var/postgresql@14\n```\n# Diesel migrations\n\nSteps to perform migrations after checkout-\n```\ndiesel setup\ndiesel migration generate \u003cmigration_name\u003e\ndiesel migration run\n```\n\nCommand to create a new migration script-\n```\ndiesel migration generate \u003cmigration_name\u003e\n```\n\nIf you want to reset the database and rerun the migrations, use the following command-\n```\ndiesel database reset\n```\n\n# Launch server\nUse the watch command if hot reloading is desired\n```\ncargo watch -x run\ncargo run\n```\n\n# Launch test cases\nTo launch the test cases with a clean database use the following command-\n```\nsh scripts/test.sh\n```\n\n## Application URLs\n\n### Backend URL\nhttp://localhost:8080/api\n\n### Swagger URL\nhttp://localhost:8080/swagger-ui/\n\n\u003cimg src=\"https://github.com/SystangoTechnologies/rustychain/blob/main/docs/images/swagger.png\" alt=\"swagger ui\"\u003e\u003c/a\u003e\n\n### Redoc URL\nhttp://localhost:8080/redoc\n\n\u003cimg src=\"https://github.com/SystangoTechnologies/rustychain/blob/main/docs/images/redoc.png\" alt=\"redoc\"\u003e\u003c/a\u003e\n\n### Rapidoc URL\nhttp://localhost:8080/rapidoc\n\n\u003cimg src=\"https://github.com/SystangoTechnologies/rustychain/blob/main/docs/images/rapidoc.png\" alt=\"rapidoc\"\u003e\u003c/a\u003e\n\n\n## Contributors ##\n\u003ca href=\"mailto:arpit@systango.com\"\u003eArpit Khandelwal\u003ca/\u003e\n\n## License\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## References\n\n[clean-architecture]: https://blog.cleancoder.com/uncle-bob/2012/08/13/the-clean-architecture.html\n[hexagonal-architecture]: https://en.wikipedia.org/wiki/Hexagonal_architecture_(software)\n[onion-architecture]: https://jeffreypalermo.com/2008/07/the-onion-architecture-part-1/\n[rust]: https://www.rust-lang.org/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsystangotechnologies%2Frustychain","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsystangotechnologies%2Frustychain","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsystangotechnologies%2Frustychain/lists"}