Skip to main content

Migrating from 3.x

Current releases are node 4.1.0, wallet 4.1.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:102. 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, which wallets speak from 3.6.0 onwards, so not new in 4.x, 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 clients older than 3.5.2 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 defaults to true and disable_checkpoints to false. On mainnet proof of work is skipped only up to the last checkpoint and fully verified above it, and disable_checkpoints is ignored. See node and wallet setup.

Changes in 4.1.0​

Node and wallet 4.1.0 tighten authentication. An integration that worked against 4.0.x can start getting 401s.

  • The wallet Owner API needs HTTP Basic. /v3/owner and /v2/owner take username epic and the contents of .owner_api_secret, on top of the v3 token. See owner access on the wallet.
  • The node's /v1 and /v2/owner fail closed. With no secret configured they answer 401 rather than running open. Only GET /v1/version and one plain get_status call answer without a credential. See the node credential.
  • New foreign method ready_for_txs reports whether the node is synced, with no credential. The wallet uses it in place of the owner get_status. See which method lives where.
  • The wallet sends its node secret far less. It never sends one to /v2/foreign, so a node with foreign_api_secret_path set cannot serve it. See the credential the wallet presents to the node.
  • /v1/kerneldownload is removed. See the v1 routes.
  • disable_checkpoints defaults to false and is ignored on mainnet, and a new checkpoint at height 3,710,000, making 13, moves the end of the skipped range. See sync validation settings.

Next​

The MimbleWimble model

A refresher on why the transaction model works this way.

Wallet Owner API

The surface most integrations target.