# 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;
    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;
    removeStored(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;
    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: CmioYieldReason,
        data: Buffer,
        logType: AccessLogType,
    ): string;

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

    //// CMIO Operations
    sendCmioResponse(reason: CmioYieldReason, data: Buffer): void;
    receiveCmioRequest(): {
        cmd: CmioYieldCommand;
        reason: CmioYieldReason;
        data: Buffer;
    };
}
```

## isEmpty

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

```ts
isEmpty(): 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;
```

## removeStored

Removes a stored machine directory.

```ts
removeStored(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.

```ts
logSendCmioResponse(
    reason: CmioYieldReason,
    data: Buffer,
    logType: AccessLogType,
): 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,
    rootHashAfter,
); // returns BreakReason
```

Checks the validity of a state transition produced by a microarchitecture step log.

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

## verifyResetUarch

Checks the validity of a state transition produced by a microarchitecture reset log.

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

## sendCmioResponse

Sends a cmio response. Should only be called as a response to cmio requests with manual yield command.

```ts
sendCmioResponse(reason: CmioYieldReason, data: Buffer): void;
```

## receiveCmioRequest

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

```ts
receiveCmioRequest(): {
    cmd: CmioYieldCommand;
    reason: CmioYieldReason;
    data: Buffer;
};
```