feat: implement ecop builtin

cairo_programs/cairo_0/ecop_builtin.cairo

@@ -0,0 +1,27 @@
+%builtins ec_op
+
+from starkware.cairo.common.cairo_builtins import EcOpBuiltin
+from starkware.cairo.common.ec_point import EcPoint
+
+func main{ec_op_ptr: EcOpBuiltin*}() {
+    let p = EcPoint(
+        0x6a4beaef5a93425b973179cdba0c9d42f30e01a5f1e2db73da0884b8d6756fc,
+        0x72565ec81bc09ff53fbfad99324a92aa5b39fb58267e395e8abe36290ebf24f,
+    );
+    let m = 34;
+    let q = EcPoint(
+        0x654fd7e67a123dd13868093b3b7777f1ffef596c2e324f25ceaf9146698482c,
+        0x4fad269cbf860980e38768fe9cb6b0b9ab03ee3fe84cfde2eccce597c874fd8,
+    );
+
+    assert ec_op_ptr.p = p;
+    assert ec_op_ptr.q = q;
+    assert ec_op_ptr.m = m;
+
+    let r = ec_op_ptr.r;
+    let ec_op_ptr = ec_op_ptr + EcOpBuiltin.SIZE;
+
+    assert r.x = 108925483682366235368969256555281508851459278989259552980345066351008608800;
+    assert r.y = 1592365885972480102953613056006596671718206128324372995731808913669237079419;
+    return ();
+}

package.json

@@ -23,6 +23,7 @@
     "printWidth": 80
   },
   "dependencies": {
+    "@scure/starknet": "^1.0.0",
     "zod": "canary"
   }
 }

src/builtins/builtin.ts

@@ -1,5 +1,6 @@
 import { SegmentValue } from 'primitives/segmentValue';
 import { bitwiseHandler } from './bitwise';
+import { ecOpHandler } from './ecop';
 
 /** Proxy handler to abstract validation & deduction rules off the VM */
 export type BuiltinHandler = ProxyHandler<Array<SegmentValue>>;
@@ -20,6 +21,7 @@ const BUILTIN_HANDLER: {
   [key: string]: BuiltinHandler;
 } = {
   bitwise: bitwiseHandler,
+  ec_op: ecOpHandler,
 };
 
 /** Getter of the object `BUILTIN_HANDLER` */

src/builtins/ecop.test.ts

@@ -0,0 +1,95 @@
+import { describe, expect, test } from 'bun:test';
+import { Memory } from 'memory/memory';
+import { Felt } from 'primitives/felt';
+import { ecOpHandler } from './ecop';
+import { Relocatable } from 'primitives/relocatable';
+
+describe('EcOp', () => {
+  test('Should correctly compute R = P + 34Q', () => {
+    const px = new Felt(
+      0x6a4beaef5a93425b973179cdba0c9d42f30e01a5f1e2db73da0884b8d6756fcn
+    );
+    const py = new Felt(
+      0x72565ec81bc09ff53fbfad99324a92aa5b39fb58267e395e8abe36290ebf24fn
+    );
+
+    const qx = new Felt(
+      0x654fd7e67a123dd13868093b3b7777f1ffef596c2e324f25ceaf9146698482cn
+    );
+    const qy = new Felt(
+      0x4fad269cbf860980e38768fe9cb6b0b9ab03ee3fe84cfde2eccce597c874fd8n
+    );
+    const m = new Felt(34n);
+
+    const memory = new Memory();
+    const { segmentId } = memory.addSegment(ecOpHandler);
+
+    const addressPx = new Relocatable(segmentId, 0);
+    const addressPy = new Relocatable(segmentId, 1);
+    const addressQx = new Relocatable(segmentId, 2);
+    const addressQy = new Relocatable(segmentId, 3);
+    const addressM = new Relocatable(segmentId, 4);
+
+    memory.assertEq(addressPx, px);
+    memory.assertEq(addressPy, py);
+    memory.assertEq(addressQx, qx);
+    memory.assertEq(addressQy, qy);
+    memory.assertEq(addressM, m);
+
+    const addressRx = new Relocatable(segmentId, 5);
+    const addressRy = new Relocatable(segmentId, 6);
+    const expectedRx = new Felt(
+      108925483682366235368969256555281508851459278989259552980345066351008608800n
+    );
+    const expectedRy = new Felt(
+      1592365885972480102953613056006596671718206128324372995731808913669237079419n
+    );
+
+    const rx = memory.get(addressRx);
+    expect(rx).toEqual(expectedRx);
+
+    const ry = memory.get(addressRy);
+    expect(ry).toEqual(expectedRy);
+  });
+
+  test('Should throw if a coordinate of a point input value is undefined', () => {
+    const px = new Felt(10n);
+    const memory = new Memory();
+    const { segmentId } = memory.addSegment(ecOpHandler);
+
+    const addressPx = new Relocatable(segmentId, 0);
+    const addressRx = new Relocatable(segmentId, 5);
+    memory.assertEq(addressPx, px);
+
+    expect(() => memory.get(addressRx)).toThrow(
+      'Invalid field element: expected bigint, got undefined'
+    );
+  });
+
+  test('Should throw if scalar is undefined', () => {
+    const px = new Felt(10n);
+    const py = new Felt(5n);
+    const qx = new Felt(3n);
+    const qy = new Felt(2n);
+
+    const memory = new Memory();
+    const { segmentId } = memory.addSegment(ecOpHandler);
+
+    const addressPx = new Relocatable(segmentId, 0);
+    const addressPy = new Relocatable(segmentId, 1);
+    const addressQx = new Relocatable(segmentId, 2);
+    const addressQy = new Relocatable(segmentId, 3);
+
+    memory.assertEq(addressPx, px);
+    memory.assertEq(addressPy, py);
+    memory.assertEq(addressQx, qx);
+    memory.assertEq(addressQy, qy);
+
+    const addressRx = new Relocatable(segmentId, 5);
+    memory.assertEq(addressPx, px);
+
+    expect(() => memory.get(addressRx)).toThrow(
+      'Expected valid bigint: 0 < bigint < curve.n'
+    );
+  });
+});

