#v3.0 Upgrade Guide - Docker

ARK v3.0 is a major update not backward compatible with v2.7.

#Upgrade Steps

Upgrading from v2.7 to v3.0 is relatively straightforward if you follow the instructions. Even though we try to ensure backward compatibility (BC) as much as possible, sometimes it is not possible or very complicated to avoid it and still create an excellent solution to a problem.

#Step 1. Getting the Needed Files

1mkdir ~/mainnet &&
2cd ~/mainnet &&
3curl -sOJ https://raw.githubusercontent.com/ArkEcosystem/core/master/docker/production/mainnet/docker-compose.yml &&
4curl -sOJ https://raw.githubusercontent.com/ArkEcosystem/core/master/docker/production/mainnet/mainnet.env &&
5curl -sOJ https://snapshots.ark.io/v3-migrations.sql

#Step 2. Performing the Upgrade

1cd ~/mainnet

Stop & Remove current ARK Core container only (preserving the DB container):

1docker-compose rm -s -v -f core

Remove the old ARK Core Docker image:

1docker rmi arkecosystem/core

Apply the DB migration SQL script(adapt the psql command with your user and database):

1docker cp v3-migrations.sql postgres-mainnet:/tmp
2docker exec -it postgres-mainnet psql -U node -d core_mainnet -f /tmp/v3-migrations.sql

Start the new ARK Core container:

1docker-compose up -d core

#Reporting Problems

If you happen to experience any issues, please open an issue with a detailed description of the problem, steps to reproduce it, and info about your environment.

#API Changes

#‘POST /search’ Endpoints Removed

All POST /search endpoints have been removed in favor of using the main index endpoint with URL parameters (e.g. GET /transactions). All main index endpoints have been improved to allow searching (see the API improvements below).

#Standardized Wallet Response Format

Wallet endpoints now return a wallet object following this format:

 1{
 2    "address",
 3    "publicKey",
 4    "balance",
 5    "nonce",
 6    "attributes": {
 7        "delegate": {
 8            "username",
 9            "resigned",  // this attribute will only be set if the delegate has resigned
10            // other delegate attributes
11        },
12        "vote",
13        "secondPublicKey",
14        "multiSignature",
15    }
16}

As a result, getting wallets based on a specific attribute requires using the full attribute path.

GET /wallets?attributes.delegate.username=mydelegate

#‘addresses’ Parameter Removed

The addresses parameter was previously used to search for multiple addresses at the same time. This parameter is now deprecated in favor of using the address parameter.

GET /transactions?address=AXGc1bvU3g3rHmx9WVkUUHLA6gbzh8La7V,AVLPrtx669XgvervE6A594poB613HG3mSM

#API improvements

#Filter by Any Field

You can now filter by any field returned in the API response.

For example, GET /delegates now returns:

 1{
 2    "username": "protokol1",
 3    "address": "ATKegnoyu9Fkej5FxiJ3biup8xv8zM34M3",
 4    "publicKey": "033f6d89ad9f3e6dfb8cfb4f2d7fca7adeb6db15c282c113d0452238293bb50046",
 5    "votes": "302776200010000",
 6    "rank": 1,
 7    "isResigned": false,
 8    "blocks": {
 9        "produced": 13886,
10        "last": {
11            "id": "9630922981846498992",
12            "height": 1150380,
13            "timestamp": {
14                "epoch": 112045656,
15                "unix": 1602146856,
16                "human": "2020-10-08T08:47:36.000Z"
17            }
18        }
19    },
20    "production": {
21        "approval": 2.42
22    },
23    "forged": {
24        "fees": "10000000",
25        "rewards": "2777200000000",
26        "total": "2777210000000"
27    }
28}

By examining the above response, we find that API queries allow filtering by any field.

For example:

• GET /delegates?isResigned=true
• GET /delegates?blocks.produced=13886

#Combining Different Fields

We also see that combining different fields (AND) is permitted.

GET /delegates?isResigned=true&blocks.produced=0

#Filtering By a Set of Values

Filtering by a set of comma-separated values for one field (OR) is also permitted.

GET /delegates?username=protokol1,protokol2

#Chaining Multiple Fields

We can also chain multiple fields.

GET /delegates?username=protokol1,protokol2&isResigned=false

#‘orderBy’ Any Field

Additionally, we can order any field using the orderBy parameter.

GET /delegates?orderBy=rank:desc

#Combining Filters

Finally, we can combine all of the previously discussed filters in one call.

GET /delegates?isResigned=false&orderBy=rank:asc