{"id":13523934,"url":"https://github.com/icopen/lightic","last_synced_at":"2025-04-01T01:33:51.471Z","repository":{"id":156311808,"uuid":"617902914","full_name":"icopen/lightic","owner":"icopen","description":null,"archived":false,"fork":false,"pushed_at":"2023-08-15T20:26:55.000Z","size":729,"stargazers_count":13,"open_issues_count":2,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-11-02T08:31:37.716Z","etag":null,"topics":["internet-computer"],"latest_commit_sha":null,"homepage":"","language":"Rust","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/icopen.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}},"created_at":"2023-03-23T10:59:03.000Z","updated_at":"2023-09-22T21:26:00.000Z","dependencies_parsed_at":"2024-01-13T22:31:38.465Z","dependency_job_id":"5a6e4feb-077e-4dc7-9c0c-80e2af9c4cb1","html_url":"https://github.com/icopen/lightic","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/icopen%2Flightic","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/icopen%2Flightic/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/icopen%2Flightic/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/icopen%2Flightic/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/icopen","download_url":"https://codeload.github.com/icopen/lightic/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246567548,"owners_count":20798193,"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":["internet-computer"],"created_at":"2024-08-01T06:01:05.246Z","updated_at":"2025-04-01T01:33:46.462Z","avatar_url":"https://github.com/icopen.png","language":"Rust","funding_links":[],"categories":["Developer Tooling"],"sub_categories":["Testing"],"readme":"# Project Description - Light Replica\n\nEthereum and other EVM chains benefit from frameworks such as truffle or hardhat. They enable easy and fast creation, testing and deployment of solutions to EVM based chains. Their strength lies in usage of JS scripts to do everything: setup local node, make tests, make deployments and more.\n“Light Replica” is a project to startup creation of similar tool for the Internet Computer ecosystem. It will be composed from two elements:\n\nLight Node - it is a local node designed for development (fast startup and cleanup), it will replicate behavior of the real node with additional logging and functions to help testing. It will be able to run and interact with any IC compatible wasm file.\nLight Runner/Cli - a set of libraries written in JS (available in npm) that can be used in node.js environment to create and build projects, write tests, create deployments and arbitrary scripts that have access to project “context” right from the js code.\n\nBoth tools are aimed at developers. To help them efficiently develop, test and deploy canisters to the IC.\n\n\nThe replica mock is run directly in node.js environment (also works with all browsers that support WASM) and enables you to deploy and test and wasm file that is compatible with Internet Computer reference\n\nIt can also be used as a local development replica (started by dfx start) replacement\n\n# How to start using, examples\n\n```\nnpm i lightic\n```\n\nFirst you need to choose the js testing framework of your preference, it could be: mocha, jest, vitest or any other.\n\nFor the mocha, you can check the examples in the folder tests\n\n## Mocha tests setup\n\n```\nnpm i     @types/mocha @types/node typescript mocha chai ts-node\n```\n\nAnd create .mochars.json with content\n\n```JSON\n// This config file contains Mocha's defaults.\n// This same configuration could be provided in the `mocha` property of your\n// project's `package.json`.\n{\n    \"diff\": true,\n    \"extension\": [\"js\", \"cjs\", \"mjs\", \"ts\"],\n    \"package\": \"./package.json\",\n    \"reporter\": \"spec\",\n    \"slow\": \"75\",\n    \"timeout\": \"2000\",\n    \"ui\": \"bdd\",\n    \"watch-files\": [\"lib/**/*.js\", \"test/**/*.ts\"],\n    \"watch-ignore\": [\"lib/vendor\"],\n    \"loader\": \"ts-node/esm\"\n  }\n```\n\n## Simple test\n\nIn order to actually test your canister, you need to add to your test file\n\n```TS\nimport { TestContext, u64IntoPrincipalId } from 'lightic'\n\nconst context = new TestContext()\nThis will create a context to run tests, it is a harness that gives you a possibility to install and run canisters\n\nconst canister = await context.deploy('./dfx/local/canisters/example/example.wasm')\nconst caller = u64IntoPrincipalId(0n)\nconst actor = Actor.createActor(canister.getIdlBuilder(), {\n  agent: context.getAgent(caller),\n  canisterId: canister.get_id()\n})\n\n```\n\n1. As you can see this works with a wasm file, so you need to first compile the project using dfx.\n```\ndfx canister build $CANISTER_NAME\n```\n\nIn the future the test harness will also take care of compilation.\n\n2. You also need to specify the identity principle (who is calling the canisters) and create an actor. There is a helper function `u64IntoPrincipalId` that creates a Principle based on supplied number, so you do not need to come up with fake principals. The created principal is not random.\n\n3. Then you get an actor, which is the same type as regular dfinity actor. In this example the actual actor class from @dfinity package is used\n\n4. In order to call canister:\n\n```TS\nconst result = await actor.test_caller()\n```\n\nReplace `test_caller()` with a function from you canister\n\n\n\n## How to deploy Ledger canister in one step\n\nLightic comes with builtin `LedgerHelper` that can download and deploy ledger canister. In order to start using ledger:\n\n```\n  const minter = u64IntoPrincipalId(0n);\n  const owner = u64IntoPrincipalId(1n);\n  const ledgerCanister = await LedgerHelper.defaults(context, minter, owner)\n```\n\nNow you can call ledger both from agent and from other deployed canisters. If possible this will deploy ledger with the same principal as it is found in IC `ryjl3-tyaaa-aaaaa-aaaba-cai`\n\n\nNext call account_balance to check if the owner, has some ICP in its account\n\n```\n  const balance = await ledgerCanister.balanceOf(minter)\n```\n\nIf you need an account number from your principal there is a helper function `getAccount` the will do just that\n\n\n## How to unit test your canisters\n\n\nYou can find examples of lightic used for testing canisters here: [https://github.com/icopen/evm_utils_ic/blob/master/__tests__/_common.mjs]. More examples to come.\n\n## HTTP Replica Endpoint\nIt is possible to launch lightic in a standalone mode and call it from DFX or any other script that can work with DFX or mainnet. In order to do so:\n\n```\n    npx lightic --p port\n```\n\nWhere port is the desired TCP port on which the lightic should listen.\n\n# Building\n\nMost of the project was written in Type Script. \n\n\n## Candid Util\n\nUtil that can parse Candid compliant data and output it as a JSON formatted string\n\n```\ncd candid_util\nwasm-pack build --target nodejs\n```\n\n\n## Specification test canister\n\nCanister that uses some of the most common features of the IC, used for testing the mock replica\n\n```\ncd spec_test\ncargo build --release --target wasm32-unknown-unknown\n```\n\n\n## Whole Package\n\n```\nyarn prePublish\n```\n\n\n# What is Implemented\n\n## IC0 Implementation\nBelow is a list of IC0 functions exposed to WASM module on IC environment. Not all calls will be implemented as part of this project.\n\n- [x] - msg_arg_data_size\n- [x] - msg_arg_data_copy\n- [x] - msg_caller_size\n- [x] - msg_caller_copy\n- [x] - msg_reject_code\n- [x] - msg_reject_msg_size\n- [x] - msg_reject_msg_copy\n- [x] - msg_reply_data_append\n- [x] - msg_reply\n- [x] - msg_reject\n- [ ] - msg_cycles_available\n- [ ] - msg_cycles_available128\n- [ ] - msg_cycles_refunded\n- [ ] - msg_cycles_refunded128\n- [x] - msg_cycles_accept\n- [ ] - msg_cycles_accept128\n- [x] - canister_self_size\n- [x] - canister_self_copy\n- [x] - canister_cycle_balance\n- [ ] - canister_cycle_balance128\n- [ ] - canister_status\n- [ ] - canister_version\n- [ ] - msg_method_name_size\n- [ ] - msg_method_name_copy\n- [ ] - accept_message\n- [x] - call_new\n- [ ] - call_on_cleanup\n- [x] - call_data_append\n- [x] - call_cycles_add\n- [ ] - call_cycles_add128\n- [x] - call_perform\n- [x] - stable_size\n- [x] - stable_grow\n- [x] - stable_write\n- [x] - stable_read\n- [x] - stable64_size\n- [ ] - stable64_grow\n- [ ] - stable64_write\n- [ ] - stable64_read\n- [x] - certified_data_set\n- [ ] - data_certificate_present\n- [ ] - data_certificate_size\n- [ ] - data_certificate_copy\n- [x] - time\n- [x] - global_timer_set\n- [x] - performance_counter\n- [x] - debug_print\n- [x] - trap\n\n## Not documented but still relevant\n- [x] - mint_cycles\n\n## Management canister functions\n- [x] - create_canister\n- [ ] - update_settings\n- [x] - install_code\n- [ ] - uninstall_code\n- [ ] - canister_status\n- [ ] - stop_canister\n- [ ] - start_canisters\n- [ ] - delete_canister\n- [ ] - deposit_cycles\n- [x] - raw_rand\n- [ ] - ecdsa_public_key\n- [ ] - sign_with_ecdsa\n- [ ] - http_request\n- [x] - provisional_create_canister_with_cycles\n- [ ] - provisional_top_up_canister\n\n# TODO\n- [x] - Candid utils WASM-WASI module\n- [x] - WASM Module Loading\n- [x] - Assignment of Canister ID upon canister creation\n- [x] - Support for canister provided Candid Specs\n- [x] - Mocha/Jest integration\n- [x] - Canister Memory Rollback\n- [x] - Update call support\n- [x] - Stable Memory support\n- [x] - BLS Signatures\n- [x] - HTTP Server Implementation\n- [x] - npmjs package with helpers and runners\n\n\n# Further work\n- [ ] - Compatibility and cooperation with dfx\n- [ ] - Backup of wasm memory (normal and stable) for faster development cycles\n- [ ] - Log of all calls\n- [ ] - Support for other environments: local/dfx, production\n- [ ] - Cycles usage counting per every call\n- [ ] - Mocking of messages (ingress, egress and xnet)\n- [ ] - Support for canister upgrades (preupgrade and postupgrade)\n- [ ] - Limit cycle usage on calls\n- [ ] - Limit message size to subnet settings, allow for different subnet settings\n- [ ] - Support for multiple subnets\n- [ ] - Full compliance ic-ref-test [https://github.com/dfinity/ic-hs#ic-ref-test-an-acceptance-test-suite]\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ficopen%2Flightic","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ficopen%2Flightic","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ficopen%2Flightic/lists"}