# CartesiMachine

## Interface

This is the complete TypeScript interface of a `machine` object.
Descriptions for each method are in the following sections.

```ts
export interface CartesiMachine {
    //// Machine Lifecycle
    isEmpty(): boolean;
    isJsonrpcMachine(): boolean;
    create(
        config: MachineConfig,
        runtimeConfig?: MachineRuntimeConfig,
        dir?: string,
    ): void;
    load(
        dir: string,
        runtimeConfig?: MachineRuntimeConfig,
        sharing?: SharingMode,
    ): void;
    cloneEmpty(): CartesiMachine;
    store(dir: string, sharing?: SharingMode): void;
    cloneStored(fromDir: string, toDir: string): void;
    renameStored(fromDir: string, toDir: string): void;
    removeStored(dir: string): void;
    syncStored(dir: string): void;
    destroy(): void;
    
    //// Configuration
    getDefaultConfig(): MachineConfig;
    getInitialConfig(): MachineConfig;
    setRuntimeConfig(runtimeConfig: MachineRuntimeConfig): void;
    getRuntimeConfig(): MachineRuntimeConfig;
    getAddressRanges(): AddressRangeDescription[];

    //// Memory Operations
    replaceMemoryRange(rangeConfig: MemoryRangeConfig): void;
    readWord(address: bigint): bigint;
    writeWord(address: bigint, value: bigint): void;
    readMemory(address: bigint, length: bigint): Buffer;
    writeMemory(address: bigint, data: Buffer): void;
    readVirtualMemory(address: bigint, length: bigint): Buffer;
    writeVirtualMemory(address: bigint, data: Buffer): void;
    translateVirtualAddress(vaddr: bigint): bigint;

    //// Register Operations
    getRegAddress(reg: Reg): bigint;
    readReg(reg: Reg): bigint;
    writeReg(reg: Reg, value: bigint): void;

    //// Execution
    run(mcycleEnd?: bigint): BreakReason;
    runUarch(uarchCycleEnd: bigint): UarchBreakReason;
    resetUarch(): void;

    //// Hash Tree Operations
    getRootHash(): Buffer;
    readRevertRootHash(): Buffer;
    writeRevertRootHash(hash: Buffer): void;
    getNodeHash(address: bigint, log2Size: number): Buffer;
    getProof(address: bigint, log2Size: number, log2RootSize?: number): Proof;
    verifyHashTree(): boolean;
    getHashTreeStats(clear?: boolean): HashTreeStats;

    //// Execution Log
    logStep(mcycleCount: bigint, logFilename: string): BreakReason;
    logStepUarch(logType: AccessLogType): AccessLog;
    logResetUarch(logType: AccessLogType): AccessLog;
    logSendCmioResponse(
        reason: HtifYieldReason,
        data: Buffer,
        logType: AccessLogType,
        revertRootHash?: Buffer,
    ): string;

    //// Verification
    verifyStepUarch(rootHashBefore: Buffer, log: AccessLog): Buffer;
    verifyResetUarch(rootHashBefore: Buffer, log: AccessLog): Buffer;

    //// CMIO Operations
    sendCmioResponse(
        reason: HtifYieldReason,
        data: Buffer,
        revertRootHash?: Buffer,
    ): void;
    receiveCmioRequest(): {
        cmd: HtifYieldCommand;
        reason: HtifYieldReason;
        data: Buffer;
    };

    //// Address Introspection
    getAddressName(paddr: bigint): string;
}
```

## isEmpty

Checks if the machine object is empty (does not hold a machine instance).

```ts
isEmpty(): boolean;
```

## isJsonrpcMachine

Checks if the machine object is a remote machine controlled via the JSON-RPC API.

```ts
isJsonrpcMachine(): boolean;
```

## create

Creates a new machine instance from the given configuration and optional runtime configuration. The machine object must be empty. The optional `dir` sets the directory for on-disk backing stores.

```ts
create(
    config: MachineConfig,
    runtimeConfig?: MachineRuntimeConfig,
    dir?: string,
): void;
```

