Library usage

Installation

The erc7730 library is available as a Python package on PyPI. You can install it using pip:

pip install --user erc7730

Overview

A typical usage of the erc7730 library is to load descriptors and compile them to a wallet manufacturer-specific format:

        ---
title: Node
---
flowchart TD
   input_json@{ shape: doc, label: "ERC-7730 descriptor file" }
   input[input ERC-7730 descriptor]
   resolved[resolved ERC-7730 descriptor]
   vendor[wallet specific ERC-7730 descriptor]
   input_json -- load/validate --> input
   input -- resolve/validate --> resolved
   resolved -- convert --> vendor

Packages

erc7730.model

The erc7730.model package implements an object model mapping for ERC-7730 descriptors using pydantic, allowing to easily read/write/transform descriptors.

input and resolved forms

Descriptors can be manipulated in 2 forms:

  • “Input” form: the descriptor document as defined in the ERC-7730 specification, after include tags have been resolved. It is possible to save back the descriptor back to the original descriptor document.

  • “Resolved” form: the descriptor after pre-processing:

    • URLs have been fetched

    • Contract addresses have been normalized to lowercase

    • References have been inlined

    • Constants have been inlined

    • Field definitions have been inlined

    • Nested fields have been flattened where possible

    • Selectors have been converted to 4 bytes form This form is the most adapted to be used by tools and applications.

erc7730.model.input.descriptor.InputERC7730Descriptor

An ERC7730 Clear Signing descriptor.

erc7730.model.resolved.descriptor.ResolvedERC7730Descriptor

An ERC7730 Clear Signing descriptor.

input data model

pydantic model erc7730.model.input.descriptor.InputERC7730Descriptor[source]View on GitHub

An ERC7730 Clear Signing descriptor.

This model is directly serializable back the original JSON document.

Specification: https://github.com/LedgerHQ/clear-signing-erc7730-registry/tree/master/specs

JSON schema: https://github.com/LedgerHQ/clear-signing-erc7730-registry/blob/master/specs/erc7730-v1.schema.json

field context: InputContractContext | InputEIP712Context [Required]

The binding context is a set of constraints that are used to bind the ERC7730 file to a specificstructured data being displayed. Currently, supported contexts include contract-specificconstraints or EIP712 message specific constraints.

field display: InputDisplay [Required]

The display section contains all the information needed to format the data in a human readableway. It contains the constants and formatters used to display the data contained in the bound structure.

field metadata: InputMetadata [Required]

The metadata section contains information about constant values relevant in the scope of thecurrent contract / message (as matched by the context section)

field schema_: str | None = None (alias '$schema')

The schema that the document should conform to. This should be the URL of a version of the clear signing JSON schemas available under https://github.com/LedgerHQ/clear-signing-erc7730-registry/tree/master/specs

resolved data model

pydantic model erc7730.model.resolved.descriptor.ResolvedERC7730Descriptor[source]View on GitHub

An ERC7730 Clear Signing descriptor.

This model represents descriptors after resolution phase:

  • URLs have been fetched

  • Contract addresses have been normalized to lowercase

  • References have been inlined

  • Constants have been inlined

  • Field definitions have been inlined

  • Nested fields have been flattened where possible

  • Selectors have been converted to 4 bytes form

Specification: https://github.com/LedgerHQ/clear-signing-erc7730-registry/tree/master/specs

JSON schema: https://github.com/LedgerHQ/clear-signing-erc7730-registry/blob/master/specs/erc7730-v1.schema.json

field context: ResolvedContractContext | ResolvedEIP712Context [Required]

The binding context is a set of constraints that are used to bind the ERC7730 file to a specificstructured data being displayed. Currently, supported contexts include contract-specificconstraints or EIP712 message specific constraints.

field display: ResolvedDisplay [Required]

The display section contains all the information needed to format the data in a human readableway. It contains the constants and formatters used to display the data contained in the bound structure.

field metadata: ResolvedMetadata [Required]

The metadata section contains information about constant values relevant in the scope of thecurrent contract / message (as matched by the context section)

field schema_: str | None = None (alias '$schema')

The schema that the document should conform to. This should be the URL of a version of the clear signing JSON schemas available under https://github.com/LedgerHQ/clear-signing-erc7730-registry/tree/master/specs

erc7730.lint

The erc7730.lint package implements the erc7730 lint command. The main interface is ERC7730Linter:

class erc7730.lint.ERC7730Linter[source]View on GitHub

Linter for ERC-7730 descriptors, inspects a (structurally valid) descriptor and emits notes, warnings, or errors.

A linter may emit false positives or false negatives. It is up to the user to interpret the output.

The package contains several linter implementations:

erc7730.lint.lint_validate_abi.ValidateABILinter

erc7730.lint.lint_validate_display_fields.ValidateDisplayFieldsLinter

erc7730.lint.lint_transaction_type_classifier.ClassifyTransactionTypeLinter

erc7730.convert

The erc7730.convert package implements the erc7730 convert command. The main interface is ERC7730Converter:

class erc7730.convert.ERC7730Converter[source]View on GitHub

Converter from/to ERC-7730 descriptor.

A converter may fail partially, in which case it should emit errors with ERROR level, or totally, in which case it should emit errors with FATAL level.

abstract convert(descriptor: InputType, out: OutputAdder) → OutputType | dict[str, OutputType] | None[source]View on GitHub

Convert a descriptor from/to ERC-7730.

Conversion may fail partially, in which case it should emit errors with WARNING level, or totally, in which case it should emit errors with ERROR level.

Conversion can return a single descriptor, or multiple ones, in the form of a dictionary with unique identifiers.

Parameters:

  • descriptor – input descriptor to convert

  • out – output sink

Returns:

converted descriptor, or None if conversion failed

The package contains several converter implementations: