tip-7730.md

July 23, 2026 · View on GitHub

tip: 7730
title: Structured Data Clear Signing Format
description: ERC-7730-compatible descriptors and a TRON matching/display profile
author: yanghang8612@gmail.com
discussions-to: https://github.com/tronprotocol/tips/issues/872
status: Draft
type: Standards Track
category: TRC
created: 2026-05-14
requires: 712

Simple Summary

Use reviewed JSON descriptors so wallets can show human-readable TRON transaction intent before signing.

This standard adopts the ERC-7730 JSON descriptor format for clear signing of TVM contract calldata and TRC-712 typed messages. Descriptors enrich raw ABI types with human-readable intent, labels, formatting, and trusted metadata so wallets can show what a transaction does before the user signs it.

The ERC-7730 schema is not forked. This document adds a TRON consumer profile for address and network matching, trusted wallet-layer trcToken enrichment, TriggerSmartContract container display, and contract binding.

Motivation

An ABI can decode a function and its primitive arguments but cannot explain intent, units, trusted names, or the relationship between fields. Users therefore approve opaque hex or developer-oriented structures, creating a large phishing and frontend-tampering surface. Reusing ERC-7730 lets TRON wallets and hardware devices share descriptors and tooling with the broader clear-signing ecosystem.

Specification

The key words "MUST", "MUST NOT", "REQUIRED", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" are to be interpreted as described in RFC 2119 and RFC 8174.

Pinned Upstream Revision

TRC-7730 V1 adopts ERC-7730 schema version 2.0.0, specifically assets/erc-7730/erc7730-v2.schema.json at commit 73672565aeb10e615905663ad457d75a19eae0c2. The schema file's SHA-256 digest is:

999c1e7366d58cb10d207a7396331e990a0d9f40f0b8b269c6bab4df78682dc1

The same commit pins the accompanying ERC prose. The top-level context, metadata, and display structures, path language, interpolation, closed format definitions, and validation behavior are those of schema 2.0.0. V1 does not adopt the deprecated v1 schema or the v3.0.0-next draft found in the same repository revision.

The pin MUST NOT move automatically with the upstream branch. A future update MUST review schema and semantic changes against this profile, publish compatibility impact, and update the pinned commit through the TIP process.

V1 Scope

V1 covers:

ABI-compatible TVM calldata carried by TriggerSmartContract;
TRC-712 typed messages;
TRX and TRC-20 display;
address and network normalization;
transaction-container display; and
descriptor resolution and proxy/implementation binding.

Native transfers, TRC-10 container values, shielded transactions, and other system contracts are outside V1. Their absence MUST NOT be hidden by overloading an existing ERC-7730 path.

Canonical Address Form

Descriptors MUST store contract and account addresses as the 20-byte ABI value, encoded as 0x plus 40 lowercase or checksummed hexadecimal characters. This is the TRON address body after removal of the leading 0x41 network byte.

For matching, a wallet MUST normalize and treat as identical:

a valid TRON Base58Check address;
a 21-byte hex address beginning with 41 or 0x41; and
the canonical 20-byte ABI hex address.

The normalizer MUST validate the Base58Check checksum and network prefix before stripping it. Display SHOULD prefer Base58Check or a trusted locally resolved name. Matching MUST never be performed on a display label.

Network Binding

TRON deployment and typed-message contexts MUST use the TRC-712 network value:

chainId = block.chainid & 0xffffffff

Examples:

Network	Hex	Decimal
Mainnet	`0x2b6653dc`	728126428
Nile	`0xcd8690dc`	3448148188

A descriptor MUST NOT match when its network id differs from the active network. Private networks MUST use their own value. Wallets MUST match both network and address before applying a descriptor.

Descriptor Resolution

For calldata, a wallet MUST resolve by at least:

(network, target contract, function selector)

For TRC-712 data, it MUST additionally match the domain and primary type as defined by the pinned ERC-7730 revision. When multiple descriptors match, the wallet MUST fail closed or apply a deterministic registry-defined priority; it MUST NOT select one silently based on fetch order.

Missing, invalid, expired, untrusted, or ambiguous metadata MUST fall back to raw ABI-decoded display with an explicit "not clear-signed" or equivalent warning. A wallet MUST NOT present such a fallback as verified clear signing.

`TriggerSmartContract` Container Mapping

The ERC-7730 container paths map as follows:

Path	TRON source	Display
`@.from`	`TriggerSmartContract.owner_address`	Base58Check/trusted name
`@.to`	`TriggerSmartContract.contract_address`	Base58Check/trusted name
`@.value`	`TriggerSmartContract.call_value`	TRX in sun

Schema 2.0.0 defines no @.feeLimit, @.expiration, or @.permissionId path. Wallets MUST therefore display Transaction.raw_data.fee_limit, Transaction.raw_data.expiration, and the contract Permission_id as trusted TRON transaction-container fields adjacent to, but outside, descriptor interpolation. fee_limit is the caller-side Energy fee/budget cap denominated in sun; it does not include Bandwidth or other independently charged fees. Wallets MUST also validate and sign the complete SHA256(Transaction.raw_data) container, not only the ABI payload.

