add deferred call manager

deferred-call-manager/.env.example

@@ -0,0 +1 @@
+PRIVATE_KEY=

deferred-call-manager/.eslintrc.cjs

@@ -0,0 +1,6 @@
+module.exports = {
+  extends: ['@massalabs'],
+  rules: {
+    'no-console': 'off',
+  },
+};

deferred-call-manager/.github/workflows/ci-tests.yml

@@ -0,0 +1,18 @@
+name: massa sc ci tests
+on: [push]
+jobs:
+  unit-tests:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+
+      - uses: actions/setup-node@v3
+        with:
+          node-version: '18'
+          cache: 'npm'
+
+      - name: Install
+        run: npm ci
+
+      - name: Test
+        run: npm run test

deferred-call-manager/.gitignore

@@ -0,0 +1,3 @@
+node_modules
+build
+.env

deferred-call-manager/README.md

@@ -0,0 +1,42 @@
+# Deferred Call Manager Contract
+
+This contract manages deferred function calls, allowing functions to be scheduled for execution at a later time. It provides mechanisms to add, execute, and remove recursive task using deferred calls. The contract schedule next task execution and store the execution infos like slot and callId. Every task schedule its next execution.
+
+## Key Functionalities
+
+- Start a recursive task to execute every given periods.
+- Executing the next deferred call and schedule the next one.
+- Stop the task recursion by canceling the next planned call.
+
+This contract is useful for scenarios where a smart contract needs to be recursively call at fixed time interval.
+The execution will last until stopped or contract coins are insufficient to next execution storage or deferred call slot booking fee.
+
+## Setup
+
+```shell
+npm i
+```
+
+Create `.env` and set `PRIVATE_KEY`:
+
+```shell
+cp .env.example .env
+```
+
+## Deploy
+
+```shell
+npm run deploy
+```
+
+## Listen to Events
+
+```shell
+npm run listen
+```
+
+## Get Execution History
+
+```shell
+npm run history
+```

deferred-call-manager/as-pect.asconfig.json

@@ -0,0 +1,24 @@
+{
+  "targets": {
+    "coverage": {
+      "lib": ["./node_modules/@as-covers/assembly/index.ts"],
+      "transform": ["@as-covers/transform", "@as-pect/transform"]
+    },
+    "noCoverage": {
+      "transform": ["@as-pect/transform"]
+    }
+  },
+  "options": {
+    "exportMemory": true,
+    "outFile": "output.wasm",
+    "textFile": "output.wat",
+    "bindings": "raw",
+    "exportStart": "_start",
+    "exportRuntime": true,
+    "use": ["RTRACE=1"],
+    "debug": true,
+    "exportTable": true
+  },
+  "extends": "./asconfig.json",
+  "entries": ["./node_modules/@as-pect/assembly/assembly/index.ts"]
+}

deferred-call-manager/as-pect.config.js

@@ -0,0 +1,28 @@
+import createMockedABI from '@massalabs/massa-as-sdk/vm-mock';
+
+export default {
+  /**
+   * A set of globs passed to the glob package that qualify typescript files for testing.
+   */
+  entries: ['assembly/__tests__/**/*.spec.ts'],
+  /**
+   * A set of globs passed to the glob package that quality files to be added to each test.
+   */
+  include: ['assembly/__tests__/**/*.include.ts'],
+  /**
+   * A set of regexp that will disclude source files from testing.
+   */
+  disclude: [/node_modules/],
+  /**
+   * Add your required AssemblyScript imports here.
+   */
+  async instantiate(memory, createImports, instantiate, binary) {
+    return createMockedABI(memory, createImports, instantiate, binary);
+  },
+  /** Enable code coverage. */
+  // coverage: ["assembly/**/*.ts"],
+  /**
+   * Specify if the binary wasm file should be written to the file system.
+   */
+  outputBinary: false,
+};

deferred-call-manager/asconfig.json

@@ -0,0 +1,13 @@
+{
+    "targets": {
+        "release": {
+            "sourceMap": true,
+            "optimizeLevel": 3,
+            "shrinkLevel": 3,
+            "converge": true,
+            "noAssert": false,
+            "exportRuntime": true,
+            "bindings": false
+        }
+    }
+}

deferred-call-manager/assembly/__tests__/as-pect.d.ts

@@ -0,0 +1 @@
+/// <reference types="@as-pect/assembly/types/as-pect" />

deferred-call-manager/assembly/__tests__/massa-example.spec.ts

@@ -0,0 +1,3 @@
+
+describe('TODO', () => {
+});

deferred-call-manager/assembly/contracts/main.ts

