RELEASE-NOTES-4.0.0.md
1 # About this release 2 3 [This][this-release] is a major Fortuna release, mainly aimed at easing development of applications using state channels in the presence of generic accounts. 4 It: 5 * Introduces State Channel FSM Generalized Accounts awareness. It now fully 6 supports creation of meta transactions and verifies them. 7 * Changes WebSocket API regarding signing transactions: now sign requests 8 provide a signed transaction to be signed. Old approach was sending unsigned 9 transactions. 10 * Changes channel reestablish checks: for on-chain transactions authentication 11 can not always be checked at current chain top. Check is done, if the last 12 transaction is an on-chain one, it must be present in on-chain. 13 * Changes the off-chain protocol to accommodate Generalized Account 14 authentication methods. This is off-chain noise protocol breaking change. 15 * Enhances the state Channels WebSocket API, that now supports starting a responder with `"initiator_id": "any"`. 16 The responder instance will get the proper initiator Id from the `channel_open` message once a 17 connection is established. 18 * Enables multiple different State Channel responder pubkeys to share the same listen port. 19 * Changes the `channel_open` and `channel_accept` messages to contain both the initiator and 20 responder public keys. This is not backwards compatible for the `noise` protocol. 21 * Enhances State Channel's WebSocket API with providing more meaningful 22 messages when failing to open a channel because of invalid opening arguments. 23 * Makes State Channel WebSocket API more consistent regarding the usage of 24 `caller` and `contract` vs `caller_id` and `contract_id`. This is an API 25 breaking change. 26 * Allows sending and receiving generic messages in State Channels in any FSM 27 state. Until this - generic messages were allowed only in `open` state. 28 `channel_id` is part of the message body and if it is unknown - the 29 temporary one is used instead. This is not backwards compatible for the 30 `noise` protocol. This enhances the WebSocket API accordingly. 31 * Fixes the value of the discriminator field (`type`) for the oracle response transaction in the user API paths returning transactions (e.g. path `/transactions/{hash}`). 32 * Enhances the response of the dry-run API (path `/debug/transactions/dry-run`) for contract create transaction by adding the information for the call of the initialization function e.g. the gas used. This makes the response of the dry-run for the contract create transaction analogous to the one for the contract call transaction. 33 34 [this-release]: https://github.com/aeternity/aeternity/releases/tag/v4.0.0 35 36 This release introduces backward incompatibilities in the channels user WebSocket API and in the channels external Noise endpoint protocol. 37 For the rest, this release is backward compatible with previous `v3.*` releases. 38 39 Please join the mainnet by following the instructions below, and let us know if you have any problems by [opening a ticket](https://github.com/aeternity/aeternity/issues). 40 Troubleshooting of common issues is documented [in the wiki](https://github.com/aeternity/aeternity/wiki/Troubleshooting). 41 42 The instructions below describe: 43 * [How to retrieve the released software for running a node](#retrieve-the-software-for-running-a-node); 44 * [How to install a node](#install-node); 45 * [How to join the mainnet](#join-the-mainnet). 46 * [How to join the testnet](#join-the-testnet). 47 48 ## Retrieve the software for running a node 49 50 You can run a node by either: 51 * Installing the published [release binary][this-release] corresponding to your platform; or 52 * Running the published [Docker image `aeternity/aeternity`][docker]; or 53 * [Building a release binary from source][build]. 54 55 [docker]: https://github.com/aeternity/aeternity/blob/v4.0.0/docs/docker.md 56 [build]: https://github.com/aeternity/aeternity/blob/v4.0.0/docs/build.md 57 58 The instructions for configuring the node using the Docker image are in [the dedicated separate document][docker]. 59 60 The node user API is documented: 61 * HTTP API endpoints are specified [online in swagger.yaml][swagger-yaml]; 62 * A JSON version of the same specification is located in the node at path `lib/aehttp-*/priv/swagger.json` (you will need to amend the wildcard `*` placeholder in the path with the version). 63 * The JSON version can be obtained from a running node using the endpoint `/api`. 64 * An interactive visualization of the same specification is available [online][swagger-ui]. 65 * WebSocket API endpoints are [specified online][api-doc]; 66 * The intended usage of the user API (HTTP and WebSocket) is [documented online][api-doc]. 67 68 [swagger-yaml]: https://github.com/aeternity/aeternity/blob/v4.0.0/config/swagger.yaml 69 [swagger-ui]: https://aeternity.github.io/api-docs/?config=https://raw.githubusercontent.com/aeternity/aeternity/v4.0.0/apps/aehttp/priv/swagger.json 70 [api-doc]: https://github.com/aeternity/protocol/blob/aeternity-node-v4.0.0/node/api/README.md 71 72 ## Install node 73 74 The instructions for installing a node using a release binary are in [the dedicated separate document](../../docs/installation.md). 75 76 For installation of a node using the Docker image, please refer to the [documentation online][docker]. 77 78 ## Join the mainnet 79 80 In order to join the mainnet follow the [operation instructions](../../docs/operation.md) to run the node with default configuration as mainnet is the default network. 81 82 To join the mainnet by using the Docker image, please refer to [docker documentation][docker]. 83 84 ### Mainnet seed nodes 85 86 The release package comes preconfigured with seed nodes. Here is example subset of the seed nodes: 87 88 * aenode://pp_2L8A5vSjnkLtfFNpJNgP9HbmGLD7ZAGFxoof47N8L4yyLAyyMi@18.136.37.63:3015 89 * aenode://pp_2gPZjuPnJnTVEbrB9Qgv7f4MdhM4Jh6PD22mB2iBA1g7FRvHTk@52.220.198.72:3015 90 * aenode://pp_tVdaaX4bX54rkaVEwqE81hCgv6dRGPPwEVsiZk41GXG1A4gBN@3.16.242.93:3015 91 * aenode://pp_2mwr9ikcyUDUWTeTQqdu8WJeQs845nYPPqjafjcGcRWUx4p85P@3.17.30.101:3015 92 * aenode://pp_2CAJwwmM2ZVBHYFB6na1M17roQNuRi98k6WPFcoBMfUXvsezVU@13.58.177.66:3015 93 * aenode://pp_7N7dkCbg39MYzQv3vCrmjVNfy6QkoVmJe3VtiZ3HRncvTWAAX@13.53.114.199:3015 94 * aenode://pp_22FndjTkMMXZ5gunCTUyeMPbgoL53smqpM4m1Jz5fVuJmPXm24@13.53.149.181:3015 95 * aenode://pp_Xgsqi4hYAjXn9BmrU4DXWT7jURy2GoBPmrHfiCoDVd3UPQYcU@13.53.164.121:3015 96 * aenode://pp_vTDXS3HJrwJecqnPqX3iRxKG5RBRz9MdicWGy8p9hSdyhAY4S@13.53.77.98:3015 97 98 ### Inspect the mainnet 99 100 Here are example nodes that can be used to inspect current top block and see information about e.g. height or target: 101 102 * http://18.136.37.63:3013/v2/blocks/top 103 * http://52.220.198.72:3013/v2/blocks/top 104 * http://13.53.114.199:3013/v2/blocks/top 105 * http://13.53.149.181:3013/v2/blocks/top 106 107 ## Join the testnet 108 109 In order to join the testnet change the [Network ID](../../docs/configuration.md#network-id) in node configuration file to `ae_uat`. 110 111 To join the testnet by using the Docker image, please refer to the [docker documentation][docker]. 112 113 ### Testnet seed nodes 114 115 The release package comes preconfigured with testnet seed nodes, this is the list: 116 117 * aenode://pp_QU9CvhAQH56a2kA15tCnWPRJ2srMJW8ZmfbbFTAy7eG4o16Bf@52.10.46.160:3015 118 * aenode://pp_27xmgQ4N1E3QwHyoutLtZsHW5DSW4zneQJ3CxT5JbUejxtFuAu@13.250.162.250:3015 119 * aenode://pp_DMLqy7Zuhoxe2FzpydyQTgwCJ52wouzxtHWsPGo51XDcxc5c8@13.53.161.215:3015 120 121 ### Inspect the testnet 122 123 The core nodes of the public test network are accessible from the Internet. 124 125 Information, e.g. height, of the top block of the longest chain as seen by these core nodes of the testnet can be obtained by opening in the browser any of the following URLs: 126 * http://52.10.46.160:3013/v2/blocks/top 127 * http://13.250.162.250:3013/v2/blocks/top 128 * http://13.53.161.215:3013/v2/blocks/top 129 130 ### Setup your node 131 132 Setting up your node consists of: 133 * Configuring your node - see instructions in [the dedicated separate document](../../docs/configuration.md); 134 * Starting your node and verifying it works as expected - see instructions in [the dedicated separate document](../../docs/operation.md).