@riseandshaheen/libcma 0.1.0-alpha.0

package/native/real/ledger_real.cc

@@ -0,0 +1,271 @@
+// Real libcma backend (riscv64 / LIBCMA_USE_REAL).
+// Uses cma_ledger_init_single_* with AssetType::BASE (Ether) — matches contracts v3
+// emergency-withdrawal accounts-drive layout (32-byte single-asset records).
+
+#include "ledger_backend.h"
+
+#include <cstdlib>
+#include <cstring>
+#include <new>
+#include <string>
+
+extern "C" {
+#include <libcma/ledger.h>
+#include <libcma/types.h>
+}
+
+namespace {
+
+thread_local std::string g_last_error;
+
+void set_err(const char *msg) {
+    g_last_error = msg ? msg : "";
+}
+
+void set_err_from_libcma() {
+    const char *msg = cma_ledger_get_last_error_message();
+    g_last_error = msg ? msg : "libcma error";
+}
+
+bool amount_is_zero(const uint8_t amount_be[32]) {
+    for (int i = 0; i < 32; i++) {
+        if (amount_be[i] != 0) {
+            return false;
+        }
+    }
+    return true;
+}
+
+void copy_amount(cma_amount_t *dst, const uint8_t amount_be[32]) {
+    std::memcpy(dst->data, amount_be, 32);
+}
+
+void copy_amount_out(uint8_t out[32], const cma_amount_t *src) {
+    std::memcpy(out, src->data, 32);
+}
+
+int resolve_account(cma_ledger_t *ledger, const uint8_t account[20], cma_ledger_account_id_t *out_id,
+    cma_ledger_retrieve_operation_t op) {
+    cma_ledger_account_id_t account_id = 0;
+    cma_ledger_account_t account_obj{};
+    cma_ledger_account_type_t account_type = CMA_LEDGER_ACCOUNT_TYPE_WALLET_ADDRESS;
+    int rc = cma_ledger_retrieve_account(ledger, &account_id, &account_obj, account, nullptr, &account_type, op);
+    if (rc < 0) {
+        set_err_from_libcma();
+        return rc;
+    }
+    *out_id = account_id;
+    return CMA_LEDGER_SUCCESS;
+}
+
+} // namespace
+
+struct CmaNodeLedger {
+    cma_ledger_t ledger{};
+    void *owned_buffer = nullptr;
+    size_t owned_length = 0;
+    bool open = false;
+};
+
+extern "C" {
+
+CmaNodeLedger *cma_node_open_buffer(size_t max_accounts) {
+    // Single-asset estimate grows with account capacity; 4 MiB covers the default
+    // log2_max_num_of_accounts=17 drive and is safe for smaller capacities.
+    constexpr size_t kDefaultMem = 4u * 1024u * 1024u;
+    size_t mem_length = kDefaultMem;
+    if (max_accounts <= 256) {
+        mem_length = CMA_LEDGER_MIN_MEM_LENGTH;
+    }
+
+    void *buffer = std::calloc(1, mem_length);
+    if (!buffer) {
+        set_err("out of memory");
+        return nullptr;
+    }
+
+    auto *node = new (std::nothrow) CmaNodeLedger();
+    if (!node) {
+        std::free(buffer);
+        set_err("out of memory");
+        return nullptr;
+    }
+
+    int rc = cma_ledger_init_single_buffer(&node->ledger, buffer, mem_length, max_accounts,
+        CMA_LEDGER_ASSET_TYPE_BASE, nullptr);
+    if (rc < 0) {
+        set_err_from_libcma();
+        std::free(buffer);
+        delete node;
+        return nullptr;
+    }
+
+    node->owned_buffer = buffer;
+    node->owned_length = mem_length;
+    node->open = true;
+    g_last_error.clear();
+    return node;
+}
+
+CmaNodeLedger *cma_node_open_file(const char *path, size_t offset, size_t memory_length, size_t max_accounts) {
+    if (!path || memory_length == 0 || max_accounts == 0) {
+        set_err("invalid open_file arguments");
+        return nullptr;
+    }
+
+    auto *node = new (std::nothrow) CmaNodeLedger();
+    if (!node) {
+        set_err("out of memory");
+        return nullptr;
+    }
+
+    int rc = cma_ledger_init_single_file(&node->ledger, path, offset, memory_length, max_accounts,
+        CMA_LEDGER_ASSET_TYPE_BASE, nullptr);
+    if (rc < 0) {
+        set_err_from_libcma();
+        delete node;
+        return nullptr;
+    }
+
+    node->open = true;
+    g_last_error.clear();
+    return node;
+}
+
+void cma_node_close(CmaNodeLedger *ledger) {
+    if (!ledger) {
+        return;
+    }
+    if (ledger->open) {
+        (void) cma_ledger_fini(&ledger->ledger);
+        ledger->open = false;
+    }
+    if (ledger->owned_buffer) {
+        std::free(ledger->owned_buffer);
+        ledger->owned_buffer = nullptr;
+    }
+    delete ledger;
+}
+
+int cma_node_deposit_ether(CmaNodeLedger *ledger, const uint8_t account[20], const uint8_t amount_be[32]) {
+    if (!ledger || !ledger->open) {
+        set_err("ledger closed");
+        return CMA_LEDGER_ERROR_UNKNOWN;
+    }
+    if (amount_is_zero(amount_be)) {
+        return CMA_LEDGER_SUCCESS;
+    }
+
+    cma_ledger_account_id_t account_id = 0;
+    int rc = resolve_account(&ledger->ledger, account, &account_id, CMA_LEDGER_OP_FIND_OR_CREATE);
+    if (rc < 0) {
+        return rc;
+    }
+
+    cma_amount_t amount{};
+    copy_amount(&amount, amount_be);
+    // Single-asset Ether ledger: fixed asset id 0.
+    rc = cma_ledger_deposit(&ledger->ledger, 0, account_id, &amount);
+    if (rc < 0) {
+        set_err_from_libcma();
+        return rc;
+    }
+    return CMA_LEDGER_SUCCESS;
+}
+
+int cma_node_transfer_ether(CmaNodeLedger *ledger, const uint8_t from[20], const uint8_t to[20],
+    const uint8_t amount_be[32]) {
+    if (!ledger || !ledger->open) {
+        set_err("ledger closed");
+        return CMA_LEDGER_ERROR_UNKNOWN;
+    }
+    if (amount_is_zero(amount_be)) {
+        return CMA_LEDGER_SUCCESS;
+    }
+
+    cma_ledger_account_id_t from_id = 0;
+    cma_ledger_account_id_t to_id = 0;
+    int rc = resolve_account(&ledger->ledger, from, &from_id, CMA_LEDGER_OP_FIND);
+    if (rc < 0) {
+        return rc;
+    }
+    rc = resolve_account(&ledger->ledger, to, &to_id, CMA_LEDGER_OP_FIND_OR_CREATE);
+    if (rc < 0) {
+        return rc;
+    }
+
+    cma_amount_t amount{};
+    copy_amount(&amount, amount_be);
+    rc = cma_ledger_transfer(&ledger->ledger, 0, from_id, to_id, &amount);
+    if (rc < 0) {
+        set_err_from_libcma();
+        return rc;
+    }
+    return CMA_LEDGER_SUCCESS;
+}
+
+int cma_node_withdraw_ether(CmaNodeLedger *ledger, const uint8_t account[20], const uint8_t amount_be[32]) {
+    if (!ledger || !ledger->open) {
+        set_err("ledger closed");
+        return CMA_LEDGER_ERROR_UNKNOWN;
+    }
+    if (amount_is_zero(amount_be)) {
+        return CMA_LEDGER_SUCCESS;
+    }
+
+    cma_ledger_account_id_t account_id = 0;
+    int rc = resolve_account(&ledger->ledger, account, &account_id, CMA_LEDGER_OP_FIND);
+    if (rc < 0) {
+        return rc;
+    }
+
+    cma_amount_t amount{};
+    copy_amount(&amount, amount_be);
+    rc = cma_ledger_withdraw(&ledger->ledger, 0, account_id, &amount);
+    if (rc < 0) {
+        set_err_from_libcma();
+        return rc;
+    }
+    return CMA_LEDGER_SUCCESS;
+}
+
+int cma_node_get_ether_balance(CmaNodeLedger *ledger, const uint8_t account[20], uint8_t out_amount_be[32]) {
+    if (!ledger || !ledger->open) {
+        set_err("ledger closed");
+        return CMA_LEDGER_ERROR_UNKNOWN;
+    }
+
+    cma_ledger_account_id_t account_id = 0;
+    int rc = resolve_account(&ledger->ledger, account, &account_id, CMA_LEDGER_OP_FIND);
+    if (rc < 0) {
+        // Missing account → zero balance (matches memory backend semantics).
+        if (rc == CMA_LEDGER_ERROR_ACCOUNT_NOT_FOUND) {
+            std::memset(out_amount_be, 0, 32);
+            return CMA_LEDGER_SUCCESS;
+        }
+        return rc;
+    }
+
+    cma_amount_t balance{};
+    rc = cma_ledger_get_balance(&ledger->ledger, 0, account_id, &balance, nullptr);
+    if (rc < 0) {
+        if (rc == CMA_LEDGER_ERROR_BALANCE_NOT_FOUND) {
+            std::memset(out_amount_be, 0, 32);
+            return CMA_LEDGER_SUCCESS;
+        }
+        set_err_from_libcma();
+        return rc;
+    }
+    copy_amount_out(out_amount_be, &balance);
+    return CMA_LEDGER_SUCCESS;
+}
+
+const char *cma_node_last_error(void) {
+    return g_last_error.c_str();
+}
+
+const char *cma_node_kind(void) {
+    return "native-libcma";
+}
+
+} // extern "C"

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "@riseandshaheen/libcma",
+  "version": "0.1.0-alpha.0",
+  "description": "Node.js / TypeScript bindings for libcma — Cartesi proveable asset ledger",
+  "license": "MIT",
+  "author": "riseandshaheen",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/riseandshaheen/libcma-binding-node.git"
+  },
+  "type": "module",
+  "main": "./lib/index.cjs",
+  "module": "./lib/index.js",
+  "types": "./lib/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./lib/index.d.ts",
+        "default": "./lib/index.js"
+      },
+      "require": {
+        "types": "./lib/index.d.cts",
+        "default": "./lib/index.cjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "LICENSE",
+    "README.md",
+    "ARCHITECTURE.md",
+    "binding.gyp",
+    "lib/",
+    "native/",
+    "scripts/",
+    "prebuilds/",
+    "deps/machine-asset-tools/include/",
+    "deps/machine-guest-tools/sys-utils/libcmt/include/"
+  ],
+  "scripts": {
+    "clean": "rm -rf lib build",
+    "build:ts": "tsup",
+    "build:native": "node-gyp rebuild",
+    "build:libcma:riscv64": "bash scripts/build-libcma-riscv64.sh",
+    "build:native:riscv64": "bash scripts/build-native-riscv64.sh",
+    "build": "npm run build:ts",
+    "install": "node scripts/install-native.mjs",
+    "test": "npm run build:ts && node --test test/*.test.js",
+    "typecheck": "tsc --noEmit"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "node-addon-api": "^8.3.0",
+    "node-gyp-build": "^4.8.4"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.0",
+    "node-gyp": "^11.2.0",
+    "tsup": "^8.4.0",
+    "typescript": "^5.8.3"
+  },
+  "binary": {
+    "napi_versions": [8]
+  },
+  "keywords": [
+    "cartesi",
+    "rollups",
+    "libcma",
+    "ledger",
+    "emergency-withdrawal"
+  ]
+}

