Skip to content

Commit 9bd9056

Browse files
aorumbayevaorumbayev
authored
feat: puya-ts support under compile command group (#612)
* feat: adding ts and typescript commands to compile group * chore: bump node to v 20 as min req version for puya-ts integration test * chore: remove 3.13 rc
1 parent 7344544 commit 9bd9056

16 files changed

Lines changed: 801 additions & 49 deletions

‎.github/workflows/build-python.yaml‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ jobs:
77
strategy:
88
matrix:
99
os: ["ubuntu-latest", "macos-latest", "windows-latest"]
10-
python: ["3.10", "3.11", "3.12", "3.13.0-rc.3"] # TODO: change to 3.13 once its out of rc
10+
python: ["3.10", "3.11", "3.12", "3.13"]
1111
runs-on: ${{ matrix.os }}
1212
steps:
1313
- name: Checkout source code
@@ -18,6 +18,11 @@ jobs:
1818
with:
1919
python-version: ${{ matrix.python }}
2020

21+
- name: Set up Node.js
22+
uses: actions/setup-node@v4
23+
with:
24+
node-version: 20
25+
2126
- name: Set up Poetry
2227
uses: ./.github/actions/setup-poetry
2328

‎docs/cli/index.md‎

Lines changed: 50 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,12 @@
1616
- [python](#python)
1717
- [Arguments](#arguments-1)
1818
- [PUYAPY_ARGS](#puyapy_args-1)
19+
- [ts](#ts)
20+
- [Arguments](#arguments-2)
21+
- [PUYATS_ARGS](#puyats_args)
22+
- [typescript](#typescript)
23+
- [Arguments](#arguments-3)
24+
- [PUYATS_ARGS](#puyats_args-1)
1925
- [completions](#completions)
2026
- [install](#install)
2127
- [Options](#options-2)
@@ -27,10 +33,10 @@
2733
- [container-engine](#container-engine)
2834
- [Options](#options-4)
2935
- [-f, --force](#-f---force)
30-
- [Arguments](#arguments-2)
36+
- [Arguments](#arguments-4)
3137
- [ENGINE](#engine)
3238
- [version-prompt](#version-prompt)
33-
- [Arguments](#arguments-3)
39+
- [Arguments](#arguments-5)
3440
- [ENABLE](#enable)
3541
- [dispenser](#dispenser)
3642
- [fund](#fund)
@@ -54,21 +60,21 @@
5460
- [Options](#options-9)
5561
- [-c, --copy-to-clipboard](#-c---copy-to-clipboard)
5662
- [explore](#explore)
57-
- [Arguments](#arguments-4)
63+
- [Arguments](#arguments-6)
5864
- [NETWORK](#network)
5965
- [generate](#generate)
6066
- [client](#client)
6167
- [Options](#options-10)
6268
- [-o, --output ](#-o---output--1)
6369
- [-l, --language ](#-l---language-)
6470
- [-v, --version ](#-v---version--1)
65-
- [Arguments](#arguments-5)
71+
- [Arguments](#arguments-7)
6672
- [APP_SPEC_PATH_OR_DIR](#app_spec_path_or_dir)
6773
- [goal](#goal)
6874
- [Options](#options-11)
6975
- [--console](#--console)
7076
- [--interactive](#--interactive)
71-
- [Arguments](#arguments-6)
77+
- [Arguments](#arguments-8)
7278
- [GOAL_ARGS](#goal_args)
7379
- [init](#init)
7480
- [Options](#options-12)
@@ -97,7 +103,7 @@
97103
- [config](#config-1)
98104
- [Options](#options-14)
99105
- [-f, --force](#-f---force-2)
100-
- [Arguments](#arguments-7)
106+
- [Arguments](#arguments-9)
101107
- [ENGINE](#engine-1)
102108
- [console](#console)
103109
- [explore](#explore-1)
@@ -137,7 +143,7 @@
137143
- [--deployer ](#--deployer-)
138144
- [--dispenser ](#--dispenser-)
139145
- [-p, --project-name ](#-p---project-name--1)
140-
- [Arguments](#arguments-8)
146+
- [Arguments](#arguments-10)
141147
- [ENVIRONMENT_NAME](#environment_name)
142148
- [EXTRA_ARGS](#extra_args)
143149
- [link](#link)
@@ -148,7 +154,7 @@
148154
- [-f, --fail-fast](#-f---fail-fast)
149155
- [-v, --version ](#-v---version--2)
150156
- [list](#list)
151-
- [Arguments](#arguments-9)
157+
- [Arguments](#arguments-11)
152158
- [WORKSPACE_PATH](#workspace_path)
153159
- [run](#run)
154160
- [task](#task)
@@ -159,7 +165,7 @@
159165
- [--diff](#--diff)
160166
- [-o, --output ](#-o---output--2)
161167
- [-e, --exclude ](#-e---exclude-)
162-
- [Arguments](#arguments-10)
168+
- [Arguments](#arguments-12)
163169
- [INPUT_PATHS](#input_paths)
164170
- [ipfs](#ipfs)
165171
- [Options](#options-25)
@@ -180,20 +186,20 @@
180186
- [nfd-lookup](#nfd-lookup)
181187
- [Options](#options-27)
182188
- [-o, --output ](#-o---output--3)
183-
- [Arguments](#arguments-11)
189+
- [Arguments](#arguments-13)
184190
- [VALUE](#value)
185191
- [opt-in](#opt-in)
186192
- [Options](#options-28)
187193
- [-a, --account ](#-a---account-)
188194
- [-n, --network ](#-n---network--1)
189-
- [Arguments](#arguments-12)
195+
- [Arguments](#arguments-14)
190196
- [ASSET_IDS](#asset_ids)
191197
- [opt-out](#opt-out)
192198
- [Options](#options-29)
193199
- [-a, --account ](#-a---account--1)
194200
- [--all](#--all)
195201
- [-n, --network ](#-n---network--2)
196-
- [Arguments](#arguments-13)
202+
- [Arguments](#arguments-15)
197203
- [ASSET_IDS](#asset_ids-1)
198204
- [send](#send)
199205
- [Options](#options-30)
@@ -222,20 +228,20 @@
222228
- [-a, --alias ](#-a---alias-)
223229
- [--file-path ](#--file-path-)
224230
- [-f, --force](#-f---force-3)
225-
- [Arguments](#arguments-14)
231+
- [Arguments](#arguments-16)
226232
- [KEYWORD](#keyword)
227233
- [wallet](#wallet)
228234
- [Options](#options-34)
229235
- [-a, --address ](#-a---address-)
230236
- [-m, --mnemonic](#-m---mnemonic)
231237
- [-f, --force](#-f---force-4)
232-
- [Arguments](#arguments-15)
238+
- [Arguments](#arguments-17)
233239
- [ALIAS_NAME](#alias_name)
234-
- [Arguments](#arguments-16)
240+
- [Arguments](#arguments-18)
235241
- [ALIAS](#alias)
236242
- [Options](#options-35)
237243
- [-f, --force](#-f---force-5)
238-
- [Arguments](#arguments-17)
244+
- [Arguments](#arguments-19)
239245
- [ALIAS](#alias-1)
240246
- [Options](#options-36)
241247
- [-f, --force](#-f---force-6)
@@ -311,6 +317,34 @@ algokit compile python [OPTIONS] [PUYAPY_ARGS]...
311317
### PUYAPY_ARGS
312318
Optional argument(s)
313319

320+
### ts
321+
322+
Compile Algorand TypeScript contract(s) using the PuyaTs compiler.
323+
324+
```shell
325+
algokit compile ts [OPTIONS] [PUYATS_ARGS]...
326+
```
327+
328+
### Arguments
329+
330+
331+
### PUYATS_ARGS
332+
Optional argument(s)
333+
334+
### typescript
335+
336+
Compile Algorand TypeScript contract(s) using the PuyaTs compiler.
337+
338+
```shell
339+
algokit compile typescript [OPTIONS] [PUYATS_ARGS]...
340+
```
341+
342+
### Arguments
343+
344+
345+
### PUYATS_ARGS
346+
Optional argument(s)
347+
314348
## completions
315349

316350
Install and Uninstall AlgoKit shell integrations.

‎docs/features/compile.md‎

Lines changed: 71 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ When running the compile command, AlgoKit will take care of working out which co
66

77
## Prerequisites
88

9-
See [Compile Python - Prerequisites](#prerequisites-1) for details.
9+
See [Compile Python - Prerequisites](#prerequisites-1) and [Compile TypeScript - Prerequisites](#prerequisites-2) for details.
1010

1111
## What is Algorand Python & PuyaPy?
1212

@@ -29,6 +29,24 @@ class HelloWorldContract(ARC4Contract):
2929

3030
For more complex examples, see the [examples](https://github.com/algorandfoundation/puya/tree/main/examples) in the [PuyaPy repo](https://github.com/algorandfoundation/puya).
3131

32+
## What is Algorand TypeScript & PuyaTs?
33+
34+
Algorand TypeScript is a typed TypeScript language that allows you to express smart contracts (apps) and smart signatures (logic signatures) for deployment on the Algorand Virtual Machine (AVM). Algorand TypeScript is currently in beta.
35+
36+
Algorand TypeScript can be deployed to Algorand by using the PuyaTs optimising compiler, which takes Algorand TypeScript and outputs [ARC-32](https://github.com/algorandfoundation/ARCs/blob/main/ARCs/arc-0032.md) application spec files (among other formats) which, [when deployed](https://github.com/algorandfoundation/algokit-cli/blob/main/docs/features/generate.md#1-typed-clients), will result in AVM bytecode execution semantics that match the given TypeScript code.
37+
38+
Below is an example Algorand TypeScript smart contract.
39+
40+
```typescript
41+
import { Contract } from "@algorandfoundation/puya-sdk";
42+
43+
class HelloWorldContract extends Contract {
44+
hello(name: string): string {
45+
return "Hello, " + name;
46+
}
47+
}
48+
```
49+
3250
## Usage
3351

3452
Available commands and possible usage are as follows:
@@ -47,8 +65,10 @@ Options:
4765
-h, --help Show this message and exit.
4866
4967
Commands:
50-
py Compile Algorand Python contract(s) using the PuyaPy compiler.
51-
python Compile Algorand Python contract(s) using the PuyaPy compiler.
68+
py Compile Algorand Python contract(s) using the PuyaPy compiler.
69+
python Compile Algorand Python contract(s) using the PuyaPy compiler.
70+
ts Compile Algorand TypeScript contract(s) using the PuyaTs compiler.
71+
typescript Compile Algorand TypeScript contract(s) using the PuyaTs compiler.
5272
```
5373

5474
### Compile Python
@@ -96,3 +116,51 @@ To compile a directory of Algorand Python smart contracts and write the output t
96116
```shell
97117
algokit compile python my_contracts
98118
```
119+
120+
### Compile TypeScript
121+
122+
The command `algokit compile typescript` or `algokit compile ts` will run the PuyaTs compiler against the supplied Algorand TypeScript smart contract.
123+
124+
All arguments supplied to the command are passed directly to PuyaTs, therefore this command supports all options supported by the PuyaTs compiler.
125+
126+
Any errors detected by PuyaTs during the compilation process will be printed to the output.
127+
128+
#### Prerequisites
129+
130+
Node.js and npm are required for the TypeScript compiler. The command will attempt to find a correctly installed PuyaTs compiler in the following order:
131+
132+
1. First, it checks if a matching version is installed at the project level (using `npm ls`).
133+
2. Next, it checks if a matching version is installed globally (using `npm --global ls`).
134+
3. If no appropriate match is found, it will run the compiler using npx with the `-y` flag.
135+
136+
#### Examples
137+
138+
To see a list of the supported PuyaTs options, run the following:
139+
140+
```shell
141+
algokit compile typescript -h
142+
```
143+
144+
To determine the version of the PuyaTs compiler in use, execute the following command:
145+
146+
```shell
147+
algokit compile typescript --version
148+
```
149+
150+
To compile a single Algorand TypeScript smart contract and write the output to a specific location, run the following:
151+
152+
```shell
153+
algokit compile typescript hello_world/contract.algo.ts --out-dir hello_world/out
154+
```
155+
156+
To build multiple Algorand TypeScript smart contracts and write the output to a specific location, run the following:
157+
158+
```shell
159+
algokit compile typescript hello_world/contract.algo.ts calculator/contract.algo.ts --out-dir my_contracts
160+
```
161+
162+
To compile a directory of Algorand TypeScript smart contracts and write the output to the default location, run the following:
163+
164+
```shell
165+
algokit compile typescript my_contracts
166+
```

0 commit comments

Comments
 (0)