{"id":19747492,"url":"https://github.com/phantasma-io/tomb","last_synced_at":"2026-05-13T18:12:55.296Z","repository":{"id":237344340,"uuid":"770322175","full_name":"phantasma-io/TOMB","owner":"phantasma-io","description":"TOMB smart contract compiler for Phantasma platform","archived":false,"fork":false,"pushed_at":"2024-03-11T10:58:38.000Z","size":905,"stargazers_count":0,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-01-10T21:09:07.949Z","etag":null,"topics":["blockchain","compiler","crypto","layer1","phantasma","phantasmachain","phantasmaio","smartcontract-language","smartcontracts","smartnft","smartnfts","solidity","tomb","tombsmartcontracts"],"latest_commit_sha":null,"homepage":"","language":"C#","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/phantasma-io.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":"2024-03-11T10:58:24.000Z","updated_at":"2024-03-11T12:10:56.000Z","dependencies_parsed_at":"2024-05-01T00:54:56.415Z","dependency_job_id":null,"html_url":"https://github.com/phantasma-io/TOMB","commit_stats":null,"previous_names":["phantasma-io/tomb"],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phantasma-io%2FTOMB","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phantasma-io%2FTOMB/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phantasma-io%2FTOMB/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phantasma-io%2FTOMB/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/phantasma-io","download_url":"https://codeload.github.com/phantasma-io/TOMB/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241078480,"owners_count":19905866,"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":["blockchain","compiler","crypto","layer1","phantasma","phantasmachain","phantasmaio","smartcontract-language","smartcontracts","smartnft","smartnfts","solidity","tomb","tombsmartcontracts"],"created_at":"2024-11-12T02:18:00.182Z","updated_at":"2026-05-13T18:12:55.290Z","avatar_url":"https://github.com/phantasma-io.png","language":"C#","funding_links":[],"categories":[],"sub_categories":[],"readme":"# TOMB\n\nTOMB is the Phantasma smart-contract compiler.\n\n- Repository name: `TOMB`\n- Current CLI executable name: `pha-tomb`\n- Target VM: Phantasma VM\n- Source files: `.tomb`\n\n## Requirements\n\nThe current NuGet tool package is built for `net10.0`. Install the .NET 10 SDK before using `dotnet tool install` or `dotnet tool update`.\n\nCheck the SDK selected by your shell:\n\n```bash\ndotnet --version\n```\n\nThe command should resolve to a `10.x` SDK. If it resolves to `9.x`, the tool install can fail with a misleading `DotnetToolSettings.xml` error because the package only contains the `net10.0` tool layout.\n\n## CLI Usage\n\nInstall `pha-tomb` as a .NET global tool:\n\n```bash\ndotnet tool install --global pha-tomb\ndotnet tool update --global pha-tomb\n```\n\nThen invoke it with the source file as the last argument.\n\n```bash\npha-tomb my_contract.tomb\n```\n\nUseful commands:\n\n```bash\npha-tomb --version\npha-tomb --help\npha-tomb output:/tmp/build protocol:19 debug nativecheck:error my_contract.tomb\n```\n\n### CLI\n\n```text\npha-tomb \u003coptions\u003e \u003csource-file\u003e\n```\n\n| Argument | Description |\n| -------- | ----------- |\n| `--version`, `-v`, `version` | Print the compiler version only. |\n| `--help`, `-h`, `help` | Print CLI help. |\n| `output:\u003cdirectory\u003e` | Output root. Artifacts go into `Output/` under this directory. |\n| `protocol:\u003cnumber\u003e` | Target protocol version. If omitted, the compiler uses the latest known protocol from the referenced Phantasma packages. |\n| `libpath:\u003cdirectory\u003e` | Additional ABI search path. Can be specified multiple times. |\n| `debug` | Enable debug mode and emit debug artifacts when available. |\n| `nativecheck:\u003coff|warn|error\u003e` | Check native-contract and interop usage against the compiler's pinned Carbon snapshots. |\n\n### Output Rules\n\n- The source file must be the last CLI argument.\n- If `output:\u003cdirectory\u003e` is omitted, the compiler uses the source file directory as the output root.\n- Artifacts are always written to `Output/` under the selected output root.\n- The CLI automatically adds that output directory to the ABI import search paths, so modules compiled in the same pass can be imported by ABI.\n- Unknown options are reported as warnings.\n- Compile-time errors exit with a non-zero status.\n\n## Generated Artifacts\n\nThe compiler emits artifacts per module:\n\n| Artifact | When emitted |\n| -------- | ------------ |\n| `.asm` | When textual assembly is generated for the module. |\n| `.pvm` | For contract, token, NFT submodule, and description modules. |\n| `.tx` | For script modules. |\n| `.abi` | When ABI metadata exists for the module. |\n| `.debug` | When debug info exists for the module. |\n| `.pvm.hex`, `.tx.hex` | Hex-encoded script output for `.pvm` / `.tx`. |\n| `.abi.hex` | Hex-encoded ABI payload. |\n\nNested NFT token submodules are exported as separate artifacts together with the parent token module.\n\n## Publishing\n\nTo publish a new `pha-tomb` package locally:\n\n```bash\nNUGET_API_KEY=... just publish-nuget\n```\n\n## Source Language\n\nTOMB source files use the `.tomb` extension.\n\n## Declarations\n\nTop-level declarations:\n\n- `contract`\n- `token`\n- `script`\n- `description`\n- `struct`\n- `enum`\n- `const`\n\nNested declarations:\n\n- `nft\u003crom, ram\u003e` submodules inside `token`\n- `property`\n- `event`\n- `constructor`\n- `trigger`\n- `task`\n- `register`\n\n### Triggers\n\nThe parser accepts only the trigger names and signatures implemented in `TombLangCompiler`.\n\n| Trigger name | Signature | Status |\n| ------------ | --------- | ------ |\n| `onMint`, `onBurn`, `onSend`, `onReceive`, `onInfuse` | `(from:address, to:address, symbol:string, amount:number)` | Compiler support exists. Chain support may vary. |\n| `onWitness`, `onSeries`, `onKill`, `onUpgrade` | `(from:address)` | Compiler support exists. Chain support may vary. |\n| `onMigrate` | `(from:address, to:address)` | Supported by the compiler. |\n| `onWrite` | `(from:address, data:any)` | Supported by the compiler. |\n| Any other trigger name | n/a | Not supported. |\n\nNotes:\n\n- Trigger names may be written with or without the `on` prefix.\n- `break` and `continue` inside triggers are not supported.\n\n## Feature Status\n\n### Supported\n\n- Constants, enums, structs, global and local variables\n- Contract methods, properties, constructors, events, triggers\n- Script and description modules\n- Nested NFT modules inside token modules\n- Numbers, strings, bools, timestamps, addresses, hashes, byte arrays\n- Maps, lists, arrays, generic types, type inference\n- `if`, `while`, `do/while`, `for`, `switch`, `break`, `continue`\n- Exceptions via `throw`\n- Multi-return methods using `: type*`\n- Inline assembly blocks\n- External contract calls and interop calls\n- ABI generation\n- Debug artifact generation\n- Postfix `++` and `--`\n\n### Partially Supported\n\n- Native contract and interop calls, because the compiler accepts more than the current Carbon runtime exposes\n- Array helper library\n- Builtin random helpers\n\n### Important Caveats\n\n- Explicit register allocation syntax still exists, but it is known to be broken because of `CALL` frame allocation. Treat it as unsupported.\n- Task syntax is parsed by the compiler, but the current Carbon runtime does not expose the required `Task.*` interops. Treat tasks as unsupported on the current chain baseline.\n- `Array.pop()` currently returns the last element without mutating the backing array, because the current Phoenix VM opcode set does not expose array-key removal.\n\n## Libraries\n\n### Importable Libraries\n\nThese libraries can be imported directly:\n\n- `Call`\n- `Runtime`\n- `Math`\n- `Token`\n- `NFT`\n- `Organization`\n- `Oracle`\n- `Storage`\n- `Contract`\n- `Array`\n- `Leaderboard`\n- `Market`\n- `Account`\n- `Crowdsale`\n- `Stake`\n- `Governance`\n- `Relay`\n- `Mail`\n- `Time`\n- `Task`\n- `UID`\n- `Map`\n- `List`\n- `String`\n- `Bytes`\n- `Decimal`\n- `Enum`\n- `Address`\n- `Module`\n- `Format`\n\n### Auto-Imported Libraries\n\nThese libraries are imported automatically in every module:\n\n- `String`\n- `Bytes`\n- `Decimal`\n- `Enum`\n\n### Additional Helpers\n\nThe compiler also has a few special-case libraries and helpers outside the main import list:\n\n- `Random`\n- `Chain`\n- `Platform`\n- `Cryptography`\n- per-struct constructor helpers\n\n### Current Library Caveats\n\n- `Format` is only valid in `description` modules.\n- `Math.sqrt`, `String.toUpper`, `String.toLower`, `String.indexOf`, `Random.seed`, and `Random.generate` are builtin helpers compiled from embedded builtin TOMB code.\n- `Address.isNull`, `Address.isUser`, `Address.isSystem`, and `Address.isInterop` are not supported. They compile to explicit runtime `THROW`.\n- `Array.set`, `Array.remove`, and `Array.clear` are not supported. They compile to explicit runtime `THROW`.\n- `Struct.fromBytes` is not supported. It compiles to explicit runtime `THROW`.\n- `Token.create` uses the signature `Token.create(from:Address, script:Bytes, abiBytes:Bytes)`.\n- `Runtime.deployContract` and `Runtime.upgradeContract` accept `Module` values, not raw `(script, abi)` argument pairs.\n\n### Runtime Availability\n\nThe compiler can parse calls that the current Carbon runtime still does not expose.\n\n`nativecheck:\u003coff|warn|error\u003e` checks:\n\n- native contract calls against `Library/src/Validation/NativeMethodAvailability.cs`\n- interops against `Library/src/Validation/InteropMethodAvailability.cs`\n\nFor real contracts, use `nativecheck:error`.\n\nExamples that are not available on the current Carbon baseline:\n\n- `Task.*`\n- `Oracle.*`\n- `Organization.*`\n- `Contract.exists`\n- `Runtime.transactionHash`\n- `Runtime.getGovernanceValue`\n- `Token.isMinter`\n- `Token.swap`\n- `Token.write`\n- `Token.getCurrentSupply`\n- `Token.availableSymbols`\n- `NFT.write`\n- `NFT.availableSymbols`\n\nSome advanced methods in `Stake`, `Account`, `Relay`, `Market`, `Crowdsale`, `Mail`, and `Storage` are only partially available. Use `nativecheck:error` to catch exact mismatches against the compiler's pinned runtime snapshots.\n\n## Macros\n\nBuiltin compiler macros handled by `MacroExpression`:\n\n- `$THIS_ADDRESS`\n- `$THIS_SYMBOL`\n- `$TYPE_OF(...)`\n\nNotes:\n\n- `$THIS_SYMBOL` is only available inside token context.\n- The compiler also registers per-module macros such as `\u003cCONTRACT_NAME\u003e_ADDRESS`.\n- Token modules also register `\u003cTOKEN_SYMBOL\u003e_SYMBOL`.\n- Literal token properties are also exposed as macros of the form `\u003cTOKEN_NAME\u003e_\u003cproperty\u003e`.\n- Host applications embedding the compiler can register additional macros through `Compiler.RegisterMacro(...)`.\n\n## Importing External ABIs\n\n`libpath:\u003cdirectory\u003e` adds an ABI search root.\n\nExternal library imports are resolved as:\n\n```text\n\u003clibpath\u003e/\u003cimport-name-with-dots-replaced-by-path-separators\u003e.abi\n```\n\nFor example, with:\n\n```bash\npha-tomb libpath:/opt/phantasma/abi my_contract.tomb\n```\n\nan import such as:\n\n```csharp\nimport Foo.Bar;\n```\n\nis resolved from:\n\n```text\n/opt/phantasma/abi/Foo/Bar.abi\n```\n\nThe CLI also adds the current output directory to the ABI lookup paths automatically.\n\n## Minimal Examples\n\nThese are small examples that use the current syntax.\n\n### Simple Contract\n\n```csharp\ncontract hello {\n\timport Runtime;\n\n\tpublic ping(from:address): number {\n\t\tRuntime.expect(Runtime.isWitness(from), \"witness failed\");\n\t\tRuntime.log(\"ping\");\n\t\treturn 1;\n\t}\n}\n```\n\n### Deploying A Contract Module\n\n```csharp\ncontract sample_contract {\n\tpublic hello(): number {\n\t\treturn 1;\n\t}\n}\n\nscript deploy_sample {\n\timport Runtime;\n\n\tcode(from:address) {\n\t\tRuntime.deployContract(from, sample_contract);\n\t}\n}\n```\n\n### Creating A Token With The Current Signature\n\n```csharp\ntoken GHOST {\n\tproperty name:string = \"Ghost\";\n}\n\nscript create_token {\n\timport Token;\n\timport Module;\n\n\tcode(from:address) {\n\t\tToken.create(from, Module.getScript(GHOST), Module.getABI(GHOST));\n\t}\n}\n```\n\n## Builtins\n\nTOMB includes builtin methods implemented as embedded TOMB code, compiled into assembly, and injected during compilation.\n\nCurrent builtin methods in this repository:\n\n- `Math.sqrt`\n- `String.toUpper`\n- `String.toLower`\n- `String.indexOf`\n- `Random.seed`\n- `Random.generate`\n\nIf you extend builtins locally, update the builtin source and the embedded builtin assembly together.\n\n## More Documentation\n\nAdditional Phantasma smart-contract documentation:\n\n- \u003chttps://phantasma.gitbook.io/main/development/tomb-lang\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fphantasma-io%2Ftomb","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fphantasma-io%2Ftomb","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fphantasma-io%2Ftomb/lists"}