Add steps to interact with Anoma Node key-value store

ANOMA_KEY_VALUE_STORE.md

@@ -0,0 +1,163 @@
+# How to Set, Get and Update Values in the Anoma Node Key-Value Store
+
+## Dependencies
+
+### Anoma Node
+
+Install [Anoma Node](https://github.com/anoma/anoma). The `base` branch should work but these instructions were tested with Anoma Node release v0.21.0.
+
+Assuming you've installed the [Anoma Node dependencies](https://github.com/anoma/anoma?tab=readme-ov-file#dependencies)
+and you are authorized to clone the [Anoma Node repository](https://github.com/anoma/anoma) run:
+
+```shell
+git clone https://github.com/anoma/anoma
+git checkout v0.21.0
+mix deps.get
+mix compile
+```
+
+### Juvix
+
+Download a copy of the [Juvix nightly build binary](https://github.com/anoma/juvix-nightly-builds/releases/latest)
+for you computer's architecture and copy this somewhere on your environment's `PATH`.
+
+## Running the Anoma Node
+
+In the directory containing the Anoma Node clone run:
+
+```shell
+MIX_ENV=prod mix run --no-halt
+```
+
+## Setting the value of a key
+
+### The Juvix module
+
+Say we want to set the value of the key `["August"; "Water"; "Miki"]` to `1`. We can write the following module:
+
+SetKey.juvix
+```
+module SetKey;
+
+import Stdlib.Prelude open;
+
+main : Pair (List String) Nat := (["August"; "Water"; "Miki"], 1);
+```
+
+Then compile this module with Juvix:
+
+```shell
+juvix compile anoma SetKey.juvix
+```
+
+This will produce a file called `SetKey.nockma`.
+
+### Workaround wrapping closure
+
+Anoma Node expects the transaction to be wrapped in a closure. We can do this with the following script. We're currently investigating this, in the meantime you need to use the following workaround:
+
+NB: on macOS you'll need to install GNU sed using [`brew install gnu-sed`](https://formulae.brew.sh/formula/gnu-sed) and use the command `gsed` instead of `sed`.
+
+```shell
+sed -i -e '1i [[1' -e '$a ]0]' SetKey.nockma
+```
+
+### Submit to Anoma Node
+
+Run the following command from the root of the Anoma Node clone:
+
+```shell
+mix client submit SetKey.nockma
+```
+
+The shell prompt will return on success.
+
+## Getting the value of a key
+
+NB: You need to wait for the SetKey transaction to complete before trying to get the value of the key.
+
+### The Juvix module
+
+Say we want to get the value of the key we just set `["August"; "Water"; "Miki"]`, we can write the following module.
+
+NB: The package containing the module must depend on [`juvix-anoma-stdlib`](https://github.com/anoma/juvix-anoma-stdlib).
+
+GetKey.juvix
+```
+module GetKey;
+
+import Stdlib.Prelude open;
+import Anoma open;
+
+main : Nat := anomaGet ["August"; "Water"; "Miki"];
+```
+
+Then compile this module with Juvix:
+
+```shell
+juvix compile anoma GetKey.juvix
+```
+
+This will produce a file called `GetKey.nockma`.
+
+### Workaround wrapping closure
+
+In a similar way to the workaround in SetKey we need to wrap this output in a closure.
+
+```
+sed -i -e '1i [[1' -e '$a ]0]' GetKey.nockma
+```
+
+### Submit to Anoma Node
+
+Run the following command from the root of the Anoma Node clone:
+
+```shell
+mix client ro-submit GetKey.nockma
+```
+
+The shell prompt will return the value of the key on success.
+
+## Updating the value of a key
+
+Say we want to increment the value of the key `["August"; "Water"; "Miki"]` by 1, we can write the following module.
+
+NB: The package containing the module must depend on [`juvix-anoma-stdlib`](https://github.com/anoma/juvix-anoma-stdlib).
+
+```
+module UpdateKey;
+
+import Stdlib.Prelude open;
+import Anoma open;
+
+main : Pair (List String) Nat :=
+  let
+    key : List String := ["August"; "Water"; "Miki"];
+  in key, anomaGet key + 1;
+```
+
+Then compile this module with Juvix:
+
+```shell
+juvix compile anoma UpdateKey.juvix
+```
+
+This will produce a file called `UpdateKey.nockma`.
+
+### Workaround wrapping closure
+
+In a similar way to the workaround in SetKey we need to wrap this output in a closure.
+
+```
+sed -i -e '1i [[1' -e '$a ]0]' UpdateKey.nockma
+```
+
+### Submit to Anoma Node
+
+Run the following command from the root of the Anoma Node clone:
+
+```shell
+mix client submit UpdateKey.nockma
+```
+
+The shell prompt will return on success.

KeyValueStorage/GetKey.juvix

@@ -0,0 +1,6 @@
+module GetKey;
+
+import Stdlib.Prelude open;
+import Anoma open;
+
+main : Nat := anomaGet ["August"; "Water"; "Miki"];

KeyValueStorage/Package.juvix

@@ -0,0 +1,15 @@
+module Package;
+
+import PackageDescription.V2 open;
+
+package : Package :=
+  defaultPackage@?{
+    name := "anoma-app-patterns";
+    version := mkVersion 0 4 0;
+    dependencies :=
+      [ github "anoma" "juvix-anoma-stdlib" "v0.6.0"
+      ; github "anoma" "juvix-stdlib" "v0.6.0"
+      ; github "anoma" "juvix-containers" "v0.14.1"
+      ; github "anoma" "juvix-test" "v0.14.0"
+      ]
+  };

KeyValueStorage/SetKey.juvix

@@ -0,0 +1,5 @@
+module SetKey;
+
+import Stdlib.Prelude open;
+
+main : Pair (List String) Nat := ["August"; "Water"; "Miki"], 1;

KeyValueStorage/UpdateKey.juvix

@@ -0,0 +1,9 @@
+module UpdateKey;
+
+import Stdlib.Prelude open;
+import Anoma open;
+
+main : Pair (List String) Nat :=
+  let
+    key : List String := ["August"; "Water"; "Miki"];
+  in key, anomaGet key + 1;

KeyValueStorage/juvix.lock.yaml

@@ -0,0 +1,41 @@
+# This file was autogenerated by Juvix version 0.6.5.
+# Do not edit this file manually.
+
+version: 2
+checksum: 70b616674cb94b23e506325d666a2e9b049d5d84c328ddf3a8e31d3ce54259fc
+dependencies:
+- git:
+    name: anoma_juvix-anoma-stdlib
+    ref: d9ef7cc44b5ae55fb823cccad0f1b69eb98c4374
+    url: https://github.com/anoma/juvix-anoma-stdlib
+  dependencies:
+  - git:
+      name: anoma_juvix-stdlib
+      ref: 17a82dd466010b51924677b16a3f09a6c4c86a80
+      url: https://github.com/anoma/juvix-stdlib
+    dependencies: []
+- git:
+    name: anoma_juvix-stdlib
+    ref: 17a82dd466010b51924677b16a3f09a6c4c86a80
+    url: https://github.com/anoma/juvix-stdlib
+  dependencies: []
+- git:
+    name: anoma_juvix-containers
+    ref: cd326e035b61b965e920270ad33991e53e39afc7
+    url: https://github.com/anoma/juvix-containers
+  dependencies:
+  - git:
+      name: anoma_juvix-stdlib
+      ref: 17a82dd466010b51924677b16a3f09a6c4c86a80
+      url: https://github.com/anoma/juvix-stdlib
+    dependencies: []
+- git:
+    name: anoma_juvix-test
+    ref: 4cc8d219082e9528f7275021e7cbb2592f0a808c
+    url: https://github.com/anoma/juvix-test
+  dependencies:
+  - git:
+      name: anoma_juvix-stdlib
+      ref: 17a82dd466010b51924677b16a3f09a6c4c86a80
+      url: https://github.com/anoma/juvix-stdlib
+    dependencies: []

README.md

@@ -3,3 +3,4 @@ This is the Anoma applications repository.
 ## Documentation
 
 [How to Submit a Transaction to an Anoma Node](./SUBMIT_TO_ANOMA_NODE.md)
+[How to Set, Get and Update Values in the Anoma Node Key-Value Store](./ANOMA_KEY_VALUE_STORE.md)