package/scripts/build-libcma-riscv64.sh

@@ -0,0 +1,80 @@
+#!/usr/bin/env bash
+# Cross-build (or native-build on riscv64) libcma.a into
+# deps/machine-asset-tools/build/riscv64/libcma.a
+#
+# Mirrors libcma_binding_rust/build.rs. Requires:
+#   - GNU make, wget, network
+#   - On non-riscv64 hosts: g++-14-riscv64-linux-gnu / gcc-14-riscv64-linux-gnu
+#     (override with CMA_RISCV64_CXX / CMA_RISCV64_CC)
+#   - Or run inside a riscv64 container / Cartesi SDK image (native gcc)
+
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+MAT="${ROOT}/deps/machine-asset-tools"
+OUT="${MAT}/build/riscv64/libcma.a"
+
+if [[ ! -d "${MAT}/include" ]]; then
+  echo "error: ${MAT}/include missing — clone machine-asset-tools into deps/" >&2
+  exit 1
+fi
+
+if [[ -f "${OUT}" && "${LIBCMA_FORCE_REBUILD:-}" != "1" ]]; then
+  echo "[libcma] ${OUT} already exists (set LIBCMA_FORCE_REBUILD=1 to rebuild)"
+  exit 0
+fi
+
+ARCH="$(uname -m)"
+NLOHMANN="${MAT}/third-party/nlohmann/json.hpp"
+mkdir -p "${MAT}/third-party/nlohmann"
+
+if [[ ! -f "${NLOHMANN}" ]]; then
+  echo "[libcma] fetching nlohmann/json.hpp"
+  wget -qO "${NLOHMANN}" \
+    https://github.com/nlohmann/json/releases/download/v3.12.0/json.hpp
+fi
+
+cd "${MAT}"
+
+if [[ "${ARCH}" == "riscv64" ]]; then
+  echo "[libcma] native riscv64 build"
+  # Makefile uses `CXX := g++` (overrides env); pass on the command line.
+  # Prefer g++-14 when present (-fhardened needs GCC ≥ 14).
+  if [[ -z "${CXX:-}" ]]; then
+    if command -v g++-14 >/dev/null 2>&1; then
+      CXX=g++-14
+    else
+      CXX=g++
+    fi
+  fi
+  if [[ -z "${CC:-}" ]]; then
+    if command -v gcc-14 >/dev/null 2>&1; then
+      CC=gcc-14
+    else
+      CC=gcc
+    fi
+  fi
+  echo "[libcma] using CXX=${CXX} CC=${CC}"
+  make third-party "CXX=${CXX}" "CC=${CC}"
+  make build/riscv64/libcma.a "CXX=${CXX}" "CC=${CC}" "AR=${AR:-ar}"
+else
+  CXX="${CMA_RISCV64_CXX:-riscv64-linux-gnu-g++-14}"
+  CC="${CMA_RISCV64_CC:-riscv64-linux-gnu-gcc-14}"
+  if ! command -v "${CXX}" >/dev/null 2>&1; then
+    echo "error: ${CXX} not found." >&2
+    echo "Install the RISC-V GCC 14 cross toolchain, or run this script on riscv64 / in Docker." >&2
+    echo "Example (Debian/Ubuntu): apt-get install g++-14-riscv64-linux-gnu" >&2
+    exit 1
+  fi
+  echo "[libcma] cross-building with ${CXX}"
+  make third-party TOOLCHAIN_PREFIX=riscv64-linux-gnu-
+  make build/riscv64/libcma.a \
+    TOOLCHAIN_PREFIX=riscv64-linux-gnu- \
+    "CXX=${CXX}" \
+    "CC=${CC}" \
+    AR=riscv64-linux-gnu-ar
+fi
+
+test -f "${OUT}"
+echo "[libcma] wrote ${OUT}"
+ls -lh "${OUT}"

