fdev 0.3.0

Freenet development tool
fdev-0.3.0 is not a library.

fdev

The Freenet Development Tool (fdev) is a command-line utility to create, build, publish, inspect, and test Freenet contracts or delegates. It also supports local node simulations, a TUI-based WASM runtime, and optional network metrics gathering.

Table of Contents

  1. Overview
  2. Installation
  3. Local Node Example
  4. Creating a New Package
  5. Building a Contract or Delegate
  6. Publishing a Contract or Delegate
  7. Updating a Contract
  8. Contract State Builder Example
  9. Inspecting a Compiled WASM
  10. Using the Local WASM Runtime (TUI)
  11. Querying Connected Peers
  12. Testing (Single-Process or Multi-Process)
  13. Network Metrics Server
  14. Directory & Module Structure
  15. Common Workflows

Overview

fdev helps Freenet developers:

  • Create new contract or web-app packages.
  • Build Rust-based WASM contracts/delegates.
  • Publish new contracts or delegates.
  • Update existing contracts’ state.
  • Inspect compiled artifacts (hash, version, etc.).
  • Run local TUI-based or multi-process network simulations.
  • Query your node for connected peers.
  • Optionally run a metrics server for simulation insights.

Installation

Usually you'll build fdev as part of the Freenet project:

  1. Clone or be inside the Freenet repository.
  2. Navigate to freenet-core/main/crates/fdev.
  3. Build in release mode: 
    cargo build --release
  4. You can then run it directly: 
    ./target/release/fdev --help
    Or place target/release/fdev on your PATH.

Local Node Example

If you want to try out a contract in local mode, you typically run a separate “local node” process that listens for contract commands. There is a local-node executable (or an equivalent) in the Freenet repository. You can do something like:

# Example: run the local node (CLI options may vary)
local-node local-node-cli --help

Once the local node is up, you can run fdev or a script to send commands to it.
Below is a legacy style example (paths/names may differ in current code):

# Example: older usage for local node exploration
./fdev run-local \
  --input-file /tmp/input \
  --terminal-output \
  --deser-format json \
  "/home/.../freenet/crates/http-gw/examples/test_web_contract.wasm"

In newer code, you will likely use fdev wasm-runtime, described in a later section, to do an equivalent local testing workflow.

Creating a New Package

fdev new scaffolds a new Freenet package. Two options:

  • contract: A standard WASM contract.
  • webapp: A contract container that also bundles a front-end (TypeScript/webpack by default).

Example:

fdev new contract

Generates Rust cargo boilerplate (and for web apps, TypeScript/webpack scaffolding too).

Building a Contract or Delegate

Use fdev build to compile a Rust-based WASM contract or delegate. For example:

fdev build \
    --package-type [contract|delegate] \
    [--features some_features] \
    [--debug] \
    [--version 0.0.2]
  • --package-type defaults to contract.
  • --features can specify crate features, e.g. freenet-main-contract or freenet-main-delegate.
  • --debug produces an unoptimized WASM (useful for local tests).
  • --version sets the embedded Freenet ABI version (defaults to 0.0.1).

fdev looks for a freenet.toml in your current directory that defines if your contract is standard or a webapp, and (for webapps) how to compile front-end code.

After building, the output artifact is typically placed in build/freenet/ unless overridden by your config file.

Publishing a Contract or Delegate

fdev publish uploads a new contract or delegate to a node (either local or network mode).

Example: Publishing a contract:

fdev publish \
    --code path/to/my_contract.wasm \
    --parameters path/to/params \
    contract \
    --state path/to/initial_state
  • --code: path to your built WASM.
  • --parameters: optional contract parameters file (typically binary format).
  • --state: optional initial state file (typically binary format).

Example: Publishing a webapp contract with pre-compressed archive:

# First compress your webapp directory
tar cf - webapp/ | xz > webapp.tar.xz

# Then publish the webapp contract
fdev publish \
    --code path/to/webapp_contract.wasm \
    --parameters path/to/params \
    contract \
    --webapp-archive webapp.tar.xz \
    --webapp-metadata path/to/metadata.json
  • --webapp-archive: path to your xz-compressed tar archive containing the webapp files. The archive should contain an index.html file at the root level.
  • --webapp-metadata: optional path to metadata file for the webapp (can be any binary format).

This alternative to the TypeScript/webpack build process allows you to provide your own pre-compressed webapp archive.

Example: Publishing a delegate:

fdev publish \
    --code path/to/my_delegate.wasm \
    --parameters delegate_params \
    delegate \
    [--nonce ... --cipher ...]
  • If you skip --nonce and --cipher, a default local-only encryption is used (fine for tests, not recommended for production).