@@ -0,0 +1,33 @@
+import {
+  Context,
+  Storage,
+} from '@massalabs/massa-as-sdk';
+import { Args, stringToBytes, u64ToBytes } from '@massalabs/as-types';
+import {
+  cancelCall,
+  NEXT_CALL_ID_KEY,
+  registerCall,
+  TASK_COUNT_KEY,
+} from '../internals';
+
+// Export task function
+export { processTask } from '../internals';
+
+export function constructor(binArgs: StaticArray<u8>): void {
+  assert(Context.isDeployingContract());
+
+  const period = new Args(binArgs).nextU64().expect('Unable to decode period');
+
+  Storage.set(TASK_COUNT_KEY, u64ToBytes(0));
+  registerCall(period);
+}
+
+export function getNextCallId(_: StaticArray<u8>): StaticArray<u8> {
+  assert(Storage.has(NEXT_CALL_ID_KEY), 'No deferred call planned');
+  return stringToBytes(Storage.get(NEXT_CALL_ID_KEY));
+}
+
+export function stop(_: StaticArray<u8>): void {
+  assert(Storage.has(NEXT_CALL_ID_KEY), 'No deferred call to stop');
+  cancelCall(Storage.get(NEXT_CALL_ID_KEY));
+}

deferred-call-manager/assembly/internals.ts

@@ -0,0 +1,90 @@
+import {
+  Args,
+  bytesToU64,
+  byteToBool,
+  stringToBytes,
+  u64ToBytes,
+} from '@massalabs/as-types';
+import {
+  balance,
+  Context,
+  deferredCallCancel,
+  deferredCallExists,
+  deferredCallRegister,
+  generateEvent,
+  Storage,
+} from '@massalabs/massa-as-sdk';
+import { History } from './serializable/history';
+
+export const NEXT_CALL_ID_KEY = 'callId';
+export const HISTORY_KEY = stringToBytes('hist');
+export const TASK_COUNT_KEY = stringToBytes('idx');
+
+export function registerCall(period: u64): void {
+  const initBal = balance();
+  generateEvent('Current contract balance: ' + initBal.toString());
+
+  const bookingPeriod = Context.currentPeriod() + period
+  const callId = deferredCallRegister(
+    Context.callee().toString(),
+    'processTask',
+    bookingPeriod,
+    Context.currentThread(),
+    20_000_000,
+    new Args().add(period).serialize(),
+    // No need to provide coins as processTask is internal function
+    0,
+  );
+
+  const bookingCost = initBal - balance();
+
+  Storage.set(NEXT_CALL_ID_KEY, callId);
+  generateEvent(`Deferred call registered. id: ${callId}. Booked slot period: ${bookingPeriod.toString()}. Booking cost: ${bookingCost.toString()}`);
+}
+
+function getTaskIndex(): u64 {
+  return bytesToU64(Storage.get(TASK_COUNT_KEY));
+}
+
+function getHistoryKey(taskIndex: u64): StaticArray<u8> {
+  return HISTORY_KEY.concat(u64ToBytes(taskIndex));
+}
+
+export function processTask(binArgs: StaticArray<u8>): void {
+
+  assert(
+    Context.callee() === Context.caller(),
+    'The caller must be the contract itself',
+  );
+
+  const taskIndex = getTaskIndex();
+  const callId = Storage.get(NEXT_CALL_ID_KEY);
+
+  generateEvent(`Processing task ${taskIndex}. Call id : ${callId}`);
+
+  // Save execution history
+  const key = getHistoryKey(taskIndex);
+  Storage.set(
+    key,
+    new History(
+      Context.currentPeriod(),
+      Context.currentThread(),
+      callId,
+    ).serialize(),
+  );
+
+  // Increment task index
+  Storage.set(TASK_COUNT_KEY, u64ToBytes(taskIndex + 1));
+
+  const period = new Args(binArgs).nextU64().expect('Unable to decode period');
+  registerCall(period);
+}
+
+export function cancelCall(callId: string): void {
+  if (deferredCallExists(callId)) {
+    deferredCallCancel(callId);
+    generateEvent('Deferred call canceled. id : ' + callId);
+  } else {
+    generateEvent('Deferred call does not exist. id: ' + callId);
+  }
+}

deferred-call-manager/assembly/serializable/history.ts

@@ -0,0 +1,27 @@
+import { Args, Result, Serializable } from '@massalabs/as-types';
+
+export class History implements Serializable {
+  constructor(
+    public period: u64 = 0,
+    public thread: u8 = 0,
+    public callId: string = '',
+  ) {}
+
+  serialize(): StaticArray<u8> {
+    return new Args()
+      .add(this.period)
+      .add(this.thread)
+      .add(this.callId)
+      .serialize();
+  }
+
+  deserialize(data: StaticArray<u8>, offset: i32): Result<i32> {
+    const args = new Args(data, offset);
+
+    this.period = args.nextU64().expect("Can't deserialize period.");
+    this.thread = args.nextU8().expect("Can't deserialize thread.");
+    this.callId = args.nextString().expect("Can't deserialize callId.");
+
+    return new Result(args.offset);
+  }
+}

deferred-call-manager/assembly/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "extends": "assemblyscript/std/assembly.json",
+  "include": [
+    "**/*.ts"
+  ],
+  "typedocOptions": {
+    "exclude": "assembly/**/__tests__",
+    "excludePrivate": true,
+    "excludeProtected": true,
+    "excludeExternals": true,
+    "includeVersion": true,
+    "skipErrorChecking": true
+  }
+}