Skip to content

Commit 64c1bdd

Browse files
bee344bee344
authored
feat: add /transaction/metadata-blob endpoint (#1886)
* feat: add metadataHash endpoint * linting * update copyright * typos * linting * override @scure/base version * update doc * dynamic imports * downgrade merkleize-metadata * downgrade again * linting * add dynamic import * test * linting * address comments
1 parent de0c540 commit 64c1bdd

21 files changed

+977
-14
lines changed

‎docs-v2/openapi-v1.yaml‎

Lines changed: 98 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2667,6 +2667,30 @@ paths:
26672667
application/json:
26682668
schema:
26692669
$ref: '#/components/schemas/Error'
2670+
/transaction/metadata-blob:
2671+
post:
2672+
tags:
2673+
- transaction
2674+
summary: Get the metadata blob for offline signers.
2675+
description: Returns the minimal metadata ("metadata blob" or "proof") needed by offline
2676+
signers to decode a transaction's signing payload, along with the metadata
2677+
hash for the CheckMetadataHash signed extension per RFC-0078.
2678+
operationId: getTransactionMetadataBlob
2679+
requestBody:
2680+
$ref: '#/components/requestBodies/TransactionMetadataBlob'
2681+
responses:
2682+
"200":
2683+
description: successful operation
2684+
content:
2685+
application/json:
2686+
schema:
2687+
$ref: '#/components/schemas/TransactionMetadataBlob'
2688+
"400":
2689+
description: invalid request body or metadata V15 not available
2690+
content:
2691+
application/json:
2692+
schema:
2693+
$ref: '#/components/schemas/Error'
26702694
/pallets/assets/{assetId}/asset-info:
26712695
get:
26722696
tags:
@@ -8406,6 +8430,74 @@ components:
84068430
- `RuntimeVersion`: https://crates.parity.io/sp_version/struct.RuntimeVersion.html
84078431
- `SignedExtension`: https://crates.parity.io/sp_runtime/traits/trait.SignedExtension.html
84088432
- FRAME Support: https://crates.parity.io/frame_support/metadata/index.html
8433+
MetadataBlobBody:
8434+
type: object
8435+
properties:
8436+
tx:
8437+
type: string
8438+
format: hex
8439+
description: Full encoded extrinsic as a hex string.
8440+
txAdditionalSigned:
8441+
type: string
8442+
format: hex
8443+
description: Optional additional signed data for the extrinsic. Used together with `tx`.
8444+
callData:
8445+
type: string
8446+
format: hex
8447+
description: Call data as hex string. Use this alongside includedInExtrinsic
8448+
and includedInSignedData instead of `tx`.
8449+
includedInExtrinsic:
8450+
type: string
8451+
format: hex
8452+
description: Signed extension data included in the extrinsic. Required when using callData.
8453+
includedInSignedData:
8454+
type: string
8455+
format: hex
8456+
description: Signed extension data included in the signature. Required when using callData.
8457+
at:
8458+
type: string
8459+
description: Block hash or number to query at. Defaults to finalized head.
8460+
format: unsignedInteger or $hex
8461+
description: >-
8462+
Request body for generating the metadata blob. You must provide either:
8463+
(1) `tx` (full extrinsic) with optional `txAdditionalSigned`, or
8464+
(2) `callData` with `includedInExtrinsic` and `includedInSignedData`.
8465+
TransactionMetadataBlob:
8466+
type: object
8467+
properties:
8468+
at:
8469+
$ref: '#/components/schemas/BlockIdentifiers'
8470+
metadataHash:
8471+
type: string
8472+
format: hex
8473+
description: The 32-byte metadata hash (hex-encoded) that should be used with
8474+
the CheckMetadataHash signed extension.
8475+
metadataBlob:
8476+
type: string
8477+
format: hex
8478+
description: The metadata blob (hex-encoded) containing the minimal metadata
8479+
required for offline signers to decode the transaction. This is a SCALE-encoded
8480+
Proof structure per RFC-0078.
8481+
specVersion:
8482+
type: number
8483+
description: The chain's spec version.
8484+
specName:
8485+
type: string
8486+
description: The chain's spec name.
8487+
base58Prefix:
8488+
type: number
8489+
description: The chain's SS58 address prefix.
8490+
decimals:
8491+
type: number
8492+
description: Number of decimals for the chain's native token.
8493+
tokenSymbol:
8494+
type: string
8495+
description: Symbol for the chain's native token.
8496+
description: >-
8497+
Response containing the metadata blob for offline signers. The metadataBlob
8498+
contains type definitions needed to decode the specific transaction, Merkle
8499+
proofs verifying these types are part of the full metadata, and extra chain
8500+
info.
84098501
TransactionPool:
84108502
type: object
84118503
properties:
@@ -8533,6 +8625,12 @@ components:
85338625
schema:
85348626
$ref: '#/components/schemas/DryRunBody'
85358627
required: true
8628+
TransactionMetadataBlob:
8629+
content:
8630+
application/json:
8631+
schema:
8632+
$ref: '#/components/schemas/MetadataBlobBody'
8633+
required: true
85368634
ContractMetadata:
85378635
content:
85388636
application/json:

‎docs/src/openapi-v1.yaml‎

Lines changed: 112 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2667,6 +2667,44 @@ paths:
26672667
application/json:
26682668
schema:
26692669
$ref: '#/components/schemas/Error'
2670+
/transaction/metadata-blob:
2671+
post:
2672+
tags:
2673+
- transaction
2674+
summary: Get the metadata blob for offline signers.
2675+
description: >-
2676+
Returns the minimal metadata ("metadata blob" or "proof") needed by offline
2677+
signers to decode a transaction's signing payload, along with the metadata
2678+
hash for the CheckMetadataHash signed extension per RFC-0078.
2679+
2680+
2681+
The metadata blob contains type definitions needed to decode the specific
2682+
transaction, Merkle proofs verifying these types are part of the full metadata,
2683+
and extra chain info (specVersion, specName, base58Prefix, decimals, tokenSymbol).
2684+
2685+
2686+
Offline signers can use this to decode the transaction to display what the user
2687+
is signing and verify the metadata subset matches the on-chain metadata via
2688+
Merkle proofs.
2689+
2690+
2691+
Reference: RFC-0078 https://polkadot-fellows.github.io/RFCs/approved/0078-merkleized-metadata.html
2692+
operationId: getTransactionMetadataBlob
2693+
requestBody:
2694+
$ref: '#/components/requestBodies/TransactionMetadataBlob'
2695+
responses:
2696+
"200":
2697+
description: successful operation
2698+
content:
2699+
application/json:
2700+
schema:
2701+
$ref: '#/components/schemas/TransactionMetadataBlob'
2702+
"400":
2703+
description: invalid request body or metadata V15 not available
2704+
content:
2705+
application/json:
2706+
schema:
2707+
$ref: '#/components/schemas/Error'
26702708
/pallets/assets/{assetId}/asset-info:
26712709
get:
26722710
tags:
@@ -8406,6 +8444,74 @@ components:
84068444
- `RuntimeVersion`: https://crates.parity.io/sp_version/struct.RuntimeVersion.html
84078445
- `SignedExtension`: https://crates.parity.io/sp_runtime/traits/trait.SignedExtension.html
84088446
- FRAME Support: https://crates.parity.io/frame_support/metadata/index.html
8447+
MetadataBlobBody:
8448+
type: object
8449+
properties:
8450+
tx:
8451+
type: string
8452+
format: hex
8453+
description: Full encoded extrinsic as a hex string.
8454+
txAdditionalSigned:
8455+
type: string
8456+
format: hex
8457+
description: Optional additional signed data for the extrinsic. Used together with `tx`.
8458+
callData:
8459+
type: string
8460+
format: hex
8461+
description: Call data as hex string. Use this alongside includedInExtrinsic
8462+
and includedInSignedData instead of `tx`.
8463+
includedInExtrinsic:
8464+
type: string
8465+
format: hex
8466+
description: Signed extension data included in the extrinsic. Required when using callData.
8467+
includedInSignedData:
8468+
type: string
8469+
format: hex
8470+
description: Signed extension data included in the signature. Required when using callData.
8471+
at:
8472+
type: string
8473+
description: Block hash or number to query at. Defaults to finalized head.
8474+
format: unsignedInteger or $hex
8475+
description: >-
8476+
Request body for generating the metadata blob. You must provide either:
8477+
(1) `tx` (full extrinsic) with optional `txAdditionalSigned`, or
8478+
(2) `callData` with `includedInExtrinsic` and `includedInSignedData`.
8479+
TransactionMetadataBlob:
8480+
type: object
8481+
properties:
8482+
at:
8483+
$ref: '#/components/schemas/BlockIdentifiers'
8484+
metadataHash:
8485+
type: string
8486+
format: hex
8487+
description: The 32-byte metadata hash (hex-encoded) that should be used with
8488+
the CheckMetadataHash signed extension.
8489+
metadataBlob:
8490+
type: string
8491+
format: hex
8492+
description: The metadata blob (hex-encoded) containing the minimal metadata
8493+
required for offline signers to decode the transaction. This is a SCALE-encoded
8494+
Proof structure per RFC-0078.
8495+
specVersion:
8496+
type: number
8497+
description: The chain's spec version.
8498+
specName:
8499+
type: string
8500+
description: The chain's spec name.
8501+
base58Prefix:
8502+
type: number
8503+
description: The chain's SS58 address prefix.
8504+
decimals:
8505+
type: number
8506+
description: Number of decimals for the chain's native token.
8507+
tokenSymbol:
8508+
type: string
8509+
description: Symbol for the chain's native token.
8510+
description: >-
8511+
Response containing the metadata blob for offline signers. The metadataBlob
8512+
contains type definitions needed to decode the specific transaction, Merkle
8513+
proofs verifying these types are part of the full metadata, and extra chain
8514+
info.
84098515
TransactionPool:
84108516
type: object
84118517
properties:
@@ -8533,6 +8639,12 @@ components:
85338639
schema:
85348640
$ref: '#/components/schemas/DryRunBody'
85358641
required: true
8642+
TransactionMetadataBlob:
8643+
content:
8644+
application/json:
8645+
schema:
8646+
$ref: '#/components/schemas/MetadataBlobBody'
8647+
required: true
85368648
ContractMetadata:
85378649
content:
85388650
application/json:

‎package.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -51,6 +51,7 @@
5151
"test:test-release": "yarn build:scripts && node scripts/build/runYarnPack.js"
5252
},
5353
"dependencies": {
54+
"@polkadot-api/merkleize-metadata": "^1.1.29",
5455
"@polkadot/api": "16.5.2",
5556
"@polkadot/api-augment": "16.5.2",
5657
"@polkadot/api-contract": "16.5.2",

‎src/chains-config/assetHubKusamaControllers.ts‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
// Copyright 2017-2025 Parity Technologies (UK) Ltd.
1+
// Copyright 2017-2026 Parity Technologies (UK) Ltd.
22
// This file is part of Substrate API Sidecar.
33
//
44
// Substrate API Sidecar is free software: you can redistribute it and/or modify
@@ -88,6 +88,7 @@ export const assetHubKusamaControllers: ControllerConfig = {
8888
'TransactionDryRun',
8989
'TransactionFeeEstimate',
9090
'TransactionMaterial',
91+
'TransactionMetadataBlob',
9192
'TransactionSubmit',
9293
],
9394
options: {

‎src/chains-config/assetHubNextWestendControllers.ts‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
// Copyright 2017-2025 Parity Technologies (UK) Ltd.
1+
// Copyright 2017-2026 Parity Technologies (UK) Ltd.
22
// This file is part of Substrate API Sidecar.
33
//
44
// Substrate API Sidecar is free software: you can redistribute it and/or modify
@@ -86,6 +86,7 @@ export const assetHubNextWestendControllers: ControllerConfig = {
8686
'TransactionDryRun',
8787
'TransactionFeeEstimate',
8888
'TransactionMaterial',
89+
'TransactionMetadataBlob',
8990
'TransactionSubmit',
9091
],
9192
options: {

‎src/chains-config/assetHubPolkadotControllers.ts‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
// Copyright 2017-2025 Parity Technologies (UK) Ltd.
1+
// Copyright 2017-2026 Parity Technologies (UK) Ltd.
22
// This file is part of Substrate API Sidecar.
33
//
44
// Substrate API Sidecar is free software: you can redistribute it and/or modify
@@ -88,6 +88,7 @@ export const assetHubPolkadotControllers: ControllerConfig = {
8888
'TransactionDryRun',
8989
'TransactionFeeEstimate',
9090
'TransactionMaterial',
91+
'TransactionMetadataBlob',
9192
'TransactionSubmit',
9293
],
9394
options: {

‎src/chains-config/assetHubWestendControllers.ts‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
// Copyright 2017-2025 Parity Technologies (UK) Ltd.
1+
// Copyright 2017-2026 Parity Technologies (UK) Ltd.
22
// This file is part of Substrate API Sidecar.
33
//
44
// Substrate API Sidecar is free software: you can redistribute it and/or modify
@@ -87,6 +87,7 @@ export const assetHubWestendControllers: ControllerConfig = {
8787
'TransactionDryRun',
8888
'TransactionFeeEstimate',
8989
'TransactionMaterial',
90+
'TransactionMetadataBlob',
9091
'TransactionSubmit',
9192
],
9293
options: {

‎src/chains-config/defaultControllers.ts‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
// Copyright 2017-2025 Parity Technologies (UK) Ltd.
1+
// Copyright 2017-2026 Parity Technologies (UK) Ltd.
22
// This file is part of Substrate API Sidecar.
33
//
44
// Substrate API Sidecar is free software: you can redistribute it and/or modify
@@ -54,6 +54,7 @@ export const defaultControllers: ControllerConfig = {
5454
'TransactionDryRun',
5555
'TransactionFeeEstimate',
5656
'TransactionMaterial',
57+
'TransactionMetadataBlob',
5758
'TransactionSubmit',
5859
],
5960
options: {

‎src/chains-config/kusamaControllers.ts‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
// Copyright 2017-2025 Parity Technologies (UK) Ltd.
1+
// Copyright 2017-2026 Parity Technologies (UK) Ltd.
22
// This file is part of Substrate API Sidecar.
33
//
44
// Substrate API Sidecar is free software: you can redistribute it and/or modify
@@ -56,6 +56,7 @@ export const kusamaControllers: ControllerConfig = {
5656
'TransactionDryRun',
5757
'TransactionFeeEstimate',
5858
'TransactionMaterial',
59+
'TransactionMetadataBlob',
5960
'TransactionSubmit',
6061
],
6162
options: {

‎src/chains-config/polkadotControllers.ts‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
// Copyright 2017-2025 Parity Technologies (UK) Ltd.
1+
// Copyright 2017-2026 Parity Technologies (UK) Ltd.
22
// This file is part of Substrate API Sidecar.
33
//
44
// Substrate API Sidecar is free software: you can redistribute it and/or modify
@@ -55,6 +55,7 @@ export const polkadotControllers: ControllerConfig = {
5555
'TransactionDryRun',
5656
'TransactionFeeEstimate',
5757
'TransactionMaterial',
58+
'TransactionMetadataBlob',
5859
'TransactionSubmit',
5960
],
6061
options: {

0 commit comments

Comments
 (0)