chore(docs): Migrate developer specific docs from wiki.trezor.io to docs.trezor.io

docs/SUMMARY.md

@@ -31,6 +31,7 @@
       - [Migration](common/communication/passphrase-redesign-migration.md)
     - [Bitcoin signing](common/communication/bitcoin-signing.md)
   - [Reproducible builds](common/reproducible-build.md)
+  - [Message Workflows](common/message-workflows.md)
 - [Storage](storage/index.md)
 - [Tests](tests/index.md)
   - [Device Tests](tests/device-tests.md)
@@ -50,3 +51,5 @@
   - [Review Process](misc/review.md)
   - [Changelog](misc/changelog.md)
   - [TOIF Image Format](misc/toif.md)
+- [Developers guide](developers/index.md)
+  - [Libraries](developers/libraries.md)

docs/common/index.md

@@ -13,3 +13,5 @@ Common Protobuf definitions for the Trezor protocol. Also see [Communication](co
 ## Tools
 
 Tools for managing coin definitions and related data.
+
+## Message Workflows

docs/common/message-workflows.md

@@ -0,0 +1,321 @@
+# Message Workflows
+
+> This page was migrated from the Trezor Wiki. The content here may contain
+outdated information.
+
+In general, the API implements a simple request-response protocol. The
+computer sends a request to the device and the device sends back a
+response. The response can be a simple Success message, a Failure
+message, or an answer to the request giving the requested data.
+Moreover, the response can be a request from the device to the computer,
+e.g., for entering the PIN, the
+passphrase or giving some other information. In
+that case the computer should send the corresponding Ack packet to
+answer the request and wait for another response.
+
+## Initialize/Features
+
+As first message, the computer should send an empty Initialize packet
+and expect a Features packet as response. The Initialize packet will
+cause the device to stop what it is currently doing and should work at
+any time. Thus, it can also be used to recover from previous errors.
+
+## Button meta-workflow
+
+If the device requires the user to press a button, it will reply with a
+ButtonRequest to the computer. The computer should immediately send a
+ButtonAck acknowledging the request. But it should also display an
+indication to the user that it should follow the instruction on the
+device. The field code in the ButtonRequest message explains what type
+of request the user should acknowledge with a button.
+
+If the user never presses the button, there will never be a reply to the
+ButtonAck message. The computer can use Cancel to abort the current
+operation. This should result in a Failure response.
+
+## PinMatrix meta-workflow
+
+If the device requires the user to unlock the device with a PIN, it will
+reply with a PinMatrixRequest. The field type gives some explanation
+what PIN is required (current pin, new pin, or confirmation of new pin).
+The computer should display an empty pin matrix and let the user enter
+the pin. The computer should encode the PIN as if the numbers are
+ordered like they are on the numeric keypad. The encoded PIN should then
+be send with a PinMatrixAck message.
+
+## Passphrase meta-workflow
+
+If the device requires the user to enter the passphrase, it will reply
+with a PassphraseRequest. The computer should ask the user for the
+passphrase and send it in clear text with a PassphraseAck message.
+
+## GetAddress
+
+The message GetAddress (send from the computer to the device) serves two
+purposes. It can be used to get a valid address or to display the
+address on the device. The field address_n gives the bip-32
+path to the
+address. The field coin_name should be set to some
+supported coin (see the Feature message for a list of supported coins).
+For multisig addresses multisig must be filled out with all
+participating master public keys and their bip-32 path. The script_type
+field has the same meaning as for transaction inputs when signing:
+
+-   SPENDADDRESS (standard P2PKH address)
+-   SPENDMULTISIG (P2SH multisig address)
+-   SPENDWITNESS (native segwit P2WPKH or
+    multisig p2wsh address)
+-   SPENDP2SHWITNESS (segwit encapsulated in a p2sh
+    address)
+
+If show_display is set the address is displayed to the user. In any
+case, it is also sent to the computer with an Address response.
+
+## GetPublicKey
+
+The message GetPublicKey can be used to get a bip-32 master public key
+from the trezor or to display it to the user. The field address_n gives
+the bip-32 path to the master key. The field ecdsa_curve_name can be
+used to get Ed25519 or
+NIST256P1 public keys.
+
+## SignTx
+
+> The following may contain imprecise/obsolete information. Refer to
+[Bitcoin signing flow](communication/bitcoin-signing.md) for more relevant
+information.
+
+Signing a transaction is a little bit complicated. The reason is that
+transactions can be several hundred kilobytes in size, but Trezor has
+only 64 kilobytes memory. So it is the task of the computer to split the
+transactions in small pieces and send only those pieces that Trezor
+requested. The general workflow is given below
+
+![](Developers_guide_signtx_workflow.png)
+
+The computer starts the transaction signing process by sending a SignTx
+message. From then on, the device drives all further communications by
+sending requests to the computer until it finally sends a TxRequest with
+request set to TXFINISHED. This final message should not be acknowledged
+by the computer.
+
+The SignTx message contains only the meta data of the transaction that
+should be signed, i.e., the number of inputs and outputs, the coin name,
+the version number, and lock_time (only for pre-signed time locked
+transactions). If the device was not unlocked before, it will respond
+with the usual PinMatrixRequest and PasswordRequest messages to
+authenticate the user. See the corresponding sections above. It may also
+send a ButtonRequest at any time to indicate that the user should
+confirm a transaction output or the total fee.
+
+Then the main process begins and Trezor will respond with TxRequest
+messages, which should be answered by TxAck message. A TxRequest message
+has up to three parts.
+
+1.  Parts of the signed transactions.
+2.  A signature for one of the inputs.
+3.  A request for one piece of the new transaction or a previous
+    transaction.
+
+If the field serialized.serialized_tx is set, it contains a chunk of the
+signed transaction in serialized format. The chunks are returned in the
+right order and just concatenating all returned chunks will result in
+the signed transaction.
+
+If the field serialized.signature is set, it contains a signature for
+one of the inputs. The signatures are returned in the same order as they
+appear in the serialized transactions. I.e., the non-segwit signatures
+come before the segwit signatures, since the latter are part of the
+witness, which is serialized at the end. Apart from that, the signatures
+are returned in the order the inputs appear in the transaction. The
+signatures are not really needed, as they are already in the serialized
+transaction. They can be useful for combining multisig signatures
+without having to parse the transactions again.
+
+If the field request equals TXFINISHED, this message contained the last
+chunk of the transaction. The signing is finished and the computer must
+not reply to this packet. In any other case, the device requested some
+piece of some transaction, which is specified by request and details.
+This request must be answered by a TxAck package containing the
+requested piece of data.
+
+If the field details.tx_hash is not set, some piece of the transaction
+that should be signed is requested. Otherwise, this field contains the
+hash of some input transaction and some piece of that transaction is
+requested.
+
+For request = TXMETA, the fields tx.version, tx.lock_time, tx.inputs_cnt
+(number of inputs), and tx.outputs_cnt must be filled. For ZCash
+transactions also tx.extra_data_len must be given. This will only be
+requested for input transactions (for the signed transaction it was
+given in the SignTx call).
+
+For request = TXINPUT, the field details.request_index contains the
+number of the input requested (starting with zero). The reply must fill
+the structure tx.inputs\[0\] (there must be exactly one input in the
+reply). Which fields must be set depends on whether details.tx_hash is
+set (an input of some previous transaction is requested, that is spend
+in the new transaction), or whether an input of the new transaction is
+requested. In both cases prev_hash, prev_index and sequence must be set.
+For a previous transaction, the script_sig must be set to the raw
+signature data.
+
+But if details.tx_hash is unset, the data must instead describe the
+private key that should be used to sign the input. This is specified by
+address_n (the bip-32 path to the private key), script_type and
+multisig. The field multisig is only given for multisig transactions and
+contains the master public keys and the derivation paths for all
+signers. The field script_type can be
+
+-   SPENDADDRESS (standard p2pkh address)
+-   SPENDMULTISIG (p2sh multisig address)
+-   SPENDWITNESS (native segwit p2wpkh or multisig p2wsh address)
+-   SPENDP2SHWITNESS (segwit encapsulated in a p2sh address)
+
+Note, that for segwit script_type does not distinguish between multisig
+or p2wpkh addresses. Instead the presence of the multisig decides this.
+For segwit inputs also the amount field must be set to the amount of
+satoshis in the input transaction.
+
+For request = TXOUTPUT, the field details.request_index contains the
+number of the output requested (starting with zero). If details.tx_hash
+is set, this is an output of a previous transaction and the
+tx.bin_outputs\[0\] field must be filled in the TxAck reply. Otherwise,
+the tx.outputs\[0\] field must be filled. For change outputs, the field
+address_n must be filled and address must be omitted. If the change is
+multisig, the multisig must be filled and it must use the same extended
+public keys as all inputs. For a change address, the script_type should
+be PAYTOADDRESS, PAYTOMULTISIG, PAYTOWITNESS or PAYTOP2SHWITNESS
+matching the corresponding cases SPEND... for inputs. For
+OP_RETURN outputs, set script_type =
+PAYTOOPRETURN and set the op_return_data field. Otherwise address should
+be set to a base58 encoded address and
+script_type to PAYTOADDRESS. Older firmware required script_type =
+PAYTOSCRIPTHASH for p2sh addresses, though (and newer firmware still
+support this).
+
+## SignMessage/VerifyMessage
+
+### Sign message
+
+Signing messages can be used to prove ownership of a specific address.
+To sign message with Trezor device, it is needed to send the message
+which the user wants to sign and also specify BIP-32 path which to use
+for message signing. There are also two optional arguments: to specify
+coin (Bitcoin is default, for more information about available coins
+check this GitHub
+[page](https://github.com/trezor/trezor-firmware/blob/master/core/src/apps/common/coininfo.py))
+and specify script type (0 = SPENDADDRESS/standard P2PKH address, 1 =
+SPENDMULTISIG/P2SH multisig address, 2 = EXTERNAL/reserved for external
+inputs (coinjoin), 3 = SPENDWITNESS/native SegWit, 4 =
+SPENDP2SHWITNESS/SegWit over P2SH (backward compatible))
+
+### Verify message
+
+Verify message asks device to verify if the signature is a signed
+message with the given address. The arguments of the message are
+signature, message being verified, address and coin which should be used
+for verifying.
+
+## CipherKeyValue
+
+Cipher key value provides symmetric encryption in the Trezor device,
+where the key doesn't exit the device, and where the user might be
+forced to confirm the encryption/decryption on the display. The data
+sent to the device are The following data are BIP-32 derivation path,
+key (that is being shown on the device), value, encrypt/decrypt
+direction, should user confirm on encrypt?, should user confirm on
+decrypt? and optional IV. Value is what is actually being encrypted. The
+key for the encryption is constructed from the private key on the BIP
+address, the key displayed on the device, and the two informations about
+whether to ask for confirmation. It is constructed in such a way, that
+different path, key or the confirm information will get a different
+encryption key and IV. So, you cannot "skip" the confirmation by using
+different input. IV can be either manually set, or it is computed
+together with the key. The value must be divisible into 16-byte blocks.
+The application has to pad the blocks itself and ensure safety; for
+example, by using PKCS7. See
+<https://github.com/satoshilabs/slips/blob/master/slip-0011.md>.
+
+## ResetDevice
+
+Reset device message performs Trezor device
+setup and generates new wallet with new recovery
+seed. The device must be in unitialized
+state, the firmware is already installed but it has not been initialized
+yet. If it is initialized and the user wants to perform a reset device,
+the device must be wiped first. If the Trezor is prepared for its
+initialization the screen is showing "Go to trezor.io". The reset device
+can be done in Trezor Wallet interface (https://trezor.io/start) and
+also with Python trezorctl command. After sending
+message to the device, device warn us to never make a digital copy of
+your recovery seed and never upload it online, this message has to be
+confirmed by pressing on "I understand" on the device. After confirmed,
+the device produces internal entropy which is random of 32 bytes,
+requests external entropy which is produced in computer and computes
+mnemonic (recovery seed) using internal, external entropy and given
+strength (12, 18 or 24 words). Trezor Wallet
+interface doesn't provide option to choose how many words there should
+be in the generated mnemonic (recovery seed). It is hardcoded to 12
+words for Trezor Model T but if done with python's trezorctl command it
+can be chosen (for initialization with python's trezorctl command, 24
+words mnemonic is default). After showing mnemonic on the Trezor device,
+Trezor Model T requires 2 random words to
+be entered to the device to confirm the user has written down the
+mnemonic properly. If there are errors in entered words, the device
+shows the recovery seed again. If the backup check is successful, the
+setup is finished. If the Trezor Wallet interface is used, user is asked
+to set the label and pin (setting up the pin can be skipped) for the
+wallet, this is optional when using python trezorctl command.
+
+## RecoveryDevice
+
+Recovery device lets user to recover BIP39 seed into
+empty Trezor device. First the device asks user for the number of words
+in recovered seed, the words are typed in one by one - on the device
+screen when using Trezor model T, with Trezor One the user can decide to
+do the advanced recovery (with entering seed using matrix similarly to
+entering PIN) or standard recovery (with entering the seed to the host
+computer one by one in random order). The process continues with
+optional check of the seed validity and optional setting up the PIN,
+which has to be confirmed. Finally the recovered wallet is saved into
+device storage. The same process is used with the dry run recovery, the
+differences are that this process can be done only with already
+initialized deviice and that the mnemonic is not saved into the device
+but it is only compared to the mnemonic already loaded into the device
+with the successful result (The seed is valid and matches the one in the
+device) or unsuccessful result(The seed is valid but does not match the
+one in the device).
+
+## LoadDevice
+
+Load device lets user to load the device with the specific recovery
+seed. This command is the subset of the recovery device and it can not
+be done with Trezor Wallet interface, only with python command
+trezorctl. This message can be used only if the device is not
+initialized.
+
+## WipeDevice
+
+Wipe device lets user wipe the device. It is possible to wipe only
+user's wallet or erase all the data from the Trezor device including
+installed firmware. Wiping device in Trezor Wallet interface wipes only
+user's wallet. It is also possible to wipe the firmware with python
+trezorctl command, Trezor device must be in bootloader mode.
+
+## ApplySettings
+
+Apply settings lets user change settings on the Trezor device, mainly
+its homescreen, label and passphrase settings. Passphrase can be set to
+enabled or disabled. Furthermore it can be set that passphrase is
+entered solely on device or solely on host, by default the device always
+ask where the user wants to enter the passphrase. All these settings
+have to be confirmed by user on the device.
+
+## ChangePin
+
+This message lets user change, remove or set new PIN. First the user is
+asked to enter old PIN if it was set before. The user is then asked to
+enter new PIN and re-enter it to confirm match. It is also possible to
+not enter new PIN, so the Change PIN message will just remove the old
+one. The action has to be confirmed by user.

docs/core/build/index.md

@@ -1,5 +1,7 @@
 # Build
 
+_Building for Trezor Model One? See the [legacy](../../legacy/index.md) documentation._
+
 ## New Project
 
 Run the following to checkout the project:

docs/developers/index.md

@@ -0,0 +1 @@
+# Developers guide

docs/developers/libraries.md

@@ -0,0 +1,52 @@
+# Libraries
+
+> This page was migrated from the old wiki, the content might be outdated.
+
+There are several libraries available which can be used to implement
+Trezor device functionalities.
+
+## SatoshiLabs libraries
+
+### Trezor Connect (Web)
+
+For more information about Trezor Connect (JavaScript), see [Trezor
+Connect API](../developers/connect.md) and this GitHub [page][].
+
+### Python-trezor
+
+For more information about Python-trezor, please see [python-trezor][]
+or this GitHub [page][1]. It is possible to use python-trezor with
+[trezorctl][] commands from the command line.
+
+### Android
+
+<https://github.com/trezor/trezor-android>
+
+*See also: [Developers guide > Android](../developers/android.md)*
+
+### Go
+
+<https://github.com/trezor/trezord-go>
+
+## Third-party libraries
+
+Check these third-party libraries for Trezor device.
+
+### Java
+
+For Trezor-java library by Gary Rowe, see this GitHub [page][3].
+
+### Trezor.Net
+
+Trezor.Net supports Android, UWP, .NET Core and .NET Framework with
+Hid.Net. Support for other platforms can be added with the Hid.Net
+dependency injection. See this [page][4] or this GitHub [page][5].
+
+  [page]: https://github.com/trezor/trezor-suite/tree/develop/packages/connect
+  [python-trezor]: https://pypi.org/project/trezor/
+  [1]: https://github.com/trezor/trezor-firmware/tree/master/python
+  [trezorctl]: ../python/trezorctl.md
+  [trezor-android]: https://github.com/trezor/trezor-android
+  [3]: https://github.com/gary-rowe/trezor-java
+  [4]: https://www.nuget.org/packages/Trezor.Net/
+  [5]: https://github.com/MelbourneDeveloper/Trezor.Net

docs/legacy/index.md

@@ -1,5 +1,7 @@
 # Trezor One Bootloader and Firmware
 
+_Building for Trezor Model T? See the [core](../core/build/index.md) documentation._
+
 ## Building with Docker
 
 Ensure that you have Docker installed. You can follow [Docker's installation instructions](https://docs.docker.com/engine/installation/).

docs/misc/contributing.md

@@ -15,3 +15,40 @@ Your Pull Request should follow these criteria:
 - A [changelog entry](changelog.md) must be part of the pull request.
 
 ### Please read and follow our [review procedure](review.md).
+
+## Adding a new coin
+
+### Forks and derivatives
+
+If the coin you are adding is a fork of Bitcoin or other cryptocurrency
+we already support (in other words, new app is not needed) you can
+modify the definitions in the [trezor-firmware][] repository and file a
+PR. In such case the coin does not have to be in TOP30 (see below), but
+we still reserve the right not to include the coin. The location depends
+on the type of the asset to be added:
+
+-   **Bitcoin clones** should be added to the [common/defs/bitcoin][]
+    subdirectory as separate .json files
+-   **Ethereum networks/chains** should be added to the
+    [ethereum-lists/chains][]
+-   **Ethereum tokens** should be added to the [ethereum-lists/tokens][]
+    repository
+-   **NEM mosaics** should be added to the
+    [common/defs/nem/nem_mosaics.json][] file
+
+### Other
+
+At the moment, we do not have the capacity to add new coins that do not
+fit the aforementioned category. Our current product goal is to unite
+what we support in firmware and in Trezor Suite and since firmware is
+way ahead of Suite we want to pause for a bit, implement the remaining
+coins into Suite and then consider adding new coins. This effectively
+means that **our team will not be accepting any requests to add new
+cryptocurrencies.**
+
+  [trezor-firmware]: https://github.com/trezor/trezor-firmware
+  [common/defs/bitcoin]: https://github.com/trezor/trezor-firmware/tree/master/common/defs/bitcoin
+  [ethereum-lists/chains]: https://github.com/ethereum-lists/chains
+  [ethereum-lists/tokens]: https://github.com/ethereum-lists/tokens
+  [common/defs/nem/nem_mosaics.json]: https://github.com/trezor/trezor-firmware/tree/master/common/defs/nem/nem_mosaics.json
+  [common/defs/misc/misc.json]: https://github.com/trezor/trezor-firmware/tree/master/common/defs/misc/misc.json

docs/misc/third-parties.md

@@ -31,7 +31,7 @@ of projects depending on Connect._
 #### Connect dependencies introduction
 
 Javascript projects that have Connect as a dependency are using the [Connect NPM
-package](https://www.npmjs.com/package/trezor-connect) on version specified in their
+package](https://www.npmjs.com/package/@trezor/connect) on version specified in their
 yarn.lock (or similar). This NPM package is not a complete Connect library, it is a
 simple layer that deals with opening an iframe and loading the newest Connect from
 connect.trezor.io.