## load

Loads a machine instance from a previously stored directory, with optional runtime configuration. The machine object must be empty. The `sharing` mode controls whether machine changes stay in-memory (`SharingMode.None`, the default) or are reflected on-disk.

```ts
load(
    dir: string,
    runtimeConfig?: MachineRuntimeConfig,
    sharing?: SharingMode,
): void;
```

## cloneEmpty

Clones an empty machine object from an existing one. The new object is empty and of the same type (local or remote) as the original.

```ts
cloneEmpty(): CartesiMachine;
```

## store

Stores the current machine instance to a directory, serializing its entire state. Will not overwrite an existing directory. The `sharing` mode defaults to `SharingMode.All` (store the full current state).

```ts
store(dir: string, sharing?: SharingMode): void;
```

## cloneStored

Clones a stored machine directory.

```ts
cloneStored(fromDir: string, toDir: string): void;
```

## renameStored

Renames a stored machine directory and makes the rename durable. The source and destination must be on the same filesystem.

```ts
renameStored(fromDir: string, toDir: string): void;
```

## removeStored

Removes a stored machine directory.

```ts
removeStored(dir: string): void;
```

## syncStored

Flushes all files of a previously stored machine to permanent storage. The expected usage is to sync after the machine using the stored files has been closed.

```ts
syncStored(dir: string): void;
```

## destroy

Destroys the current machine instance and removes it from the object. Does not delete the machine object itself.

```ts
destroy(): void;
```

## getDefaultConfig

Returns the default machine configuration. The returned config is not sufficient to run a machine; additional fields must be set.

```ts
getDefaultConfig(): MachineConfig;
```

## getInitialConfig

Returns the initial configuration used to create the current machine instance.

```ts
getInitialConfig(): MachineConfig;
```

## setRuntimeConfig

Changes the machine runtime configuration.

```ts
setRuntimeConfig(runtimeConfig: MachineRuntimeConfig): void;
```

## getRuntimeConfig

Returns the current machine runtime configuration.

```ts
getRuntimeConfig(): MachineRuntimeConfig;
```

## getAddressRanges

Returns a list of all address ranges in the machine.

```ts
getAddressRanges(): AddressRangeDescription[];
```

## replaceMemoryRange

Replaces a memory range in the machine. The new range must match an existing range's start and length.

```ts
replaceMemoryRange(rangeConfig: MemoryRangeConfig): void;
```

## readWord

Reads a 64-bit word from memory at the given physical address.

```ts
readWord(address: bigint): bigint;
```

## writeWord

Writes a 64-bit word to memory at the given physical address.

```ts
writeWord(address: bigint, value: bigint): void;
```

## readMemory

Reads a chunk of data from memory at the given physical address and length.

```ts
readMemory(address: bigint, length: bigint): Buffer;
```

## writeMemory

Writes a chunk of data to memory at the given physical address and length.

```ts
writeMemory(address: bigint, data: Buffer): void;
```

## readVirtualMemory

Reads a chunk of data from memory at the given virtual address and length, using the current address mapping.

```ts
readVirtualMemory(address: bigint, length: bigint): Buffer;
```

## writeVirtualMemory

Writes a chunk of data to memory at the given virtual address and length, using the current address mapping.

```ts
writeVirtualMemory(address: bigint, data: Buffer): void;
```

## translateVirtualAddress

Translates a virtual memory address to its corresponding physical memory address.

```ts
translateVirtualAddress(vaddr: bigint): bigint;
```

## getRegAddress

Returns the address of a register.

```ts
getRegAddress(reg: Reg): bigint;
```

## readReg

Reads the value of a register.

```ts
readReg(reg: Reg): bigint;
```

## writeReg

Writes a value to a register.

```ts
writeReg(reg: Reg, value: bigint): void;
```

## run

Runs the machine until the given cycle, or until it yields or halts. If no argument is provided, runs until `MAX_MCYCLE` (the maximum cycle value), which is equivalent to running until the machine yields or halts.

