arno/trezor-firmware
1
0
Fork 0
mirror of https://github.com/trezor/trezor-firmware.git synced 2025-07-19 21:18:14 +00:00
Code Issues Releases Wiki Activity

chore(docs): protobuf doc extended

Browse Source
This commit is contained in:
Martin Novak 2022-06-15 12:27:48 +02:00
parent 58276a7443
commit ed89bb132a
1 changed files with 60 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

60
common/protob/protocol.md
View File

@ -19,3 +19,63 @@ Following packets has the following structure:
|--------|--------|-------------|----------------------------------------------------------------------------------------|
| 0 | 1 | char[1] | '?' magic constant |
| 1 | 63 | uint8_t[63] | following bytes of message encoded in Protocol Buffers (padded with zeroes if shorter) |
## Adding new message
To add new message to Trezor protocol follow these steps:
1. Reconsider if there isn't already a message, that would suit your needs.
2. Choose the right place (file) to put new message:
- [`messages.proto`](messages.proto) are for management of the messages itself (wire type to message type mapping and etc.)
- [`messages-common.proto`](messages-common.proto) are for common messages
- all other files have a suffix `messages-SUFFIX.proto`, where suffix describes specific use case of messages contained within the file
3. Add new message and comment it properly following our [Messages naming and documenting conventions](#messages-naming-and-documenting-conventions).
4. If message is not embedded in another message, it has to have a wire type number assigned. This number is used to map
between Trezor wire identifier (uint) and a protobuf message. Mapping is defined in [`messages.proto`](messages.proto#L76). You have to find the lowest
free number and assign it to new message.
## Messages naming and documenting conventions
Message names must:
- be as self explanatory as possible
- have `Ack` suffix if the message is a received message (send from host to device) and serves as a response to some request made by device before
(e.g. initial messages from host to device doesn't have to have this suffix)
Documenting/commenting the messages is mandatory. Please use the following template:
```protobuf
/**
* MSG_TYPE: Description of the message
* MSG_FLOW_TAG
* MSG_FLOW_TAG
* ...
*/
```
where:
- `MSG_TYPE` is used to describe the purpose of the message and its type. Possible values are:
- `Request` for inbound messages (coming to the device (Trezor))
- `Response` for outbound messages (coming out from the device)
- in case that the message is embedded in another message we don't state the message type
- `MSG_FLOW_TAG` denotes the flow of the messages in a session (use case). Possible tags are:
- `@start` means that this message is first
- `@end`means that this message is last
- `@next` denotes messages that could follow after this message
- `@embed` denotes messages that are embedded into other message(s)
- `@auxstart` - ?? diamond start
- `@auxend` - ?? diamond end
Messages flow is checked at the compile time.
Using the template and the rules we can create for example this messages:
```protobuf
/**
* Request: Ask device to sign transaction
* @start
* @next TxRequest
* @next Failure
*/
```
```protobuf
/**
* Structure representing BIP32 (hierarchical deterministic) node
* Used for imports of private key into the device and exporting public key out of device
* @embed
*/
```