{"id":13425627,"url":"https://github.com/hone-labs/aqua-compiler","last_synced_at":"2025-03-15T20:30:50.296Z","repository":{"id":178761509,"uuid":"406607676","full_name":"hone-labs/aqua-compiler","owner":"hone-labs","description":"An expressive high level language for the Algorand block chain that compiles to TEAL code.","archived":false,"fork":false,"pushed_at":"2022-07-27T06:37:25.000Z","size":1151,"stargazers_count":2,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-04-12T15:05:20.563Z","etag":null,"topics":["algorand","blockchain","defi","smartcontract","teal"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","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/hone-labs.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":"2021-09-15T04:01:09.000Z","updated_at":"2023-02-10T12:45:03.000Z","dependencies_parsed_at":"2024-01-03T05:17:20.124Z","dependency_job_id":"a692e952-59d6-4921-8cca-e4ed723ebc35","html_url":"https://github.com/hone-labs/aqua-compiler","commit_stats":null,"previous_names":["hone-labs/aqua-compiler","optio-labs/aqua-compiler"],"tags_count":31,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hone-labs%2Faqua-compiler","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hone-labs%2Faqua-compiler/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hone-labs%2Faqua-compiler/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hone-labs%2Faqua-compiler/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hone-labs","download_url":"https://codeload.github.com/hone-labs/aqua-compiler/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243790938,"owners_count":20348378,"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":["algorand","blockchain","defi","smartcontract","teal"],"created_at":"2024-07-31T00:01:15.758Z","updated_at":"2025-03-15T20:30:50.290Z","avatar_url":"https://github.com/hone-labs.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Aqua-compiler\n\nAn expressive high level language for [the Algorand blockchain](https://en.wikipedia.org/wiki/Algorand) smart contracts that compiles to [TEAL](https://developer.algorand.org/docs/get-details/dapps/avm/teal/specification/) code.\n\nThis is a work in progress. Please report issues and help set the direction for this project.\n\n## Using the Aqua command\n\nDownload the latest executable for your platform from [the releases page](https://github.com/optio-labs/aqua-compiler/releases).\n\nAdd the executable to your path. If you are on MacOS or Linux you should rename the executable from `aqua-mac` or `aqua-linux` to just be called `aqua` (so the rest of the instructions make sense).\n\nYou can also install Aqua using npm:\n\n```bash\nnpm install -g aqua-compiler\n```\n\n## REPL\n\nRunning the executable with no arguments starts the REPL:\n\n```bash\naqua\n```\n\nYou can type Aqua expressions and statements at the REPL and see the TEAL code that is generated.\n\nTrying entering expressions at the REPL prompt:\n\n- `txn.Amount \u003e= 1000;`\n- `15 + txn.Amount \u003e= 1000;`\n- `txn.Amount \u003c= arg[0];`\n- `txn.Amount + arg[0] \u003e 1000 \u0026\u0026 arg[1] \u003e 30;`\n- `txn.Receiver == addr ABC123;`\n- `\"a string\" == txn.Something;`\n- `return 1+2;`\n\n\n## Compiling an Aqua file\n\nTo compile an Aqua file to TEAL code, input the Aqua filename:\n\n```bash\naqua my-smart-contract.aqua\n```\n\nThat prints the generated TEAL code to standard output.\n\nTypically you'll want to capture the TEAL code to a file (so you can run it against the blockchain):\n\n```bash\naqua my-smart-contact.aqua \u003e my-smart-contract.teal\n```\n\n## Examples of Aqua code\n\nSee the `examples` subdirectory for various examples of Aqua code.\n\n## Using the Aqua API\n\nYou can compile Aqua to TEAL code using Aqua's JavaScript/TypesScript API.\n\nFirst install Aqua in your Node.js project:\n\n```bash\nnpm install --save aqua-compiler\n```\n\nThen import Aqua's `compile` function:\n\n```javascript\nconst { compile } = require(\"aqua-compiler\");\n```\n\nOr in TypeScript:\n\n```typescript\nimport { compile } from \"aqua-compiler\";\n```\n\nNow use `compile` to compile Aqua to TEAL:\n\n```javascript\nconst aquaCode = \"return 1 + 2;\"\nconst tealCode = compiler(aquaCode);\nconsole.log(tealCode);\n```\n\n## Testing Aqua code with Jest\n\nOne reason why you might want to use Aqua's API is to enable automated testing.\n\nFor example, here's a Jest test that compiles Aqua to TEAL:\n\n```javascript\nimport { compile } from \"aqua-compiler\";\nimport { readFile } from \"fs/promises\";\n\ndescribe(\"My smart contract test suite\", () =\u003e {\n\n    test(\"My first test\", async () =\u003e {\n\n        const tealCode = await compileAquaFile(\"my-smart-contract.aqua\");\n\n        // ... test that you can execute teal code against your sandbox blockchain ...\n    });\n\n    // ... other tests go here ...\n\n});\n\n//\n// Loads and compiles an Aqua file.\n//\nasync function compileAquaFile(fileName) {\n    const fileContent = await readFile(join(tealPath, tealFileName), { encoding: \"utf8\" });\n    return compile(fileContent);\n}\n```\n\nAfter compiling an Aqua file to TEAL code you can then deploy that code against your sandbox Algorand blockchain.\n\nAnother way of testing that is faster and doesn't require having an actual Algorand node instance is to use [the TEAL interpreter](https://www.npmjs.com/package/teal-interpreter) to simulate the Algorand virtual machine.\n\nA Jest test that runs Aqua code against the TEAL interpreter might look like this:\n\n```javascript\nimport { compile } from \"aqua-compiler\";\nimport { readFile } from \"fs/promises\";\nimport { execute } from \"teal-interpreter\";\n\ndescribe(\"My smart contract test suite\", () =\u003e {\n\n    test(\"My first test\", async () =\u003e {\n\n        const config = {\n            // ... configure the initial state of the TEAL interpreter ...\n        }\n        const result = await executeAqua(\"my-smart-contract.aqua\", config);\n\n        // ... run expectations against the result to check that execution of the aqua code has expected results ...\n        \n    });\n\n    // ... other tests go here ...\n\n});\n\n//\n// Loads and compiles an Aqua file.\n//\nasync function compileAquaFile(fileName) {\n    const fileContent = await readFile(join(tealPath, tealFileName), { encoding: \"utf8\" });\n    return compile(fileContent);\n}\n\n//\n// Executes Aqua code against the TEAL interpreter.\n//\nasync function executeAqua(fileName, config) {\n    const tealCode = await compileAquaFile(fileName);\n    return await execute(tealCode, config);\n}\n````\n\n\n\n## Development\n\nSee [the development guide](docs/DEVELOPMENT.md) for instructions on development of Aqua.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhone-labs%2Faqua-compiler","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhone-labs%2Faqua-compiler","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhone-labs%2Faqua-compiler/lists"}