src/builtins/ecop.ts

@@ -0,0 +1,51 @@
+import { ProjectivePoint } from '@scure/starknet';
+import { BuiltinHandler } from './builtin';
+import { isFelt } from 'primitives/segmentValue';
+import { ExpectedFelt } from 'errors/virtualMachine';
+import { Felt } from 'primitives/felt';
+import { LadderFailed } from 'errors/builtins';
+
+const _1n = BigInt(1);
+
+/**
+ * EcOp Builtin - Computes R = P + mQ
+ * P and Q are points on the STARK curve
+ * m is a scalar (a strictly positive element of the STARK Field)
+ */
+export const ecOpHandler: BuiltinHandler = {
+  get(target, prop) {
+    if (isNaN(Number(prop))) {
+      return Reflect.get(target, prop);
+    }
+
+    const cellsPerEcOp = 7;
+    const inputCellsPerEcOp = 5;
+
+    const offset = Number(prop);
+    const ecOpIndex = offset % cellsPerEcOp;
+    if (ecOpIndex < inputCellsPerEcOp) {
+      return target[offset];
+    }
+
+    const inputOffset = offset - ecOpIndex;
+    const outputOffset = inputOffset + inputCellsPerEcOp;
+
+    const inputs = target.slice(inputOffset, outputOffset).map((value) => {
+      if (!isFelt(value)) throw new ExpectedFelt();
+      return value.toBigInt();
+    });
+
+    const p = ProjectivePoint.fromAffine({ x: inputs[0], y: inputs[1] });
+    const q = ProjectivePoint.fromAffine({ x: inputs[2], y: inputs[3] });
+
+    const r = p.multiplyAndAddUnsafe(q, _1n, inputs[4]);
+    if (r === undefined) throw new LadderFailed();
+
+    switch (ecOpIndex - inputCellsPerEcOp) {
+      case 0:
+        return (target[outputOffset] = new Felt(r.x));
+      default:
+        return (target[outputOffset + 1] = new Felt(r.y));
+    }
+  },
+};

src/errors/builtins.ts

@@ -10,3 +10,6 @@ export class UndefinedValue extends BuiltinError {
     this.offset = offset;
   }
 }
+
+/** Ladder formula R = P + mQ failed in EcOp builtin */
+export class LadderFailed extends BuiltinError {}

src/runners/cairoRunner.test.ts

@@ -15,13 +15,18 @@ const FIBONACCI_PROGRAM_STRING = fs.readFileSync(
   'cairo_programs/cairo_0/fibonacci.json',
   'utf8'
 );
-const FIBONACCI_PROGRAM = parseProgram(FIBONACCI_PROGRAM_STRING);
-
 const BITWISE_PROGRAM_STRING = fs.readFileSync(
   'cairo_programs/cairo_0/bitwise_test.json',
   'utf8'
 );
+const EC_OP_PROGRAM_STRING = fs.readFileSync(
+  'cairo_programs/cairo_0/ecop_builtin.json',
+  'utf8'
+);
+
+const FIBONACCI_PROGRAM = parseProgram(FIBONACCI_PROGRAM_STRING);
 const BITWISE_PROGRAM = parseProgram(BITWISE_PROGRAM_STRING);
+const EC_OP_PROGRAM = parseProgram(EC_OP_PROGRAM_STRING);
 
 describe('cairoRunner', () => {
   describe('constructor', () => {
@@ -94,7 +99,6 @@ describe('cairoRunner', () => {
 
   describe('builtins', () => {
     describe('bitwise', () => {
-      // Test returns an error: InconsistentMemory during bitwise run, must investigate
       test('should compute bitwise 12 & 10', () => {
         const runner = new CairoRunner(BITWISE_PROGRAM);
         const config: RunOptions = {
@@ -107,5 +111,28 @@ describe('cairoRunner', () => {
         expect(runner.vm.memory.get(executionEnd.sub(2))).toEqual(new Felt(8n));
       });
     });
+
+    describe('ec_op', () => {
+      test('should properly compute  R = P + 34Q', () => {
+        const runner = new CairoRunner(EC_OP_PROGRAM);
+        const config: RunOptions = {
+          relocate: true,
+          relocateOffset: 1,
+        };
+        runner.run(config);
+
+        const expectedRx = new Felt(
+          108925483682366235368969256555281508851459278989259552980345066351008608800n
+        );
+        const expectedRy = new Felt(
+          1592365885972480102953613056006596671718206128324372995731808913669237079419n
+        );
+
+        const executionSize = runner.vm.memory.getSegmentSize(1);
+        const executionEnd = runner.executionBase.add(executionSize);
+        expect(runner.vm.memory.get(executionEnd.sub(3))).toEqual(expectedRx);
+        expect(runner.vm.memory.get(executionEnd.sub(2))).toEqual(expectedRy);
+      });
+    });
   });
 });