By default, fdev publish pushes in local mode unless you specify --mode network or set MODE=network.

Updating a Contract

To push a state delta to an existing contract (identified by its Base58 key):

fdev execute update <BASE58_CONTRACT_KEY> \
    --delta path/to/delta \
    [--address 127.0.0.1 \
     --port 50509 \
     --release]
  • --delta: The state delta file (JSON or binary).
  • --release indicates you want to push to the network, instead of local-only.

Contract State Builder Example

Sometimes you only want to build the “state artifact” for a contract or a web front-end. fdev build can do this if your freenet.toml includes a state-sources or webapp config.
Older Freenet docs mention build_state as a separate script, but in practice you can do:

# Build a web-based front end
fdev build \
    --input-metadata-path /optional/metadata \
    --input-state-path contracts/freenet-microblogging/view/web \
    --output-file contracts/freenet-microblogging-web/freenet_microblogging_view \
    --package-type contract  # or 'webapp' if your config demands

Similarly, you can specify --state for a model-only contract:

fdev build \
    --input-state-path contracts/freenet-microblogging/model/ \
    --output-file contracts/freenet-microblogging-data/freenet_microblogging_model

(Adjust paths, actual flags, and config to match your usage.)

Inspecting a Compiled WASM

fdev inspect prints metadata about a built WASM artifact, such as its hash, version, or a derived contract key.

Examples:

# Show code hash + contract API version
fdev inspect code path/to/contract.wasm

# Display the contract key (hash+empty params => key)
fdev inspect key path/to/contract.wasm

# For a delegate
fdev inspect delegate path/to/delegate.wasm

Using the Local WASM Runtime (TUI)

fdev wasm-runtime provides a local, interactive environment to test your contract. For instance:

fdev wasm-runtime \
    --input-file /tmp/input \
    --deserialization-format binary \
    --terminal-output
  • The tool will connect to a local Freenet node by default (see --mode, --address, --port if needed).
  • Commands you type—like put, get, update, or exit—are forwarded to the local node.
  • Additional command data is read from the file specified by --input-file.

Common subcommands once inside the TUI:

help      # print instructions
put       # publish a fresh contract state
get       # retrieve the current contract state
update    # apply a delta to the contract state
exit      # quit TUI

Querying Connected Peers

You can list a node’s open connections:

fdev query

It prints a table of peer identifiers and socket addresses for debugging or analysis.

Testing (Single-Process or Multi-Process)

fdev test orchestrates an entire simulated network of Freenet nodes for end-to-end testing.

Single Process

Spins up multiple in-memory nodes under one process:

fdev test \
    --gateways 2 \
    --nodes 10 \
    --events 100 \
    single-process
  • --gateways: number of gateway nodes
  • --nodes: number of normal nodes
  • --events: random events (contract puts, updates, etc.)

Multi-Process

fdev test \
    --gateways 2 \
    --nodes 10 \
    network
  • One node acts as a supervisor (you run fdev test ... network --mode supervisor).
  • Others run as peers (--mode peer) connecting to the supervisor. This can scale across multiple machines or containers.

(See internal documentation or run fdev test --help for more detail.)

Network Metrics Server

fdev network-metrics-server [--log-directory path]
  • Launches an HTTP server (default port 55010) for collecting or pushing network stats and event logs.
  • You can then visualize or store the data for debugging or simulation metrics analysis.

Directory & Module Structure

Here’s a quick look at the major modules in the fdev crate:

fdev
├── src
│   ├── main.rs                # CLI entrypoint, top-level subcommands
│   ├── config.rs              # Config structs, subcommand definitions
│   ├── commands/              # 'put', 'update', connect to node, etc.
│   ├── build.rs               # Builds Rust WASM, web assets, etc.
│   ├── wasm_runtime/          # Local TUI runtime for testing contracts
│   ├── testing/               # Tools for single vs multi-process simulations
│   ├── network_metrics_server # Optional server for collecting network stats
│   └── util.rs                # Shared utility helpers
└── Cargo.toml

Common Workflows

Below are a few typical steps you might perform:

  1. Create a new contract (or webapp): 
    fdev new contract
  2. Build: 
    fdev build
  3. Publish (locally by default): 
    fdev publish \
    --code build/freenet/my_contract.wasm \
    contract \
    --state initial_state
  4. Update the contract: 
    fdev execute update <contract_key> \
    --delta path/to/delta.json
  5. Inspect a compiled WASM: 
    fdev inspect code build/freenet/my_contract.wasm
  6. Run local TUI (optionally): 
    fdev wasm-runtime \
    --input-file my_input.json \
    --terminal-output \
    --deserialization-format json
  7. Check open peers: 
    fdev query
  8. Simulate a small test network: 
    fdev test --nodes 5 --gateways 1 single-process
  9. (Optional) Start metrics server: 
    fdev network-metrics-server --log-directory /path/to/logs

