Skip to main content

Migrating from 3.x

Current releases are node 4.0.3, wallet 4.0.0 and epicbox protocol 3.0.0.

API changes​

total_difficulty is an object​

Difficulty is tracked separately for each proof-of-work algorithm:

{
  "total_difficulty": {
    "cuckaroo": 0,
    "cuckatoo": 1234,
    "randomx": 5678,
    "progpow": 9012
  }
}

Block headers describe proofs with two fields​

proof names the algorithm and solution is a tagged union whose shape depends on it. In 3.x a single scalar field carried the solution.

Wallet output and transaction reads take pagination​

retrieve_outputs and retrieve_txs take limit, offset and sort_order. Supply them explicitly.

Status gains supply fields​

supply and max_supply are amounts in freemen. blocks_to_next_halving is a count of blocks, at api/src/types.rs:96. Reward steps are not all halvings; see emission.

Kernels appear in two shapes​

get_block returns a flattened kernel. get_kernel and get_last_n_kernels return the raw type with an externally tagged features field.

Command line changes​

Flags moved. init -h for the current directory is now -w, scan -h <height> is now -s <height>, and the node's taxes argument is start_height. New wallet commands are export_tx, import_tx and change_password, plus --slate_version on the transfer commands. Every command and flag is in configuration and CLI.

The algorithm mix on the test networks is selected by config key, not by a command-line flag. See the block policy.

Toolchain and build​

Each repository pins its Rust version, so installing rustup is sufficient and you should not pin a version yourself. Building also needs system packages beyond a Rust toolchain, listed per platform in building from source.

Storage changes​

The wallet stores data in SQLite at db/sqlite/epic.db, in WAL mode, and its Tor directory is wallet_tor. Anything that read the 3.x wallet database directly needs rewriting. Paths and keys are in wallet configuration.

New behaviour​

Bundled Tor​

Building with --features with-tor downloads a Tor expert bundle and verifies it against a committed digest. Release builds do not enable the feature. See what this version does not cover.

Epicbox acknowledges delivery​

Protocol 3.0.0 adds a Made acknowledgement carrying a per-message id, so a slate is marked delivered only once the recipient confirms it processed it. Compatibility with pre-3.5.2 clients is preserved. See the protocol.

Mempool confirmation after posting​

The wallet watches the node's mempool after posting a transaction and records a distinct state when it appears. That wait is why a send can look unresponsive, covered in the send appears to hang, and it moves a posted transfer out of the set cancel_tx accepts, covered in cancelling has preconditions.

The epicbox relay implementation changed​

The relay is EpicCash/epic-epicbox-docker, Node.js with a Rust verification helper. Its deployment topology and storage are in the epicbox reference.

Behaviour to check in your integration​

  • tx_lock_outputs is required in a manual send sequence. See what reserves outputs.
  • Epicbox converts every slate to V2, which drops a payment proof request. See the transport comparison.
  • change_password removes the backup seed unless --remove-backup is passed.
  • Sync validation defaults changed shape. skip_pow_validation and disable_checkpoints default to true, which skips proof of work for checkpointed history while always fully verifying the most recent 1,000 blocks. See node and wallet setup.

Next​

The MimbleWimble model

A refresher on why the transaction model works this way.

Wallet Owner API

The surface most integrations target.