Skip to content

Commit 6b9a80b

Browse files
VinocisVinocis
committed
improve doc
1 parent cc12c70 commit 6b9a80b

1 file changed

Lines changed: 186 additions & 18 deletions

File tree

‎README.md‎

Lines changed: 186 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# Numscript WASM CLI
22

3-
This project was originally a fork of the original [formancehq/numscript](https://github.com/formancehq/numscript) repository, adapted for WASM compatibility while maintaining the core CLI functionality.
3+
This project is a WebAssembly (WASM) port of the [formancehq/numscript](https://github.com/formancehq/numscript) CLI, enabling you to run Numscript execution in any WASM-compatible environment. Originally forked from the official repository, it now provides a standalone WASM binary that maintains full compatibility with the original CLI functionality.
44

55
## What is Numscript?
66

@@ -17,17 +17,18 @@ You can try Numscript online at [playground.numscript.org](https://playground.nu
1717

1818
## Installation
1919

20-
Clone the repository and build the binary:
20+
### Prerequisites
2121

22-
```bash
23-
git clone git@github.com:PagoPlus/numscript-wasm.git
24-
25-
cd numscript-wasm
22+
You'll need a WebAssembly (WASM) runtime to execute the numscript-wasm binary. This guide uses Wasmtime, but you can also use other WASM runtimes like Wasmer.
2623

27-
go build -o numscript-wasm main.go
24+
**Install Wasmtime:**
25+
```bash
26+
curl https://wasmtime.dev/install.sh -sSf | bash
2827
```
2928

30-
This will create a `numscript-wasm` executable in the current directory.
29+
### Download the Binary
30+
31+
Download the WASM binary from the [latest release](https://github.com/PagoPlus/numscript-wasm/releases/latest) for your platform.
3132

3233
## Usage
3334

@@ -38,7 +39,7 @@ The CLI provides two commands: `version` and `run`.
3839
Display the current version of the CLI:
3940

4041
```bash
41-
./numscript-wasm version
42+
wasmtime numscript.wasm version
4243
```
4344

4445
**Output:**
@@ -57,15 +58,50 @@ Execute a Numscript with the provided input data. The command reads JSON input f
5758

5859
The input JSON must follow this structure:
5960

60-
| Field | Type | Description |
61-
|-------|------|-------------|
62-
| `script` | string | The Numscript code to execute |
63-
| `variables` | object | [variables](https://docs.formance.com/numscript/reference/variables) used inside the script. |
64-
| `metadata` | object | [metada variables](https://docs.formance.com/numscript/reference/metadata) |
65-
| `balances` | object | Current account balances (nested object: account -> asset -> amount) |
66-
| `featureFlags` | object | Experimental features to enable (empty object) |
61+
| Field | Type | Required | Description |
62+
|-------|------|----------|-------------|
63+
| `script` | string | ✅ | The Numscript code to execute |
64+
| `variables` | object | ❌ | [Variables](https://docs.formance.com/modules/numscript/reference/variables) |
65+
| `metadata` | object | ❌ | [Account metadata](https://docs.formance.com/modules/numscript/reference/metadata) |
66+
| `balances` | object | ✅ | Current account balances. [Example below](#balances). |
67+
| `featureFlags` | object | ❌ | Experimental features to enable (empty objects as values). [Example below](#featureflags) |
68+
69+
##### balances
70+
Is an object containing the account name and their respective assets and balances. Ex:
71+
```json
72+
"balances": {
73+
"foo": {
74+
"USD/2": 200,
75+
"EUR/2": 100
76+
},
77+
"bar": {
78+
"BRL/2": 200,
79+
"JPY/2": 100
80+
}
81+
},
82+
```
83+
###### Asset Format
84+
Assets use the format `CURRENCY/PRECISION`:
85+
- `USD/2` = US Dollars with 2 decimal places
86+
- `EUR/2` = Euros with 2 decimal places
87+
- `BTC/8` = Bitcoin with 8 decimal places
88+
89+
##### featureFlags
90+
Is an object containing the name of the feature flag you want to use with an empty object as their value. Ex:
91+
```json
92+
"featureFlags": {
93+
"experimental-oneof": {},
94+
"experimental-get-amount-function": {},
95+
"experimental-mid-script-function-call": {}
96+
}
97+
```
98+
99+
Numscript does not have an official list of feature flags, but you can see the [source code](https://github.com/formancehq/numscript/blob/v0.0.17/internal/flags/flags.go) and the documentation with the [experimental features usage](https://github.com/formancehq/numscript/blob/main/differences-with-machine.md#new-functionalities-feature-flags)
67100

68-
#### Complete Example
101+
#### Examples
102+
103+
##### Basic Transfer
104+
Simple account-to-account transfer:
69105

70106
1. **Create an input file** (`example.json`):
71107

@@ -87,7 +123,7 @@ The input JSON must follow this structure:
87123
2. **Execute the script**:
88124

89125
```bash
90-
./numscript-wasm run < example.json
126+
wasmtime numscript.wasm run < example.json
91127
```
92128

93129
3. **Expected output** (JSON format):
@@ -107,10 +143,121 @@ The input JSON must follow this structure:
107143
}
108144
```
109145

146+
#### Using variables
147+
148+
1. **Input File:** (`example.json`):
149+
```json
150+
{
151+
"script": "vars { account $user monetary $fee portion $tax } send $fee (source = $user destination = { $tax to @platform:tax remaining to @platform:revenue })",
152+
"balances": {
153+
"users:1234": {
154+
"USD/2": 10000
155+
}
156+
},
157+
"variables": {
158+
"user": "users:1234",
159+
"fee": "USD/2 100",
160+
"tax": "20%"
161+
},
162+
"metadata": {},
163+
"featureFlags": {
164+
"experimental-oneof": {},
165+
"experimental-get-amount-function": {},
166+
"experimental-mid-script-function-call": {}
167+
}
168+
}
169+
```
170+
171+
2. **Execute the script**:
172+
```bash
173+
wasmtime numscript.wasm run < example.json
174+
```
175+
176+
3. **Expected output** (JSON format):
177+
```json
178+
{
179+
"postings": [
180+
{
181+
"source": "users:1234",
182+
"destination": "platform:tax",
183+
"amount": 20,
184+
"asset": "USD/2"
185+
},
186+
{
187+
"source": "users:1234",
188+
"destination": "platform:revenue",
189+
"amount": 80,
190+
"asset": "USD/2"
191+
}
192+
],
193+
"txMeta": {},
194+
"accountsMeta": {}
195+
}
196+
```
197+
198+
199+
#### Using metadata
200+
201+
1. **Input File:** (`example.json`):
202+
```json
203+
{
204+
"script": "vars { account $order account $merchant = meta($order, \"merchant\") portion $commission = meta($merchant, \"commission\") } send [USD/2 *] ( source = $order destination = { $commission to @platform:fees remaining to $merchant })",
205+
"balances": {
206+
"orders:2345": {
207+
"USD/2": 1000
208+
}
209+
},
210+
"variables": {
211+
"order": "orders:2345"
212+
},
213+
"metadata": {
214+
"orders:2345": {
215+
"merchant": "merchants:1234"
216+
},
217+
"merchants:1234": {
218+
"commission": "15%"
219+
}
220+
},
221+
"featureFlags": {
222+
"experimental-oneof": {},
223+
"experimental-get-amount-function": {},
224+
"experimental-mid-script-function-call": {}
225+
}
226+
}
227+
```
228+
229+
2. **Execute the script**:
230+
```bash
231+
wasmtime numscript.wasm run < example.json
232+
```
233+
234+
3. **Expected output** (JSON format):
235+
```json
236+
{
237+
"postings": [
238+
{
239+
"source": "orders:2345",
240+
"destination": "platform:fees",
241+
"amount": 150,
242+
"asset": "USD/2"
243+
},
244+
{
245+
"source": "orders:2345",
246+
"destination": "merchants:1234",
247+
"amount": 850,
248+
"asset": "USD/2"
249+
}
250+
],
251+
"txMeta": {},
252+
"accountsMeta": {}
253+
}
254+
```
255+
110256
#### Allowing experimental features
111257

112258
If you want to use experimental features, you need to enable them by adding their respective feature flag:
113259

260+
1. **Input File:** (`example.json`):
114261
```json
115262
{
116263
"script": "vars { monetary $mon = [USD/2 100] number $n = get_amount($mon) } send [USD/2 $n] (source = oneof { @foo @bar } destination = @baz)",
@@ -132,6 +279,27 @@ If you want to use experimental features, you need to enable them by adding thei
132279
}
133280
```
134281

282+
2. **Execute the script**:
283+
```bash
284+
wasmtime numscript.wasm run < example.json
285+
```
286+
287+
3. **Expected output** (JSON format):
288+
```json
289+
{
290+
"postings": [
291+
{
292+
"source": "bar",
293+
"destination": "baz",
294+
"amount": 100,
295+
"asset": "USD/2"
296+
}
297+
],
298+
"txMeta": {},
299+
"accountsMeta": {}
300+
}
301+
```
302+
135303
## Error Handling
136304

137305
The CLI will exit with status code 1 and write error messages to stderr if:

0 commit comments

Comments
 (0)