Feel free to run fdev <subcommand> --help for more details on any step. Enjoy building with Freenet!Below is a comprehensive README for fdev that combines the existing reference documentation and the original README content. You can drop it in place of your current README.md.

fdev

The Freenet Development Tool (fdev) is a command-line utility to create, build, publish, inspect, and test Freenet contracts or delegates. It also supports local node simulations, a TUI-based WASM runtime, and optional network metrics gathering.

Table of Contents

  1. Overview
  2. Installation
  3. Local Node Example
  4. Creating a New Package
  5. Building a Contract or Delegate
  6. Publishing a Contract or Delegate
  7. Updating a Contract
  8. Contract State Builder Example
  9. Inspecting a Compiled WASM
  10. Using the Local WASM Runtime (TUI)
  11. Querying Connected Peers
  12. Testing (Single-Process or Multi-Process)
  13. Network Metrics Server
  14. Directory & Module Structure
  15. Common Workflows

Overview

fdev helps Freenet developers:

  • Create new contract or web-app packages.
  • Build Rust-based WASM contracts/delegates.
  • Publish new contracts or delegates.
  • Update existing contracts’ state.
  • Inspect compiled artifacts (hash, version, etc.).
  • Run local TUI-based or multi-process network simulations.
  • Query your node for connected peers.
  • Optionally run a metrics server for simulation insights.

Installation

Usually you'll build fdev as part of the Freenet project:

  1. Clone or be inside the Freenet repository.
  2. Navigate to freenet-core/main/crates/fdev.
  3. Build in release mode: 
    cargo build --release
  4. You can then run it directly: 
    ./target/release/fdev --help
    Or place target/release/fdev on your PATH.

Local Node Example

If you want to try out a contract in local mode, you typically run a separate “local node” process that listens for contract commands. There is a local-node executable (or an equivalent) in the Freenet repository. You can do something like:

# Example: run the local node (CLI options may vary)
local-node local-node-cli --help

Once the local node is up, you can run fdev or a script to send commands to it.
Below is a legacy style example (paths/names may differ in current code):

# Example: older usage for local node exploration
./fdev run-local \
  --input-file /tmp/input \
  --terminal-output \
  --deser-format json \
  "/home/.../freenet/crates/http-gw/examples/test_web_contract.wasm"

In newer code, you will likely use fdev wasm-runtime, described in a later section, to do an equivalent local testing workflow.

Creating a New Package

fdev new scaffolds a new Freenet package. Two options:

  • contract: A standard WASM contract.
  • webapp: A contract container that also bundles a front-end (TypeScript/webpack by default).

Example:

fdev new contract

Generates Rust cargo boilerplate (and for web apps, TypeScript/webpack scaffolding too).

Building a Contract or Delegate

Use fdev build to compile a Rust-based WASM contract or delegate. For example:

fdev build \
    --package-type [contract|delegate] \
    [--features some_features] \
    [--debug] \
    [--version 0.0.2]
  • --package-type defaults to contract.
  • --features can specify crate features, e.g. freenet-main-contract or freenet-main-delegate.
  • --debug produces an unoptimized WASM (useful for local tests).
  • --version sets the embedded Freenet ABI version (defaults to 0.0.1).

fdev looks for a freenet.toml in your current directory that defines if your contract is standard or a webapp, and (for webapps) how to compile front-end code.

After building, the output artifact is typically placed in build/freenet/ unless overridden by your config file.

Publishing a Contract or Delegate

fdev publish uploads a new contract or delegate to a node (either local or network mode).

Example: Publishing a contract:

fdev publish \
    --code path/to/my_contract.wasm \
    --parameters path/to/params.json \
    contract \
    --state path/to/initial_state.json
  • --code: path to your built WASM.
  • --parameters: optional contract parameters.
  • --state: optional initial state JSON or binary.

Example: Publishing a delegate:

fdev publish \
    --code path/to/my_delegate.wasm \
    --parameters delegate_params.json \
    delegate \
    [--nonce ... --cipher ...]
  • If you skip --nonce and --cipher, a default local-only encryption is used (fine for tests, not recommended for production).

By default, fdev publish pushes in local mode unless you specify --mode network or set MODE=network.

Updating a Contract

To push a state delta to an existing contract (identified by its Base58 key):

fdev execute update <BASE58_CONTRACT_KEY> \
    --delta path/to/delta.json \
    [--address 127.0.0.1 \
     --port 50509 \
     --release]
  • --delta: The state delta file (JSON or binary).
  • --release indicates you want to push to the network, instead of local-only.

