feat: implement dict hints primitives

.trunk/trunk.yaml

@@ -45,6 +45,5 @@ actions:
   disabled:
     - trunk-announce
     - trunk-check-pre-push
-    - trunk-fmt-pre-commit
   enabled:
     - trunk-upgrade-available

README.md

@@ -165,14 +165,20 @@ You can still add it as a dependency with a local copy:
 | [Keccak](https://github.com/kkrt-labs/cairo-vm-ts/issues/69)         | ☑ |
 | [Poseidon](https://github.com/kkrt-labs/cairo-vm-ts/issues/71)       | ☑ |
 | [Range Check 96](https://github.com/kkrt-labs/cairo-vm-ts/issues/81) | ☑ |
-| Segment Arena                                                        | ☐ |
+| [Segment Arena](https://github.com/kkrt-labs/cairo-vm-ts/pull/106)   | ☑ |
 | AddMod                                                               | ☐ |
 | MulMod                                                               | ☐ |
 
 ### Hints
 
-<!-- Add a table with the hint list and state done/to be done -->
-<!-- If the list is too long, maybe separate in chunks, put the list in an issue to track it and reference the issue here -->
+Hints are currently being implemented.
+
+Their development can be tracked
+[here](https://github.com/kkrt-labs/cairo-vm-ts/issues/90).
+
+#### How to implement a hint ?
+
+A how-to guide has been written [here](/docs/howToImplementAHint.md).
 
 ### Differential Testing & Benchmark
 

cairo_programs/cairo/hints/alloc_felt_dict.cairo

@@ -0,0 +1,3 @@
+fn main() {
+    let mut _balances: Felt252Dict<u64> = Default::default();
+}

cairo_programs/cairo/hints/array_append.cairo

@@ -0,0 +1,6 @@
+fn main() {
+    let mut a = ArrayTrait::new();
+    a.append(0);
+    a.append(1);
+    a.append(2);
+}

cairo_programs/cairo/hints/dict_get.cairo

@@ -0,0 +1,5 @@
+fn main() {
+    let mut balances: Felt252Dict<u64> = Default::default();
+    balances.insert('Simon', 100);
+    balances.get('Simon');
+}

cairo_programs/cairo/hints/dict_insert.cairo

@@ -0,0 +1,6 @@
+fn main() {
+    let mut balances: Felt252Dict<u64> = Default::default();
+    balances.insert('Simon', 100);
+    balances.insert('Alice', 500);
+    balances.insert('Bob', 30);
+}

cairo_programs/cairo/hints/dict_multiple_insert.cairo

@@ -0,0 +1,7 @@
+fn main() {
+    let mut balances: Felt252Dict<u64> = Default::default();
+    balances.insert('Simon', 100);
+    balances.insert('Simon', 500);
+    balances.insert('Simon', 600);
+    balances.insert('Simon', 700);
+}

cairo_programs/cairo/hints/dict_squash.cairo

@@ -0,0 +1,7 @@
+fn main() {
+    let mut dict = felt252_dict_new::<felt252>();
+    dict.insert(1, 64);
+    dict.insert(2, 75);
+    dict.insert(3, 75);
+    dict.squash();
+}

cairo_programs/cairo/hints/multiple_dict.cairo

@@ -0,0 +1,6 @@
+fn main() {
+    let mut balances_1: Felt252Dict<u64> = Default::default();
+    let mut balances_2: Felt252Dict<u64> = Default::default();
+    balances_1.insert('Alice', 500);
+    balances_2.insert('Bob', 30);
+}

docs/howToImplementAHint.md

@@ -0,0 +1,155 @@
+# How to implement a hint
+
+Here is a how-to, using the hint `GetSegmentArenaIndex` as an example:
+
+## Find the signature
+
+Find the signature of the hint in the
+[Cairo compiler](https://github.com/starkware-libs/cairo/blob/b741c26c553fd9fa3246cee91fd5c637f225cdb9/crates/cairo-lang-casm/src/hints/mod.rs):
+[GetSegmentArenaIndex](https://github.com/starkware-libs/cairo/blob/b741c26c553fd9fa3246cee91fd5c637f225cdb9/crates/cairo-lang-casm/src/hints/mod.rs#L203)
+
+```rust
+/// Retrieves the index of the given dict in the dict_infos segment.
+GetSegmentArenaIndex { dict_end_ptr: ResOperand, dict_index: CellRef },
+```
+
+Here, `dict_end_ptr` is a `ResOperand` while `dict_index` is a `CellRef`.
+
+The definitions of `Cellref` and `ResOperand` can be found in
+`hintParamSchema.ts`. Hint arguments can only be one of these two types.
+
+## Parsing
+
+The Cairo VM takes the serialized compilation artifacts as input, we use Zod to
+parse them. Each hint has its own parser object.
+
+The GetSegmentArenaIndex hint can be found in a format similar to this one:
+
+```json
+"GetSegmentArenaIndex": {
+  "dict_end_ptr": {
+    "Deref": {
+      "register": "FP",
+      "offset": -3
+    }
+  },
+  "dict_index": {
+    "register": "FP",
+    "offset": 0
+  }
+}
+```
+
+- Add `GetSegmentArenaIndex` to the `HintName` enum in `src/hints/hintName.ts`.
+  It is used to identify the hint before executing it in a run. Hints are
+  ordered in an ascending alphabetical order.
+
+  ```typescript
+  // hintName.ts
+  export enum HintName {
+    // ...
+    GetSegmentArenaIndex = 'GetSegmentArenaIndex',
+  }
+  ```
+
+- Create the file `src/hints/dict/getSegmentArenaIndex.ts`. Place the file in
+  the appropriate sub-folder category, here `dict` because the hint is dedicated
+  to dictionaries.
+
+- Create and export a Zod object `getSegmentArenaIndexParser` which follows the
+  hint signature:
+
+  ```typescript
+  // getSegmentArenaIndex.ts
+  export const getSegmentArenaIndexParser = z
+    .object({
+      GetSegmentArenaIndex: z.object({
+        dict_end_ptr: resOperand,
+        dict_index: cellRef,
+      }),
+    })
+    .transform(({ GetSegmentArenaIndex: { dict_end_ptr, dict_index } }) => ({
+      type: HintName.GetSegmentArenaIndex,
+      dictEndPtr: dict_end_ptr,
+      dictIndex: dict_index,
+    }));
+  ```
+
+  The parsed object must be transformed in two ways:
+
+  1. Enforce camelCase in fields name
+  2. Add a field `type` which takes the corresponding value of the `HintName`
+     enum.
+
+- Add the parser to the Zod union `hint` in `src/hints/hintSchema.ts`:
+
+  ```typescript
+  // hintSchema.ts
+  const hint = z.union([
+    // ...
+    getSegmentArenaIndexParser,
+  ]);
+  ```
+
+Now, we can implement the core logic of the hint.
+
+## Core Logic
+
+The core logic of the hint will be implemented in the same file as the hint
+parser, here `getSegmentArenaIndex.ts`. The function implementing this logic
+must be named as the camelCase version of the hint: `getSegmentArenaIndex()`
+(similar to its filename).
+
+The parameters of the function are the virtual machine, as the hint must
+interact with it, and the signature of the hint.
+
+So, in our case, the function signature would be
+`export getSegmentArenaIndex(vm: VirtualMachine, dictEndPtr: ResOperand, dictIndex: CellRef)`
+
+To implement the logic, refer yourself to its implementation in the
+[`cairo-vm`](https://github.com/lambdaclass/cairo-vm/blob/24c2349cc19832fd8c1552304fe0439765ed82c6/vm/src/hint_processor/cairo_1_hint_processor/hint_processor.rs#L427-L444)
+and the
+[`cairo-lang-runner`](https://github.com/starkware-libs/cairo/blob/b741c26c553fd9fa3246cee91fd5c637f225cdb9/crates/cairo-lang-runner/src/casm_run/mod.rs#L1873-L1880)
+from the Cairo compiler.
+
+The last step is adding the hint to the handler object.
+
+## Handler
+
+The handler is defined in `src/hints/hintHandler.ts`
+
+It is a dictionary which maps a `HintName` value to a function executing the
+corresponding core logic function.
+
+```typescript
+export const handlers: Record<
+  HintName,
+  (vm: VirtualMachine, hint: Hint) => void
+> = {
+  [HintName.GetSegmentArenaIndex]: (vm, hint) => {
+    const h = hint as GetSegmentArenaIndex;
+    getSegmentArenaIndex(vm, h.dictEndptr, h.dictIndex);
+  },
+};
+```
+
+- Set the key as the HintName value, `HintName.GetSegmentArenaIndex`
+- Set the value to a function which takes `(vm, hint)` as parameters and execute
+  the core logic function of the corresponding hint.
+
+To do so, we make a type assertion of the hint, matching the `HintName` value,
+and we call the corresponding core logic function with the appropriate
+arguments.
+
+The hint has been implemented, the last thing to do is testing it.
+
+## Testing
+
+Unit tests must test the correct parsing of the hint and the execution of the
+core logic. Those tests are done in a `.test.ts` file in the same folder as the
+hint. In our example, it would be `src/hints/dict/getSegmentArenaIndex.test.ts`.
+
+Integration test is done by creating a Cairo program in
+`cairo_programs/cairo/hints`. We must verify its proper execution by compiling
+it with `make compile` and executing it with the command
+`cairo run path/to/my_program.json`

src/builtins/builtin.ts

@@ -7,6 +7,7 @@ import { poseidonHandler } from './poseidon';
 import { keccakHandler } from './keccak';
 import { outputHandler } from './output';
 import { rangeCheckHandler } from './rangeCheck';
+import { segmentArenaHandler } from './segmentArena';
 
 /** Proxy handler to abstract validation & deduction rules off the VM */
 export type BuiltinHandler = ProxyHandler<Array<SegmentValue>>;
@@ -20,7 +21,7 @@ export type BuiltinHandler = ProxyHandler<Array<SegmentValue>>;
  * - Keccak: Builtin for keccak hash family
  * - Pedersen: Builtin for pedersen hash family
  * - Poseidon: Builtin for poseidon hash family
- * - Segment Arena: Unknown usage, must investigate
+ * - Segment Arena: Builtin to manage the dictionaries
  * - Output: Output builtin
  */
 const BUILTIN_HANDLER: {
@@ -35,6 +36,7 @@ const BUILTIN_HANDLER: {
   keccak: keccakHandler,
   range_check: rangeCheckHandler(128n),
   range_check96: rangeCheckHandler(96n),
+  segment_arena: segmentArenaHandler,
 };
 
 /** Getter of the object `BUILTIN_HANDLER` */

src/builtins/segmentArena.ts

@@ -0,0 +1,30 @@
+import { BuiltinHandler } from './builtin';
+
+/**
+ * Offset to compute the address
+ * of the info segment pointer.
+ */
+export const INFO_PTR_OFFSET = 3;
+
+/**
+ * Offset to read the current number
+ * of allocated dictionaries.
+ */
+export const DICT_NUMBER_OFFSET = 2;
+
+/**
+ * The segment arena builtin manages Cairo dictionaries.
+ *
+ * It works by block of 3 cells:
+ * - The first cell contains the base address of the info pointer.
+ * - The second cell contains the current number of allocated dictionaries.
+ * - The third cell contains the current number of squashed dictionaries.
+ *
+ * The Info segment is tightly closed to the segment arena builtin.
+ *
+ * It also works by block of 3 cells:
+ * - The first cell is the base address of a dictionary
+ * - The second cell is the end address of a dictionary when squashed.
+ * - The third cell is the current number of squashed dictionaries (i.e. its squashing index).
+ */
+export const segmentArenaHandler: BuiltinHandler = {};

src/errors/builtins.ts

@@ -22,11 +22,11 @@ export class RangeCheckOutOfBounds extends BuiltinError {
   }
 }
 
-/** ECDSA signature cannot be retrieved from dictionnary at `offset` */
+/** ECDSA signature cannot be retrieved from dictionary at `offset` */
 export class UndefinedECDSASignature extends BuiltinError {
   constructor(offset: number) {
     super(
-      `ECDSA signature cannot be retrieved from dictionnary at offset ${offset}`
+      `ECDSA signature cannot be retrieved from dictionary at offset ${offset}`
     );
   }
 }
@@ -48,7 +48,7 @@ public key (negative): ${pubKeyNegHex}
   }
 }
 
-/** The signature dictionnary is undefined */
+/** The signature dictionary is undefined */
 export class UndefinedSignatureDict extends BuiltinError {}
 
 /** An offset of type number is expected */

src/errors/dictionary.ts

@@ -0,0 +1,10 @@
+import { Relocatable } from 'primitives/relocatable';
+
+class DictionaryError extends Error {}
+
+/** Cannot find Dictionary at `address` */
+export class DictNotFound extends DictionaryError {
+  constructor(address: Relocatable) {
+    super(`Cannot found any Dictionary at address ${address.toString()}`);
+  }
+}

src/errors/hints.ts

@@ -3,20 +3,32 @@ import { Hint } from 'hints/hintSchema';
 
 class HintError extends Error {}
 
+/** The provided register at `cell` is incorrect. It must either be AP or FP. */
 export class InvalidCellRefRegister extends HintError {
   constructor(cell: CellRef) {
     super(`Invalid register, expected AP or FP, got ${cell}`);
   }
 }
 
+/** The operator of the BinOp operation `op` must either be `Add` or `Mul`. */
 export class InvalidOperation extends HintError {
   constructor(op: string) {
     super(`Invalid BinOp operator - Expected Add or Mul, received ${op}`);
   }
 }
 
+/** The hint to be executed is unknown. */
 export class UnknownHint extends HintError {
   constructor(hint: Hint) {
     super(`Unknown hint: ${hint}`);
   }
 }
+
+/** The number of dict accesses is invalid. */
+export class InvalidDictAccessesNumber extends HintError {
+  constructor(ptrDiffValue: number, dictAccessSize: number) {
+    super(
+      `The number of dictionary accesses (${ptrDiffValue}) must be a multiple of the dictionary access size (${dictAccessSize})`
+    );
+  }
+}

src/errors/memory.ts

@@ -24,3 +24,10 @@ export class SegmentOutOfBounds extends MemoryError {
     );
   }
 }
+
+/** Expected a SegmentValue but read `undefined` */
+export class UndefinedSegmentValue extends MemoryError {
+  constructor() {
+    super(`Expected a SegmentValue, read undefined`);
+  }
+}

src/errors/scopeManager.ts

@@ -0,0 +1,15 @@
+class ScopeManagerError extends Error {}
+
+/** The main scope cannot be removed, there must always be at least one scope. */
+export class CannotExitMainScope extends ScopeManagerError {
+  constructor() {
+    super('Cannot exit the main scope');
+  }
+}
+
+/** The variable `name` is not accessible in the current scope. */
+export class VariableNotInScope extends ScopeManagerError {
+  constructor(name: string) {
+    super(`Variable ${name} is not in scope`);
+  }
+}