ref_block_bytes and ref_block_hash MUST remain bound in the signed raw data and SHOULD be available in an advanced-details view. @.value MUST NOT represent call_token_value or token_id; TRC-10 support requires a later additive profile.

Wallets SHOULD display energy and bandwidth estimates separately, because they are independent TRON resource pools and a single fee figure can be misleading.

TRC-712 and `trcToken`

TRC-712 fields retain their declared type. trcToken is encoded as uint256 on the wire but semantically identifies a TRC-10 token. A V1 descriptor MUST use only schema 2.0.0 paths and format names; it MUST NOT introduce tip712TrcToken, tokenIdPath, or any other undeclared schema property.

The descriptor displays the field using an upstream-supported primitive format such as raw. A TRON-aware wallet MAY additionally recognize that the corresponding TRC-712 field was declared as trcToken and enrich the raw identifier from a configured trusted TRON metadata source. When trusted metadata exists it SHOULD render SYMBOL (id: RAW_ID); when lookup is missing, untrusted, or fails it MUST render the raw token id. This enrichment is wallet policy outside the descriptor and does not change schema validation. A descriptor containing an unknown format or property is invalid and MUST fall back to an explicitly unverified raw display.

Proxy and Implementation Binding

For an upgradeable contract, the descriptor MUST bind the stable called proxy address and network through context.contract.deployments, following schema 2.0.0. A descriptor for one proxy MUST NOT apply automatically to a look-alike proxy or clone.

A signed registry entry MAY additionally attest an implementation address or code hash, proxy-resolution method, and descriptor revision as metadata outside the ERC-7730 document. A registry using such attestations MUST version and document their encoding, hash algorithm, resolver, and failure behavior. A wallet that relies on an implementation attestation MUST treat a mismatch, unresolved proxy, unexpected beacon, or changed implementation as a clear-signing failure and fall back to raw display. These implementation attestations strengthen registry policy but are not new ERC-7730 schema fields.

For non-proxy contracts, the descriptor binds directly to the called address and network.

Descriptor Trust and Registry

A canonical registry SHOULD use pull-request submission and require:

schema validation;
verified source or ABI;
proof or attestation from the contract/protocol owner when available;
human review of intent labels and field roles;
strict deployment and proxy binding; and
versioning and cache-invalidation metadata.

Automatic generation from a verified ABI MAY create paths and formatting scaffolding. Human review remains REQUIRED before registry trust because intent text and semantic field roles cannot be inferred safely from an ABI alone.

Registry governance, distribution, hardware-vendor signing, and rollout sequencing belong to a companion implementation/deployment guide rather than the JSON schema.

Rationale

Profile, Not Fork

Schema compatibility is the main value of adopting ERC-7730. TRON-specific behavior therefore lives in normalization, matching, trusted metadata enrichment, and container display rather than a parallel descriptor language.

Complete Signing Surface

Clear calldata with opaque fee_limit, expiration, or native permission selection is incomplete. The container requirements cover the exact Transaction.raw_data that a TRON wallet signs and prevent a malicious frontend from hiding transaction-level authority or cost.

Producers and Consumers

Descriptors are inert unless protocol teams produce reviewed metadata and wallets consume it consistently. A companion guide SHOULD define protocol-author responsibilities, a shared parser/semantic-model SDK for software wallets, registry review, hardware-wallet distribution, conformance cases, and fallback behavior. Internationalization remains wallet-layer guidance; changing descriptor strings for i18n would fork the schema.

Backwards Compatibility

Wallets that do not recognize the TRON profile continue to parse the pinned ERC-7730 structures and safely display primitive values. Existing contracts require no changes. Unsupported descriptors fall back to ordinary ABI display and MUST be labeled unverified.

Test Cases

A conformance pack MUST cover:

equivalent Base58Check, 0x41, and 20-byte address matching plus invalid-checksum rejection;
Mainnet/Nile network mismatch rejection;
TRC-20 transfer and TRC-721 transfer display;
TRC-712 typed data and trusted wallet-layer trcToken enrichment with raw fallback;
feeLimit, expiration, and non-zero permissionId display;
proxy-address matching, clone mismatch, and changed-implementation failure when an implementation attestation is used;
descriptor ambiguity, stale cache, and unverifiable-metadata fallback; and
separate energy/bandwidth estimation presentation.

Security Considerations

A malicious descriptor can relabel attacker-controlled fields, so schema validity alone is not trust.
Address normalization MUST validate checksum and prefix before matching.
Network, called address, and selector form the minimum binding. When a registry supplies a trusted implementation attestation, wallets MUST enforce it consistently.
Metadata resolution and token labels MUST use trusted sources and safe raw fallbacks.
Wallets MUST show when no trusted descriptor matched.
Registry and device caches need signed/versioned updates and explicit invalidation after upgrades.
Transaction simulation complements but does not replace descriptor binding; simulation output can itself be incomplete or manipulated by changing state.