package/scripts/build-native-riscv64.sh

@@ -0,0 +1,40 @@
+#!/usr/bin/env bash
+# Build the N-API addon for linux-riscv64 against real libcma.a.
+# Intended to run inside a riscv64 Node image (or qemu-user), e.g.:
+#
+#   docker run --rm --platform linux/riscv64 -v "$PWD":/work -w /work \
+#     cartesi/node:22.14.0-noble \
+#     bash -lc 'apt-get update && apt-get install -y build-essential python3 make g++ wget &&
+#               npm ci && npm run build:libcma:riscv64 && npm run build:native'
+#
+# Produces: build/Release/cma_napi.node with kind === "native-libcma"
+
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+cd "${ROOT}"
+
+if [[ "$(uname -m)" != "riscv64" && "${LIBCMA_FORCE_REAL:-}" != "1" ]]; then
+  echo "warning: host is $(uname -m); set LIBCMA_FORCE_REAL=1 only if libcma.a matches this arch." >&2
+fi
+
+bash "${ROOT}/scripts/build-libcma-riscv64.sh"
+
+export LIBCMA_FORCE_REAL=1
+export LIBCMA_LIB_DIR="${LIBCMA_LIB_DIR:-${ROOT}/deps/machine-asset-tools/build/riscv64}"
+
+npm run build:native
+
+node -e "
+const { createRequire } = require('module');
+const requireFromRoot = createRequire(require('path').join('${ROOT}', 'package.json'));
+const binding = requireFromRoot('node-gyp-build')('${ROOT}');
+const l = binding.openEtherBuffer(8);
+console.log('kind=', l.kind);
+if (l.kind !== 'native-libcma') {
+  console.error('expected native-libcma, got', l.kind);
+  process.exit(1);
+}
+l.close();
+console.log('ok: real libcma backend loaded');
+"

