From 6c8c9780b019d549156c8af8c23d47466e4a3f0f Mon Sep 17 00:00:00 2001 From: Kyryl R Date: Tue, 30 Jun 2026 14:39:37 +0300 Subject: [PATCH 1/5] clear-signing: add basic draft --- clear-signing.mediawiki | 621 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 621 insertions(+) create mode 100644 clear-signing.mediawiki diff --git a/clear-signing.mediawiki b/clear-signing.mediawiki new file mode 100644 index 0000000..785e953 --- /dev/null +++ b/clear-signing.mediawiki @@ -0,0 +1,621 @@ +
+ELIP: TBD
+Layer: Wallet
+Title: Clear Signing for Liquid
+Author: TBD
+Comments-Summary: No comments yet.
+Comments-URI: TBD
+Status: Draft
+Type: Standards Track
+Created: 2026-06-09
+License: BSD-3-Clause
+
+ +==Abstract== + +This document defines a structured metadata profile for wallets to interpret an Elements transaction for the user. It helps users understand the consequences of signing a particular transaction and lowers the risk of blind signing as much as possible. + +It does not specify how this metadata is verified or made trusted. + +==Copyright== + +This document is licensed under the 3-clause BSD license. + +==Motivation== + +To expand the Liquid ecosystem, infrastructure and user-facing applications should be able to explain to a non-technical user what is happening and which outcomes to expect. Similar to banking systems, users should be given as much security as possible by default. Therefore, ecosystem participants should make as much effort as possible in explaining actions to the user. + +This profile presents a way to interpret a general-purpose action of signing a transaction on the Liquid network to the user. + +==Specification== + +The keywords "MUST", "MUST NOT", "REQUIRED", "SHOULD", "SHOULD NOT", and "MAY" in this document are to be interpreted as described in [https://www.rfc-editor.org/rfc/rfc2119 RFC 2119]. + +==Scope== + +This document is scoped to regular Liquid transfers, asset issuance, asset burn, multisig signing flows that a wallet can identify with sufficient confidence, and Simplicity covenant spends. + +Non-Simplicity Taproot script-path spends are out of scope. Bitcoin Script and Miniscript covenant interpretation outside the regular cases above is out of scope. A separate library, BIP, or ELIP should define clear signing for non-Simplicity Taproot and general Bitcoin Script covenant interpretation. + +This document does not specify the final shape of wallet views. It specifies what information should be available to the wallet and what information should be included in the metadata documents used for clear signing. + +==General== + +This document defines a clear-signing request. + +A clear-signing request is the request or proposal displayed to the user for review. This request MUST be presented from the simplest form to a deep technical level. + +A wallet SHOULD make the best effort to inform the user about the action being executed and its consequences. + +The ideal example to follow is: + +Transfer request: + +
+You send Alice 10.25 USDT
+
+ +where: + + +# Alice is an alias for the receiver account. +# 10.25 is the amount with decimals. +# USDT is an alias for the token being spent. + +Multisig request, initiating the multisig transfer: + +
+Initiating a send of Yours and Bob's 10.25 USDT to Alice
+
+ +where: + + +# Initiating a send is the action being performed. +# Yours and Bob's are the parties involved in multisig. +# 10.25, USDT, and Alice have the same definitions as in the transfer request. + +Multisig request, finalizing the multisig transfer: + +
+Finalizing a send of Yours and Bob's 10.25 USDT to Alice
+
+ +where all definitions are the same as in the multisig request example, and the only difference is the action being performed. + +Taproot spend, Simplicity, lending a settlement asset to the borrower: + +
+Lending 1500.00 USDT to , receiving a Lending liquidation token
+ is bip122:1466275836220db2944ca059a3a10ef6:b781-7bc7-db64-c3de-3937-7eb7-c9ab-f799
+Lending liquidation token gives an opportunity to liquidate in case of borrower offer expiry.
+
+ +This information is the first information shown to the user. + +The wallet MUST allow entering a detailed view for: + + +# Accounts and their aliases, later referred to as account. +# The action being performed. +# Asset ID and its metadata, later referred to as the asset metadata document. +# Amounts. +# Simplicity covenant spend information, later referred to as the covenant metadata document. + +Every detailed view is meant to inform the user about the exact final transaction shape. + +==Account and Chain Binding== + +Every clear-signing request MUST be bound to the active Liquid or Elements chain. + +
+chain_id = "bip122:" + first_32_lowercase_hex_characters_of_genesis_block_hash
+
+ +Liquid mainnet uses: + +
+bip122:1466275836220db2944ca059a3a10ef6
+
+ +Liquid testnet uses: + +
+bip122:a771da8e52ee6ad581ed1e9a99825e5b
+
+ +Liquid asset identifiers MUST use the [https://github.com/ElementsProject/ELIPs/blob/main/elip-0144.mediawiki ELIP-0144] asset ID form: + +
+asset_id = chain_id + "/" + asset_namespace + ":" + asset_reference
+asset_namespace = "elip144"
+asset_reference = 64 lowercase hex characters
+
+ +The Liquid mainnet policy asset ID is: + +
+bip122:1466275836220db2944ca059a3a10ef6/elip144:6f0279e9ed041c3d710a9f57d0c02928416460c4b722ae3457a11eec381c526d
+
+ +A wallet MUST validate that every chainId, account, asset metadata document, covenant metadata document, and asset ID refers to the active chain. + +==Metadata Document Model== + +Each imported metadata object is a standalone document. A user imports an account metadata document, an asset metadata document, an action metadata document, or a covenant metadata document. + +A clear-signing request MAY reference standalone documents by hash, by local identifier, by registry identifier, or by embedding the document directly. This document does not specify the transport mechanism for metadata documents. + +Each metadata document MUST contain: + +{| +! Field +! Type +! Required +! Description +|- +| $schema +| String +| Yes +| The JSON Schema URI for this document type. +|- +| kind +| String +| Yes +| The metadata document kind. +|- +| version +| Integer +| Yes +| The version of the document kind. +|- +| context +| Object +| Yes +| The constraints that MUST match before the document is used. +|- +| metadata +| Object +| Yes +| Trusted constants values that are usable after context matching. +|- +| display +| Object +| Yes +| User-facing labels, intent strings, detail labels, and formatting rules. +|} + +A wallet MUST verify the context before applying metadata or display. + +A wallet MUST NOT use metadata as the source of truth for the final transaction shape. A wallet MUST compute final transaction shape from the transaction, PSET, wallet state, and wallet policy. + +A metadata document MAY contain a documentId field. If present, documentId MUST be a hash of the canonical document bytes or a registry identifier bound to that hash. + +==Clear-Signing Review Layers== + +A wallet SHOULD review a clear-signing request in layers: + + +# Summary layer. +# Net balance layer. +# Account details layer. +# Asset details layer. +# Action details layer. +# Amount details layer. +# Simplicity covenant details layer. +# Raw fallback layer. + +The summary layer SHOULD be short and user-facing. + +The net balance layer MUST be wallet-computed and grouped per asset. + +The account details layer MUST show the full account identifier based on [https://github.com/ElementsProject/ELIPs/blob/main/elip-0144.mediawiki ELIP-0144]. + +The asset details layer MUST show the full asset ID. + +The action details layer MUST show the action being performed and the source of the action match. + +The amount details layer MUST show the base-unit amount and the formatted display amount when asset precision is available. + +The Simplicity covenant details layer MUST show the covenant metadata document and the matched action. + +The raw fallback layer SHOULD show the raw account, asset, action, and covenant binding values when the wallet cannot safely shorten or explain them. + +==Account Metadata Document== + +An account metadata document binds an [https://github.com/ElementsProject/ELIPs/blob/main/elip-0144.mediawiki ELIP-0144] account ID to a user-facing alias. + +The detailed account view MUST show the full account ID. The detailed account view MUST NOT shorten the account ID itself. + +If possible, a wallet SHOULD use an alias. If there is no alias, the wallet SHOULD make its best effort to point the user to the full account form so the user can verify it. + +A wallet MAY abbreviate an account in the summary layer only if the full account ID is available in the detailed view. + +===Account Metadata Fields=== + +{| +! Field +! Type +! Required +! Description +|- +| kind +| String +| Yes +| MUST be liquid.accountMetadata. +|- +| context.chainId +| String +| Yes +| The active Liquid or Elements chain ID. +|- +| context.account +| String +| Yes +| The full account ID. +|- +| metadata.alias +| String +| No +| The account alias. +|- +| metadata.description +| String +| No +| A human-readable description of the account. +|- +| metadata.owner +| String +| No +| A human-readable owner label. +|- +| metadata.infoUrl +| String +| No +| A URL with more information. +|- +| display.summaryLabel +| String +| No +| A short label for summary views. +|- +| display.detailFields +| Array +| No +| A list of detailed fields to display. +|} + +===Account Metadata Example=== + +
+{
+  "$schema": "https://example.invalid/liquid-clear-signing/account-metadata-v0.schema.json",
+  "kind": "liquid.accountMetadata",
+  "version": 0,
+  "context": {
+    "chainId": "bip122:1466275836220db2944ca059a3a10ef6",
+    "account": "bip122:1466275836220db2944ca059a3a10ef6:b781-7bc7-db64-c3de-3937-7eb7-c9ab-f799"
+  },
+  "metadata": {
+    "alias": "Alice",
+    "description": "Receiver account"
+  },
+  "display": {
+    "summaryLabel": "Alice",
+    "detailFields": [
+      { "label": "Account", "path": "$.context.account" },
+      { "label": "Alias", "path": "$.metadata.alias" }
+    ]
+  }
+}
+
+ +==Asset Metadata Document== + +An asset metadata document binds an [https://github.com/ElementsProject/ELIPs/blob/main/elip-0144.mediawiki ELIP-0144] asset ID to asset metadata. + +The detailed asset view MUST show the full asset ID. If an asset alias, ticker, or name is unavailable, the wallet MUST fall back to displaying the full asset ID. + +The wallet MUST validate that the asset metadata document refers to the active chain. + +The asset metadata document SHOULD be compatible with the existing Liquid asset contract shape used by the Liquid asset registry and [https://github.com/ElementsProject/ELIPs/blob/main/elip-0100.mediawiki ELIP-0100], including entity.domain, issuer_pubkey, name, precision, ticker, and version when those fields are available. + +===Asset Metadata Fields=== + +{| +! Field +! Type +! Required +! Description +|- +| kind +| String +| Yes +| MUST be liquid.assetMetadata. +|- +| context.chainId +| String +| Yes +| The active Liquid or Elements chain ID. +|- +| context.assetId +| String +| Yes +| The full ELIP-0144 asset ID. +|- +| metadata.name +| String +| No +| The asset display name. +|- +| metadata.ticker +| String +| No +| The ticker shown in the summary layer. +|- +| metadata.precision +| Integer +| No +| The decimal precision used to format base-unit amounts. +|- +| metadata.entity.domain +| String +| No +| The issuer or entity domain. +|- +| metadata.issuer_pubkey +| String +| No +| The issuer public key from the asset contract. +|- +| metadata.version +| Integer +| No +| The asset contract version. +|- +| display.summaryLabel +| String +| No +| A short label for summary views. +|- +| display.detailFields +| Array +| No +| A list of detailed fields to display. +|} + +===Asset Amount Formatting=== + +Amounts MUST be computed in base units first. + +If metadata.precision is available and valid, the wallet MAY display the amount as a decimal value. If precision is unavailable, the wallet MUST display the base-unit amount and SHOULD show that decimal precision is unavailable. + +Asset metadata MUST NOT override the asset ID of a transaction input or output. + +===Asset Metadata Example=== + +
+{
+  "$schema": "https://example.invalid/liquid-clear-signing/asset-metadata-v0.schema.json",
+  "kind": "liquid.assetMetadata",
+  "version": 0,
+  "context": {
+    "chainId": "bip122:1466275836220db2944ca059a3a10ef6",
+    "assetId": "bip122:1466275836220db2944ca059a3a10ef6/elip144:ce091c998b83c78bb71a632313ba3760f1763d9cfcffae02258ffa9865a37bd2"
+  },
+  "metadata": {
+    "entity": {
+      "domain": "tether.to"
+    },
+    "name": "Tether USDt",
+    "precision": 8,
+    "ticker": "USDT",
+    "version": 0
+  },
+  "display": {
+    "summaryLabel": "USDT",
+    "detailFields": [
+      { "label": "Asset ID", "path": "$.context.assetId" },
+      { "label": "Ticker", "path": "$.metadata.ticker" },
+      { "label": "Name", "path": "$.metadata.name" },
+      { "label": "Precision", "path": "$.metadata.precision" }
+    ]
+  }
+}
+
+ +==Amounts and Net Balance Changes== + +A wallet MUST compute net balance changes per asset. + +A wallet MUST compute the amount lost by the wallet, the amount gained by the wallet, and the amount that stays in the wallet as change, per asset, when the required transaction data and wallet state are available. + +A wallet MUST show fees as part of the net balance review for the fee asset. + +A wallet MUST NOT use a metadata document as the source of truth for amount or asset movement. + +A wallet MUST reject or clearly downgrade the review if it cannot compute a safe review of wallet inputs, wallet outputs, fees, and confidentiality status. + +===Net Balance Change Fields=== + +A clear-signing request review SHOULD expose the following wallet-computed structure to the display layer: + +{| +! Field +! Type +! Required +! Description +|- +| assetId +| String +| Yes +| The ELIP-0144 asset ID. +|- +| inputAmount +| String +| Yes +| Wallet-owned input amount in base units. +|- +| outputAmount +| String +| Yes +| Wallet-owned output amount in base units. +|- +| changeAmount +| String +| No +| Wallet-owned change amount in base units when the wallet can identify change. +|- +| externalReceiveAmount +| String +| No +| Amount received by external accounts when known. +|- +| feeAmount +| String +| No +| Fee amount for this asset when this asset pays fees. +|- +| netAmount +| String +| Yes +| outputAmount - inputAmount, in base units, from the wallet perspective. +|- +| direction +| String +| Yes +| loss, gain, or neutral. +|- +| confidence +| String +| Yes +| verified, partial, or unknown. +|} + +===Net Balance Change Example=== + +
+{
+  "assetId": "bip122:1466275836220db2944ca059a3a10ef6/elip144:ce091c998b83c78bb71a632313ba3760f1763d9cfcffae02258ffa9865a37bd2",
+  "inputAmount": "1025000000",
+  "outputAmount": "0",
+  "externalReceiveAmount": "1025000000",
+  "netAmount": "-1025000000",
+  "direction": "loss",
+  "confidence": "verified"
+}
+
+ +==Action Metadata Document== + +An action metadata document describes the action being performed. + +In cases like issuance, burn, transfer, and multisig, the action can be a special case recognized by the wallet. + +In some cases, a wallet MAY rely on Bitcoin Script or transaction pattern matching to understand what is happening. In some cases, this cannot be possible because of the complexity of multisig schemes and because some schemes are indistinguishable from each other from the pure transaction point of view. + +An action metadata document MUST NOT override wallet-computed transaction shape. + +===Built-In Regular Actions=== + +This profile recognizes the following regular actions: + +{| +! Action +! Description +|- +| transfer +| A transfer of an existing asset. +|- +| issuance +| A issuance of a new Liquid asset. +|- +| re-issuance +| A re-issuance of a Liquid asset. +|- +| burn +| A burn of an existing Liquid asset. +|- +| unknown +| A non-Simplicity action that the wallet cannot classify. +|} + +===Action Metadata Fields=== + +{| +! Field +! Type +! Required +! Description +|- +| kind +| String +| Yes +| MUST be liquid.actionMetadata. +|- +| context.chainId +| String +| Yes +| The active Liquid or Elements chain ID. +|- +| context.actionType +| String +| Yes +| A built-in regular action identifier. +|- +| metadata.name +| String +| No +| The action display name. +|- +| metadata.description +| String +| No +| The action description. +|- +| display.intent +| String +| Yes +| A short action intent. +|- +| display.interpolatedIntent +| String +| No +| A short summary template. +|- +| display.fields +| Array +| No +| Display fields required for the action. +|} + +===Action Metadata Example=== + +
+{
+  "$schema": "https://example.invalid/liquid-clear-signing/action-metadata-v0.schema.json",
+  "kind": "liquid.actionMetadata",
+  "version": 0,
+  "context": {
+    "chainId": "bip122:1466275836220db2944ca059a3a10ef6",
+    "actionType": "transfer"
+  },
+  "metadata": {
+    "name": "Transfer",
+    "description": "A regular transfer of a Liquid asset."
+  },
+  "display": {
+    "intent": "Send",
+    "interpolatedIntent": "You send {to} {amount} {asset}",
+    "fields": [
+      { "path": "to", "label": "To", "format": "account" },
+      { "path": "amount", "label": "Amount", "format": "assetAmount" },
+      { "path": "asset", "label": "Asset", "format": "asset" }
+    ]
+  }
+}
+
+ +==Simplicity Covenant Metadata Document== + +TBD From 1e86fda46814d5c606b37ebe3333dab09da180d1 Mon Sep 17 00:00:00 2001 From: Kyryl R Date: Fri, 4 Sep 2026 15:36:50 +0300 Subject: [PATCH 2/5] update header, abstract, and motivation sections, remove outdated sections --- clear-signing.mediawiki | 621 ---------------------------------------- elip-0206.mediawiki | 42 +++ 2 files changed, 42 insertions(+), 621 deletions(-) delete mode 100644 clear-signing.mediawiki create mode 100644 elip-0206.mediawiki diff --git a/clear-signing.mediawiki b/clear-signing.mediawiki deleted file mode 100644 index 785e953..0000000 --- a/clear-signing.mediawiki +++ /dev/null @@ -1,621 +0,0 @@ -
-ELIP: TBD
-Layer: Wallet
-Title: Clear Signing for Liquid
-Author: TBD
-Comments-Summary: No comments yet.
-Comments-URI: TBD
-Status: Draft
-Type: Standards Track
-Created: 2026-06-09
-License: BSD-3-Clause
-
- -==Abstract== - -This document defines a structured metadata profile for wallets to interpret an Elements transaction for the user. It helps users understand the consequences of signing a particular transaction and lowers the risk of blind signing as much as possible. - -It does not specify how this metadata is verified or made trusted. - -==Copyright== - -This document is licensed under the 3-clause BSD license. - -==Motivation== - -To expand the Liquid ecosystem, infrastructure and user-facing applications should be able to explain to a non-technical user what is happening and which outcomes to expect. Similar to banking systems, users should be given as much security as possible by default. Therefore, ecosystem participants should make as much effort as possible in explaining actions to the user. - -This profile presents a way to interpret a general-purpose action of signing a transaction on the Liquid network to the user. - -==Specification== - -The keywords "MUST", "MUST NOT", "REQUIRED", "SHOULD", "SHOULD NOT", and "MAY" in this document are to be interpreted as described in [https://www.rfc-editor.org/rfc/rfc2119 RFC 2119]. - -==Scope== - -This document is scoped to regular Liquid transfers, asset issuance, asset burn, multisig signing flows that a wallet can identify with sufficient confidence, and Simplicity covenant spends. - -Non-Simplicity Taproot script-path spends are out of scope. Bitcoin Script and Miniscript covenant interpretation outside the regular cases above is out of scope. A separate library, BIP, or ELIP should define clear signing for non-Simplicity Taproot and general Bitcoin Script covenant interpretation. - -This document does not specify the final shape of wallet views. It specifies what information should be available to the wallet and what information should be included in the metadata documents used for clear signing. - -==General== - -This document defines a clear-signing request. - -A clear-signing request is the request or proposal displayed to the user for review. This request MUST be presented from the simplest form to a deep technical level. - -A wallet SHOULD make the best effort to inform the user about the action being executed and its consequences. - -The ideal example to follow is: - -Transfer request: - -
-You send Alice 10.25 USDT
-
- -where: - - -# Alice is an alias for the receiver account. -# 10.25 is the amount with decimals. -# USDT is an alias for the token being spent. - -Multisig request, initiating the multisig transfer: - -
-Initiating a send of Yours and Bob's 10.25 USDT to Alice
-
- -where: - - -# Initiating a send is the action being performed. -# Yours and Bob's are the parties involved in multisig. -# 10.25, USDT, and Alice have the same definitions as in the transfer request. - -Multisig request, finalizing the multisig transfer: - -
-Finalizing a send of Yours and Bob's 10.25 USDT to Alice
-
- -where all definitions are the same as in the multisig request example, and the only difference is the action being performed. - -Taproot spend, Simplicity, lending a settlement asset to the borrower: - -
-Lending 1500.00 USDT to , receiving a Lending liquidation token
- is bip122:1466275836220db2944ca059a3a10ef6:b781-7bc7-db64-c3de-3937-7eb7-c9ab-f799
-Lending liquidation token gives an opportunity to liquidate in case of borrower offer expiry.
-
- -This information is the first information shown to the user. - -The wallet MUST allow entering a detailed view for: - - -# Accounts and their aliases, later referred to as account. -# The action being performed. -# Asset ID and its metadata, later referred to as the asset metadata document. -# Amounts. -# Simplicity covenant spend information, later referred to as the covenant metadata document. - -Every detailed view is meant to inform the user about the exact final transaction shape. - -==Account and Chain Binding== - -Every clear-signing request MUST be bound to the active Liquid or Elements chain. - -
-chain_id = "bip122:" + first_32_lowercase_hex_characters_of_genesis_block_hash
-
- -Liquid mainnet uses: - -
-bip122:1466275836220db2944ca059a3a10ef6
-
- -Liquid testnet uses: - -
-bip122:a771da8e52ee6ad581ed1e9a99825e5b
-
- -Liquid asset identifiers MUST use the [https://github.com/ElementsProject/ELIPs/blob/main/elip-0144.mediawiki ELIP-0144] asset ID form: - -
-asset_id = chain_id + "/" + asset_namespace + ":" + asset_reference
-asset_namespace = "elip144"
-asset_reference = 64 lowercase hex characters
-
- -The Liquid mainnet policy asset ID is: - -
-bip122:1466275836220db2944ca059a3a10ef6/elip144:6f0279e9ed041c3d710a9f57d0c02928416460c4b722ae3457a11eec381c526d
-
- -A wallet MUST validate that every chainId, account, asset metadata document, covenant metadata document, and asset ID refers to the active chain. - -==Metadata Document Model== - -Each imported metadata object is a standalone document. A user imports an account metadata document, an asset metadata document, an action metadata document, or a covenant metadata document. - -A clear-signing request MAY reference standalone documents by hash, by local identifier, by registry identifier, or by embedding the document directly. This document does not specify the transport mechanism for metadata documents. - -Each metadata document MUST contain: - -{| -! Field -! Type -! Required -! Description -|- -| $schema -| String -| Yes -| The JSON Schema URI for this document type. -|- -| kind -| String -| Yes -| The metadata document kind. -|- -| version -| Integer -| Yes -| The version of the document kind. -|- -| context -| Object -| Yes -| The constraints that MUST match before the document is used. -|- -| metadata -| Object -| Yes -| Trusted constants values that are usable after context matching. -|- -| display -| Object -| Yes -| User-facing labels, intent strings, detail labels, and formatting rules. -|} - -A wallet MUST verify the context before applying metadata or display. - -A wallet MUST NOT use metadata as the source of truth for the final transaction shape. A wallet MUST compute final transaction shape from the transaction, PSET, wallet state, and wallet policy. - -A metadata document MAY contain a documentId field. If present, documentId MUST be a hash of the canonical document bytes or a registry identifier bound to that hash. - -==Clear-Signing Review Layers== - -A wallet SHOULD review a clear-signing request in layers: - - -# Summary layer. -# Net balance layer. -# Account details layer. -# Asset details layer. -# Action details layer. -# Amount details layer. -# Simplicity covenant details layer. -# Raw fallback layer. - -The summary layer SHOULD be short and user-facing. - -The net balance layer MUST be wallet-computed and grouped per asset. - -The account details layer MUST show the full account identifier based on [https://github.com/ElementsProject/ELIPs/blob/main/elip-0144.mediawiki ELIP-0144]. - -The asset details layer MUST show the full asset ID. - -The action details layer MUST show the action being performed and the source of the action match. - -The amount details layer MUST show the base-unit amount and the formatted display amount when asset precision is available. - -The Simplicity covenant details layer MUST show the covenant metadata document and the matched action. - -The raw fallback layer SHOULD show the raw account, asset, action, and covenant binding values when the wallet cannot safely shorten or explain them. - -==Account Metadata Document== - -An account metadata document binds an [https://github.com/ElementsProject/ELIPs/blob/main/elip-0144.mediawiki ELIP-0144] account ID to a user-facing alias. - -The detailed account view MUST show the full account ID. The detailed account view MUST NOT shorten the account ID itself. - -If possible, a wallet SHOULD use an alias. If there is no alias, the wallet SHOULD make its best effort to point the user to the full account form so the user can verify it. - -A wallet MAY abbreviate an account in the summary layer only if the full account ID is available in the detailed view. - -===Account Metadata Fields=== - -{| -! Field -! Type -! Required -! Description -|- -| kind -| String -| Yes -| MUST be liquid.accountMetadata. -|- -| context.chainId -| String -| Yes -| The active Liquid or Elements chain ID. -|- -| context.account -| String -| Yes -| The full account ID. -|- -| metadata.alias -| String -| No -| The account alias. -|- -| metadata.description -| String -| No -| A human-readable description of the account. -|- -| metadata.owner -| String -| No -| A human-readable owner label. -|- -| metadata.infoUrl -| String -| No -| A URL with more information. -|- -| display.summaryLabel -| String -| No -| A short label for summary views. -|- -| display.detailFields -| Array -| No -| A list of detailed fields to display. -|} - -===Account Metadata Example=== - -
-{
-  "$schema": "https://example.invalid/liquid-clear-signing/account-metadata-v0.schema.json",
-  "kind": "liquid.accountMetadata",
-  "version": 0,
-  "context": {
-    "chainId": "bip122:1466275836220db2944ca059a3a10ef6",
-    "account": "bip122:1466275836220db2944ca059a3a10ef6:b781-7bc7-db64-c3de-3937-7eb7-c9ab-f799"
-  },
-  "metadata": {
-    "alias": "Alice",
-    "description": "Receiver account"
-  },
-  "display": {
-    "summaryLabel": "Alice",
-    "detailFields": [
-      { "label": "Account", "path": "$.context.account" },
-      { "label": "Alias", "path": "$.metadata.alias" }
-    ]
-  }
-}
-
- -==Asset Metadata Document== - -An asset metadata document binds an [https://github.com/ElementsProject/ELIPs/blob/main/elip-0144.mediawiki ELIP-0144] asset ID to asset metadata. - -The detailed asset view MUST show the full asset ID. If an asset alias, ticker, or name is unavailable, the wallet MUST fall back to displaying the full asset ID. - -The wallet MUST validate that the asset metadata document refers to the active chain. - -The asset metadata document SHOULD be compatible with the existing Liquid asset contract shape used by the Liquid asset registry and [https://github.com/ElementsProject/ELIPs/blob/main/elip-0100.mediawiki ELIP-0100], including entity.domain, issuer_pubkey, name, precision, ticker, and version when those fields are available. - -===Asset Metadata Fields=== - -{| -! Field -! Type -! Required -! Description -|- -| kind -| String -| Yes -| MUST be liquid.assetMetadata. -|- -| context.chainId -| String -| Yes -| The active Liquid or Elements chain ID. -|- -| context.assetId -| String -| Yes -| The full ELIP-0144 asset ID. -|- -| metadata.name -| String -| No -| The asset display name. -|- -| metadata.ticker -| String -| No -| The ticker shown in the summary layer. -|- -| metadata.precision -| Integer -| No -| The decimal precision used to format base-unit amounts. -|- -| metadata.entity.domain -| String -| No -| The issuer or entity domain. -|- -| metadata.issuer_pubkey -| String -| No -| The issuer public key from the asset contract. -|- -| metadata.version -| Integer -| No -| The asset contract version. -|- -| display.summaryLabel -| String -| No -| A short label for summary views. -|- -| display.detailFields -| Array -| No -| A list of detailed fields to display. -|} - -===Asset Amount Formatting=== - -Amounts MUST be computed in base units first. - -If metadata.precision is available and valid, the wallet MAY display the amount as a decimal value. If precision is unavailable, the wallet MUST display the base-unit amount and SHOULD show that decimal precision is unavailable. - -Asset metadata MUST NOT override the asset ID of a transaction input or output. - -===Asset Metadata Example=== - -
-{
-  "$schema": "https://example.invalid/liquid-clear-signing/asset-metadata-v0.schema.json",
-  "kind": "liquid.assetMetadata",
-  "version": 0,
-  "context": {
-    "chainId": "bip122:1466275836220db2944ca059a3a10ef6",
-    "assetId": "bip122:1466275836220db2944ca059a3a10ef6/elip144:ce091c998b83c78bb71a632313ba3760f1763d9cfcffae02258ffa9865a37bd2"
-  },
-  "metadata": {
-    "entity": {
-      "domain": "tether.to"
-    },
-    "name": "Tether USDt",
-    "precision": 8,
-    "ticker": "USDT",
-    "version": 0
-  },
-  "display": {
-    "summaryLabel": "USDT",
-    "detailFields": [
-      { "label": "Asset ID", "path": "$.context.assetId" },
-      { "label": "Ticker", "path": "$.metadata.ticker" },
-      { "label": "Name", "path": "$.metadata.name" },
-      { "label": "Precision", "path": "$.metadata.precision" }
-    ]
-  }
-}
-
- -==Amounts and Net Balance Changes== - -A wallet MUST compute net balance changes per asset. - -A wallet MUST compute the amount lost by the wallet, the amount gained by the wallet, and the amount that stays in the wallet as change, per asset, when the required transaction data and wallet state are available. - -A wallet MUST show fees as part of the net balance review for the fee asset. - -A wallet MUST NOT use a metadata document as the source of truth for amount or asset movement. - -A wallet MUST reject or clearly downgrade the review if it cannot compute a safe review of wallet inputs, wallet outputs, fees, and confidentiality status. - -===Net Balance Change Fields=== - -A clear-signing request review SHOULD expose the following wallet-computed structure to the display layer: - -{| -! Field -! Type -! Required -! Description -|- -| assetId -| String -| Yes -| The ELIP-0144 asset ID. -|- -| inputAmount -| String -| Yes -| Wallet-owned input amount in base units. -|- -| outputAmount -| String -| Yes -| Wallet-owned output amount in base units. -|- -| changeAmount -| String -| No -| Wallet-owned change amount in base units when the wallet can identify change. -|- -| externalReceiveAmount -| String -| No -| Amount received by external accounts when known. -|- -| feeAmount -| String -| No -| Fee amount for this asset when this asset pays fees. -|- -| netAmount -| String -| Yes -| outputAmount - inputAmount, in base units, from the wallet perspective. -|- -| direction -| String -| Yes -| loss, gain, or neutral. -|- -| confidence -| String -| Yes -| verified, partial, or unknown. -|} - -===Net Balance Change Example=== - -
-{
-  "assetId": "bip122:1466275836220db2944ca059a3a10ef6/elip144:ce091c998b83c78bb71a632313ba3760f1763d9cfcffae02258ffa9865a37bd2",
-  "inputAmount": "1025000000",
-  "outputAmount": "0",
-  "externalReceiveAmount": "1025000000",
-  "netAmount": "-1025000000",
-  "direction": "loss",
-  "confidence": "verified"
-}
-
- -==Action Metadata Document== - -An action metadata document describes the action being performed. - -In cases like issuance, burn, transfer, and multisig, the action can be a special case recognized by the wallet. - -In some cases, a wallet MAY rely on Bitcoin Script or transaction pattern matching to understand what is happening. In some cases, this cannot be possible because of the complexity of multisig schemes and because some schemes are indistinguishable from each other from the pure transaction point of view. - -An action metadata document MUST NOT override wallet-computed transaction shape. - -===Built-In Regular Actions=== - -This profile recognizes the following regular actions: - -{| -! Action -! Description -|- -| transfer -| A transfer of an existing asset. -|- -| issuance -| A issuance of a new Liquid asset. -|- -| re-issuance -| A re-issuance of a Liquid asset. -|- -| burn -| A burn of an existing Liquid asset. -|- -| unknown -| A non-Simplicity action that the wallet cannot classify. -|} - -===Action Metadata Fields=== - -{| -! Field -! Type -! Required -! Description -|- -| kind -| String -| Yes -| MUST be liquid.actionMetadata. -|- -| context.chainId -| String -| Yes -| The active Liquid or Elements chain ID. -|- -| context.actionType -| String -| Yes -| A built-in regular action identifier. -|- -| metadata.name -| String -| No -| The action display name. -|- -| metadata.description -| String -| No -| The action description. -|- -| display.intent -| String -| Yes -| A short action intent. -|- -| display.interpolatedIntent -| String -| No -| A short summary template. -|- -| display.fields -| Array -| No -| Display fields required for the action. -|} - -===Action Metadata Example=== - -
-{
-  "$schema": "https://example.invalid/liquid-clear-signing/action-metadata-v0.schema.json",
-  "kind": "liquid.actionMetadata",
-  "version": 0,
-  "context": {
-    "chainId": "bip122:1466275836220db2944ca059a3a10ef6",
-    "actionType": "transfer"
-  },
-  "metadata": {
-    "name": "Transfer",
-    "description": "A regular transfer of a Liquid asset."
-  },
-  "display": {
-    "intent": "Send",
-    "interpolatedIntent": "You send {to} {amount} {asset}",
-    "fields": [
-      { "path": "to", "label": "To", "format": "account" },
-      { "path": "amount", "label": "Amount", "format": "assetAmount" },
-      { "path": "asset", "label": "Asset", "format": "asset" }
-    ]
-  }
-}
-
- -==Simplicity Covenant Metadata Document== - -TBD diff --git a/elip-0206.mediawiki b/elip-0206.mediawiki new file mode 100644 index 0000000..c88e0c3 --- /dev/null +++ b/elip-0206.mediawiki @@ -0,0 +1,42 @@ +
+  ELIP: 206
+  Layer: Wallet
+  Title: Clear Signing for Liquid Wallets
+  Author: Kyrylo Riabov 
+          Artem Chystiakov 
+  Comments-Summary: No comments yet.
+  Comments-URI: https://github.com/ElementsProject/ELIPs/pull/40
+  Status: Draft
+  Type: Standards Track
+  Created: 2026-06-09
+  License: BSD-3-Clause
+
+ +==Introduction== + +===Abstract=== + +This document defines a structured metadata profile for wallets to interpret an Elements transaction for the user. +It helps users understand the consequences of signing a particular transaction and lowers the risk of blind signing +as much as possible. + +It does not specify how this metadata is verified or made trusted. + +===Copyright=== + +This document is licensed under the 3-clause BSD license. + +===Motivation=== + +To expand the Liquid ecosystem, infrastructure and user-facing applications should be able to explain +to a non-technical user what is happening and which outcomes to expect. Similar to banking systems, +users should be given as much security as possible by default. + +Therefore, ecosystem participants should make as much effort as possible in explaining actions to the user. + +This ELIP gathers available resources on existing methods to attach and read metadata related to transaction. +As well as, presents a way to interpret a general-purpose action of signing a transaction on the Liquid network to the user. + +==Specification== + +The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [https://www.rfc-editor.org/rfc/rfc2119 RFC 2119] and [https://www.rfc-editor.org/rfc/rfc8174 RFC 8174] when, and only when, they appear in all capitals. From 78bd83d42eaba4b3467f71022f787433a58f9e2d Mon Sep 17 00:00:00 2001 From: Kyryl R Date: Fri, 4 Sep 2026 15:37:12 +0300 Subject: [PATCH 3/5] add elip to the list of ELIPs in README --- README.mediawiki | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/README.mediawiki b/README.mediawiki index 6240aca..7b88225 100644 --- a/README.mediawiki +++ b/README.mediawiki @@ -109,6 +109,13 @@ Having an ELIP here does not make it a formally accepted standard until its stat | Tom Trevethan | Standards Track | Draft +|- style="background-color: #ffcfcf" +| [[elip-0206.mediawiki|206]] +| Wallet +| Clear Signing for Liquid Wallets +| Kyrylo Riabov, Artem Chystiakov +| Standards Track +| Draft |} From daca2d025cb7252bb16e407767e50bb92853b47a Mon Sep 17 00:00:00 2001 From: Kyryl R Date: Wed, 9 Sep 2026 10:41:05 +0300 Subject: [PATCH 4/5] clarify wording in the abstract and motivation --- elip-0206.mediawiki | 11 ++++------- 1 file changed, 4 insertions(+), 7 deletions(-) diff --git a/elip-0206.mediawiki b/elip-0206.mediawiki index c88e0c3..8da83ec 100644 --- a/elip-0206.mediawiki +++ b/elip-0206.mediawiki @@ -16,11 +16,11 @@ ===Abstract=== -This document defines a structured metadata profile for wallets to interpret an Elements transaction for the user. -It helps users understand the consequences of signing a particular transaction and lowers the risk of blind signing -as much as possible. +This proposal gathers available resources on existing methods to attach and read metadata related to transaction. +As well as, presents a way to interpret a general-purpose action of signing a transaction on the Liquid network to the user. -It does not specify how this metadata is verified or made trusted. +It helps users understand the consequences of signing a particular transaction and lowers the risk of blind signing +as much as possible within provided trust assumptions. ===Copyright=== @@ -34,9 +34,6 @@ users should be given as much security as possible by default. Therefore, ecosystem participants should make as much effort as possible in explaining actions to the user. -This ELIP gathers available resources on existing methods to attach and read metadata related to transaction. -As well as, presents a way to interpret a general-purpose action of signing a transaction on the Liquid network to the user. - ==Specification== The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [https://www.rfc-editor.org/rfc/rfc2119 RFC 2119] and [https://www.rfc-editor.org/rfc/rfc8174 RFC 8174] when, and only when, they appear in all capitals. From 34aaa026202ac12be4e36a26e6a25e1f1bebfbbc Mon Sep 17 00:00:00 2001 From: Kyryl R Date: Wed, 9 Sep 2026 15:46:35 +0300 Subject: [PATCH 5/5] complete core of ELIP-206 --- elip-0206.mediawiki | 204 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 204 insertions(+) diff --git a/elip-0206.mediawiki b/elip-0206.mediawiki index 8da83ec..b18c88b 100644 --- a/elip-0206.mediawiki +++ b/elip-0206.mediawiki @@ -37,3 +37,207 @@ Therefore, ecosystem participants should make as much effort as possible in expl ==Specification== The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [https://www.rfc-editor.org/rfc/rfc2119 RFC 2119] and [https://www.rfc-editor.org/rfc/rfc8174 RFC 8174] when, and only when, they appear in all capitals. + +===High-level verification procedure=== + +The wallet should show which assets and amounts the user is spending or receiving, so the user can recognize the intended asset and check for unrecognized spendings. +It should also explain how the transaction affects the user's ability to spend those assets later, including any conditions attached to the new outputs. + +On Liquid, spending conditions can be written directly in [Bitcoin Script with Elements extensions](https://github.com/ElementsProject/elements/blob/c7e856fab1b0c4d37005e25c0940184d812a26a0/src/script/interpreter.cpp), expressed using [Miniscript](https://github.com/ElementsProject/elements-miniscript/blob/e6eca8bd52bdc397e7d386b481deb7be980683de/README.md), or written in [Simplicity](https://github.com/BlockstreamResearch/simplicity/blob/91d89bac54e9411281ee3b6e766a0ea20eb0a3d3/README.md). +Those can require a signature, multiple signatures, a waiting period, or restrictions on the outputs a transaction creates. +Simplicity programs and the [https://github.com/ElementsProject/elements-miniscript/blob/e6eca8bd52bdc397e7d386b481deb7be980683de/src/extensions/introspect_ops.rs Elements extensions to Miniscript] can also constrain the assets, amounts, scripts, and structure of transaction inputs and outputs. +For example, the [https://github.com/BlockstreamResearch/damp/blob/96db9a2226951fd1be57a9b1cfb4105ce4dcb2a3/paper/main.tex DAMP paper] describes Simplicity covenants that enforce issuer-defined blacklists, whitelists, and per-transaction payment limits for regulated assets. + +Liquid outputs can keep their assets and amounts confidential. +Wallets should show which outputs use this protection and explain any privacy consequences by modifying those. + +The wallet's explanation should distinguish its own checks from information it accepts from an application or registry, and identify any part it cannot explain. +See [[#Security_considerations|Security considerations]] for the risks involved. + +===Asset verification=== + +Names and tickers such as L-BTC and USDT help users recognize assets. +The asset identifier itself is 32 bytes. +[https://github.com/ElementsProject/ELIPs/blob/d886692e44cc7c47340d8659f60f9478707c7ad8/elip-0100.mediawiki ELIP 100] describes how a contract and issuance prevout bind an issued asset's identifier to metadata such as its name, ticker, precision, and issuer domain, etc. +Wallets and signers MUST follow its applicable verification rules before relying on that metadata. + +====Implementation examples==== + +These products show how wallets and services handle asset metadata. + +{| class="wikitable" +! Project +! Asset metadata handling +|- +| Jade +| The Liquid signing RPC reads asset_info in [https://github.com/Blockstream/Jade/blob/9c097297f58339c15fb9b8df4c7fe105efefb902/main/process/sign_tx.c#L466-L478 sign_tx.c]. [https://github.com/Blockstream/Jade/blob/9c097297f58339c15fb9b8df4c7fe105efefb902/main/assets.c#L105-L180 assets_get_allocate] recomputes the asset identifier from the contract and issuance prevout before accepting the supplied metadata. [https://github.com/Blockstream/Jade/commit/f6433446ee76a5c9c481452166b7c384bd6bbbf7 Commit f6433446] introduced this RPC support. The limitation is in the separate [https://github.com/Blockstream/Jade/blob/9c097297f58339c15fb9b8df4c7fe105efefb902/main/process/sign_psbt.c#L989-L1007 PSET signing path], which passes no external asset metadata to the display at the linked revision. +|- +| Simplicity Lending +| [https://github.com/BlockstreamResearch/simplicity-lending/pull/124 PR #124], from feat/clear-signing-asset-metadata, added asset metadata integration. The [https://github.com/BlockstreamResearch/simplicity-lending/blob/f1f6c29c592d635775fed2d120bb292e4f418a2e/web/src/lwk/assetContract.ts client] constructs contracts for protocol-issued assets. The [https://github.com/BlockstreamResearch/simplicity-lending/blob/f1f6c29c592d635775fed2d120bb292e4f418a2e/crates/indexer/src/indexer/asset_registration.rs#L87-L140 indexer] checks their issuance binding before registration. The [https://github.com/BlockstreamResearch/simplicity-lending/blob/f1f6c29c592d635775fed2d120bb292e4f418a2e/crates/indexer/src/api/assets/handlers.rs#L32-L62 domain-proof endpoint] serves evidence for known protocol assets, and the [https://github.com/BlockstreamResearch/simplicity-lending/blob/f1f6c29c592d635775fed2d120bb292e4f418a2e/web/src/providers/wallet/WalletProvider.tsx#L327-L346 wallet integration] adds available registry contracts to PSETs. The signer remains responsible for ELIP 100 verification. +|- +| Liquid Asset Registry +| In the published asset_registry implementation, [https://github.com/Blockstream/asset_registry/blob/5ecf533caffeec23ea3887f89ccf0962bf601ebe/src/registry.rs#L47-L59 registration] calls [https://github.com/Blockstream/asset_registry/blob/5ecf533caffeec23ea3887f89ccf0962bf601ebe/src/asset.rs#L135-L147 Asset::verify] to check the contract binding, asset fields, on-chain issuance, and domain association. [https://github.com/Blockstream/asset_registry/blob/5ecf533caffeec23ea3887f89ccf0962bf601ebe/src/entity.rs entity.rs] implements HTTP and DNS domain proofs. The separate [https://github.com/Blockstream/asset_registry_v2/blob/bea05e99b86b0b619dd1c3199e2f30bbcc523b2c/README.md registry v2 trust model] also describes domain verification as an acceptance check at registration time. +|} + +====Asset metadata example==== + +This excerpt shows an issued asset's metadata in the [https://github.com/Blockstream/asset_registry/blob/5ecf533caffeec23ea3887f89ccf0962bf601ebe/src/asset.rs Liquid Asset Registry] format. + +
+{
+  "asset_id": "ce091c998b83c78bb71a632313ba3760f1763d9cfcffae02258ffa9865a37bd2",
+  "contract": {
+    "entity": {"domain": "tether.to"},
+    "issuer_pubkey": "0337cceec0beea0232ebe14cba0197a9fbd45fcf2ec946749de920e71434c2b904",
+    "name": "Tether USD",
+    "precision": 8,
+    "ticker": "USDt",
+    "version": 0
+  },
+  "issuance_prevout": {
+    "txid": "9596d259270ef5bac0020435e6d859aea633409483ba64e232b8ba04ce288668",
+    "vout": 0
+  }
+}
+
+ +A wallet still needs to verify metadata supplied by the registry. + +The registry expects an HTTP domain proof at /.well-known/liquid-asset-proof- in this form, with the placeholders replaced: + +Authorize linking the domain name to the Liquid asset + +====Issuer and registry trust==== + +An ELIP 100 check establishes the binding between a contract and an asset identifier. +It does not establish the issuer's real-world identity, the asset's value, or whether an issuer will honor a redemption promise. +Those judgments depend on the issuer and the evidence the user relies on about that issuer. + +Anyone can issue a different asset with copied metadata, including the same domain string. +That copied string alone does not satisfy the registry's domain-proof check for the new asset identifier. +The cited legacy registry implementation also rejects a second registration with the same entity and ticker. +These acceptance rules depend on the registry enforcing them correctly and on the security of the domain's control. +A recorded acceptance decision does not prove that the domain remains under the same control or still serves the proof. + +The issuer_pubkey field is part of the contract's metadata. +It does not by itself grant authority to spend or reissue the asset. +The cited legacy registry implementation uses that key to authorize [https://github.com/Blockstream/asset_registry/blob/5ecf533caffeec23ea3887f89ccf0962bf601ebe/src/asset.rs#L154-L161 deletion of a registration]. +Losing the corresponding private key can prevent that authorization. +Compromise can allow another party to authorize it. +Neither event changes the contract already bound to the on-chain asset identifier. + +===Verification of spending conditions=== + +To explain a spend, a wallet needs to identify the method used to lock the funds. + +Existing methods shown in the table below demonstrate the portion of functionality that wallets should handle to enable proper explanation of the UTXO spending to the user. + +{| class="wikitable" +! Mechanism +! What the user needs to understand +! Reference +|- +| Multisignature scripts +| Which keys authorize the spend and how many signatures are required. +| [https://github.com/bitcoin/bips/blob/09e21036a4001fe6c9ba65c1d3a39b737768132f/bip-0011.mediawiki BIP 11] +|- +| Absolute and relative timelocks +| Which block height, time, or output age the spending path requires. +| [https://github.com/bitcoin/bips/blob/09e21036a4001fe6c9ba65c1d3a39b737768132f/bip-0065.mediawiki BIP 65], [https://github.com/bitcoin/bips/blob/09e21036a4001fe6c9ba65c1d3a39b737768132f/bip-0112.mediawiki BIP 112] +|- +| Pay-to-script-hash and SegWit script commitments +| Which redeem script or witness script defines the spending conditions. +| [https://github.com/bitcoin/bips/blob/09e21036a4001fe6c9ba65c1d3a39b737768132f/bip-0016.mediawiki BIP 16], [https://github.com/bitcoin/bips/blob/09e21036a4001fe6c9ba65c1d3a39b737768132f/bip-0141.mediawiki BIP 141] +|- +| Taproot +| Whether the transaction uses the key path or a script path, and what authorizes that path. +| [https://github.com/bitcoin/bips/blob/09e21036a4001fe6c9ba65c1d3a39b737768132f/bip-0341.mediawiki BIP 341], [https://github.com/bitcoin/bips/blob/09e21036a4001fe6c9ba65c1d3a39b737768132f/bip-0342.mediawiki BIP 342] +|- +| Miniscript +| Which signatures, hash preimages or timelocks are required, and which inputs and outputs its Elements extensions constrain. +| [https://github.com/ElementsProject/elements-miniscript/blob/e6eca8bd52bdc397e7d386b481deb7be980683de/README.md Elements Miniscript], [https://github.com/ElementsProject/elements-miniscript/blob/e6eca8bd52bdc397e7d386b481deb7be980683de/src/extensions/introspect_ops.rs Elements extensions] +|- +| Simplicity +| Which signatures or other witness values the program requires, and how it restricts transaction inputs and outputs. +| [https://github.com/BlockstreamResearch/simplicity/blob/8adafc9b55d694111c99fa11f90c7e48376ed1e5/Simplicity-TR.pdf Simplicity technical report] +|} + +A Simplicity program can require several UTXOs to be spent together and restrict the outputs created by the transaction. + +Some of those would require a separate ELIP/BIP to standardize the parsing and explanation for the user. +In the case of Simplicity, we rely on [https://github.com/stringhandler/ELIPs/blob/41462cfbd02e6eae8795f7753ceb5ef0c779b84c/elip-0205.mediawiki ELIP 205], which is explained in the next section. + +====Transaction manifests for Simplicity contracts==== + +[https://github.com/stringhandler/ELIPs/blob/41462cfbd02e6eae8795f7753ceb5ef0c779b84c/elip-0205.mediawiki ELIP 205] describes how to construct a protocol transaction, including the inputs it consumes, outputs it creates and witnesses needed to satisfy its inputs. +Its manifests carry signer-facing text to explain the operation. +The draft currently defines only the Simplicity script type and allows other types to be added. +A wallet using a transaction manifest to explain a Simplicity operation MUST follow ELIP 205's applicable construction and validation rules. +ELIP 205 supplies the manifest rules. +Elements' Simplicity execution rules determine whether the program and witness satisfy the spending conditions. +The [https://github.com/ElementsProject/ELIPs/pull/41 draft proposal] names [https://github.com/stringhandler/txmanifest-wallet/tree/5624dfc77f742d66798d469de1bb79c8f09fcf0b txmanifest-wallet] as its reference implementation and records known conformance gaps. + +==Rationale== + +===Readable explanations with supporting evidence=== + +Clear signing separates a description from the evidence that supports it. +A familiar ticker or contract name helps the user recognize an operation, but recognition alone cannot establish that the description applies to the transaction being authorized. +Keeping full identifiers accessible lets the user inspect what a displayed label refers to, including when two assets use the same label. + +===Using existing specifications=== + +ELIP 100 carries issued-asset evidence to offline signers, while ELIP 205 describes how a wallet constructs and explains a protocol transaction. +Referencing these specifications gives implementers a defined place to find the rules for each part of the review. + +===Ongoing work=== + +ELIP 206 remains a draft under discussion in [https://github.com/ElementsProject/ELIPs/pull/40 PR #40]. +It can be updated as new proposals improve clear signing, existing standards evolve, and implementations provide better ways to explain transactions. + +==Backwards compatibility== + +This ELIP changes neither Elements consensus nor transaction serialization. +Wallets can adopt ELIP 100 asset metadata support independently of support for Simplicity transaction manifests. + +==Security considerations== + +===Misleading metadata=== + +An attacker can substitute a familiar name or ticker for a different asset. +Even correctly bound metadata can use a visually confusing label. +Wallets should make the verification result clear and keep the full asset identifier accessible, following ELIP 100's display guidance. +Interfaces should defend against Unicode confusables and ambiguous truncation. + +===External sources and unavailable evidence=== + +An authenticated connection identifies the endpoint serving data. +The wallet must still check that the description matches the transaction. +A wallet should identify the source of labels and explain what it could not verify. +Failures and timeouts must not turn an unchecked description into a verified one. +These recommendations on source attribution and fallback draw on the [https://github.com/ethereum/clear-signing-erc7730-registry/blob/0318f9a51ec4fc7ba4aed6de5e315c8884d1fe38/specs/erc-7730.md#security-considerations security considerations in ERC-7730]. + +===Confidential transactions=== + +A signer can produce a valid [https://github.com/ElementsProject/elements/blob/c7e856fab1b0c4d37005e25c0940184d812a26a0/src/script/interpreter.cpp#L2688-L2756 Taproot signature] over confidential commitments without knowing the underlying asset or amount. +A signer can verify explicit assets and amounts supplied with the [https://github.com/ElementsProject/elements/blob/c7e856fab1b0c4d37005e25c0940184d812a26a0/doc/pset.mediawiki PSET commitment proofs] without holding the blinding keys. +Without unblinding data or these proofs, it cannot verify a confidential output's claimed asset and amount. +Sharing an output's unblinding data reveals its asset and amount to the recipient of that data. + +===Manifest descriptions=== + +Signer-facing text in a manifest is author-supplied. +The user still relies on the manifest author to describe the declared operation honestly. +A valid signature over a manifest does not make a transaction conform to that manifest. + +===Constrained signers=== + +A hardware or otherwise constrained signer MUST independently verify every transaction-specific claim it marks as verified. +Host-supplied claims that cannot be checked on the signer MUST be marked unverified or omitted. +An implementation may split verification across components only when the user can tell which component established each claim and the authorization policy does not silently promote a host assertion. + +===Resource exhaustion=== + +Metadata and manifest parsers handle attacker-controlled input. +Implementations SHOULD limit document size, nesting, field lengths, compilation work, network requests and cached entries. +If a resource limit prevents a required verification, the implementation MUST fail closed.