```ts
run(mcycleEnd?: bigint): BreakReason;
```

**Note:** `MAX_MCYCLE` is exported as a constant and can be used to explicitly specify the maximum cycle value.

## runUarch

Runs the machine microarchitecture until the given micro cycle or until it halts.

```ts
runUarch(uarchCycleEnd: bigint): UarchBreakReason;
```

## resetUarch

Resets the entire microarchitecture state to pristine values.

```ts
resetUarch(): void;
```

## getRootHash

Obtains the root hash of the current machine state.

```ts
getRootHash(): Buffer;
```

## getNodeHash

Obtains the hash of a node in the machine state hash tree.

```ts
getNodeHash(address: bigint, log2Size: number): Buffer;
```

## getProof

Obtains a Merkle proof for a range in the machine state. `log2RootSize` defaults to 64 (the full state).

```ts
getProof(address: bigint, log2Size: number, log2RootSize?: number): Proof;
```

## verifyHashTree

Verifies the integrity of the hash tree against the current machine state.

```ts
verifyHashTree(): boolean;
```

## getHashTreeStats

Returns hash tree statistics, optionally clearing the counters.

```ts
getHashTreeStats(clear?: boolean): HashTreeStats;
```

## logStep

Runs the machine for the given cycle count and generates a log of accessed pages and proof data.

```ts
logStep(mcycleCount: bigint, logFilename: string): BreakReason;
```

## logStepUarch

Runs the machine microarchitecture for one cycle and returns a log of state accesses.

```ts
logStepUarch(logType: AccessLogType): AccessLog;
```

## logResetUarch

Resets the microarchitecture state to pristine values and returns a log of state accesses.

```ts
logResetUarch(logType: AccessLogType): AccessLog;
```

## logSendCmioResponse

Sends a cmio response and returns a log of state accesses. The revert root hash is recorded as part of the logged input; it defaults to the machine's current root hash.

```ts
logSendCmioResponse(
    reason: HtifYieldReason,
    data: Buffer,
    logType: AccessLogType,
    revertRootHash?: Buffer,
): string;
```

## verifyStepUarch

**Note:** verifying a big-machine step log (`verifyStep`) is a module-level function, not a machine method:

```ts
import { verifyStep } from "@deroll/cm";

verifyStep(
    rootHashBefore,
    logFilename,
    mcycleCount,
); // returns the obtained root hash after the step, for the caller to check
```

Checks the validity of a state transition produced by a microarchitecture step log and returns the root hash obtained after the step, for the caller to check.

```ts
verifyStepUarch(rootHashBefore: Buffer, log: AccessLog): Buffer;
```

## verifyResetUarch

Checks the validity of a state transition produced by a microarchitecture reset log and returns the root hash obtained after the reset, for the caller to check.

```ts
verifyResetUarch(rootHashBefore: Buffer, log: AccessLog): Buffer;
```

## sendCmioResponse

Sends a cmio response. Should only be called as a response to cmio requests with manual yield command. The revert root hash is the machine root hash to revert to in case the response is eventually rejected. It is required for advance-state responses — where it defaults to the machine's current root hash, the value the emulator checks for — and must be absent for other responses (inspect-state queries and GIO responses).

```ts
sendCmioResponse(
    reason: HtifYieldReason,
    data: Buffer,
    revertRootHash?: Buffer,
): void;
```

## receiveCmioRequest

Receives a cmio request, including the yield command, reason, and data.

```ts
receiveCmioRequest(): {
    cmd: HtifYieldCommand;
    reason: HtifYieldReason;
    data: Buffer;
};
```

## readRevertRootHash / writeRevertRootHash

Reads and writes the revert root hash recorded in the shadow state — the root hash verifiers accept for a rejected rollup input.

```ts
readRevertRootHash(): Buffer;
writeRevertRootHash(hash: Buffer): void;
```

## getAddressName

Gets a description of what is at a given target physical address (also available as a module-level function).

```ts
getAddressName(paddr: bigint): string;
```