{"id":20078705,"url":"https://github.com/wpdas/chain-db-rs","last_synced_at":"2025-03-02T13:14:43.943Z","repository":{"id":184327548,"uuid":"667660623","full_name":"wpdas/chain-db-rs","owner":"wpdas","description":"ChainDB TS is a library that allows the usage of the ChainDB database in Rust projects.","archived":false,"fork":false,"pushed_at":"2023-07-27T23:42:55.000Z","size":38,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-01-13T01:11:44.299Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","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/wpdas.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-07-18T03:02:19.000Z","updated_at":"2023-07-27T23:41:35.000Z","dependencies_parsed_at":null,"dependency_job_id":"b6dd86d2-7438-45f5-8a06-1cf5f0c0faed","html_url":"https://github.com/wpdas/chain-db-rs","commit_stats":null,"previous_names":["wpdas/chain-db-rs"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wpdas%2Fchain-db-rs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wpdas%2Fchain-db-rs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wpdas%2Fchain-db-rs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wpdas%2Fchain-db-rs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wpdas","download_url":"https://codeload.github.com/wpdas/chain-db-rs/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241509658,"owners_count":19974071,"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-13T15:16:17.091Z","updated_at":"2025-03-02T13:14:43.937Z","avatar_url":"https://github.com/wpdas.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Chain DB - RS\n\nChainDB RS is a library that allows the usage of the ChainDB database in Rust projects.\n\nChain DB is a Story-driven database. This system uses a chain of blocks with stored data. Each change generates a transaction that is saved in a block. The network works centrally, so persistent data is not decentralized.\n\nThis database has some features by default, such as: create user account, get user account, transfer units and get transfer records as well as the main feature that is tables.\n\nThe `unit` property present in each user's account can be anything the project wants, it can be a type of currency, item, resource.\n\nVisit the [Chain DB repository](https://github.com/wpdas/chain-db) to get to know more.\n\n## Install\n\nInstall using cargo. You'll need to install serde json to create your tables structs as well:\n\n```sh\n# TODO: Not available yet\ncargo add chain_db_rs\ncargo add serde_json\n```\n\n## Usage examples\n\nFirst of all, it's good to know that all requests return a `BasicResponse\u003cD\u003e` structure that has the following structure:\n\n**success:** `bool` (informs if the transaction was successful) \u003cbr/\u003e\n**error_msg:** `String` (error message) \u003cbr/\u003e\n**data:** `D` (any expected data type depending on the request) \u003cbr/\u003e\n\nMake sure you have the database running on your local machine or use the server link from where the database is running.\n\n### Table\n\nTables must a struct. This struct will be used as a reference to create the table's fields.\n\nWhen it's time to persist the table's data on the chain, just call the `persit` database function.\n\n```rs\n// Greeting Table\nuse serde::{Deserialize, Serialize};\n\n#[derive(Serialize, Deserialize, Debug)]\npub struct GreetingTable {\n    pub greeting: String,\n}\n\nimpl GreetingTable {\n    pub fn new() -\u003e Self {\n        Self {\n            greeting: String::from(\"Hi\"),\n        }\n    }\n}\n```\n\n```rs\n#[tokio::main]\nasync fn main() {\n  // server | db-name | user | password\n  // If the `server` parameter is empty(None), then \"http://localhost:2818\" will be used.\n  let db = ChainDB::connect(None, \"my-db\", \"root\", \"1234\");\n\n  // Initialize the \"greeting\" table using the \"GreetingTable\"\n  // class as a template. If there is already any data saved in\n  // the chain, this data will be populated in the table instance.\n  let mut greeting = db.get_table(\"greeting\", GreetingTable::new).await;\n  println!(\"Current greeting: {:?}\", greeting.table); // { greeting: 'Hi' }\n\n  // Mutating data\n  greeting.table.set_greeting(String::from(\"Hello my dear!\"));\n  greeting.persist().await; // Data is persisted on the blockchain\n\n  // See the most updated values of the table\n  println!(\"Current greeting: {:?}\", greeting.table); // { greeting: 'Hello my dear!' }\n}\n```\n\nThe next examples will not include the `db` implementation and the `async fn main() {}` block as this is implied.\n\n### Get Table's History\n\nYou can use `Table.get_history(depth: u64)` to get the last X changes.\n\n```rs\nlet mut test_table = _db.get_table(\"test\", TestTable::new).await;\n\n// Persist some data\ntest_table.table.greeting = \"Ola amigo!\".to_string();\ntest_table.table.year = 1990;\ntest_table.persist().await;\n\ntest_table.table.greeting = \"Hello my dear friend!\".to_string();\ntest_table.table.year = 2012;\ntest_table.persist().await;\n\nlet history = test_table.get_history(50).await;\n\nprintln!(\"{:?}\", history);\n// [\n//     TestTable { greeting: 'Hello my dear friend!', year: 2012 }\n//     TestTable { greeting: 'Ola amigo!', year: 1990 }\n//     TestTable { greeting: 'Oi', year: 2022 }\n//     TestTable { greeting: 'E ae!!!', year: 1990 }\n//     TestTable { greeting: 'Hi', year: 1999 }\n//     ...\n// ]\n```\n\nThis can be useful when the application needs to fetch a list of things, such as messages.\n\n### Create User Account\n\nThis is a default database feature that allows you to create user accounts within the database. As these are hashed accounts, the only data required is: Username and Password. This data is hashed, that is, only the user with the correct data can access the data.\n\nIt is not possible to recover an account in which the user has forgotten access data.\n\n```rs\nlet user_name = \"wenderson.fake\";\nlet user_pass = \"1234\";\n\n// Check if the given name is already in use\nlet user_name_taken = db.check_user_name(\u0026user_name).await;\nif !user_name_taken.success {\n\n    // user name | password | units (optional) | password hint (optional - may be used in the future versions)\n    let user = db\n        .create_user_account(user_name, user_pass, Some(2), None)\n        .await;\n\n    println!(\"{:?}\", user.data.unwrap());\n    // SignedUserAccount {\n    //     id: \"b2e4e7c15f733d8c18836ffd22051ed855226d9041fb9452f17f498fc2bcbce3\",\n    //     user_name: \"wenderson.fake\",\n    //     units: 2\n    // }\n}\n```\n\n### Get User Account Info\n\nThis feature can be used for the \"Login/Sign In\" action.\n\n```rs\nlet user_name = \"wenderson.fake\";\nlet user_pass = \"1234\";\n\nlet user = db.get_user_account(\u0026user_name, user_pass).await;\nprintln!(\"{:?}\", user.data.unwrap());\n// SignedUserAccount {\n//     id: \"b2e4e7c15f733d8c18836ffd22051ed855226d9041fb9452f17f498fc2bcbce3\",\n//     user_name: \"wenderson.fake\",\n//     units: 2\n// }\n```\n\n### Get User Account Info By User Id\n\nJust another way to fetch the user info.\n\n```rs\nlet wenderson_id = \"b2e4e7c15f733d8c18836ffd22051ed855226d9041fb9452f17f498fc2bcbce3\";\nlet user = db.get_user_account_by_id(\u0026wenderson_id).await;\n\nprintln!(\"{:?}\", user.data.unwrap());\n// SignedUserAccount {\n//     id: \"b2e4e7c15f733d8c18836ffd22051ed855226d9041fb9452f17f498fc2bcbce3\",\n//     user_name: \"wenderson.fake\",\n//     units: 2\n// }\n```\n\n### Transfer Units Between Two Users\n\nAs said before, `unit` property present in each user's account can be anything the project wants, it can be a type of currency, item, resource.\n\nBelow is an example of user `wenderson` trying to send 2 units to `suly`:\n\n```rs\nlet wenderson_id = \"b2e4e7c15f733d8c18836ffd22051ed855226d9041fb9452f17f498fc2bcbce3\";\nlet suly_id = \"136c406933d98e5c8bb4820f5145869bb5ad40647b768de4e9adb2a52d0dea2f\";\n\nlet wenderson_data_opt = db.get_user_account_by_id(\u0026wenderson_id).await;\nlet wenderson_data = wenderson_data_opt.data.unwrap();\nlet units_to_transfer = 2;\n\nif wenderson_data.units \u003e= units_to_transfer {\n    let res = db.transfer_units(\u0026wenderson_id, \u0026suly_id, units_to_transfer).await;\n    println!(\"{:?}\", res.success);\n    // true / false\n}\n```\n\n### Fetching the Latest Units Transfer Record\n\nUse this feature to get the last unit transfer record involving a user.\n\n```rs\nlet wenderson_id = \"b2e4e7c15f733d8c18836ffd22051ed855226d9041fb9452f17f498fc2bcbce3\";\nlet last_units_transference_record = db.get_transfer_by_user_id(\u0026wenderson_id).await;\n\nprintln!(\"{:?}\", last_units_transference_record.data.unwrap());\n// TransferUnitsRegistry {\n//     from: \"b2e4e7c15f733d8c18836ffd22051ed855226d9041fb9452f17f498fc2bcbce3\",\n//     to: \"136c406933d98e5c8bb4820f5145869bb5ad40647b768de4e9adb2a52d0dea2f\",\n//     units: 2\n// }\n```\n\n### Fetching All the Transfer of Units Records\n\nUse this feature to get the last unit transfer record involving a user.\n\n```rs\nlet wenderson_id = \"b2e4e7c15f733d8c18836ffd22051ed855226d9041fb9452f17f498fc2bcbce3\";\nlet all_units_transfers_record = db.get_all_transfers_by_user_id(\u0026wenderson_id).await;\n\nprintln!(\"{:?}\", all_units_transfers_record.data.unwrap());\n// [\n//    TransferUnitsRegistry {\n//        from: \"b2e4e7c15f733d8c18836ffd22051ed855226d9041fb9452f17f498fc2bcbce3\",\n//        to: \"136c406933d98e5c8bb4820f5145869bb5ad40647b768de4e9adb2a52d0dea2f\",\n//        units: 2\n//    },\n//    TransferUnitsRegistry {\n//        from: \"b2e4e7c15f733d8c18836ffd22051ed855226d9041fb9452f17f498fc2bcbce3\",\n//        to: \"136c406933d98e5c8bb4820f5145869bb5ad40647b768de4e9adb2a52d0dea2f\",\n//        units: 2\n//    }\n// ]\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwpdas%2Fchain-db-rs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwpdas%2Fchain-db-rs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwpdas%2Fchain-db-rs/lists"}