Contract State Builder Example

Sometimes you only want to build the “state artifact” for a contract or a web front-end. fdev build can do this if your freenet.toml includes a state-sources or webapp config.
Older Freenet docs mention build_state as a separate script, but in practice you can do:

# Build a web-based front end
fdev build \
    --input-metadata-path /optional/metadata \
    --input-state-path contracts/freenet-microblogging/view/web \
    --output-file contracts/freenet-microblogging-web/freenet_microblogging_view \
    --package-type contract  # or 'webapp' if your config demands

Similarly, you can specify --state for a model-only contract:

fdev build \
    --input-state-path contracts/freenet-microblogging/model/ \
    --output-file contracts/freenet-microblogging-data/freenet_microblogging_model

(Adjust paths, actual flags, and config to match your usage.)

Inspecting a Compiled WASM

fdev inspect prints metadata about a built WASM artifact, such as its hash, version, or a derived contract key.

Examples:

# Show code hash + contract API version
fdev inspect code path/to/contract.wasm

# Display the contract key (hash+empty params => key)
fdev inspect key path/to/contract.wasm

# For a delegate
fdev inspect delegate path/to/delegate.wasm

Using the Local WASM Runtime (TUI)

fdev wasm-runtime provides a local, interactive environment to test your contract. For instance:

fdev wasm-runtime \
    --input-file /tmp/input.json \
    --deserialization-format json \
    --terminal-output
  • The tool will connect to a local Freenet node by default (see --mode, --address, --port if needed).
  • Commands you type—like put, get, update, or exit—are forwarded to the local node.
  • Additional command data is read from the file specified by --input-file.

Common subcommands once inside the TUI:

help      # print instructions
put       # publish a fresh contract state
get       # retrieve the current contract state
update    # apply a delta to the contract state
exit      # quit TUI

Querying Connected Peers

You can list a node’s open connections:

fdev query

It prints a table of peer identifiers and socket addresses for debugging or analysis.

Testing (Single-Process or Multi-Process)

fdev test orchestrates an entire simulated network of Freenet nodes for end-to-end testing.

Single Process

Spins up multiple in-memory nodes under one process:

fdev test \
    --gateways 2 \
    --nodes 10 \
    --events 100 \
    single-process
  • --gateways: number of gateway nodes
  • --nodes: number of normal nodes
  • --events: random events (contract puts, updates, etc.)

Multi-Process

fdev test \
    --gateways 2 \
    --nodes 10 \
    network
  • One node acts as a supervisor (you run fdev test ... network --mode supervisor).
  • Others run as peers (--mode peer) connecting to the supervisor. This can scale across multiple machines or containers.

(See internal documentation or run fdev test --help for more detail.)

Network Metrics Server

fdev network-metrics-server [--log-directory path]
  • Launches an HTTP server (default port 55010) for collecting or pushing network stats and event logs.
  • You can then visualize or store the data for debugging or simulation metrics analysis.

Directory & Module Structure

Here’s a quick look at the major modules in the fdev crate:

fdev
├── src
│   ├── main.rs                # CLI entrypoint, top-level subcommands
│   ├── config.rs              # Config structs, subcommand definitions
│   ├── commands/              # 'put', 'update', connect to node, etc.
│   ├── build.rs               # Builds Rust WASM, web assets, etc.
│   ├── wasm_runtime/          # Local TUI runtime for testing contracts
│   ├── testing/               # Tools for single vs multi-process simulations
│   ├── network_metrics_server # Optional server for collecting network stats
│   └── util.rs                # Shared utility helpers
└── Cargo.toml

Common Workflows

Below are a few typical steps you might perform:

  1. Create a new contract (or webapp): 
    fdev new contract
  2. Build: 
    fdev build
  3. Publish (locally by default): 
    fdev publish \
    --code build/freenet/my_contract.wasm \
    contract \
    --state initial_state.json
  4. Update the contract: 
    fdev execute update <contract_key> \
    --delta path/to/delta.json
  5. Inspect a compiled WASM: 
    fdev inspect code build/freenet/my_contract.wasm
  6. Run local TUI (optionally): 
    fdev wasm-runtime \
    --input-file my_input.json \
    --terminal-output \
    --deserialization-format json
  7. Check open peers: 
    fdev query
  8. Simulate a small test network: 
    fdev test --nodes 5 --gateways 1 single-process
  9. (Optional) Start metrics server: 
    fdev network-metrics-server --log-directory /path/to/logs

Feel free to run fdev <subcommand> --help for more details on any step. Enjoy building with Freenet!