ELIP: 100 Layer: Applications Title: Hardware Wallet Extensions for Partially Signed Elements Transaction Format Author: Mikhail Tolkachev <contact@miketolkachev.dev> Comments-Summary: No comments yet. Status: Draft Type: Standards Track Created: 2022-12-01 License: BSD-2-Clause
This document describes proprietary extensions to the BIP 370 PSBT Version 2. These extensions are for use in Elements Sidechains to hold the information necessary for interaction with hardware wallets and other offline signer applications having no network access. It is assumed that the lifecycle of the proposed fields is limited to a communication session between the host software and an offline device.
This ELIP is licensed under the 2-clause BSD license.
The Hardware Wallet Extensions complement the Partially Signed Elements Transaction (PSET) format, which extends the BIP 370 PSBT format. The changes are new proprietary type fields. This specification inherits a magic sequence, roles, and additional constraints from the main PSET specification (Partially Signed Elements Transaction Format). To avoid duplication of information, basic definitions from the PSET specification are not included in this ELIP. At the time of writing, PSET specification had not been issued as an ELIP and is available at:
https://github.com/ElementsProject/elements/blob/master/doc/pset.mediawiki
To avoid possible collisions with PSET fields from the main specification, a distinct proprietary field prefix "pset_hww" is used for the fields belonging to Hardware Wallet Extensions. For example, identifier of PSBT_ELEMENTS_HWW_GLOBAL_ASSET_METADATA is a sequence of 11 bytes 0xfc08707365745f68777700.
The new global proprietary types specific to Hardware Wallet Extensions are as follows:
| Name | <keytype> | <keydata> | <keydata> Description | <valuedata> | <valuedata> Description | Versions Requiring Inclusion | Versions Requiring Exclusion | Versions Allowing Inclusion |
|---|---|---|---|---|---|---|---|---|
| Asset Metadata | PSBT_ELEMENTS_HWW_GLOBAL_ASSET_METADATA = 0x00 | <32 byte asset tag> | A 32-byte asset tag which corresponds to this metadata. | <compact size uint contractLen><contract><32-byte prevoutTxid><32-bit little endian uint prevoutIndex> | A compact size unsigned integer representing size of the contract in bytes, contractLen, is followed with the contract itself as a JSON document, canonicalized to have its keys sorted lexicographically. The input of an asset issuance transaction is represented as prevoutTxid - a 32-byte previous transaction hash, and prevoutIndex - a 32-bit little endian unsigned integer containing a zero-based index of the previous transaction's output. | 0 | 2 | |
| Reissuance Token Definition | PSBT_ELEMENTS_HWW_GLOBAL_REISSUANCE_TOKEN = 0x01 | <32 byte token tag> | A 32-byte asset tag of a reissuance token. | <1 byte boolean issuanceBlinded><32-byte asset tag> | A boolean flag issuanceBlinded indicates a non-blinded issuance if set to 0x00, and a blinded issuance if set to 0x01. A 32-byte tag that follows it corresponds to an asset to which this reissuance token belongs. | 0 | 2 |
For all Elements PSBT proprietary fields, PSETs cannot be combined when there are duplicate fields except in the case where those fields are identical.
Using the transaction format involves many different responsibilities. Multiple responsibilities can be handled by a single entity, but each responsibility is specialized in what it should be capable of doing. This specification relies on definition of roles in the main PSET standard. The following statements describe specifics of handling Hardware Wallet Extensions for some of the roles for which it is applicable.
Besides the responsibilities defined in PSET specification, Updater should add asset metadata for each asset referenced in any inputs or issuance outputs. This information is typically queried from the global asset registry, but cached or pre-defined information could be used as well. For each asset, the Updater adds a separate field using asset tag as keydata. The Updater is responsible to make a reasonable number of checks for the asset metadata before it is injected into a PSET intended for offline signing. These checks must include verification of the metadata source. It is also critical for the Updater to perform best effort checking to detect bogus assets impersonating legitimate assets through visually or semantically similar names and tickers.
For the transactions involving asset reissuance tokens, Updater should also include the PSET reissuance token definition field for each of the tokens in use. Such transactions include asset issuance, asset reissuance, reissuance token transfer, and reissuance token burn. If an Updater adds a definition for some reissuance token, it's obligatory to include a metadata field for the asset to which this reissuance token belongs. A PSET with a reissuance token definition missing associated asset metadata is considered invalid. However, it's allowed for an asset metadata field to not have a corresponding reissuance token definition if the reissuance token is unknown or irrelevant to the transaction.
As a single entity is likely to be both a Creator and Updater, and thus it makes possible to fill-in asset metadata and reissuance token definition on PSET creation step.
WARNING: PSET containing the fields belonging to Hardware Wallet Extensions is not supposed to be transmitted to other parties, to avoid encouraging them to trust this information. Updater must remove all asset metadata and reissuance token definition records after completing the signature process involving an offline entity.
In addition to the Signer behavior defined in BIP 370 PSBT and the main PSET standard, the Signer should be responsible for properly handling fields belonging to Hardware Wallet Extensions. Within the scope of this specification, it is assumed that the Signer role is implemented by a hardware wallet or any application running on an airgapped device with similar concept.
Asset metadata fields, PSBT_ELEMENTS_HWW_GLOBAL_ASSET_METADATA are fully optional, meaning that the Signer should not assume their presence for all or some of the assets referenced in the transaction. But if any of the asset metadata fields is present, the Signer must verify it by re-computing the asset tag from the given contract and issuance transaction's input. This field is provided to the Signer for displaying rich asset information to the user. For security reasons, it is highly recommended that externally provided asset metadata is displayed along with the full asset tag in hexadecimal form, if it is within technical capabilities of the HWW. This is because the asset metadata may be valid, but contain, e.g., a ticker that mimics another asset. If only the ticker is shown, the users signing the transaction may be tricked into signing an asset that they did not intend. Since a hardware wallet typically does not have access to the network, PSET fields may be the only source of metadata for this category of Signer implementation, except for its internal asset database.
Reissuance token definition fields PSBT_ELEMENTS_HWW_GLOBAL_REISSUANCE_TOKEN are supplementary fields for the corresponding asset metadata fields. Their presence in PSET is optional; however, if present, every reissuance token definition must have an associated asset metadata field. The Signer should not assume the presence of a reissuance token definition for every asset metadata field included in PSET. If any of the reissuance token definition fields are present, the Signer must perform the verification of these fields by computing the reissuance token's tag. This is done by using the information stored in the associated asset metadata fields and the value of issuanceBlinded flag. Verification is considered successful if the computed tag matches the one included in keydata. It is supposed that a Signer uses definitions of reissuance tokens to display textual information on them, like a ticker of the associated asset wrapped with a comment unambiguously denoting this token as a reissuance token.
The Transaction Extractor should normally ignore the fields belonging to Hardware Wallet Extensions as none of these fields affects the produced transaction.
Valid asset metadata record in PSET composed of the listed below values:
Source values:
Asset tag : 48f835622f34e8fdc313c90d4a8659aa4afe993e32dcb03ae6ec9ccdc6fcbe18
Reissuance token : d739234098f77172cb22f0de8affd6826d6b9d23d97e04575764786a5b0056e1
Contract. : {"entity":{"domain":"example.com"},"issuer_pubkey":"03455ee7cedc97b0ba435b80066fc92c963a34c600317981d135330c4ee43ac7a3","name":"Testcoin","precision":2,"ticker":"TEST","version":0}
prevoutTxid : 3514a07cf4812272c24a898c482f587a51126beef8c9b76a9e30bf41b0cbe53c
prevoutIndex : 1
issuance : blinded
Resulting asset metadata record:
key : fc08707365745f6877770018befcc6cd9cece63ab0dc323e99fe4aaa59864a0dc913c3fde8342f6235f848
value : b47b22656e74697479223a7b22646f6d61696e223a226578616d706c652e636f6d227d2c226973737565725f7075626b6579223a22303334353565653763656463393762306261343335623830303636666339326339363361333463363030333137393831643133353333306334656534336163376133222c226e616d65223a2254657374636f696e222c22707265636973696f6e223a322c227469636b6572223a2254455354222c2276657273696f6e223a307d3ce5cbb041bf309e6ab7c9f8ee6b12517a582f488c894ac2722281f47ca0143501000000
Resulting reissuance token definition record:
key : fc08707365745f68777701e156005b6a78645757047ed9239d6b6d82d6ff8adef022cb7271f798402339d7
value : 0118befcc6cd9cece63ab0dc323e99fe4aaa59864a0dc913c3fde8342f6235f848
Invalid contracts that should be detected by contract parser:
- Missing ticker:
{"entity":{"domain":"example.com"},"issuer_pubkey":"03455ee7cedc97b0ba435b80066fc92c963a34c600317981d135330c4ee43ac7a3","name":"Testcoin","precision":2,"version":0} - Missing precision:
{"entity":{"domain":"example.com"},"issuer_pubkey":"03455ee7cedc97b0ba435b80066fc92c963a34c600317981d135330c4ee43ac7a3","name":"Testcoin","ticker":"TEST","version":0} - Ticker is too long:
{"entity":{"domain":"example.com"},"issuer_pubkey":"03455ee7cedc97b0ba435b80066fc92c963a34c600317981d135330c4ee43ac7a3","name":"Testcoin","precision":2,"ticker":"1234567890123456789012345","version":0} - Forbidden whitespace:
{"entity":{"domain":"example.com"}, "issuer_pubkey":"03455ee7cedc97b0ba435b80066fc92c963a34c600317981d135330c4ee43ac7a3","name":"Testcoin","precision":2,"ticker":"TEST","version":0} - Duplicate key (name):
{"entity":{"domain":"example.com"},"issuer_pubkey":"03455ee7cedc97b0ba435b80066fc92c963a34c600317981d135330c4ee43ac7a3","name":"Testcoin","name":"Othercoin","precision":2,"ticker":"TEST","version":0} - Non-sorted keys:
{"name":"Testcoin","entity":{"domain":"example.com"},"issuer_pubkey":"03455ee7cedc97b0ba435b80066fc92c963a34c600317981d135330c4ee43ac7a3","precision":2,"ticker":"TEST","version":0}
PSETs containing Hardware Wallet Extensions are considered backwards compatible with both the mainstream PSET format and the BIP 370 PSBT Version 2 format, on which PSET is based.
Existing implementations, following the policy specified in the initial BIP 174 PSBT specification, ignore all unknown fields, and thus should not be affected by the presence of the new fields belonging to Hardware Wallet Extensions. Since none of the new fields affect produced signatures nor the network format transaction, inability to process these new fields has no functional consequences.
New implementations taking advantage of the Hardware Wallet Extensions should not rely on the presence of these new fields. For example, a hardware wallet application discovering the absence of the expected asset metadata must fall back to displaying hexadecimal asset identifier instead of ticker.
TBD