{"id":19070864,"url":"https://github.com/ohager/signum-smartc-testbed-starter","last_synced_at":"2026-01-03T09:34:01.810Z","repository":{"id":199497200,"uuid":"702705679","full_name":"ohager/signum-smartc-testbed-starter","owner":"ohager","description":"Starter Project for developing Signum Smart Contracts with SmartC using TDD ","archived":false,"fork":false,"pushed_at":"2024-05-18T14:37:32.000Z","size":81,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-01-24T06:23:35.930Z","etag":null,"topics":["signum","signum-network","smart-contracts","smartc","web3"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ohager.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":"2023-10-09T20:56:35.000Z","updated_at":"2024-05-18T14:37:36.000Z","dependencies_parsed_at":null,"dependency_job_id":"5a92fd18-e696-4c01-bf38-7a1592c80051","html_url":"https://github.com/ohager/signum-smartc-testbed-starter","commit_stats":null,"previous_names":["ohager/signum-smartc-testbed-starter"],"tags_count":0,"template":true,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ohager%2Fsignum-smartc-testbed-starter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ohager%2Fsignum-smartc-testbed-starter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ohager%2Fsignum-smartc-testbed-starter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ohager%2Fsignum-smartc-testbed-starter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ohager","download_url":"https://codeload.github.com/ohager/signum-smartc-testbed-starter/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244094272,"owners_count":20397020,"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":["signum","signum-network","smart-contracts","smartc","web3"],"created_at":"2024-11-09T01:21:03.958Z","updated_at":"2026-01-03T09:33:56.778Z","avatar_url":"https://github.com/ohager.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# signum-smartc-testbed-starter\n\nStarter Project for developing Signum Smart Contracts with [SmartC](https://github.com/deleterium/SmartC) using TDD\n\n\u003e Note: this project is still in an early development phase, but used for real world projects already. There might be changes in the interface, but the basic functionality is pretty stable already.\n\n## Motivation\n\nDeveloping Smart Contracts requires some additional caution, as 1) contracts cannot be changed once in production, 2) can involve significant costs when something fails.\nThe [SmartC Simulator](https://deleterium.info/sc-simulator/) is a great environment to test and debug Smart Contracts, but it is very time-consuming to test all possible execution paths on the visual environment.\nThis can cause testing fatigue and lead to erroneous code. Applying [TDD](https://en.wikipedia.org/wiki/Test-driven_development) technique can come to help here. \nAs of my own experience, the contracts testing coverage is higher and even the development itself is faster. \n\nThis project shall help Smart Contract Developer to set up a TDD testbed quickly, such s/he can focus on the contract implementation.\n\n## Prerequisites\n\nHaving [NodeJS](https://nodejs.org/en/download) 18+ installed\n\nIt's recommended to use `nvm` to install/manage different NodeJS versions on your computer.\n\n- Windows: https://github.com/coreybutler/nvm-windows\n- Linux/MacOS: https://github.com/nvm-sh/nvm\n\n\n## How does it work?\n\nThis project uses the [Signum SmartC Testbed](https://github.com/ohager/signum-smartc-testbed) package and [Vitest Test Runner](https://vitest.dev/).\nThe Testbed uses the isolated [SmartC Simulator](https://www.npmjs.com/package/smartc-signum-simulator) under the hood. \nUsing the testbed, one can load a contract, initialize it and entirely interact with it (see [Testbed API](https://ohager.github.io/signum-smartc-testbed/index.html)).\nThe testbed simulates all blockchain transactions, gives access to internal data structures (memory stack, maps etc) of the contract and complete control over \nthe entire environment - __No own Blockchain Node needed, no costs involved__.   \n\nNote, that it's not possible (yet) to debug the SmartC code directly (use the [SmartC Simulator](https://deleterium.info/sc-simulator/) instead)   \n\n## How to use?\n\nUse this project either as a template for your own github repository. Or use `tiged` (or `degit`) to create a unversioned local copy\n\n`npx tiged git@github.com:ohager/signum-smartc-testbed-starter.git \u003cyour-project-folder\u003e`\n\nThen go into `\u003cyour-project-folder\u003e` and run `npm install` to set up all dependencies.\n\nRunning `npm test` should run the test suite for the `sample-contract` and you should see something like this:\n\n```\n$ npm t\n\n\u003e signum-smartc-testbed-starter@1.0.0 test\n\u003e vitest run --single-thread\n\n\n RUN  v0.34.6 /home/ohager/code/signum/signum-smartc-testbed-starter\n\nstdout | sample-contract/update-percentage/update-percentage.test.ts \u003e Sample Contract - Update Percentage \u003e should update percentage as expected\nC contract successfully compiled and deployed with id 999 on slot 0. Ready to run\nBlock #2 forged!\nBlock #3 forged!\nBlock #4 forged!\nBlock #5 forged!\nBlock #6 forged!\n\nstdout | sample-contract/update-percentage/update-percentage.test.ts \u003e Sample Contract - Update Percentage \u003e should not update percentage as sender is not creator\nC contract successfully compiled and deployed with id 999 on slot 0. Ready to run\nBlock #2 forged!\nBlock #3 forged!\nBlock #4 forged!\nBlock #5 forged!\nBlock #6 forged!\n\n...\n\nstdout | sample-contract/set-map-value/set-map-value.test.ts \u003e Sample Contract - Set Map Value \u003e should set map values as expected\nC contract successfully compiled and deployed with id 999 on slot 0. Ready to run\nBlock #2 forged!\nBlock #3 forged!\nBlock #4 forged!\nBlock #5 forged!\nBlock #6 forged!\nBlock #7 forged!\nBlock #8 forged!\n\n ✓ sample-contract/update-percentage/update-percentage.test.ts (2)\n ✓ sample-contract/pull-funds/pull-funds.test.ts (2)\n ✓ sample-contract/forward-percentage/forward-percentage.test.ts (4)\n ✓ sample-contract/set-map-value/set-map-value.test.ts (1)\n\n Test Files  4 passed (4)\n      Tests  9 passed (9)\n   Start at  09:41:01\n   Duration  1.31s (transform 73ms, setup 0ms, collect 759ms, tests 248ms, environment 0ms, prepare 100ms)\n```\n\nYou are set up!\n\n### Project Structure\n\n```\n├── package.json\n├── package-lock.json\n├── README.md\n├── sample-contract\n│   ├── context.ts\n│   ├── CONTRACT_API.md\n│   ├── forward-percentage\n│   │   ├── forward-percentage.scenarios.ts\n│   │   └── forward-percentage.test.ts\n│   ├── pull-funds\n│   │   ├── pull-funds.scenarios.ts\n│   │   └── pull-funds.test.ts\n│   ├── sample-contract.smart.c\n│   ├── set-map-value\n│   │   ├── set-map-value.scenarios.ts\n│   │   └── set-map-value.test.ts\n│   └── update-percentage\n│       ├── update-percentage.scenarios.ts\n│       └── update-percentage.test.ts\n├── tsconfig.json\n└── vitest.config.ts\n```\n\nAs of my own experience it seems to be a good practice to keep a folder per smart contract, here: `sample-contract`.\nI often have contracts with multiple functionality, which are split into methods. As per TDD practice I test each method \nin an isolated manner, i.e. here per folder.\n\nInside a contracts folder you should have:\n\n- the contract itself, here: `sample-contract.smart.c`\n- a markdown file to describe the API of a contract, here: `CONTRACT_API.md` \n- a file with contracts constants, like account numbers, method Ids, Map Ids, etc, here: `context.ts`\n- a folder per function, which has the scenarios (in form of JSONs) defined, and the test suite itself, example here: `set-map-value`\n\n\n### How to debug\n\nWith VSCode or WebStorm it's pretty straightforward. Inside your test suite set break points and run the test in Debug Mode. You should then get access\nto all internal variables.\n\n![image](https://github.com/ohager/signum-smartc-testbed-starter/assets/3920663/0b3e54f6-8e60-4768-8830-7521af04ad12)\n\n\u003e Note: If you want to debug the SmartC Code itself, you need to use the SmartC Simulator IDE. It's not possible to debug the contract within the IDEs (yet).\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fohager%2Fsignum-smartc-testbed-starter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fohager%2Fsignum-smartc-testbed-starter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fohager%2Fsignum-smartc-testbed-starter/lists"}