package/scripts/install-native.mjs

@@ -0,0 +1,94 @@
+/**
+ * Native install:
+ * - Prefer prebuild / existing .node
+ * - On riscv64 (or LIBCMA_FORCE_REAL=1): ensure libcma.a then rebuild against real libcma
+ * - Else: host mock addon (best-effort; memory backend always works)
+ */
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { arch } from "node:os";
+
+const root = join(dirname(fileURLToPath(import.meta.url)), "..");
+const require = createRequire(import.meta.url);
+
+if (process.env.LIBCMA_SKIP_NATIVE === "1") {
+  console.log("[libcma] LIBCMA_SKIP_NATIVE=1 — skipping native build");
+  process.exit(0);
+}
+
+const useReal =
+  process.env.LIBCMA_FORCE_REAL === "1" || arch() === "riscv64";
+
+try {
+  const binding = require("node-gyp-build")(root);
+  // If we need real libcma but an old mock prebuild loaded, rebuild.
+  if (useReal) {
+    const probe = binding.openEtherBuffer?.(4);
+    const kind = probe?.kind;
+    probe?.close?.();
+    if (kind === "native-libcma") {
+      console.log("[libcma] native-libcma addon ready");
+      process.exit(0);
+    }
+    console.log(`[libcma] found addon kind=${kind}; rebuilding for real libcma`);
+  } else {
+    console.log("[libcma] native addon loaded (prebuild or previous build)");
+    process.exit(0);
+  }
+} catch {
+  // Fall through to compile.
+}
+
+if (!existsSync(join(root, "binding.gyp"))) {
+  process.exit(0);
+}
+
+if (useReal) {
+  const libPath = join(
+    root,
+    process.env.LIBCMA_LIB_DIR || "deps/machine-asset-tools/build/riscv64",
+    "libcma.a",
+  );
+  if (!existsSync(libPath)) {
+    console.log("[libcma] building libcma.a for riscv64…");
+    const built = spawnSync("bash", ["scripts/build-libcma-riscv64.sh"], {
+      cwd: root,
+      stdio: "inherit",
+    });
+    if (built.status !== 0) {
+      console.warn(
+        "[libcma] failed to build libcma.a — install cross toolchain or run on riscv64.",
+      );
+      process.exit(0);
+    }
+  }
+}
+
+const env = { ...process.env };
+if (useReal) {
+  env.LIBCMA_FORCE_REAL = "1";
+}
+
+const result = spawnSync(
+  process.platform === "win32" ? "node-gyp.cmd" : "node-gyp",
+  ["rebuild"],
+  {
+    cwd: root,
+    stdio: "inherit",
+    shell: process.platform === "win32",
+    env,
+  },
+);
+
+if (result.status !== 0) {
+  console.warn(
+    "[libcma] native build failed — TypeScript memory backend remains available for host use.",
+  );
+  console.warn(
+    "[libcma] Set LIBCMA_SKIP_NATIVE=1 to silence this, or install build tools and retry `npm run build:native`.",
+  );
+  process.exit(0);
+}