@cartesi/cli 0.14.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2024 Cartesi and individual contributors
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,19 @@
+# Cartesi CLI
+
+Cartesi CLI provides a tool to help developers to:
+
+-   `create` applications from templates
+-   `build` applications from source to a cartesi machine
+-   `run` applications in a local development environment
+-   `deploy` applications to a live network
+
+It's distributed through several channels including `npm` and `homebrew`.
+
+## Installation
+
+```shell
+brew install cartesi/tap/cartesi
+cartesi --help
+```
+
+More documentation at [https://docs.cartesi.io](https://docs.cartesi.io).

package/bin/dev.cmd

@@ -0,0 +1,3 @@
+@echo off
+
+node "%~dp0\dev" %*

package/bin/dev.js

@@ -0,0 +1,25 @@
+#!/usr/bin/env node --no-warnings=ExperimentalWarning --loader ts-node/esm
+
+import oclif from "@oclif/core";
+import path from "node:path";
+import url from "node:url";
+import { register } from "ts-node";
+
+// In dev mode -> use ts-node and dev plugins
+process.env.NODE_ENV = "development";
+
+const project = path.join(
+    path.dirname(url.fileURLToPath(import.meta.url)),
+    "..",
+    "tsconfig.json"
+);
+register({ project });
+
+// In dev mode, always show stack traces
+oclif.settings.debug = true;
+
+// Start the CLI
+oclif
+    .run(process.argv.slice(2), import.meta.url)
+    .then(oclif.flush)
+    .catch(oclif.Errors.handle);

package/bin/run.cmd

@@ -0,0 +1,3 @@
+@echo off
+
+node "%~dp0\run" %*

package/bin/run.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+
+import oclif from "@oclif/core";
+
+oclif
+    .run(process.argv.slice(2), import.meta.url)
+    .then(oclif.flush)
+    .catch(oclif.Errors.handle);

package/dist/baseCommand.d.ts

@@ -0,0 +1,26 @@
+import { Command, Interfaces } from "@oclif/core";
+import { Address, Hash } from "viem";
+export type Flags<T extends typeof Command> = Interfaces.InferredFlags<(typeof BaseCommand)["baseFlags"] & T["flags"]>;
+export type Args<T extends typeof Command> = Interfaces.InferredArgs<T["args"]>;
+export type AddressBook = Record<string, Address>;
+export interface DApp {
+    address: Address;
+    blockHash: Address;
+    blockNumber: number;
+    transactionHash: Address;
+}
+export declare abstract class BaseCommand<T extends typeof Command> extends Command {
+    protected flags: Flags<T>;
+    protected args: Args<T>;
+    protected getServiceState(projectName: string, serviceName: string): Promise<string | undefined>;
+    protected getContextPath(...paths: string[]): string;
+    protected getMachineHash(): Hash | undefined;
+    protected logPrompt({ title, value }: {
+        title: string;
+        value: string;
+    }): void;
+    protected getApplicationAddress(): Promise<Address | undefined>;
+    protected getAddressBook(): Promise<AddressBook>;
+    init(): Promise<void>;
+}
+//# sourceMappingURL=baseCommand.d.ts.map

package/dist/baseCommand.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"baseCommand.d.ts","sourceRoot":"","sources":["../src/baseCommand.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAKlD,OAAO,EAAE,OAAO,EAAE,IAAI,EAAU,MAAM,MAAM,CAAC;AAmB7C,MAAM,MAAM,KAAK,CAAC,CAAC,SAAS,OAAO,OAAO,IAAI,UAAU,CAAC,aAAa,CAClE,CAAC,OAAO,WAAW,CAAC,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,CACjD,CAAC;AACF,MAAM,MAAM,IAAI,CAAC,CAAC,SAAS,OAAO,OAAO,IAAI,UAAU,CAAC,YAAY,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC;AAEhF,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAClD,MAAM,WAAW,IAAI;IACjB,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,EAAE,OAAO,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,eAAe,EAAE,OAAO,CAAC;CAC5B;AAED,8BAAsB,WAAW,CAAC,CAAC,SAAS,OAAO,OAAO,CAAE,SAAQ,OAAO;IACvE,SAAS,CAAC,KAAK,EAAG,KAAK,CAAC,CAAC,CAAC,CAAC;IAC3B,SAAS,CAAC,IAAI,EAAG,IAAI,CAAC,CAAC,CAAC,CAAC;cAET,eAAe,CAC3B,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,MAAM,GACpB,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC;IAe9B,SAAS,CAAC,cAAc,CAAC,GAAG,KAAK,EAAE,MAAM,EAAE,GAAG,MAAM;IAIpD,SAAS,CAAC,cAAc,IAAI,IAAI,GAAG,SAAS;IAY5C,SAAS,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE;cAItD,qBAAqB,IAAI,OAAO,CAAC,OAAO,GAAG,SAAS,CAAC;cAKrD,cAAc,IAAI,OAAO,CAAC,WAAW,CAAC;IA0BzC,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CAYrC"}

package/dist/baseCommand.js

@@ -0,0 +1,80 @@
+import { Command } from "@oclif/core";
+import chalk from "chalk";
+import { execa } from "execa";
+import fs from "fs";
+import path from "path";
+import { isHash } from "viem";
+import { authorityHistoryPairFactoryAddress, cartesiDAppFactoryAddress, dAppAddressRelayAddress, erc1155BatchPortalAddress, erc1155SinglePortalAddress, erc20PortalAddress, erc721PortalAddress, etherPortalAddress, inputBoxAddress, selfHostedApplicationFactoryAddress, testMultiTokenAddress, testNftAddress, testTokenAddress, } from "./contracts.js";
+export class BaseCommand extends Command {
+    async getServiceState(projectName, serviceName) {
+        // get service information
+        const { stdout } = await execa("docker", [
+            "compose",
+            "--project-name",
+            projectName,
+            "ps",
+            serviceName,
+            "--format",
+            "json",
+        ]);
+        const ps = stdout ? JSON.parse(stdout) : undefined;
+        return ps?.State;
+    }
+    getContextPath(...paths) {
+        return path.join(".cartesi", ...paths);
+    }
+    getMachineHash() {
+        // read hash of the cartesi machine snapshot, if one exists
+        const hashPath = this.getContextPath("image", "hash");
+        if (fs.existsSync(hashPath)) {
+            const hash = fs.readFileSync(hashPath).toString("hex");
+            if (isHash(`0x${hash}`)) {
+                return `0x${hash}`;
+            }
+        }
+        return undefined;
+    }
+    logPrompt({ title, value }) {
+        this.log(`${chalk.green("?")} ${title} ${chalk.cyan(value)}`);
+    }
+    async getApplicationAddress() {
+        // fixed value, as we do deterministic deployment with a zero hash
+        return "0xab7528bb862fb57e8a2bcd567a2e929a0be56a5e";
+    }
+    async getAddressBook() {
+        // build rollups contracts address book
+        const contracts = {
+            AuthorityHistoryPairFactory: authorityHistoryPairFactoryAddress,
+            CartesiDAppFactory: cartesiDAppFactoryAddress,
+            DAppAddressRelay: dAppAddressRelayAddress,
+            ERC1155BatchPortal: erc1155BatchPortalAddress,
+            ERC1155SinglePortal: erc1155SinglePortalAddress,
+            ERC20Portal: erc20PortalAddress,
+            ERC721Portal: erc721PortalAddress,
+            EtherPortal: etherPortalAddress,
+            InputBox: inputBoxAddress,
+            SelfHostedApplicationFactory: selfHostedApplicationFactoryAddress,
+            TestToken: testTokenAddress,
+            TestNFT: testNftAddress,
+            TestMultiToken: testMultiTokenAddress,
+        };
+        // get dapp address
+        const applicationAddress = await this.getApplicationAddress();
+        if (applicationAddress) {
+            contracts["CartesiDApp"] = applicationAddress;
+        }
+        return contracts;
+    }
+    async init() {
+        await super.init();
+        const { args, flags } = await this.parse({
+            flags: this.ctor.flags,
+            baseFlags: super.ctor.baseFlags,
+            args: this.ctor.args,
+            enableJsonFlag: this.ctor.enableJsonFlag,
+            strict: this.ctor.strict,
+        });
+        this.flags = flags;
+        this.args = args;
+    }
+}

package/dist/commands/address-book.d.ts

@@ -0,0 +1,9 @@
+import { AddressBook as AddressBookType, BaseCommand } from "../baseCommand.js";
+export default class AddressBook extends BaseCommand<typeof AddressBook> {
+    static summary: string;
+    static description: string;
+    static examples: string[];
+    static enableJsonFlag: boolean;
+    run(): Promise<AddressBookType>;
+}
+//# sourceMappingURL=address-book.d.ts.map

package/dist/commands/address-book.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"address-book.d.ts","sourceRoot":"","sources":["../../src/commands/address-book.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,WAAW,IAAI,eAAe,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAEhF,MAAM,CAAC,OAAO,OAAO,WAAY,SAAQ,WAAW,CAAC,OAAO,WAAW,CAAC;IACpE,MAAM,CAAC,OAAO,SAAmD;IAEjE,MAAM,CAAC,WAAW,SACwF;IAE1G,MAAM,CAAC,QAAQ,WAA2C;IAE1D,OAAc,cAAc,UAAQ;IAEvB,GAAG,IAAI,OAAO,CAAC,eAAe,CAAC;CAe/C"}

package/dist/commands/address-book.js

@@ -0,0 +1,21 @@
+import { ux } from "@oclif/core";
+import { BaseCommand } from "../baseCommand.js";
+class AddressBook extends BaseCommand {
+    async run() {
+        const addressBook = await super.getAddressBook();
+        if (!this.jsonEnabled()) {
+            // print as a table
+            ux.table(Object.entries(addressBook).map(([name, address]) => ({
+                name,
+                address,
+            })), { name: { header: "Contract" }, address: {} });
+        }
+        // return (as json)
+        return addressBook;
+    }
+}
+AddressBook.summary = "Prints addresses of smart contracts deployed.";
+AddressBook.description = "Prints the addresses of all smart contracts deployed to the runtime environment of the application.";
+AddressBook.examples = ["<%= config.bin %> <%= command.id %>"];
+AddressBook.enableJsonFlag = true;
+export default AddressBook;

package/dist/commands/build.d.ts

@@ -0,0 +1,24 @@
+import { BaseCommand } from "../baseCommand.js";
+export default class BuildApplication extends BaseCommand<typeof BuildApplication> {
+    static summary: string;
+    static description: string;
+    static examples: string[];
+    static args: {};
+    static flags: {
+        "from-image": import("@oclif/core/lib/interfaces/parser.js").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces/parser.js").CustomOptions>;
+        target: import("@oclif/core/lib/interfaces/parser.js").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces/parser.js").CustomOptions>;
+    };
+    /**
+     * Build DApp image (linux/riscv64). Returns image id.
+     * @param directory path of context containing Dockerfile
+     */
+    private buildImage;
+    private getImageInfo;
+    private createTarball;
+    private sdkRun;
+    private static createRootfsTarCommand;
+    private static createExt2Command;
+    private static createMachineSnapshotCommand;
+    run(): Promise<void>;
+}
+//# sourceMappingURL=build.d.ts.map

package/dist/commands/build.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build.d.ts","sourceRoot":"","sources":["../../src/commands/build.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAyBhD,MAAM,CAAC,OAAO,OAAO,gBAAiB,SAAQ,WAAW,CACrD,OAAO,gBAAgB,CAC1B;IACG,MAAM,CAAC,OAAO,SAAwB;IAEtC,MAAM,CAAC,WAAW,SAC8V;IAEhX,MAAM,CAAC,QAAQ,WAGb;IAEF,MAAM,CAAC,IAAI,KAAM;IAEjB,MAAM,CAAC,KAAK;;;MAWV;IAEF;;;OAGG;YACW,UAAU;YAcV,YAAY;YAkEZ,aAAa;YAgBb,MAAM;IA+BpB,OAAO,CAAC,MAAM,CAAC,sBAAsB;IAoBrC,OAAO,CAAC,MAAM,CAAC,iBAAiB;IAkBhC,OAAO,CAAC,MAAM,CAAC,4BAA4B;IA4B9B,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC;CA0DpC"}

package/dist/commands/build.js

@@ -0,0 +1,219 @@
+import { Flags } from "@oclif/core";
+import bytes from "bytes";
+import { execa } from "execa";
+import fs from "fs-extra";
+import semver from "semver";
+import tmp from "tmp";
+import { BaseCommand } from "../baseCommand.js";
+import { DEFAULT_TEMPLATES_BRANCH } from "./create.js";
+const CARTESI_LABEL_PREFIX = "io.cartesi.rollups";
+const CARTESI_LABEL_RAM_SIZE = `${CARTESI_LABEL_PREFIX}.ram_size`;
+const CARTESI_LABEL_DATA_SIZE = `${CARTESI_LABEL_PREFIX}.data_size`;
+const CARTESI_DEFAULT_RAM_SIZE = "128Mi";
+const CARTESI_LABEL_SDK_VERSION = `${CARTESI_LABEL_PREFIX}.sdk_version`;
+const CARTESI_DEFAULT_SDK_VERSION = "0.6.0";
+class BuildApplication extends BaseCommand {
+    /**
+     * Build DApp image (linux/riscv64). Returns image id.
+     * @param directory path of context containing Dockerfile
+     */
+    async buildImage(options) {
+        const buildResult = tmp.tmpNameSync();
+        this.debug(`building docker image and writing result to ${buildResult}`);
+        const args = ["buildx", "build", "--load", "--iidfile", buildResult];
+        if (options.target) {
+            args.push("--target", options.target);
+        }
+        await execa("docker", [...args, process.cwd()], { stdio: "inherit" });
+        return fs.readFileSync(buildResult, "utf8");
+    }
+    async getImageInfo(image) {
+        const { stdout: jsonStr } = await execa("docker", [
+            "image",
+            "inspect",
+            image,
+        ]);
+        // parse image info from docker inspect output
+        const [imageInfo] = JSON.parse(jsonStr);
+        // validate image architecture (must be riscv64)
+        if (imageInfo["Architecture"] !== "riscv64") {
+            throw new Error(`Invalid image Architecture: ${imageInfo["Architecture"]}. Expected riscv64`);
+        }
+        const labels = imageInfo["Config"]["Labels"] || {};
+        const info = {
+            cmd: imageInfo["Config"]["Cmd"] ?? [],
+            dataSize: labels[CARTESI_LABEL_DATA_SIZE] ?? "10Mb",
+            entrypoint: imageInfo["Config"]["Entrypoint"] ?? [],
+            env: imageInfo["Config"]["Env"] || [],
+            ramSize: labels[CARTESI_LABEL_RAM_SIZE] ?? CARTESI_DEFAULT_RAM_SIZE,
+            sdkVersion: labels[CARTESI_LABEL_SDK_VERSION] ??
+                CARTESI_DEFAULT_SDK_VERSION,
+            workdir: imageInfo["Config"]["WorkingDir"],
+        };
+        if (!info.entrypoint && !info.cmd) {
+            throw new Error("Undefined image ENTRYPOINT or CMD");
+        }
+        // fail if using unsupported sdk version
+        if (!semver.valid(info.sdkVersion)) {
+            this.warn("sdk version is not a valid semver");
+        }
+        else if (semver.lt(info.sdkVersion, CARTESI_DEFAULT_SDK_VERSION)) {
+            throw new Error(`Unsupported sdk version: ${info.sdkVersion} (used) < ${CARTESI_DEFAULT_SDK_VERSION} (minimum).
+Update your application Dockerfile using one of the templates at https://github.com/cartesi/application-templates/tree/${DEFAULT_TEMPLATES_BRANCH}
+`);
+        }
+        // warn for using default values
+        info.sdkVersion ||
+            this.warn(`Undefined ${CARTESI_LABEL_SDK_VERSION} label, defaulting to ${CARTESI_DEFAULT_SDK_VERSION}`);
+        info.ramSize ||
+            this.warn(`Undefined ${CARTESI_LABEL_RAM_SIZE} label, defaulting to ${CARTESI_DEFAULT_RAM_SIZE}`);
+        // validate data size value
+        if (bytes(info.dataSize) === null) {
+            throw new Error(`Invalid ${CARTESI_LABEL_DATA_SIZE} value: ${info.dataSize}`);
+        }
+        // XXX: validate other values
+        return info;
+    }
+    // saves the OCI Image to a tarball
+    async createTarball(image, outputFilePath) {
+        // create docker tarball from app image
+        const { stdout: appCid } = await execa("docker", [
+            "image",
+            "save",
+            image,
+            "-o",
+            outputFilePath,
+        ]);
+    }
+    // this wraps the call to the sdk image with a one-shot approach
+    // the (inputPath, outputPath) signature will mount the input as a volume and copy the output with docker cp
+    async sdkRun(sdkImage, cmd, inputPath, outputPath) {
+        const { stdout: cid } = await execa("docker", [
+            "container",
+            "create",
+            "--volume",
+            `./${inputPath}:/tmp/input`,
+            sdkImage,
+            ...cmd,
+        ]);
+        await execa("docker", ["container", "start", "-a", cid], {
+            stdio: "inherit",
+        });
+        await execa("docker", [
+            "container",
+            "cp",
+            `${cid}:/tmp/output`,
+            outputPath,
+        ]);
+        await execa("docker", ["container", "stop", cid]);
+        await execa("docker", ["container", "rm", cid]);
+    }
+    // returns the command to create rootfs tarball from an OCI Image tarball
+    static createRootfsTarCommand() {
+        const cmd = [
+            "cat",
+            "/tmp/input",
+            "|",
+            "crane",
+            "export",
+            "-", // OCI Image from stdin
+            "-", // rootfs tarball to stdout
+            "|",
+            "bsdtar",
+            "-cf",
+            "/tmp/output",
+            "--format=gnutar",
+            "@/dev/stdin", // rootfs tarball from stdin
+        ];
+        return ["/usr/bin/env", "bash", "-c", cmd.join(" ")];
+    }
+    // returns the command to create ext2 from a rootfs
+    static createExt2Command(extraBytes) {
+        const blockSize = 4096;
+        const extraBlocks = Math.ceil(extraBytes / blockSize);
+        const extraSize = `+${extraBlocks}`;
+        return [
+            "xgenext2fs",
+            "--tarball",
+            "/tmp/input",
+            "--block-size",
+            blockSize.toString(),
+            "--faketime",
+            "-r",
+            extraSize,
+            "/tmp/output",
+        ];
+    }
+    static createMachineSnapshotCommand(info) {
+        const ramSize = info.ramSize;
+        const driveLabel = "root"; // XXX: does this need to be customizable?
+        // list of environment variables of docker image
+        const envs = info.env.map((variable) => `--append-entrypoint=export ${variable}`);
+        // ENTRYPOINT and CMD as a space separated string
+        const entrypoint = [...info.entrypoint, ...info.cmd].join(" ");
+        // command to change working directory if WORKDIR is defined
+        const cwd = info.workdir ? `--append-init=WORKDIR=${info.workdir}` : "";
+        return [
+            "cartesi-machine",
+            "--assert-rolling-template",
+            `--ram-length=${ramSize}`,
+            `--flash-drive=label:${driveLabel},filename:/tmp/input`,
+            "--final-hash",
+            `--store=/tmp/output`,
+            "--append-bootargs=no4lvl",
+            cwd,
+            ...envs,
+            `--append-entrypoint=${entrypoint}`,
+        ];
+    }
+    async run() {
+        const { flags } = await this.parse(BuildApplication);
+        const snapshotPath = this.getContextPath("image");
+        const tarPath = this.getContextPath("image.tar");
+        const gnuTarPath = this.getContextPath("image.gnutar");
+        const ext2Path = this.getContextPath("image.ext2");
+        // clean up temp files we create along the process
+        tmp.setGracefulCleanup();
+        // use pre-existing image or build dapp image
+        const appImage = flags["from-image"] || (await this.buildImage(flags));
+        // prepare context directory
+        await fs.emptyDir(this.getContextPath()); // XXX: make it less error prone
+        // get and validate image info
+        const imageInfo = await this.getImageInfo(appImage);
+        // resolve sdk version
+        const sdkImage = `cartesi/sdk:${imageInfo.sdkVersion}`;
+        try {
+            // create docker tarball for image specified
+            await this.createTarball(appImage, tarPath);
+            // create rootfs tar
+            await this.sdkRun(sdkImage, BuildApplication.createRootfsTarCommand(), tarPath, gnuTarPath);
+            // create ext2
+            await this.sdkRun(sdkImage, BuildApplication.createExt2Command(bytes.parse(imageInfo.dataSize)), gnuTarPath, ext2Path);
+            // create machine snapshot
+            await this.sdkRun(sdkImage, BuildApplication.createMachineSnapshotCommand(imageInfo), ext2Path, snapshotPath);
+            await fs.chmod(snapshotPath, 0o755);
+        }
+        finally {
+            await fs.remove(gnuTarPath);
+            await fs.remove(tarPath);
+        }
+    }
+}
+BuildApplication.summary = "Build application.";
+BuildApplication.description = "Build application starting from a Dockerfile and ending with a snapshot of the corresponding Cartesi Machine already booted and yielded for the first time. This snapshot can be used to start a Cartesi node for the application using `run`. The process can also start from a Docker image built by the developer using `docker build` using the option `--from-image`";
+BuildApplication.examples = [
+    "<%= config.bin %> <%= command.id %>",
+    "<%= config.bin %> <%= command.id %> --from-image my-app",
+];
+BuildApplication.args = {};
+BuildApplication.flags = {
+    "from-image": Flags.string({
+        summary: "skip docker build and start from this image.",
+        description: "if the build process of the application Dockerfile needs more control the developer can build the image using the `docker build` command, and then start the build process of the Cartesi machine starting from that image.",
+    }),
+    target: Flags.string({
+        summary: "target of docker multi-stage build.",
+        description: "if the application Dockerfile uses a multi-stage strategy, and stage of the image to be exported as a Cartesi machine is not the last stage, use this parameter to specify the target stage.",
+    }),
+};
+export default BuildApplication;