@trezor/protobuf

@trezor/protobuf

Library for handling protobuf interfaces with Trezor, powered by @bufbuild/protobuf.

From Protobuf to TypeScript

This section describes how the definitions of protobuf messages maintained in the firmware repo are semi-automatically translated to TypeScript definitions that are used in Connect codebase and by Connect users respectively.

The short version

In order to be able to use new features of trezor-firmware you need to update protobuf definitions.

1. yarn update-protobuf <branch-name> to generate new ./src/definitions/*_pb.ts and ./src/types/messages.ts. If you don't provide branch-name argument, 'main' will be used.

In depth explanation

The beginning and source of truth are the .proto definitions in the firmware repository.

The .proto definitions are compiled to TypeScript modules (*_pb.ts) using @bufbuild/protobuf. These generated modules provide static message schemas used by ProtobufManager for encoding/decoding and are also used to generate TypeScript type definitions.

TypeScript definitions are generated by a script in scripts/protobuf-types.js. The script also applies 'patches' described in scripts/protobuf-patches.js. The patches compensate for/fix

• The source .proto definitions that do not reflect the actual business logic. Usually fields marked as required which are in fact optional.
• Fields typed as uint32, uint64, sint32, sint64 in protobuf that need to be represented as strings in runtime because of javascript number's insufficient range. Runtime conversion is handled automatically by @trezor/transport.
• Similarly, fields typed as bytes in protobuf may be represented as hexadecimal string, Buffer, Uint8Array or Array<number> in runtime.
• Optional protobuf fields that get typed as <T> | undefined but are in fact deserialized as <T> | null. This could be handled globally by @trezor/transport. The patches exist mainly for historical reasons.

All these steps are done manually and all the generated files are tracked in git.