From 360aca086d75d663e3691b9b4362cd539623f795 Mon Sep 17 00:00:00 2001 From: cryptoBeliever Date: Thu, 2 Apr 2026 00:42:51 +0200 Subject: [PATCH 1/3] feat: improve OpenAPI docs for transaction endpoints --- .../routes/announceTransaction.yml | 24 +++- .../routes/getConfirmedTransaction.yml | 48 +++++++- .../routes/getConfirmedTransactions.yml | 36 +++++- .../routes/getPartialTransaction.yml | 45 +++++++- .../routes/getPartialTransactions.yml | 49 +++++++- .../routes/getUnconfirmedTransaction.yml | 28 ++++- .../routes/getUnconfirmedTransactions.yml | 32 +++++- .../routes/searchConfirmedTransactions.yml | 105 +++++++++++++++++- .../routes/searchPartialTransactions.yml | 74 +++++++++++- .../routes/searchUnconfirmedTransactions.yml | 36 +++++- .../schemas/AnnounceTransactionInfoDTO.yml | 13 +++ .../schemas/EmbeddedTransactionBodyDTO.yml | 1 + .../schemas/EmbeddedTransactionDTO.yml | 1 + .../schemas/EmbeddedTransactionInfoDTO.yml | 2 + .../schemas/EmbeddedTransactionMetaDTO.yml | 16 ++- .../schemas/TransactionBodyDTO.yml | 5 + .../schemas/TransactionInfoDTO.yml | 14 +++ .../schemas/TransactionMetaDTO.yml | 29 ++++- .../transaction/schemas/TransactionPage.yml | 1 + .../schemas/TransactionStatusDTO.yml | 1 + .../schemas/TransactionTypeEnum.yml | 2 +- spec/parameters/path/transactionHashPath.yml | 2 +- spec/parameters/path/transactionIdPath.yml | 2 +- spec/parameters/query/addressQuery.yml | 14 ++- spec/parameters/query/embeddedQuery.yml | 26 ++++- spec/parameters/query/fromHeightQuery.yml | 2 +- .../query/fromTransferAmountQuery.yml | 2 +- spec/parameters/query/heightQuery.yml | 4 +- spec/parameters/query/orderQuery.yml | 1 + spec/parameters/query/pageSizeQuery.yml | 4 +- .../query/recipientAddressQuery.yml | 2 +- .../parameters/query/signerPublicKeyQuery.yml | 2 +- spec/parameters/query/toHeightQuery.yml | 2 +- .../query/toTransferAmountQuery.yml | 2 +- .../query/transactionTypesQuery.yml | 1 + .../query/transferMosaicIdQuery.yml | 2 +- .../AccountKeyLinkTransactionBodyDTO.yml | 1 + .../EmbeddedAccountKeyLinkTransactionDTO.yml | 1 + .../EmbeddedNodeKeyLinkTransactionDTO.yml | 1 + .../schemas/NodeKeyLinkTransactionBodyDTO.yml | 1 + .../routes/announceCosignatureTransaction.yml | 17 ++- .../routes/announcePartialTransaction.yml | 18 ++- .../schemas/AggregateTransactionBodyDTO.yml | 3 + .../AggregateTransactionBodyExtendedDTO.yml | 3 + .../EmbeddedVotingKeyLinkTransactionDTO.yml | 1 + .../EmbeddedVrfKeyLinkTransactionDTO.yml | 1 + .../VotingKeyLinkTransactionBodyDTO.yml | 1 + .../schemas/VrfKeyLinkTransactionBodyDTO.yml | 1 + .../EmbeddedHashLockTransactionDTO.yml | 1 + .../schemas/HashLockTransactionBodyDTO.yml | 1 + .../EmbeddedSecretLockTransactionDTO.yml | 1 + .../EmbeddedSecretProofTransactionDTO.yml | 1 + .../schemas/SecretLockTransactionBodyDTO.yml | 1 + .../schemas/SecretProofTransactionBodyDTO.yml | 3 +- .../AccountMetadataTransactionBodyDTO.yml | 9 +- .../schemas/AccountMetadataTransactionDTO.yml | 2 +- .../EmbeddedAccountMetadataTransactionDTO.yml | 1 + .../EmbeddedMosaicMetadataTransactionDTO.yml | 1 + ...mbeddedNamespaceMetadataTransactionDTO.yml | 1 + .../metadata/schemas/MetadataEntryDTO.yml | 5 +- .../MosaicMetadataTransactionBodyDTO.yml | 9 +- .../schemas/MosaicMetadataTransactionDTO.yml | 2 +- .../NamespaceMetadataTransactionBodyDTO.yml | 11 +- .../NamespaceMetadataTransactionDTO.yml | 2 +- ...EmbeddedMosaicDefinitionTransactionDTO.yml | 1 + ...beddedMosaicSupplyChangeTransactionDTO.yml | 1 + ...edMosaicSupplyRevocationTransactionDTO.yml | 1 + .../MosaicDefinitionTransactionBodyDTO.yml | 4 +- .../schemas/MosaicSupplyChangeActionEnum.yml | 9 +- .../MosaicSupplyChangeTransactionBodyDTO.yml | 1 + ...saicSupplyRevocationTransactionBodyDTO.yml | 1 + ...tisigAccountModificationTransactionDTO.yml | 1 + ...gAccountModificationTransactionBodyDTO.yml | 2 +- .../AddressAliasTransactionBodyDTO.yml | 1 + .../namespace/schemas/AliasActionEnum.yml | 9 +- .../EmbeddedAddressAliasTransactionDTO.yml | 1 + .../EmbeddedMosaicAliasTransactionDTO.yml | 1 + ...dedNamespaceRegistrationTransactionDTO.yml | 1 + .../schemas/MosaicAliasTransactionBodyDTO.yml | 1 + ...amespaceRegistrationTransactionBodyDTO.yml | 1 + ...ntAddressRestrictionTransactionBodyDTO.yml | 1 + ...untMosaicRestrictionTransactionBodyDTO.yml | 1 + ...OperationRestrictionTransactionBodyDTO.yml | 1 + ...ccountAddressRestrictionTransactionDTO.yml | 1 + ...AccountMosaicRestrictionTransactionDTO.yml | 1 + ...ountOperationRestrictionTransactionDTO.yml | 1 + ...MosaicAddressRestrictionTransactionDTO.yml | 1 + ...dMosaicGlobalRestrictionTransactionDTO.yml | 1 + ...icAddressRestrictionTransactionBodyDTO.yml | 1 + ...aicGlobalRestrictionTransactionBodyDTO.yml | 1 + .../EmbeddedTransferTransactionDTO.yml | 1 + .../schemas/TransferTransactionBodyDTO.yml | 3 +- spec/request_bodies/cosignature.yml | 1 + spec/request_bodies/schemas/cosignature.yml | 8 ++ .../schemas/transactionHashes.yml | 2 + .../request_bodies/schemas/transactionIds.yml | 5 +- .../schemas/transactionPayload.yml | 11 +- spec/request_bodies/transactionIds.yml | 1 + spec/request_bodies/transactionPayload.yml | 4 + spec/schemas/CosignatureVersion.yml | 7 +- spec/schemas/LinkActionEnum.yml | 6 +- spec/schemas/MetadataValue.yml | 3 +- spec/schemas/MetadataValueSize.yml | 10 ++ spec/schemas/MetadataValueSizeDelta.yml | 9 ++ spec/schemas/Order.yml | 1 - spec/schemas/TransactionMetaHeight.yml | 10 ++ spec/schemas/VotingKey.yml | 8 +- spec/tags.yml | 13 +++ 108 files changed, 770 insertions(+), 109 deletions(-) create mode 100644 spec/schemas/MetadataValueSize.yml create mode 100644 spec/schemas/MetadataValueSizeDelta.yml create mode 100644 spec/schemas/TransactionMetaHeight.yml diff --git a/spec/core/transaction/routes/announceTransaction.yml b/spec/core/transaction/routes/announceTransaction.yml index 3d4d6334..2a5430c1 100644 --- a/spec/core/transaction/routes/announceTransaction.yml +++ b/spec/core/transaction/routes/announceTransaction.yml @@ -2,21 +2,33 @@ tags: - Transaction routes summary: Announce a new transaction description: | - Announces a transaction to the network. - The [catbuffer library](https://github.com/symbol/symbol/tree/main/catbuffer) - defines the protocol to serialize and deserialize Symbol entities. - Catbuffers are integrated into [Symbol SDKs](https://docs.symbol.dev/sdk.html). - It's recommended to use SDKs instead of calling the API endpoint directly to announce transactions. + Broadcasts a signed transaction to the network through this node. + + The request must contain the serialized transaction payload in hexadecimal form. Transactions are + normally created and signed client-side with a [Symbol SDK](https://docs.symbol.dev/sdk.html) and + then announced with this endpoint. + + The [catbuffer library](https://github.com/symbol/symbol/tree/main/catbuffer) defines the binary + serialization format used by Symbol entities. + + To verify the final result, query ``GET /transactionStatus/{hash}`` on the same node that received + the announce request. If that node drops the transaction before propagation, other nodes may not + know the transaction at all and can return ``404`` for the same hash. operationId: announceTransaction requestBody: $ref: "../../../request_bodies/transactionPayload.yml" responses: "202": - description: success + description: Transaction accepted for processing and broadcast by the node. content: application/json: schema: $ref: "../schemas/AnnounceTransactionInfoDTO.yml" + examples: + success: + summary: Transaction packet pushed to the node + value: + message: "packet 9 was pushed to the network via /transactions" "400": $ref: "../../../responses/InvalidContent.yml" "409": diff --git a/spec/core/transaction/routes/getConfirmedTransaction.yml b/spec/core/transaction/routes/getConfirmedTransaction.yml index 2b1a8042..c8de2c5d 100644 --- a/spec/core/transaction/routes/getConfirmedTransaction.yml +++ b/spec/core/transaction/routes/getConfirmedTransaction.yml @@ -1,17 +1,61 @@ tags: - Transaction routes summary: Get confirmed transaction information -description: Returns confirmed transaction information given a transactionId or hash. +description: Returns confirmed transaction information given a transaction ID assigned by the node or transaction hash. operationId: getConfirmedTransaction parameters: - $ref: "../../../parameters/path/transactionIdPath.yml" responses: "200": - description: success + description: Confirmed transaction information. content: application/json: schema: $ref: "../schemas/TransactionInfoDTO.yml" + examples: + aggregateTransaction: + summary: Example confirmed aggregate transaction + value: + meta: + height: "5299379" + hash: "399724B8F6EBA9327D84B52B39BD6B6B1CD07819DEEE633F3AB9BDC9A305B930" + merkleComponentHash: "215CA36FDB4FA94796DE931FAA68C97C855D69770CF0CAED0AC4D7E460580844" + index: 0 + timestamp: "159214132791" + feeMultiplier: 128 + transaction: + size: 368 + signature: "0C34EA160F07070DAED62E734EAE734D1DFBD78499486A09561094551946DE3BAF79317AA000718724255C67BE..." + signerPublicKey: "B93B3931652DF080F1699F0EA14C6C760075785981C034AD4F435AC1EBEDA137" + version: 3 + network: 104 + type: 16961 + maxFee: "47200" + deadline: "159221254067" + transactionsHash: "2C4946AB5EAD0224CBF43EE1432A06833243892CD27FE3B6CD0797E959CA5DC7" + cosignatures: + - version: "0" + signerPublicKey: "3AB7AF84CC38E4E112F840ABD31866BD83AD5BCE765F31F84601D35799B9FFF4" + signature: "07BBD3BD1EBFDDE9B771F646278DEAEA245ED8FA66800169EE533377884F76816DEEDA8A8319EC838930DCC..." + transactions: + - meta: + height: "5299379" + aggregateHash: "399724B8F6EBA9327D84B52B39BD6B6B1CD07819DEEE633F3AB9BDC9A305B930" + aggregateId: "69CD60B02976BBB47C19E5D9" + index: 0 + timestamp: "159214132791" + feeMultiplier: 128 + transaction: + signerPublicKey: "8AC8A6034897189C1C7F30CDD4FE88D881E2CE5F94E2580C390CCEAAD06362D3" + version: 1 + network: 104 + type: 16724 + recipientAddress: "680D52CD378CDA123BFBBC54DB3CED5C4031473BF0B5EC02" + mosaics: + - id: "6BED913FA20223F8" + amount: "11254000000" + id: "69CD60B02976BBB47C19E5DA" + id: "69CD60B02976BBB47C19E5D9" "404": $ref: "../../../responses/ResourceNotFound.yml" "409": diff --git a/spec/core/transaction/routes/getConfirmedTransactions.yml b/spec/core/transaction/routes/getConfirmedTransactions.yml index b6044ba4..b028c0e8 100644 --- a/spec/core/transaction/routes/getConfirmedTransactions.yml +++ b/spec/core/transaction/routes/getConfirmedTransactions.yml @@ -1,20 +1,48 @@ tags: - Transaction routes -summary: Get confirmed trasactions information -description: Returns confirmed transactions information for a given array of transactionIds. +summary: Get confirmed transactions information +description: | + Returns confirmed transactions for the list of identifiers in the request body. + Each request item can be either a transaction ID assigned by the node or a transaction hash. operationId: getConfirmedTransactions requestBody: $ref: "../../../request_bodies/transactionIds.yml" responses: "200": - description: success + description: Confirmed transaction information for the requested identifiers. content: application/json: schema: type: array - description: Array of transactions information. + description: Array of confirmed transaction entries. items: $ref: "../schemas/TransactionInfoDTO.yml" + examples: + default: + summary: Example confirmed transaction batch response + value: + - meta: + height: "5299379" + hash: "399724B8F6EBA9327D84B52B39BD6B6B1CD07819DEEE633F3AB9BDC9A305B930" + merkleComponentHash: "215CA36FDB4FA94796DE931FAA68C97C855D69770CF0CAED0AC4D7E460580844" + index: 0 + timestamp: "159214132791" + feeMultiplier: 128 + transaction: + size: 368 + signature: "0C34EA160F07070DAED62E734EAE734D1DFBD78499486A09561094551946DE3BAF79317AA000718724255C67BE..." + signerPublicKey: "B93B3931652DF080F1699F0EA14C6C760075785981C034AD4F435AC1EBEDA137" + version: 3 + network: 104 + type: 16961 + maxFee: "47200" + deadline: "159221254067" + transactionsHash: "2C4946AB5EAD0224CBF43EE1432A06833243892CD27FE3B6CD0797E959CA5DC7" + cosignatures: + - version: "0" + signerPublicKey: "3AB7AF84CC38E4E112F840ABD31866BD83AD5BCE765F31F84601D35799B9FFF4" + signature: "07BBD3BD1EBFDDE9B771F646278DEAEA245ED8FA66800169EE533377884F76816DEEDA8A8319EC838930DC..." + id: "69CD60B02976BBB47C19E5D9" "400": $ref: "../../../responses/InvalidContent.yml" "409": diff --git a/spec/core/transaction/routes/getPartialTransaction.yml b/spec/core/transaction/routes/getPartialTransaction.yml index c9fba91e..08a5e256 100644 --- a/spec/core/transaction/routes/getPartialTransaction.yml +++ b/spec/core/transaction/routes/getPartialTransaction.yml @@ -1,17 +1,58 @@ tags: - Transaction routes summary: Get partial transaction information -description: Returns partial transaction information given a transactionId or hash. +description: | + Returns one partial transaction identified by the path value. + + The path accepts either the transaction ID assigned by the node or the transaction hash. Partial + transactions are aggregate bonded transactions waiting for the remaining cosignatures. operationId: getPartialTransaction parameters: - $ref: "../../../parameters/path/transactionIdPath.yml" responses: "200": - description: success + description: Partial transaction information. content: application/json: schema: $ref: "../schemas/TransactionInfoDTO.yml" + examples: + aggregateBondedTransaction: + summary: Example partial aggregate bonded transaction + value: + meta: + height: "0" + hash: "D304E55AFE3CAC0D86F78A708570FADDF41490981D8242C043A12EDE90225409" + merkleComponentHash: "0000000000000000000000000000000000000000000000000000000000000000" + index: 0 + transaction: + size: 264 + signature: "C17FEC2639C3BEE110C11FA199AC96C29D41A502B3E90F0E879FD00AB0BEBC2BEA27CFD006CEA1E6E12AE4D3D149..." + signerPublicKey: "C46AA9E7F1953C8EC9E20CEE783378CE556C01648B3C9CC185FBA6ACFDB8AC9E" + version: 3 + network: 152 + type: 16961 + maxFee: "43732" + deadline: "107964975712" + transactionsHash: "CDB1283FFAC65D16C0756EF55276C2715DEFC8606518FA60A2D6C3DC4AE902FB" + cosignatures: [] + transactions: + - meta: + height: "0" + aggregateHash: "D304E55AFE3CAC0D86F78A708570FADDF41490981D8242C043A12EDE90225409" + aggregateId: "69CD0083C72A61F64A176E3A" + index: 0 + transaction: + signerPublicKey: "7E1BB23C2E24A699697383DA8EB28BED5986165EBA502BA8B66576531DB04503" + version: 1 + network: 152 + type: 16724 + recipientAddress: "989D5AF7FB3149A8C9A34CBDDBB29714A4632239525161F6" + mosaics: + - id: "72C0212E67A08BCE" + amount: "12000000" + id: "69CD0083C72A61F64A176E3B" + id: "69CD0083C72A61F64A176E3A" "404": $ref: "../../../responses/ResourceNotFound.yml" "409": diff --git a/spec/core/transaction/routes/getPartialTransactions.yml b/spec/core/transaction/routes/getPartialTransactions.yml index c218c130..cd1819d4 100644 --- a/spec/core/transaction/routes/getPartialTransactions.yml +++ b/spec/core/transaction/routes/getPartialTransactions.yml @@ -1,20 +1,61 @@ tags: - Transaction routes -summary: Get partial trasactions information -description: Returns partial transactions information for a given array of transactionIds. +summary: Get partial transactions information +description: | + Returns partial transactions for the list of identifiers in the request body. + + Each request item can be either a transaction ID assigned by the node or a transaction hash. operationId: getPartialTransactions requestBody: $ref: "../../../request_bodies/transactionIds.yml" responses: "200": - description: success + description: Partial transaction information for the requested identifiers. content: application/json: schema: type: array - description: Array of transactions information. + description: Array of partial transaction entries. items: $ref: "../schemas/TransactionInfoDTO.yml" + examples: + default: + summary: Example partial transaction batch response + value: + - meta: + height: "0" + hash: "D304E55AFE3CAC0D86F78A708570FADDF41490981D8242C043A12EDE90225409" + merkleComponentHash: "0000000000000000000000000000000000000000000000000000000000000000" + index: 0 + transaction: + size: 264 + signature: "C17FEC2639C3BEE110C11FA199AC96C29D41A502B3E90F0E879FD00AB0BEBC2BEA27CFD006CEA1E6E12AE4D3D1..." + signerPublicKey: "C46AA9E7F1953C8EC9E20CEE783378CE556C01648B3C9CC185FBA6ACFDB8AC9E" + version: 3 + network: 152 + type: 16961 + maxFee: "43732" + deadline: "107964975712" + transactionsHash: "CDB1283FFAC65D16C0756EF55276C2715DEFC8606518FA60A2D6C3DC4AE902FB" + cosignatures: [] + id: "69CD0083C72A61F64A176E3A" + - meta: + height: "0" + hash: "E7FACE48AA997C6249D49C9BE4F30A0F8DB898BF266D578D06C8372CF0012305" + merkleComponentHash: "0000000000000000000000000000000000000000000000000000000000000000" + index: 0 + transaction: + size: 248 + signature: "416F363728A4F3BD89DF251138BDC4DD2B58B69C9C2CB0D9B2735E4643781023499F442CEB2D2796D4DA1A7CAB..." + signerPublicKey: "FFEA4F971FA8A6DCF63B410F1FF2868A9A7E1EFFD8B73DFB39F190E324F23049" + version: 3 + network: 152 + type: 16961 + maxFee: "45600" + deadline: "107989381281" + transactionsHash: "4C88E5297F38E158CAEFDB2674138E581553630F7CAA08C14920688F392F6557" + cosignatures: [] + id: "69CD5FAFC72A61F64A177DFC" "400": $ref: "../../../responses/InvalidContent.yml" "409": diff --git a/spec/core/transaction/routes/getUnconfirmedTransaction.yml b/spec/core/transaction/routes/getUnconfirmedTransaction.yml index c8394896..f5db94de 100644 --- a/spec/core/transaction/routes/getUnconfirmedTransaction.yml +++ b/spec/core/transaction/routes/getUnconfirmedTransaction.yml @@ -1,17 +1,41 @@ tags: - Transaction routes summary: Get unconfirmed transaction information -description: Returns unconfirmed transaction information given a transactionId or hash. +description: | + Returns one unconfirmed transaction identified by the path value. + + The path accepts either the transaction ID assigned by the node or the transaction hash. operationId: getUnconfirmedTransaction parameters: - $ref: "../../../parameters/path/transactionIdPath.yml" responses: "200": - description: success + description: Unconfirmed transaction information. content: application/json: schema: $ref: "../schemas/TransactionInfoDTO.yml" + examples: + aggregateTransaction: + summary: Example unconfirmed transaction response + value: + meta: + height: "0" + hash: "E5D72BEE9EF4BFD1F44757E8929E5434E9213DDB63A1783AA061086F2054D719" + merkleComponentHash: "E5D72BEE9EF4BFD1F44757E8929E5434E9213DDB63A1783AA061086F2054D719" + index: 0 + transaction: + size: 328 + signature: "862748DA2628D09C0D53EF937DC0FB8A52388B287368D105F287320153D1B4B372F0B20A82A5B695FE73BFFEFFCD..." + signerPublicKey: "D3078EDE1559AF366629C81E33CBB2859187A682EADC338C7F79E228959A2CC4" + version: 3 + network: 152 + type: 16705 + maxFee: "32800" + deadline: "107828961814" + transactionsHash: "96596CE7C3DF325418D75014A37606DC5E7D6840D9181D434F29BD9D0655D2C3" + cosignatures: [] + id: "69CD73E4C72A61F64A178158" "404": $ref: "../../../responses/ResourceNotFound.yml" "409": diff --git a/spec/core/transaction/routes/getUnconfirmedTransactions.yml b/spec/core/transaction/routes/getUnconfirmedTransactions.yml index 4100be57..396607a8 100644 --- a/spec/core/transaction/routes/getUnconfirmedTransactions.yml +++ b/spec/core/transaction/routes/getUnconfirmedTransactions.yml @@ -1,20 +1,44 @@ tags: - Transaction routes -summary: Get unconfirmed trasactions information -description: Returns unconfirmed transactions information for a given array of transactionIds. +summary: Get unconfirmed transactions information +description: | + Returns unconfirmed transactions for the list of identifiers in the request body. + + Each request item can be either a transaction ID assigned by the node or a transaction hash. operationId: getUnconfirmedTransactions requestBody: $ref: "../../../request_bodies/transactionIds.yml" responses: "200": - description: success + description: Unconfirmed transaction information for the requested identifiers. content: application/json: schema: type: array - description: Array of transactions information. + description: Array of unconfirmed transaction entries. items: $ref: "../schemas/TransactionInfoDTO.yml" + examples: + default: + summary: Example unconfirmed transaction batch response + value: + - meta: + height: "0" + hash: "E5D72BEE9EF4BFD1F44757E8929E5434E9213DDB63A1783AA061086F2054D719" + merkleComponentHash: "E5D72BEE9EF4BFD1F44757E8929E5434E9213DDB63A1783AA061086F2054D719" + index: 0 + transaction: + size: 328 + signature: "862748DA2628D09C0D53EF937DC0FB8A52388B287368D105F287320153D1B4B372F0B20A82A5B695FE73BFFEFF..." + signerPublicKey: "D3078EDE1559AF366629C81E33CBB2859187A682EADC338C7F79E228959A2CC4" + version: 3 + network: 152 + type: 16705 + maxFee: "32800" + deadline: "107828961814" + transactionsHash: "96596CE7C3DF325418D75014A37606DC5E7D6840D9181D434F29BD9D0655D2C3" + cosignatures: [] + id: "69CD73E4C72A61F64A178158" "400": $ref: "../../../responses/InvalidContent.yml" "409": diff --git a/spec/core/transaction/routes/searchConfirmedTransactions.yml b/spec/core/transaction/routes/searchConfirmedTransactions.yml index 193c80d5..12ad8b6d 100644 --- a/spec/core/transaction/routes/searchConfirmedTransactions.yml +++ b/spec/core/transaction/routes/searchConfirmedTransactions.yml @@ -2,10 +2,12 @@ tags: - Transaction routes summary: Search confirmed transactions description: | - Returns an array of confirmed transactions. - If a transaction was announced with an alias rather than an address, the - address that will be considered when querying is the one that - was resolved from the alias at confirmation time. + Returns a paginated list of confirmed transactions matching the supplied filters. + + If a transaction was announced with an alias rather than an address, the address considered during + filtering is the one resolved from that alias at confirmation time. + + Pagination on this endpoint is ordered by transaction record ``id``. operationId: searchConfirmedTransactions parameters: - $ref: "../../../parameters/query/addressQuery.yml" @@ -25,10 +27,101 @@ parameters: - $ref: "../../../parameters/query/orderQuery.yml" responses: "200": - description: success + description: Page of confirmed transactions. content: application/json: schema: $ref: "../schemas/TransactionPage.yml" + examples: + topLevelOnly: + summary: Example response with embedded set to false + value: + data: + - meta: + height: "1" + hash: "96285C7EB0622892F4F67772DB2E030E4FDDBF389CAF164790CA846D8280EA1A" + merkleComponentHash: "96285C7EB0622892F4F67772DB2E030E4FDDBF389CAF164790CA846D8280EA1A" + index: 6505 + timestamp: "0" + feeMultiplier: 0 + transaction: + size: 176 + signature: "86499F4AF09ED620D961C0A2CD5D22400A632E360F7FA23EA5D62C2B60A63E00EE1F34455657C1C72FA597D..." + signerPublicKey: "BE0B4CF546B7B4F4BBFCFF9F574FDA527C07A53D3FC76F8BB7DB746F8E8E0A9F" + version: 1 + network: 104 + type: 16724 + maxFee: "0" + deadline: "1" + recipientAddress: "68338CA70482DF1658E60BBC4657C1D74A2E5827FEF4DC37" + mosaics: + - id: "E74B99BA41F4AFEE" + amount: "24441954321" + id: "60574DCDA0A3E6414C032983" + pagination: + pageNumber: 1 + pageSize: 10 + includingEmbedded: + summary: Example response with embedded set to true + value: + data: + - meta: + height: "5299119" + hash: "E4D08A928C14038E34482EFBC5BC213B481FCB6212F3302968565B96E81963D6" + merkleComponentHash: "E59CEFF103FA692C2AEFCBEAAE75B0609C860E5B47BF9A05BCDA1AC1B11099B3" + index: 0 + timestamp: "159206499627" + feeMultiplier: 100 + transaction: + size: 712 + signature: "E6ACAA3328B6DE2650918FC24360F70D3AD8B65C7CD139815A453D37B3F22C21D7A32ED98E1CECA924C..." + signerPublicKey: "0544EA984581DBF1C0A98F14231F83AAAFC4F26E09DB035CE0C99737DE4E1DD7" + version: 3 + network: 104 + type: 16961 + maxFee: "71200" + deadline: "159213671557" + transactionsHash: "C8E3AD4E745AC47D688337EF4E23A9238600D41771E68EA1783A33E50A67F8DC" + cosignatures: + - version: "0" + signerPublicKey: "DD8710269484573DB6C497B6722B6B8A5D1136305C16CD81313F899CD792FCA5" + signature: "F29AC6AF8FB7EE85535927502253B04A3EA934A60AB57F39C30EBFFE72D9F52A3F42173A6D9BDEC8..." + transactions: + - meta: + height: "5299119" + aggregateHash: "E4D08A928C14038E34482EFBC5BC213B481FCB6212F3302968565B96E81963D6" + aggregateId: "69CD42DF2976BBB47C19E3AE" + index: 1 + timestamp: "159206499627" + feeMultiplier: 100 + transaction: + signerPublicKey: "88F44BBD37BE0F98A7F06B6D958E0A8807F05A9A14F5DE408012E2AA6E2A84DE" + version: 1 + network: 104 + type: 16724 + recipientAddress: "68E5AC45A655D1F08C4D13825DA9D9822C89080F5ADCAAD1" + message: "011F102526858BE43F4CBA54E9F62E80B22830DEB5FA180431ED4633701D2ABC0C6129D1719C087BCE1C23..." + mosaics: [] + id: "69CD42DF2976BBB47C19E3B0" + id: "69CD42DF2976BBB47C19E3AE" + - meta: + height: "5299119" + aggregateHash: "E4D08A928C14038E34482EFBC5BC213B481FCB6212F3302968565B96E81963D6" + aggregateId: "69CD42DF2976BBB47C19E3AE" + index: 1 + timestamp: "159206499627" + feeMultiplier: 100 + transaction: + signerPublicKey: "88F44BBD37BE0F98A7F06B6D958E0A8807F05A9A14F5DE408012E2AA6E2A84DE" + version: 1 + network: 104 + type: 16724 + recipientAddress: "68E5AC45A655D1F08C4D13825DA9D9822C89080F5ADCAAD1" + message: "011F102526858BE43F4CBA54E9F62E80B22830DEB5FA180431ED4633701D2ABC0C6129D1719C087BCE1C23..." + mosaics: [] + id: "69CD42DF2976BBB47C19E3B0" + pagination: + pageNumber: 1 + pageSize: 100 "409": - $ref : "../../../responses/InvalidArgument.yml" + $ref: "../../../responses/InvalidArgument.yml" diff --git a/spec/core/transaction/routes/searchPartialTransactions.yml b/spec/core/transaction/routes/searchPartialTransactions.yml index 43a7ec46..7753f2eb 100644 --- a/spec/core/transaction/routes/searchPartialTransactions.yml +++ b/spec/core/transaction/routes/searchPartialTransactions.yml @@ -1,7 +1,10 @@ tags: - Transaction routes summary: Search partial transactions -description: Returns an array of partial transactions. +description: | + Returns a paginated list of partial transactions matching the supplied filters. + + Pagination on this endpoint is ordered by transaction record ``id``. operationId: searchPartialTransactions parameters: - $ref: "../../../parameters/query/addressQuery.yml" @@ -21,10 +24,75 @@ parameters: - $ref: "../../../parameters/query/orderQuery.yml" responses: "200": - description: success + description: Page of partial transactions. content: application/json: schema: $ref: "../schemas/TransactionPage.yml" + examples: + topLevelOnly: + summary: Example response with partial aggregate bonded transactions + value: + data: + - meta: + height: "0" + hash: "E7FACE48AA997C6249D49C9BE4F30A0F8DB898BF266D578D06C8372CF0012305" + merkleComponentHash: "0000000000000000000000000000000000000000000000000000000000000000" + index: 0 + transaction: + size: 248 + signature: "416F363728A4F3BD89DF251138BDC4DD2B58B69C9C2CB0D9B2735E4643781023499F442CEB2D2796D4DA1A7C..." + signerPublicKey: "FFEA4F971FA8A6DCF63B410F1FF2868A9A7E1EFFD8B73DFB39F190E324F23049" + version: 3 + network: 152 + type: 16961 + maxFee: "45600" + deadline: "107989381281" + transactionsHash: "4C88E5297F38E158CAEFDB2674138E581553630F7CAA08C14920688F392F6557" + cosignatures: [] + id: "69CD5FAFC72A61F64A177DFC" + pagination: + pageNumber: 1 + pageSize: 10 + includingEmbedded: + summary: Example response with embedded set to true + value: + data: + - meta: + height: "0" + hash: "E7FACE48AA997C6249D49C9BE4F30A0F8DB898BF266D578D06C8372CF0012305" + merkleComponentHash: "0000000000000000000000000000000000000000000000000000000000000000" + index: 0 + transaction: + size: 248 + signature: "416F363728A4F3BD89DF251138BDC4DD2B58B69C9C2CB0D9B2735E4643781023499F442CEB2D2796D4DA1A7C..." + signerPublicKey: "FFEA4F971FA8A6DCF63B410F1FF2868A9A7E1EFFD8B73DFB39F190E324F23049" + version: 3 + network: 152 + type: 16961 + maxFee: "45600" + deadline: "107989381281" + transactionsHash: "4C88E5297F38E158CAEFDB2674138E581553630F7CAA08C14920688F392F6557" + cosignatures: [] + id: "69CD5FAFC72A61F64A177DFC" + - meta: + height: "0" + aggregateHash: "E7FACE48AA997C6249D49C9BE4F30A0F8DB898BF266D578D06C8372CF0012305" + aggregateId: "69CD5FAFC72A61F64A177DFC" + index: 0 + transaction: + signerPublicKey: "FFEA4F971FA8A6DCF63B410F1FF2868A9A7E1EFFD8B73DFB39F190E324F23049" + version: 1 + network: 152 + type: 16725 + minRemovalDelta: 1 + minApprovalDelta: 1 + addressAdditions: + - "98F5D0F176F14A39D523A8FD787D9C8F30CF4C838969411D" + addressDeletions: [] + id: "69CD5FAFC72A61F64A177DFD" + pagination: + pageNumber: 1 + pageSize: 20 "409": - $ref : "../../../responses/InvalidArgument.yml" + $ref: "../../../responses/InvalidArgument.yml" diff --git a/spec/core/transaction/routes/searchUnconfirmedTransactions.yml b/spec/core/transaction/routes/searchUnconfirmedTransactions.yml index fcaad46a..d960d7f9 100644 --- a/spec/core/transaction/routes/searchUnconfirmedTransactions.yml +++ b/spec/core/transaction/routes/searchUnconfirmedTransactions.yml @@ -1,7 +1,10 @@ tags: - Transaction routes summary: Search unconfirmed transactions -description: Returns an array of unconfirmed transactions. +description: | + Returns a paginated list of unconfirmed transactions matching the supplied filters. + + Pagination on this endpoint is ordered by transaction record ``id``. operationId: searchUnconfirmedTransactions parameters: - $ref: "../../../parameters/query/addressQuery.yml" @@ -21,10 +24,37 @@ parameters: - $ref: "../../../parameters/query/orderQuery.yml" responses: "200": - description: success + description: Page of unconfirmed transactions. content: application/json: schema: $ref: "../schemas/TransactionPage.yml" + examples: + default: + summary: Example response with an unconfirmed transaction + value: + data: + - meta: + height: "0" + hash: "031FE3A39574F2AC073ACC107A18F175F74ADD0A9CE6C4C5B26AA220986662F0" + merkleComponentHash: "031FE3A39574F2AC073ACC107A18F175F74ADD0A9CE6C4C5B26AA220986662F0" + index: 0 + transaction: + size: 176 + signature: "25163A3D6607C900841DC3BF23C5054D47F75D87C22E4143616AA9225D3853DD60FF8DC314DCAC4911CB261B..." + signerPublicKey: "A6977B7FF4C3354EFC9393F7EC6F0FBD85A2A649A0B50A06A6A5452629B28006" + version: 1 + network: 104 + type: 16724 + maxFee: "17600" + deadline: "159220199218" + recipientAddress: "68F17F8F3647965E8587F4CADD6B4177213DA8CE3E609EF6" + mosaics: + - id: "6BED913FA20223F8" + amount: "1000000" + id: "69CD5C452976BBB47C19E584" + pagination: + pageNumber: 1 + pageSize: 10 "409": - $ref : "../../../responses/InvalidArgument.yml" + $ref: "../../../responses/InvalidArgument.yml" diff --git a/spec/core/transaction/schemas/AnnounceTransactionInfoDTO.yml b/spec/core/transaction/schemas/AnnounceTransactionInfoDTO.yml index aa3e7ae7..9f6aaa9b 100644 --- a/spec/core/transaction/schemas/AnnounceTransactionInfoDTO.yml +++ b/spec/core/transaction/schemas/AnnounceTransactionInfoDTO.yml @@ -1,6 +1,19 @@ type: object +description: | + Informational response returned after a transaction announce request is accepted. + + This object does not contain the announced transaction payload or its final execution result. It + only carries the node message associated with the announce request. + + To verify the final result, query ``GET /transactionStatus/{hash}`` on the same node that received + the announce request. If that node drops the transaction before propagation, other nodes may not + know the transaction at all and can return ``404`` for the same hash. + + In some cases the transaction can be dropped without any failure status being returned. Common causes include using + a fee below the minimum accepted by that node or using a generation hash seed that does not match the target network. required: - message properties: message: type: string + description: Human-readable message returned by the node for the announce request. diff --git a/spec/core/transaction/schemas/EmbeddedTransactionBodyDTO.yml b/spec/core/transaction/schemas/EmbeddedTransactionBodyDTO.yml index 92d2988a..3a6ab855 100644 --- a/spec/core/transaction/schemas/EmbeddedTransactionBodyDTO.yml +++ b/spec/core/transaction/schemas/EmbeddedTransactionBodyDTO.yml @@ -1,4 +1,5 @@ type: object +description: Wrapper for embedded transactions carried inside an aggregate transaction. required: - transactions properties: diff --git a/spec/core/transaction/schemas/EmbeddedTransactionDTO.yml b/spec/core/transaction/schemas/EmbeddedTransactionDTO.yml index a4853264..ca3cf18e 100644 --- a/spec/core/transaction/schemas/EmbeddedTransactionDTO.yml +++ b/spec/core/transaction/schemas/EmbeddedTransactionDTO.yml @@ -1,3 +1,4 @@ type: object +description: Transaction payload embedded inside an aggregate transaction. allOf: - $ref: "../../entity/schemas/EntityDTO.yml" diff --git a/spec/core/transaction/schemas/EmbeddedTransactionInfoDTO.yml b/spec/core/transaction/schemas/EmbeddedTransactionInfoDTO.yml index 9c7ab9ca..76b6b978 100644 --- a/spec/core/transaction/schemas/EmbeddedTransactionInfoDTO.yml +++ b/spec/core/transaction/schemas/EmbeddedTransactionInfoDTO.yml @@ -1,4 +1,5 @@ type: object +description: Embedded transaction record returned from aggregate transaction payloads. required: - id - meta @@ -9,6 +10,7 @@ properties: meta: $ref: "./EmbeddedTransactionMetaDTO.yml" transaction: + description: Concrete embedded transaction payload represented by one of the listed transaction DTOs. anyOf: - $ref: "../../../plugins/account_link/schemas/EmbeddedAccountKeyLinkTransactionDTO.yml" - $ref: "../../../plugins/account_link/schemas/EmbeddedNodeKeyLinkTransactionDTO.yml" diff --git a/spec/core/transaction/schemas/EmbeddedTransactionMetaDTO.yml b/spec/core/transaction/schemas/EmbeddedTransactionMetaDTO.yml index 43f11cac..b7cb65c6 100644 --- a/spec/core/transaction/schemas/EmbeddedTransactionMetaDTO.yml +++ b/spec/core/transaction/schemas/EmbeddedTransactionMetaDTO.yml @@ -1,4 +1,7 @@ type: object +description: | + Metadata for an embedded transaction entry returned by the transaction endpoints. + These fields identify the parent aggregate transaction and the embedded transaction's position inside it. required: - height - aggregateHash @@ -6,15 +9,24 @@ required: - index properties: height: - $ref: "../../../schemas/Height.yml" + $ref: "../../../schemas/TransactionMetaHeight.yml" + description: | + Height of the block that contains the parent aggregate transaction. + For embedded transactions returned from partial aggregate transactions, this value is ``"0"``. aggregateHash: $ref: "../../../schemas/Hash256.yml" + description: Hash of the parent aggregate transaction. aggregateId: $ref: "../../../schemas/ObjectId.yml" + description: Database record ID of the parent aggregate transaction. index: type: integer - description: Transaction index within the aggregate. + description: Embedded transaction index within the parent aggregate transaction. timestamp: $ref: "../../../schemas/Timestamp.yml" + description: | + Timestamp of the block that contains the parent aggregate transaction, + in milliseconds since the creation of the nemesis (first) block. feeMultiplier: $ref: "../../../schemas/BlockFeeMultiplier.yml" + description: Fee multiplier of the block that contains the parent aggregate transaction. diff --git a/spec/core/transaction/schemas/TransactionBodyDTO.yml b/spec/core/transaction/schemas/TransactionBodyDTO.yml index 578d1c7c..e2a2a5a2 100644 --- a/spec/core/transaction/schemas/TransactionBodyDTO.yml +++ b/spec/core/transaction/schemas/TransactionBodyDTO.yml @@ -1,9 +1,14 @@ type: object +description: Common body fields shared by all top-level transactions. required: - maxFee - deadline properties: maxFee: $ref: "../../../schemas/Amount.yml" + description: Maximum fee the signer is willing to pay for this transaction, in smallest (atomic) units. deadline: $ref: "../../../schemas/Timestamp.yml" + description: | + Latest network time at which the transaction can still be included in a block, expressed in milliseconds + since the creation of the nemesis (first) block. diff --git a/spec/core/transaction/schemas/TransactionInfoDTO.yml b/spec/core/transaction/schemas/TransactionInfoDTO.yml index 1961b35e..bcfdb025 100644 --- a/spec/core/transaction/schemas/TransactionInfoDTO.yml +++ b/spec/core/transaction/schemas/TransactionInfoDTO.yml @@ -1,4 +1,11 @@ type: object +description: | + Transaction record returned by transaction lookup and search endpoints. + + The same wrapper is used for confirmed, unconfirmed, and partial transaction groups. The exact + ``meta`` shape depends on whether the returned entry is a top-level transaction or an embedded + transaction inside an aggregate. When an aggregate transaction is retrieved by ID or hash, REST can + also expand its embedded transactions under ``transaction.transactions``. required: - id - meta @@ -7,10 +14,17 @@ properties: id: $ref: "../../../schemas/ObjectId.yml" meta: + description: | + Metadata for the returned transaction entry. + Top-level entries use ``TransactionMetaDTO``. Embedded entries use ``EmbeddedTransactionMetaDTO``. anyOf: - $ref: "./TransactionMetaDTO.yml" - $ref: "./EmbeddedTransactionMetaDTO.yml" transaction: + description: | + Concrete transaction payload represented by one of the listed transaction DTOs. + For aggregate transaction lookups, REST can populate ``transaction.transactions`` with the + embedded transaction records linked to that aggregate. anyOf: - $ref: "../../../plugins/account_link/schemas/AccountKeyLinkTransactionDTO.yml" - $ref: "../../../plugins/account_link/schemas/EmbeddedAccountKeyLinkTransactionDTO.yml" diff --git a/spec/core/transaction/schemas/TransactionMetaDTO.yml b/spec/core/transaction/schemas/TransactionMetaDTO.yml index 09ec9bfe..b159e2a2 100644 --- a/spec/core/transaction/schemas/TransactionMetaDTO.yml +++ b/spec/core/transaction/schemas/TransactionMetaDTO.yml @@ -1,4 +1,17 @@ type: object +description: | + Metadata for a top-level transaction entry returned by the transaction endpoints. + For confirmed transactions, these fields describe the transaction's position in the block and the + proof-related hashes associated with that block entry. + + For unconfirmed top-level transactions, REST returns: + - ``height`` = ``"0"`` + - ``index`` = ``0`` + - ``hash`` = transaction hash + - ``merkleComponentHash`` = transaction hash + + Block-derived fields such as ``timestamp`` and ``feeMultiplier`` are not present until the transaction + is included in a block. required: - height - hash @@ -6,15 +19,27 @@ required: - index properties: height: - $ref: "../../../schemas/Height.yml" + $ref: "../../../schemas/TransactionMetaHeight.yml" + description: Height of the block that contains the transaction. For unconfirmed top-level transactions, this value is ``"0"``. hash: $ref: "../../../schemas/Hash256.yml" + description: Hash of the top-level transaction. merkleComponentHash: $ref: "../../../schemas/Hash256.yml" + description: | + Merkle component hash of the top-level transaction used in block transaction proofs. + For unconfirmed top-level transactions, this value matches ``hash``. index: type: integer - description: Transaction index within the block. + description: | + Transaction index within the block. For unconfirmed top-level transactions, this value is ``0``. timestamp: $ref: "../../../schemas/Timestamp.yml" + description: | + Timestamp of the block that contains the transaction, in milliseconds since the creation of the + nemesis (first) block. This field is absent for unconfirmed top-level transactions. feeMultiplier: $ref: "../../../schemas/BlockFeeMultiplier.yml" + description: | + Fee multiplier of the block that contains the transaction. + This field is absent for unconfirmed top-level transactions. diff --git a/spec/core/transaction/schemas/TransactionPage.yml b/spec/core/transaction/schemas/TransactionPage.yml index 16507df4..9aea2a1c 100644 --- a/spec/core/transaction/schemas/TransactionPage.yml +++ b/spec/core/transaction/schemas/TransactionPage.yml @@ -1,4 +1,5 @@ type: object +description: Paginated transaction search result. required: - data - pagination diff --git a/spec/core/transaction/schemas/TransactionStatusDTO.yml b/spec/core/transaction/schemas/TransactionStatusDTO.yml index 713c3a1c..fb309814 100644 --- a/spec/core/transaction/schemas/TransactionStatusDTO.yml +++ b/spec/core/transaction/schemas/TransactionStatusDTO.yml @@ -14,6 +14,7 @@ properties: description: Hash of the transaction. deadline: $ref: "../../../schemas/Timestamp.yml" + description: Deadline specified by the transaction, expressed in milliseconds since the creation of the nemesis (first) block. height: $ref: "../../../schemas/Height.yml" description: Block height at which the transaction was confirmed, when available. diff --git a/spec/core/transaction/schemas/TransactionTypeEnum.yml b/spec/core/transaction/schemas/TransactionTypeEnum.yml index f9a9eb3c..eb13d6f7 100644 --- a/spec/core/transaction/schemas/TransactionTypeEnum.yml +++ b/spec/core/transaction/schemas/TransactionTypeEnum.yml @@ -26,7 +26,7 @@ enum: - 16977 - 16724 description: | - Transaction type identifier: + Numeric transaction type identifiers used on transaction payloads and search filters: - `0x414C` (`16716`): `AccountKeyLinkTransaction` - `0x4243` (`16963`): `VrfKeyLinkTransaction` - `0x4143` (`16707`): `VotingKeyLinkTransaction` diff --git a/spec/parameters/path/transactionHashPath.yml b/spec/parameters/path/transactionHashPath.yml index 1f6af8f3..ea846908 100644 --- a/spec/parameters/path/transactionHashPath.yml +++ b/spec/parameters/path/transactionHashPath.yml @@ -1,6 +1,6 @@ name: hash in: path -description: Transaction hash. +description: Transaction hash encoded as a 64-character hexadecimal string. required: true schema: $ref: "../../schemas/Hash256.yml" diff --git a/spec/parameters/path/transactionIdPath.yml b/spec/parameters/path/transactionIdPath.yml index dd6a32ff..b7a716cd 100644 --- a/spec/parameters/path/transactionIdPath.yml +++ b/spec/parameters/path/transactionIdPath.yml @@ -1,6 +1,6 @@ name: transactionId in: path -description: Transaction ID or hash. +description: Transaction ID assigned by the node or transaction hash. required: true schema: type: string diff --git a/spec/parameters/query/addressQuery.yml b/spec/parameters/query/addressQuery.yml index 0e6e2931..45f2c416 100644 --- a/spec/parameters/query/addressQuery.yml +++ b/spec/parameters/query/addressQuery.yml @@ -1,8 +1,16 @@ name: address in: query description: | - Filter by address. For transaction search: an account's address is considered involved when the account is the sender, - recipient, or cosigner; this filter cannot be combined with ``recipientAddress`` and ``signerPublicKey``. - For account, restriction, and lock search: returns entities matching or associated with the address. + Filter by address. + + The exact meaning depends on the endpoint: + - transaction search: returns transactions involving the address, meaning the address is considered + as the sender, recipient, or cosigner + - account search: matches the account address + - account restriction search: matches the restricted account address + - hash lock and secret lock search: matches the lock owner address + + On transaction search endpoints, this filter cannot be combined with ``recipientAddress`` and + ``signerPublicKey``. schema: $ref: "../../schemas/Address.yml" diff --git a/spec/parameters/query/embeddedQuery.yml b/spec/parameters/query/embeddedQuery.yml index 4900d172..4d4384ae 100644 --- a/spec/parameters/query/embeddedQuery.yml +++ b/spec/parameters/query/embeddedQuery.yml @@ -1,12 +1,26 @@ name: embedded in: query description: | - When true, the endpoint also returns all the embedded aggregate transactions. - Otherwise, only top-level transactions used to calculate the block transactionsHash are returned. - **Note:** This field does not work when combined with the ``address`` parameter. This is, - embedded transactions containing the address specified through the ``address`` parameter - will not be returned even when used with ``embedded=true``. There is no problem when using - other parameters like ``recipientAddress`` instead. + When ``true``, the search also includes transactions embedded inside aggregate transactions. + Otherwise, only top-level transactions are returned. + + Results are **flattened**. Embedded transactions are returned as separate entries in the same + ``data`` array as top-level transactions, not nested under their parent aggregate transaction. + Sorting, filtering, and pagination are therefore applied to one combined result set containing + both top-level and embedded transaction records. + + In the database, embedded transactions are stored as separate documents linked to their + parent aggregate by ``meta.aggregateId`` and ``meta.aggregateHash``. When ``embedded=false``, the + search excludes documents with ``meta.aggregateId``. When ``embedded=true``, those documents are + included in the page result alongside regular transactions. In REST responses, embedded entries + are identified by ``meta.aggregateId``, ``meta.aggregateHash``, and their inner ``meta.index``; + unlike top-level transactions, they do not carry their own ``meta.hash``. + + **Note:** This field does not work as expected with the ``address`` filter. That filter matches the + internal ``meta.addresses`` field used on top-level transaction documents, while embedded + transaction documents do not carry that field. As a result, embedded transactions involving the + specified address will not be returned even when ``embedded=true``. Filters such as + ``recipientAddress`` and ``signerPublicKey`` do not have this limitation. schema: type: boolean default: false diff --git a/spec/parameters/query/fromHeightQuery.yml b/spec/parameters/query/fromHeightQuery.yml index fdbff702..6b15e700 100644 --- a/spec/parameters/query/fromHeightQuery.yml +++ b/spec/parameters/query/fromHeightQuery.yml @@ -1,5 +1,5 @@ name: fromHeight in: query -description: Only blocks with height greater or equal than this one are returned. +description: Only transactions at or above this block height are returned. schema: $ref: "../../schemas/Height.yml" diff --git a/spec/parameters/query/fromTransferAmountQuery.yml b/spec/parameters/query/fromTransferAmountQuery.yml index fe535add..f7b52382 100644 --- a/spec/parameters/query/fromTransferAmountQuery.yml +++ b/spec/parameters/query/fromTransferAmountQuery.yml @@ -2,6 +2,6 @@ name: fromTransferAmount in: query description: | Requires providing the `transferMosaicId` filter. - Only transfer transactions with a transfer amount of the provided mosaic ID, greater or equal than this amount are returned. + Only transfer transactions with an amount greater than or equal to this value for the specified mosaic ID are returned. schema: $ref: "../../schemas/Amount.yml" diff --git a/spec/parameters/query/heightQuery.yml b/spec/parameters/query/heightQuery.yml index 0b5f8beb..1c5e0335 100644 --- a/spec/parameters/query/heightQuery.yml +++ b/spec/parameters/query/heightQuery.yml @@ -1,6 +1,8 @@ name: height in: query description: | - Filter by block height. Sequential block position in the chain; starts at 1 and increments by one. + Filter by height. + The exact meaning depends on the endpoint, for example block height for blocks or inclusion height for + confirmed transactions. schema: $ref: "../../schemas/Height.yml" diff --git a/spec/parameters/query/orderQuery.yml b/spec/parameters/query/orderQuery.yml index 4baf3c44..e1f59522 100644 --- a/spec/parameters/query/orderQuery.yml +++ b/spec/parameters/query/orderQuery.yml @@ -3,5 +3,6 @@ in: query description: | Sort responses in ascending or descending order based on the collection property set on the param ``orderBy``. If the request does not specify ``orderBy``, REST returns the collection ordered by id. + The default sort direction depends on the endpoint implementation. schema: $ref: "../../schemas/Order.yml" diff --git a/spec/parameters/query/pageSizeQuery.yml b/spec/parameters/query/pageSizeQuery.yml index 94020c46..7a0cdffe 100644 --- a/spec/parameters/query/pageSizeQuery.yml +++ b/spec/parameters/query/pageSizeQuery.yml @@ -1,6 +1,8 @@ name: pageSize in: query -description: Select the number of entries to return. +description: | + Select the number of entries to return per page. + Values outside the allowed range are clamped to the schema minimum or maximum. schema: type: integer minimum: 10 diff --git a/spec/parameters/query/recipientAddressQuery.yml b/spec/parameters/query/recipientAddressQuery.yml index 686fde0c..19fc6ada 100644 --- a/spec/parameters/query/recipientAddressQuery.yml +++ b/spec/parameters/query/recipientAddressQuery.yml @@ -1,5 +1,5 @@ name: recipientAddress in: query -description: Filter by recipient address in Base32. +description: Filter transactions by recipient address in Base32 format. schema: $ref: "../../schemas/Address.yml" diff --git a/spec/parameters/query/signerPublicKeyQuery.yml b/spec/parameters/query/signerPublicKeyQuery.yml index 4fd01762..3f74813c 100644 --- a/spec/parameters/query/signerPublicKeyQuery.yml +++ b/spec/parameters/query/signerPublicKeyQuery.yml @@ -1,5 +1,5 @@ name: signerPublicKey in: query -description: Filter by public key of the account signing the entity. +description: Filter transactions by the public key of the signing account. schema: $ref: "../../schemas/PublicKey.yml" diff --git a/spec/parameters/query/toHeightQuery.yml b/spec/parameters/query/toHeightQuery.yml index b51bec25..23166b72 100644 --- a/spec/parameters/query/toHeightQuery.yml +++ b/spec/parameters/query/toHeightQuery.yml @@ -1,5 +1,5 @@ name: toHeight in: query -description: Only blocks with height smaller or equal than this one are returned. +description: Only transactions at or below this block height are returned. schema: $ref: "../../schemas/Height.yml" diff --git a/spec/parameters/query/toTransferAmountQuery.yml b/spec/parameters/query/toTransferAmountQuery.yml index 9ce6411c..1daf75e9 100644 --- a/spec/parameters/query/toTransferAmountQuery.yml +++ b/spec/parameters/query/toTransferAmountQuery.yml @@ -2,6 +2,6 @@ name: toTransferAmount in: query description: | Requires providing the `transferMosaicId` filter. - Only transfer transactions with a transfer amount of the provided mosaic ID, lesser or equal than this amount are returned. + Only transfer transactions with an amount less than or equal to this value for the specified mosaic ID are returned. schema: $ref: "../../schemas/Amount.yml" diff --git a/spec/parameters/query/transactionTypesQuery.yml b/spec/parameters/query/transactionTypesQuery.yml index 73b51220..85f324e9 100644 --- a/spec/parameters/query/transactionTypesQuery.yml +++ b/spec/parameters/query/transactionTypesQuery.yml @@ -7,5 +7,6 @@ style: form explode: true schema: type: array + description: Array of transaction type identifiers to match. items: $ref: "../../core/transaction/schemas/TransactionTypeEnum.yml" diff --git a/spec/parameters/query/transferMosaicIdQuery.yml b/spec/parameters/query/transferMosaicIdQuery.yml index 2bc1e5c9..90f3b1bb 100644 --- a/spec/parameters/query/transferMosaicIdQuery.yml +++ b/spec/parameters/query/transferMosaicIdQuery.yml @@ -1,5 +1,5 @@ name: transferMosaicId in: query -description: Filters transactions involving a specific ``mosaicId``. +description: Filter transfer transactions by the mosaic ID carried in the transfer. schema: $ref: "../../schemas/MosaicId.yml" diff --git a/spec/plugins/account_link/schemas/AccountKeyLinkTransactionBodyDTO.yml b/spec/plugins/account_link/schemas/AccountKeyLinkTransactionBodyDTO.yml index 68b22b55..8ede10b9 100644 --- a/spec/plugins/account_link/schemas/AccountKeyLinkTransactionBodyDTO.yml +++ b/spec/plugins/account_link/schemas/AccountKeyLinkTransactionBodyDTO.yml @@ -1,4 +1,5 @@ type: object +description: Account key link transaction body that links or unlinks a remote account public key. required: - linkedPublicKey - linkAction diff --git a/spec/plugins/account_link/schemas/EmbeddedAccountKeyLinkTransactionDTO.yml b/spec/plugins/account_link/schemas/EmbeddedAccountKeyLinkTransactionDTO.yml index e65e6973..06373c8c 100644 --- a/spec/plugins/account_link/schemas/EmbeddedAccountKeyLinkTransactionDTO.yml +++ b/spec/plugins/account_link/schemas/EmbeddedAccountKeyLinkTransactionDTO.yml @@ -1,4 +1,5 @@ type: object +description: Embedded transaction variant of ``AccountKeyLinkTransactionDTO``. allOf: - $ref: "../../../core/transaction/schemas/EmbeddedTransactionDTO.yml" - $ref: "./AccountKeyLinkTransactionBodyDTO.yml" diff --git a/spec/plugins/account_link/schemas/EmbeddedNodeKeyLinkTransactionDTO.yml b/spec/plugins/account_link/schemas/EmbeddedNodeKeyLinkTransactionDTO.yml index 81efc1d5..47cd0102 100644 --- a/spec/plugins/account_link/schemas/EmbeddedNodeKeyLinkTransactionDTO.yml +++ b/spec/plugins/account_link/schemas/EmbeddedNodeKeyLinkTransactionDTO.yml @@ -1,4 +1,5 @@ type: object +description: Embedded transaction variant of ``NodeKeyLinkTransactionDTO``. allOf: - $ref: "../../../core/transaction/schemas/EmbeddedTransactionDTO.yml" - $ref: "./NodeKeyLinkTransactionBodyDTO.yml" diff --git a/spec/plugins/account_link/schemas/NodeKeyLinkTransactionBodyDTO.yml b/spec/plugins/account_link/schemas/NodeKeyLinkTransactionBodyDTO.yml index 68b22b55..16926d68 100644 --- a/spec/plugins/account_link/schemas/NodeKeyLinkTransactionBodyDTO.yml +++ b/spec/plugins/account_link/schemas/NodeKeyLinkTransactionBodyDTO.yml @@ -1,4 +1,5 @@ type: object +description: Node key link transaction body that links or unlinks a remote node public key. required: - linkedPublicKey - linkAction diff --git a/spec/plugins/aggregate/routes/announceCosignatureTransaction.yml b/spec/plugins/aggregate/routes/announceCosignatureTransaction.yml index 4d937b56..40976a59 100644 --- a/spec/plugins/aggregate/routes/announceCosignatureTransaction.yml +++ b/spec/plugins/aggregate/routes/announceCosignatureTransaction.yml @@ -1,17 +1,30 @@ tags: - Transaction routes summary: Announce a cosignature transaction -description: Announces a cosignature transaction to the network. +description: | + Broadcasts a detached cosignature for an aggregate bonded transaction to the network through this node. + + The request must contain the detached cosignature fields: cosignature version, signer public key, + cosignature signature, and the parent aggregate transaction hash. + + To verify the effect of the cosignature, query the **parent aggregate bonded transaction**, + for example with [`GET /transactionStatus/{hash}`](/transactionStatus/{hash}) using the + parent aggregate transaction hash. operationId: announceCosignatureTransaction requestBody: $ref: "../../../request_bodies/cosignature.yml" responses: "202": - description: success + description: Detached cosignature accepted for processing and broadcast by the node. content: application/json: schema: $ref: "../../../core/transaction/schemas/AnnounceTransactionInfoDTO.yml" + examples: + success: + summary: Cosignature packet pushed to the node + value: + message: "packet 257 was pushed to the network via /transactions/cosignature" "400": $ref: "../../../responses/InvalidContent.yml" "409": diff --git a/spec/plugins/aggregate/routes/announcePartialTransaction.yml b/spec/plugins/aggregate/routes/announcePartialTransaction.yml index f57fad91..333f858f 100644 --- a/spec/plugins/aggregate/routes/announcePartialTransaction.yml +++ b/spec/plugins/aggregate/routes/announcePartialTransaction.yml @@ -1,17 +1,31 @@ tags: - Transaction routes summary: Announce an aggregate bonded transaction -description: Announces an aggregate bonded transaction to the network. +description: | + Broadcasts a signed aggregate bonded transaction to the network through this node. + + The request must contain the serialized aggregate bonded transaction payload in hexadecimal form. + Transactions are normally created and signed client-side with a [Symbol SDK](https://docs.symbol.dev/sdk.html) + and then announced with this endpoint. + + To verify the final result, query ``GET /transactionStatus/{hash}`` on the same node that received + the announce request. If that node drops the transaction before propagation, other nodes may not + know the transaction at all and can return ``404`` for the same hash. operationId: announcePartialTransaction requestBody: $ref: "../../../request_bodies/transactionPayload.yml" responses: "202": - description: success + description: Aggregate bonded transaction accepted for processing and broadcast by the node. content: application/json: schema: $ref: "../../../core/transaction/schemas/AnnounceTransactionInfoDTO.yml" + examples: + success: + summary: Partial transaction packet pushed to the node + value: + message: "packet 256 was pushed to the network via /transactions/partial" "400": $ref: "../../../responses/InvalidContent.yml" "409": diff --git a/spec/plugins/aggregate/schemas/AggregateTransactionBodyDTO.yml b/spec/plugins/aggregate/schemas/AggregateTransactionBodyDTO.yml index f76226b3..cdb3e112 100644 --- a/spec/plugins/aggregate/schemas/AggregateTransactionBodyDTO.yml +++ b/spec/plugins/aggregate/schemas/AggregateTransactionBodyDTO.yml @@ -1,4 +1,7 @@ type: object +description: | + Aggregate transaction body with the hash of embedded transactions and the cosignatures attached to + the aggregate transaction. required: - transactionsHash - cosignatures diff --git a/spec/plugins/aggregate/schemas/AggregateTransactionBodyExtendedDTO.yml b/spec/plugins/aggregate/schemas/AggregateTransactionBodyExtendedDTO.yml index 571c8803..28ee1f5a 100644 --- a/spec/plugins/aggregate/schemas/AggregateTransactionBodyExtendedDTO.yml +++ b/spec/plugins/aggregate/schemas/AggregateTransactionBodyExtendedDTO.yml @@ -1,4 +1,7 @@ type: object +description: | + Extended aggregate transaction body that, in addition to aggregate-level fields, also includes the + embedded transactions contained in the aggregate. allOf: - $ref: "./AggregateTransactionBodyDTO.yml" - $ref: "../../../core/transaction/schemas/EmbeddedTransactionBodyDTO.yml" diff --git a/spec/plugins/coresystem/schemas/EmbeddedVotingKeyLinkTransactionDTO.yml b/spec/plugins/coresystem/schemas/EmbeddedVotingKeyLinkTransactionDTO.yml index 6e69aa4c..db0f6452 100644 --- a/spec/plugins/coresystem/schemas/EmbeddedVotingKeyLinkTransactionDTO.yml +++ b/spec/plugins/coresystem/schemas/EmbeddedVotingKeyLinkTransactionDTO.yml @@ -1,4 +1,5 @@ type: object +description: Embedded transaction variant of ``VotingKeyLinkTransactionDTO``. allOf: - $ref: "../../../core/transaction/schemas/EmbeddedTransactionDTO.yml" - $ref: "./VotingKeyLinkTransactionBodyDTO.yml" diff --git a/spec/plugins/coresystem/schemas/EmbeddedVrfKeyLinkTransactionDTO.yml b/spec/plugins/coresystem/schemas/EmbeddedVrfKeyLinkTransactionDTO.yml index 2b2639ce..9424c350 100644 --- a/spec/plugins/coresystem/schemas/EmbeddedVrfKeyLinkTransactionDTO.yml +++ b/spec/plugins/coresystem/schemas/EmbeddedVrfKeyLinkTransactionDTO.yml @@ -1,4 +1,5 @@ type: object +description: Embedded transaction variant of ``VrfKeyLinkTransactionDTO``. allOf: - $ref: "../../../core/transaction/schemas/EmbeddedTransactionDTO.yml" - $ref: "./VrfKeyLinkTransactionBodyDTO.yml" diff --git a/spec/plugins/coresystem/schemas/VotingKeyLinkTransactionBodyDTO.yml b/spec/plugins/coresystem/schemas/VotingKeyLinkTransactionBodyDTO.yml index a7b27abd..170568cd 100644 --- a/spec/plugins/coresystem/schemas/VotingKeyLinkTransactionBodyDTO.yml +++ b/spec/plugins/coresystem/schemas/VotingKeyLinkTransactionBodyDTO.yml @@ -1,4 +1,5 @@ type: object +description: Voting key link transaction body that links or unlinks a voting key for a finalization epoch range. required: - linkedPublicKey - startEpoch diff --git a/spec/plugins/coresystem/schemas/VrfKeyLinkTransactionBodyDTO.yml b/spec/plugins/coresystem/schemas/VrfKeyLinkTransactionBodyDTO.yml index 68b22b55..55aa0279 100644 --- a/spec/plugins/coresystem/schemas/VrfKeyLinkTransactionBodyDTO.yml +++ b/spec/plugins/coresystem/schemas/VrfKeyLinkTransactionBodyDTO.yml @@ -1,4 +1,5 @@ type: object +description: VRF key link transaction body that links or unlinks a VRF public key. required: - linkedPublicKey - linkAction diff --git a/spec/plugins/lock_hash/schemas/EmbeddedHashLockTransactionDTO.yml b/spec/plugins/lock_hash/schemas/EmbeddedHashLockTransactionDTO.yml index d5be9ce1..67d3315c 100644 --- a/spec/plugins/lock_hash/schemas/EmbeddedHashLockTransactionDTO.yml +++ b/spec/plugins/lock_hash/schemas/EmbeddedHashLockTransactionDTO.yml @@ -1,4 +1,5 @@ type: object +description: Embedded transaction variant of ``HashLockTransactionDTO``. allOf: - $ref: "../../../core/transaction/schemas/EmbeddedTransactionDTO.yml" - $ref: "./HashLockTransactionBodyDTO.yml" diff --git a/spec/plugins/lock_hash/schemas/HashLockTransactionBodyDTO.yml b/spec/plugins/lock_hash/schemas/HashLockTransactionBodyDTO.yml index e71e254c..b29a594c 100644 --- a/spec/plugins/lock_hash/schemas/HashLockTransactionBodyDTO.yml +++ b/spec/plugins/lock_hash/schemas/HashLockTransactionBodyDTO.yml @@ -1,4 +1,5 @@ type: object +description: Hash lock transaction body that locks mosaics as a prerequisite for announcing an aggregate bonded transaction. required: - mosaicId - amount diff --git a/spec/plugins/lock_secret/schemas/EmbeddedSecretLockTransactionDTO.yml b/spec/plugins/lock_secret/schemas/EmbeddedSecretLockTransactionDTO.yml index 7e17e25e..45d1f673 100644 --- a/spec/plugins/lock_secret/schemas/EmbeddedSecretLockTransactionDTO.yml +++ b/spec/plugins/lock_secret/schemas/EmbeddedSecretLockTransactionDTO.yml @@ -1,4 +1,5 @@ type: object +description: Embedded transaction variant of ``SecretLockTransactionDTO``. allOf: - $ref: "../../../core/transaction/schemas/EmbeddedTransactionDTO.yml" - $ref: "./SecretLockTransactionBodyDTO.yml" diff --git a/spec/plugins/lock_secret/schemas/EmbeddedSecretProofTransactionDTO.yml b/spec/plugins/lock_secret/schemas/EmbeddedSecretProofTransactionDTO.yml index 24a9ece0..87a66f6f 100644 --- a/spec/plugins/lock_secret/schemas/EmbeddedSecretProofTransactionDTO.yml +++ b/spec/plugins/lock_secret/schemas/EmbeddedSecretProofTransactionDTO.yml @@ -1,4 +1,5 @@ type: object +description: Embedded transaction variant of ``SecretProofTransactionDTO``. allOf: - $ref: "../../../core/transaction/schemas/EmbeddedTransactionDTO.yml" - $ref: "./SecretProofTransactionBodyDTO.yml" diff --git a/spec/plugins/lock_secret/schemas/SecretLockTransactionBodyDTO.yml b/spec/plugins/lock_secret/schemas/SecretLockTransactionBodyDTO.yml index d49d98d5..e727cf93 100644 --- a/spec/plugins/lock_secret/schemas/SecretLockTransactionBodyDTO.yml +++ b/spec/plugins/lock_secret/schemas/SecretLockTransactionBodyDTO.yml @@ -1,4 +1,5 @@ type: object +description: Secret lock transaction body that locks a mosaic for a recipient until the secret proof is revealed. required: - recipientAddress - secret diff --git a/spec/plugins/lock_secret/schemas/SecretProofTransactionBodyDTO.yml b/spec/plugins/lock_secret/schemas/SecretProofTransactionBodyDTO.yml index 5a2603ec..63f5ca7f 100644 --- a/spec/plugins/lock_secret/schemas/SecretProofTransactionBodyDTO.yml +++ b/spec/plugins/lock_secret/schemas/SecretProofTransactionBodyDTO.yml @@ -1,4 +1,5 @@ type: object +description: Secret proof transaction body that reveals the proof needed to complete a secret lock. required: - recipientAddress - secret @@ -13,5 +14,5 @@ properties: $ref: "./LockHashAlgorithmEnum.yml" proof: type: string - description: Original random set of bytes. + description: Proof data whose hash, using ``hashAlgorithm``, must match ``secret``. diff --git a/spec/plugins/metadata/schemas/AccountMetadataTransactionBodyDTO.yml b/spec/plugins/metadata/schemas/AccountMetadataTransactionBodyDTO.yml index 7a4934b1..bbb97e10 100644 --- a/spec/plugins/metadata/schemas/AccountMetadataTransactionBodyDTO.yml +++ b/spec/plugins/metadata/schemas/AccountMetadataTransactionBodyDTO.yml @@ -1,4 +1,7 @@ type: object +description: | + Account metadata transaction body with the target account, metadata key, and metadata value + update. required: - targetAddress - scopedMetadataKey @@ -11,10 +14,8 @@ properties: scopedMetadataKey: $ref: "../../../schemas/MetadataKey.yml" valueSizeDelta: - type: integer - description: Change in value size in bytes. + $ref: "../../../schemas/MetadataValueSizeDelta.yml" valueSize: - $ref: "../../../schemas/UInt32.yml" - description: Value size in bytes. + $ref: "../../../schemas/MetadataValueSize.yml" value: $ref: "../../../schemas/MetadataValue.yml" diff --git a/spec/plugins/metadata/schemas/AccountMetadataTransactionDTO.yml b/spec/plugins/metadata/schemas/AccountMetadataTransactionDTO.yml index 2782f658..cb39df34 100644 --- a/spec/plugins/metadata/schemas/AccountMetadataTransactionDTO.yml +++ b/spec/plugins/metadata/schemas/AccountMetadataTransactionDTO.yml @@ -1,5 +1,5 @@ type: object -description: Transaction to create or modify a multisig account. +description: Transaction to create or modify metadata attached to an account. allOf: - $ref: "../../../core/transaction/schemas/TransactionDTO.yml" - $ref: "./AccountMetadataTransactionBodyDTO.yml" diff --git a/spec/plugins/metadata/schemas/EmbeddedAccountMetadataTransactionDTO.yml b/spec/plugins/metadata/schemas/EmbeddedAccountMetadataTransactionDTO.yml index e574ed1c..9def2460 100644 --- a/spec/plugins/metadata/schemas/EmbeddedAccountMetadataTransactionDTO.yml +++ b/spec/plugins/metadata/schemas/EmbeddedAccountMetadataTransactionDTO.yml @@ -1,4 +1,5 @@ type: object +description: Embedded transaction variant of ``AccountMetadataTransactionDTO``. allOf: - $ref: "../../../core/transaction/schemas/EmbeddedTransactionDTO.yml" - $ref: "./AccountMetadataTransactionBodyDTO.yml" diff --git a/spec/plugins/metadata/schemas/EmbeddedMosaicMetadataTransactionDTO.yml b/spec/plugins/metadata/schemas/EmbeddedMosaicMetadataTransactionDTO.yml index c44ca5c3..d4ff3965 100644 --- a/spec/plugins/metadata/schemas/EmbeddedMosaicMetadataTransactionDTO.yml +++ b/spec/plugins/metadata/schemas/EmbeddedMosaicMetadataTransactionDTO.yml @@ -1,4 +1,5 @@ type: object +description: Embedded transaction variant of ``MosaicMetadataTransactionDTO``. allOf: - $ref: "../../../core/transaction/schemas/EmbeddedTransactionDTO.yml" - $ref: "./MosaicMetadataTransactionBodyDTO.yml" diff --git a/spec/plugins/metadata/schemas/EmbeddedNamespaceMetadataTransactionDTO.yml b/spec/plugins/metadata/schemas/EmbeddedNamespaceMetadataTransactionDTO.yml index e0ab4e38..506b35e5 100644 --- a/spec/plugins/metadata/schemas/EmbeddedNamespaceMetadataTransactionDTO.yml +++ b/spec/plugins/metadata/schemas/EmbeddedNamespaceMetadataTransactionDTO.yml @@ -1,4 +1,5 @@ type: object +description: Embedded transaction variant of ``NamespaceMetadataTransactionDTO``. allOf: - $ref: "../../../core/transaction/schemas/EmbeddedTransactionDTO.yml" - $ref: "./NamespaceMetadataTransactionBodyDTO.yml" diff --git a/spec/plugins/metadata/schemas/MetadataEntryDTO.yml b/spec/plugins/metadata/schemas/MetadataEntryDTO.yml index ffcfbfab..9e92f364 100644 --- a/spec/plugins/metadata/schemas/MetadataEntryDTO.yml +++ b/spec/plugins/metadata/schemas/MetadataEntryDTO.yml @@ -35,9 +35,6 @@ properties: metadataType: $ref: "./MetadataTypeEnum.yml" valueSize: - type: integer - description: Size of the metadata value in bytes. - examples: - - 6 + $ref: "../../../schemas/MetadataValueSize.yml" value: $ref: "../../../schemas/MetadataValue.yml" diff --git a/spec/plugins/metadata/schemas/MosaicMetadataTransactionBodyDTO.yml b/spec/plugins/metadata/schemas/MosaicMetadataTransactionBodyDTO.yml index ebcd599b..1d0a9283 100644 --- a/spec/plugins/metadata/schemas/MosaicMetadataTransactionBodyDTO.yml +++ b/spec/plugins/metadata/schemas/MosaicMetadataTransactionBodyDTO.yml @@ -1,4 +1,7 @@ type: object +description: | + Mosaic metadata transaction body with the target mosaic, metadata key, and metadata value + update. required: - targetAddress - scopedMetadataKey @@ -14,10 +17,8 @@ properties: targetMosaicId: $ref: "../../../schemas/UnresolvedMosaicId.yml" valueSizeDelta: - type: integer - description: Change in value size in bytes. + $ref: "../../../schemas/MetadataValueSizeDelta.yml" valueSize: - $ref: "../../../schemas/UInt32.yml" - description: Value size in bytes. + $ref: "../../../schemas/MetadataValueSize.yml" value: $ref: "../../../schemas/MetadataValue.yml" diff --git a/spec/plugins/metadata/schemas/MosaicMetadataTransactionDTO.yml b/spec/plugins/metadata/schemas/MosaicMetadataTransactionDTO.yml index 13b0eedd..e2ca4c77 100644 --- a/spec/plugins/metadata/schemas/MosaicMetadataTransactionDTO.yml +++ b/spec/plugins/metadata/schemas/MosaicMetadataTransactionDTO.yml @@ -1,5 +1,5 @@ type: object -description: Transaction to create or modify a multisig account. +description: Transaction to create or modify metadata attached to a mosaic. allOf: - $ref: "../../../core/transaction/schemas/TransactionDTO.yml" - $ref: "./MosaicMetadataTransactionBodyDTO.yml" diff --git a/spec/plugins/metadata/schemas/NamespaceMetadataTransactionBodyDTO.yml b/spec/plugins/metadata/schemas/NamespaceMetadataTransactionBodyDTO.yml index 8919d997..3d62481f 100644 --- a/spec/plugins/metadata/schemas/NamespaceMetadataTransactionBodyDTO.yml +++ b/spec/plugins/metadata/schemas/NamespaceMetadataTransactionBodyDTO.yml @@ -1,8 +1,11 @@ type: object +description: | + Namespace metadata transaction body with the target namespace, metadata key, and metadata value + update. required: - targetAddress - scopedMetadataKey - - targetMosaicId + - targetNamespaceId - valueSizeDelta - valueSize - value @@ -14,10 +17,8 @@ properties: targetNamespaceId: $ref: "../../../schemas/NamespaceId.yml" valueSizeDelta: - type: integer - description: Change in value size in bytes. + $ref: "../../../schemas/MetadataValueSizeDelta.yml" valueSize: - $ref: "../../../schemas/UInt32.yml" - description: Value size in bytes. + $ref: "../../../schemas/MetadataValueSize.yml" value: $ref: "../../../schemas/MetadataValue.yml" diff --git a/spec/plugins/metadata/schemas/NamespaceMetadataTransactionDTO.yml b/spec/plugins/metadata/schemas/NamespaceMetadataTransactionDTO.yml index 7e8eb60f..7fe754d2 100644 --- a/spec/plugins/metadata/schemas/NamespaceMetadataTransactionDTO.yml +++ b/spec/plugins/metadata/schemas/NamespaceMetadataTransactionDTO.yml @@ -1,5 +1,5 @@ type: object -description: Transaction to create or modify a multisig account. +description: Transaction to create or modify metadata attached to a namespace. allOf: - $ref: "../../../core/transaction/schemas/TransactionDTO.yml" - $ref: "./NamespaceMetadataTransactionBodyDTO.yml" diff --git a/spec/plugins/mosaic/schemas/EmbeddedMosaicDefinitionTransactionDTO.yml b/spec/plugins/mosaic/schemas/EmbeddedMosaicDefinitionTransactionDTO.yml index 67bf0525..fb249707 100644 --- a/spec/plugins/mosaic/schemas/EmbeddedMosaicDefinitionTransactionDTO.yml +++ b/spec/plugins/mosaic/schemas/EmbeddedMosaicDefinitionTransactionDTO.yml @@ -1,4 +1,5 @@ type: object +description: Embedded transaction variant of ``MosaicDefinitionTransactionDTO``. allOf: - $ref: "../../../core/transaction/schemas/EmbeddedTransactionDTO.yml" - $ref: "./MosaicDefinitionTransactionBodyDTO.yml" diff --git a/spec/plugins/mosaic/schemas/EmbeddedMosaicSupplyChangeTransactionDTO.yml b/spec/plugins/mosaic/schemas/EmbeddedMosaicSupplyChangeTransactionDTO.yml index 651fe5d0..a29fa2dd 100644 --- a/spec/plugins/mosaic/schemas/EmbeddedMosaicSupplyChangeTransactionDTO.yml +++ b/spec/plugins/mosaic/schemas/EmbeddedMosaicSupplyChangeTransactionDTO.yml @@ -1,4 +1,5 @@ type: object +description: Embedded transaction variant of ``MosaicSupplyChangeTransactionDTO``. allOf: - $ref: "../../../core/transaction/schemas/EmbeddedTransactionDTO.yml" - $ref: "./MosaicSupplyChangeTransactionBodyDTO.yml" diff --git a/spec/plugins/mosaic/schemas/EmbeddedMosaicSupplyRevocationTransactionDTO.yml b/spec/plugins/mosaic/schemas/EmbeddedMosaicSupplyRevocationTransactionDTO.yml index 73931d74..dc3724db 100644 --- a/spec/plugins/mosaic/schemas/EmbeddedMosaicSupplyRevocationTransactionDTO.yml +++ b/spec/plugins/mosaic/schemas/EmbeddedMosaicSupplyRevocationTransactionDTO.yml @@ -1,4 +1,5 @@ type: object +description: Embedded transaction variant of ``MosaicSupplyRevocationTransactionDTO``. allOf: - $ref: "../../../core/transaction/schemas/EmbeddedTransactionDTO.yml" - $ref: "./MosaicSupplyRevocationTransactionBodyDTO.yml" diff --git a/spec/plugins/mosaic/schemas/MosaicDefinitionTransactionBodyDTO.yml b/spec/plugins/mosaic/schemas/MosaicDefinitionTransactionBodyDTO.yml index d2fda256..535820cc 100644 --- a/spec/plugins/mosaic/schemas/MosaicDefinitionTransactionBodyDTO.yml +++ b/spec/plugins/mosaic/schemas/MosaicDefinitionTransactionBodyDTO.yml @@ -1,4 +1,5 @@ type: object +description: Mosaic definition transaction body with the mosaic ID inputs and immutable configuration values. required: - id - duration @@ -13,7 +14,8 @@ properties: nonce: $ref: "../../../schemas/UInt32.yml" description: Random nonce used to generate the mosaic ID. - example: 0 + examples: + - 0 flags: $ref: "./MosaicFlagsEnum.yml" divisibility: diff --git a/spec/plugins/mosaic/schemas/MosaicSupplyChangeActionEnum.yml b/spec/plugins/mosaic/schemas/MosaicSupplyChangeActionEnum.yml index 9acbabc3..f990b69f 100644 --- a/spec/plugins/mosaic/schemas/MosaicSupplyChangeActionEnum.yml +++ b/spec/plugins/mosaic/schemas/MosaicSupplyChangeActionEnum.yml @@ -3,7 +3,8 @@ enum: - 0 - 1 description: | - Direction of the supply change: - * 0 - Decrease. - * 1 - Increase. -example: 0 + Mosaic supply change action: + - `0`: Decrease the mosaic supply. + - `1`: Increase the mosaic supply. +examples: + - 0 diff --git a/spec/plugins/mosaic/schemas/MosaicSupplyChangeTransactionBodyDTO.yml b/spec/plugins/mosaic/schemas/MosaicSupplyChangeTransactionBodyDTO.yml index 2975d4aa..a249651c 100644 --- a/spec/plugins/mosaic/schemas/MosaicSupplyChangeTransactionBodyDTO.yml +++ b/spec/plugins/mosaic/schemas/MosaicSupplyChangeTransactionBodyDTO.yml @@ -1,4 +1,5 @@ type: object +description: Mosaic supply change transaction body with the target mosaic, supply delta, and direction. required: - mosaicId - delta diff --git a/spec/plugins/mosaic/schemas/MosaicSupplyRevocationTransactionBodyDTO.yml b/spec/plugins/mosaic/schemas/MosaicSupplyRevocationTransactionBodyDTO.yml index 34034b25..e77c592e 100644 --- a/spec/plugins/mosaic/schemas/MosaicSupplyRevocationTransactionBodyDTO.yml +++ b/spec/plugins/mosaic/schemas/MosaicSupplyRevocationTransactionBodyDTO.yml @@ -1,4 +1,5 @@ type: object +description: Mosaic supply revocation transaction body with the source account, mosaic, and revoked amount. required: - sourceAddress - mosaicId diff --git a/spec/plugins/multisig/schemas/EmbeddedMultisigAccountModificationTransactionDTO.yml b/spec/plugins/multisig/schemas/EmbeddedMultisigAccountModificationTransactionDTO.yml index 182ae2ca..b215efc5 100644 --- a/spec/plugins/multisig/schemas/EmbeddedMultisigAccountModificationTransactionDTO.yml +++ b/spec/plugins/multisig/schemas/EmbeddedMultisigAccountModificationTransactionDTO.yml @@ -1,4 +1,5 @@ type: object +description: Embedded transaction variant of ``MultisigAccountModificationTransactionDTO``. allOf: - $ref: "../../../core/transaction/schemas/EmbeddedTransactionDTO.yml" - $ref: "./MultisigAccountModificationTransactionBodyDTO.yml" diff --git a/spec/plugins/multisig/schemas/MultisigAccountModificationTransactionBodyDTO.yml b/spec/plugins/multisig/schemas/MultisigAccountModificationTransactionBodyDTO.yml index 64bec45c..f1dfc00d 100644 --- a/spec/plugins/multisig/schemas/MultisigAccountModificationTransactionBodyDTO.yml +++ b/spec/plugins/multisig/schemas/MultisigAccountModificationTransactionBodyDTO.yml @@ -1,5 +1,5 @@ type: object -description: Fields specific to a multisig account modification transaction. +description: Multisig account modification transaction body with threshold deltas and cosignatory changes. required: - minRemovalDelta - minApprovalDelta diff --git a/spec/plugins/namespace/schemas/AddressAliasTransactionBodyDTO.yml b/spec/plugins/namespace/schemas/AddressAliasTransactionBodyDTO.yml index 7866dc23..36257729 100644 --- a/spec/plugins/namespace/schemas/AddressAliasTransactionBodyDTO.yml +++ b/spec/plugins/namespace/schemas/AddressAliasTransactionBodyDTO.yml @@ -1,4 +1,5 @@ type: object +description: Address alias transaction body that links or unlinks a namespace to an address. required: - namespaceId - address diff --git a/spec/plugins/namespace/schemas/AliasActionEnum.yml b/spec/plugins/namespace/schemas/AliasActionEnum.yml index dac06520..c74bc294 100644 --- a/spec/plugins/namespace/schemas/AliasActionEnum.yml +++ b/spec/plugins/namespace/schemas/AliasActionEnum.yml @@ -3,7 +3,8 @@ enum: - 0 - 1 description: | - Alias action: - * 0 - Unlink alias. - * 1 - Link alias. -example: 0 + Alias link action: + - `0`: Unlink the namespace from the current address or mosaic. + - `1`: Link the namespace to the specified address or mosaic. +examples: + - 0 diff --git a/spec/plugins/namespace/schemas/EmbeddedAddressAliasTransactionDTO.yml b/spec/plugins/namespace/schemas/EmbeddedAddressAliasTransactionDTO.yml index dd268cd6..89cff79b 100644 --- a/spec/plugins/namespace/schemas/EmbeddedAddressAliasTransactionDTO.yml +++ b/spec/plugins/namespace/schemas/EmbeddedAddressAliasTransactionDTO.yml @@ -1,4 +1,5 @@ type: object +description: Embedded transaction variant of ``AddressAliasTransactionDTO``. allOf: - $ref: "../../../core/transaction/schemas/EmbeddedTransactionDTO.yml" - $ref: "./AddressAliasTransactionBodyDTO.yml" diff --git a/spec/plugins/namespace/schemas/EmbeddedMosaicAliasTransactionDTO.yml b/spec/plugins/namespace/schemas/EmbeddedMosaicAliasTransactionDTO.yml index ff96c5d2..1a6409ba 100644 --- a/spec/plugins/namespace/schemas/EmbeddedMosaicAliasTransactionDTO.yml +++ b/spec/plugins/namespace/schemas/EmbeddedMosaicAliasTransactionDTO.yml @@ -1,4 +1,5 @@ type: object +description: Embedded transaction variant of ``MosaicAliasTransactionDTO``. allOf: - $ref: "../../../core/transaction/schemas/EmbeddedTransactionDTO.yml" - $ref: "./MosaicAliasTransactionBodyDTO.yml" diff --git a/spec/plugins/namespace/schemas/EmbeddedNamespaceRegistrationTransactionDTO.yml b/spec/plugins/namespace/schemas/EmbeddedNamespaceRegistrationTransactionDTO.yml index df97a548..2e967571 100644 --- a/spec/plugins/namespace/schemas/EmbeddedNamespaceRegistrationTransactionDTO.yml +++ b/spec/plugins/namespace/schemas/EmbeddedNamespaceRegistrationTransactionDTO.yml @@ -1,4 +1,5 @@ type: object +description: Embedded transaction variant of ``NamespaceRegistrationTransactionDTO``. allOf: - $ref: "../../../core/transaction/schemas/EmbeddedTransactionDTO.yml" - $ref: "./NamespaceRegistrationTransactionBodyDTO.yml" diff --git a/spec/plugins/namespace/schemas/MosaicAliasTransactionBodyDTO.yml b/spec/plugins/namespace/schemas/MosaicAliasTransactionBodyDTO.yml index baa22d61..7fe26dd7 100644 --- a/spec/plugins/namespace/schemas/MosaicAliasTransactionBodyDTO.yml +++ b/spec/plugins/namespace/schemas/MosaicAliasTransactionBodyDTO.yml @@ -1,4 +1,5 @@ type: object +description: Mosaic alias transaction body that links or unlinks a namespace to a mosaic. required: - namespaceId - mosaicId diff --git a/spec/plugins/namespace/schemas/NamespaceRegistrationTransactionBodyDTO.yml b/spec/plugins/namespace/schemas/NamespaceRegistrationTransactionBodyDTO.yml index 34b85b16..29ceb8c0 100644 --- a/spec/plugins/namespace/schemas/NamespaceRegistrationTransactionBodyDTO.yml +++ b/spec/plugins/namespace/schemas/NamespaceRegistrationTransactionBodyDTO.yml @@ -1,4 +1,5 @@ type: object +description: Namespace registration transaction body for creating a root namespace or a child namespace. required: - id - registrationType diff --git a/spec/plugins/restriction_account/schemas/AccountAddressRestrictionTransactionBodyDTO.yml b/spec/plugins/restriction_account/schemas/AccountAddressRestrictionTransactionBodyDTO.yml index 7edec054..7bf334e5 100644 --- a/spec/plugins/restriction_account/schemas/AccountAddressRestrictionTransactionBodyDTO.yml +++ b/spec/plugins/restriction_account/schemas/AccountAddressRestrictionTransactionBodyDTO.yml @@ -1,4 +1,5 @@ type: object +description: Account address restriction transaction body that updates the allowed or blocked address list. required: - restrictionFlags - restrictionAdditions diff --git a/spec/plugins/restriction_account/schemas/AccountMosaicRestrictionTransactionBodyDTO.yml b/spec/plugins/restriction_account/schemas/AccountMosaicRestrictionTransactionBodyDTO.yml index d5d34091..cd29f0cf 100644 --- a/spec/plugins/restriction_account/schemas/AccountMosaicRestrictionTransactionBodyDTO.yml +++ b/spec/plugins/restriction_account/schemas/AccountMosaicRestrictionTransactionBodyDTO.yml @@ -1,4 +1,5 @@ type: object +description: Account mosaic restriction transaction body that updates the allowed or blocked mosaic ID list. required: - restrictionFlags - restrictionAdditions diff --git a/spec/plugins/restriction_account/schemas/AccountOperationRestrictionTransactionBodyDTO.yml b/spec/plugins/restriction_account/schemas/AccountOperationRestrictionTransactionBodyDTO.yml index 09f41d53..7d91744f 100644 --- a/spec/plugins/restriction_account/schemas/AccountOperationRestrictionTransactionBodyDTO.yml +++ b/spec/plugins/restriction_account/schemas/AccountOperationRestrictionTransactionBodyDTO.yml @@ -1,4 +1,5 @@ type: object +description: Account operation restriction transaction body that updates the allowed or blocked transaction type list. required: - restrictionFlags - restrictionAdditions diff --git a/spec/plugins/restriction_account/schemas/EmbeddedAccountAddressRestrictionTransactionDTO.yml b/spec/plugins/restriction_account/schemas/EmbeddedAccountAddressRestrictionTransactionDTO.yml index d44c4aa8..2373b2e5 100644 --- a/spec/plugins/restriction_account/schemas/EmbeddedAccountAddressRestrictionTransactionDTO.yml +++ b/spec/plugins/restriction_account/schemas/EmbeddedAccountAddressRestrictionTransactionDTO.yml @@ -1,4 +1,5 @@ type: object +description: Embedded transaction variant of ``AccountAddressRestrictionTransactionDTO``. allOf: - $ref: "../../../core/transaction/schemas/EmbeddedTransactionDTO.yml" - $ref: "./AccountAddressRestrictionTransactionBodyDTO.yml" diff --git a/spec/plugins/restriction_account/schemas/EmbeddedAccountMosaicRestrictionTransactionDTO.yml b/spec/plugins/restriction_account/schemas/EmbeddedAccountMosaicRestrictionTransactionDTO.yml index 582e7415..4a68af58 100644 --- a/spec/plugins/restriction_account/schemas/EmbeddedAccountMosaicRestrictionTransactionDTO.yml +++ b/spec/plugins/restriction_account/schemas/EmbeddedAccountMosaicRestrictionTransactionDTO.yml @@ -1,4 +1,5 @@ type: object +description: Embedded transaction variant of ``AccountMosaicRestrictionTransactionDTO``. allOf: - $ref: "../../../core/transaction/schemas/EmbeddedTransactionDTO.yml" - $ref: "./AccountMosaicRestrictionTransactionBodyDTO.yml" diff --git a/spec/plugins/restriction_account/schemas/EmbeddedAccountOperationRestrictionTransactionDTO.yml b/spec/plugins/restriction_account/schemas/EmbeddedAccountOperationRestrictionTransactionDTO.yml index 41ddfd19..520570f4 100644 --- a/spec/plugins/restriction_account/schemas/EmbeddedAccountOperationRestrictionTransactionDTO.yml +++ b/spec/plugins/restriction_account/schemas/EmbeddedAccountOperationRestrictionTransactionDTO.yml @@ -1,4 +1,5 @@ type: object +description: Embedded transaction variant of ``AccountOperationRestrictionTransactionDTO``. allOf: - $ref: "../../../core/transaction/schemas/EmbeddedTransactionDTO.yml" - $ref: "./AccountOperationRestrictionTransactionBodyDTO.yml" diff --git a/spec/plugins/restriction_mosaic/schemas/EmbeddedMosaicAddressRestrictionTransactionDTO.yml b/spec/plugins/restriction_mosaic/schemas/EmbeddedMosaicAddressRestrictionTransactionDTO.yml index 4e2c66df..93740ee3 100644 --- a/spec/plugins/restriction_mosaic/schemas/EmbeddedMosaicAddressRestrictionTransactionDTO.yml +++ b/spec/plugins/restriction_mosaic/schemas/EmbeddedMosaicAddressRestrictionTransactionDTO.yml @@ -1,4 +1,5 @@ type: object +description: Embedded transaction variant of ``MosaicAddressRestrictionTransactionDTO``. allOf: - $ref: "../../../core/transaction/schemas/EmbeddedTransactionDTO.yml" - $ref: "./MosaicAddressRestrictionTransactionBodyDTO.yml" diff --git a/spec/plugins/restriction_mosaic/schemas/EmbeddedMosaicGlobalRestrictionTransactionDTO.yml b/spec/plugins/restriction_mosaic/schemas/EmbeddedMosaicGlobalRestrictionTransactionDTO.yml index a5f7d4cf..e4c8f764 100644 --- a/spec/plugins/restriction_mosaic/schemas/EmbeddedMosaicGlobalRestrictionTransactionDTO.yml +++ b/spec/plugins/restriction_mosaic/schemas/EmbeddedMosaicGlobalRestrictionTransactionDTO.yml @@ -1,4 +1,5 @@ type: object +description: Embedded transaction variant of ``MosaicGlobalRestrictionTransactionDTO``. allOf: - $ref: "../../../core/transaction/schemas/EmbeddedTransactionDTO.yml" - $ref: "./MosaicGlobalRestrictionTransactionBodyDTO.yml" diff --git a/spec/plugins/restriction_mosaic/schemas/MosaicAddressRestrictionTransactionBodyDTO.yml b/spec/plugins/restriction_mosaic/schemas/MosaicAddressRestrictionTransactionBodyDTO.yml index 0bc050d1..eea73777 100644 --- a/spec/plugins/restriction_mosaic/schemas/MosaicAddressRestrictionTransactionBodyDTO.yml +++ b/spec/plugins/restriction_mosaic/schemas/MosaicAddressRestrictionTransactionBodyDTO.yml @@ -1,4 +1,5 @@ type: object +description: Mosaic address restriction transaction body that sets a restriction value for a target address and key. required: - mosaicId - restrictionKey diff --git a/spec/plugins/restriction_mosaic/schemas/MosaicGlobalRestrictionTransactionBodyDTO.yml b/spec/plugins/restriction_mosaic/schemas/MosaicGlobalRestrictionTransactionBodyDTO.yml index 71fe4024..345b8142 100644 --- a/spec/plugins/restriction_mosaic/schemas/MosaicGlobalRestrictionTransactionBodyDTO.yml +++ b/spec/plugins/restriction_mosaic/schemas/MosaicGlobalRestrictionTransactionBodyDTO.yml @@ -1,4 +1,5 @@ type: object +description: Mosaic global restriction transaction body that defines the rule and reference value for a restriction key. required: - mosaicId - referenceMosaicId diff --git a/spec/plugins/transfer/schemas/EmbeddedTransferTransactionDTO.yml b/spec/plugins/transfer/schemas/EmbeddedTransferTransactionDTO.yml index 6505bc85..82e58391 100644 --- a/spec/plugins/transfer/schemas/EmbeddedTransferTransactionDTO.yml +++ b/spec/plugins/transfer/schemas/EmbeddedTransferTransactionDTO.yml @@ -1,4 +1,5 @@ type: object +description: Embedded transaction variant of ``TransferTransactionDTO``. allOf: - $ref: "../../../core/transaction/schemas/EmbeddedTransactionDTO.yml" - $ref: "./TransferTransactionBodyDTO.yml" diff --git a/spec/plugins/transfer/schemas/TransferTransactionBodyDTO.yml b/spec/plugins/transfer/schemas/TransferTransactionBodyDTO.yml index 5f566c99..7678fd22 100644 --- a/spec/plugins/transfer/schemas/TransferTransactionBodyDTO.yml +++ b/spec/plugins/transfer/schemas/TransferTransactionBodyDTO.yml @@ -1,4 +1,5 @@ type: object +description: Transfer transaction body with the recipient, transferred mosaics, and optional message. required: - recipientAddress - mosaics @@ -13,4 +14,4 @@ properties: $ref: "../../../schemas/UnresolvedMosaic.yml" message: type: string - description: Transfer transaction message + description: Optional transfer message payload, encoded as a hexadecimal string. diff --git a/spec/request_bodies/cosignature.yml b/spec/request_bodies/cosignature.yml index ef36e154..9c70438d 100644 --- a/spec/request_bodies/cosignature.yml +++ b/spec/request_bodies/cosignature.yml @@ -1,3 +1,4 @@ +description: Request body for announcing one detached cosignature for an aggregate bonded transaction. content: application/json: schema: diff --git a/spec/request_bodies/schemas/cosignature.yml b/spec/request_bodies/schemas/cosignature.yml index 3ad767fe..4d6a7bb3 100644 --- a/spec/request_bodies/schemas/cosignature.yml +++ b/spec/request_bodies/schemas/cosignature.yml @@ -1,10 +1,18 @@ type: object +description: Wrapper object containing the detached cosignature fields required to cosign an aggregate bonded transaction. +required: + - parentHash + - signature + - signerPublicKey + - version properties: parentHash: $ref: "../../schemas/Hash256.yml" + description: Hash of the parent aggregate bonded transaction being cosigned. signature: $ref: "../../schemas/Signature.yml" signerPublicKey: $ref: "../../schemas/PublicKey.yml" + description: Public key of the cosigner creating the cosignature. version: $ref: "../../schemas/CosignatureVersion.yml" diff --git a/spec/request_bodies/schemas/transactionHashes.yml b/spec/request_bodies/schemas/transactionHashes.yml index e1cc60ec..27f237a9 100644 --- a/spec/request_bodies/schemas/transactionHashes.yml +++ b/spec/request_bodies/schemas/transactionHashes.yml @@ -1,5 +1,7 @@ type: object description: Array wrapper used to request transaction statuses by transaction hash. +required: + - hashes properties: hashes: type: array diff --git a/spec/request_bodies/schemas/transactionIds.yml b/spec/request_bodies/schemas/transactionIds.yml index 18eba91b..bc70e6e3 100644 --- a/spec/request_bodies/schemas/transactionIds.yml +++ b/spec/request_bodies/schemas/transactionIds.yml @@ -1,8 +1,11 @@ type: object +description: Wrapper object containing transaction identifiers for batch transaction lookup. +required: + - transactionIds properties: transactionIds: type: array - description: Array of transaction identifiers. + description: Array of transaction IDs or transaction hashes. items: type: string examples: diff --git a/spec/request_bodies/schemas/transactionPayload.yml b/spec/request_bodies/schemas/transactionPayload.yml index bb5f731d..105fa557 100644 --- a/spec/request_bodies/schemas/transactionPayload.yml +++ b/spec/request_bodies/schemas/transactionPayload.yml @@ -1,6 +1,13 @@ type: object +description: | + Wrapper object used to announce one signed transaction payload. +required: + - payload properties: payload: type: string - description: Transaction payload in hexadecimal format. - example: "00112233445566778899AABBCCDDEEFF" + description: | + Signed transaction payload encoded as a hexadecimal string. + To obtain this value, use your SDK's transaction serialization. See the announce endpoint description for more SDK links. + examples: + - "CE000000000000003CA4BBA1CFF24DEA27FD659AA48334DB71FF2E377F641E52773959C58B8A3F77E1255762A39097716FCA94CD55FFE..." diff --git a/spec/request_bodies/transactionIds.yml b/spec/request_bodies/transactionIds.yml index 44244da9..3dd8196a 100644 --- a/spec/request_bodies/transactionIds.yml +++ b/spec/request_bodies/transactionIds.yml @@ -1,3 +1,4 @@ +description: Request body containing transaction IDs or hashes to retrieve in batch. content: application/json: schema: diff --git a/spec/request_bodies/transactionPayload.yml b/spec/request_bodies/transactionPayload.yml index 419d0aad..d8b6d389 100644 --- a/spec/request_bodies/transactionPayload.yml +++ b/spec/request_bodies/transactionPayload.yml @@ -1,3 +1,7 @@ +description: | + Request body for transaction announcement. + + Contains one signed transaction payload serialized in hexadecimal form. content: application/json: schema: diff --git a/spec/schemas/CosignatureVersion.yml b/spec/schemas/CosignatureVersion.yml index 08a01b50..99dc748b 100644 --- a/spec/schemas/CosignatureVersion.yml +++ b/spec/schemas/CosignatureVersion.yml @@ -1,3 +1,6 @@ type: string -description: Cosignature version. -example: "0" +description: | + Version of a detached cosignature attached to an aggregate bonded transaction. + Returned and submitted as a string because the value is encoded as an unsigned integer. +examples: + - "0" diff --git a/spec/schemas/LinkActionEnum.yml b/spec/schemas/LinkActionEnum.yml index b3ffdf8a..309ad59a 100644 --- a/spec/schemas/LinkActionEnum.yml +++ b/spec/schemas/LinkActionEnum.yml @@ -3,6 +3,6 @@ enum: - 0 - 1 description: | - Type of action: - * 0 - Unlink. - * 1 - Link. + Link action: + - `0`: Unlink key. + - `1`: Link key. diff --git a/spec/schemas/MetadataValue.yml b/spec/schemas/MetadataValue.yml index a8dc9357..a6099508 100644 --- a/spec/schemas/MetadataValue.yml +++ b/spec/schemas/MetadataValue.yml @@ -2,7 +2,8 @@ type: string format: hex description: | Metadata value encoded as hex. - In metadata transactions, this field contains the new value when no previous value exists. + In metadata transactions, this field carries the metadata value update payload. + When no previous value exists, it contains the new value. When updating existing metadata, it contains the byte-wise XOR of the previous value and the new value. examples: - "333433383334" diff --git a/spec/schemas/MetadataValueSize.yml b/spec/schemas/MetadataValueSize.yml new file mode 100644 index 00000000..13938311 --- /dev/null +++ b/spec/schemas/MetadataValueSize.yml @@ -0,0 +1,10 @@ +type: integer +description: | + Size of a metadata value or metadata value update payload, in bytes. + In metadata transactions, when no previous value exists, or when the value grows, this is the new + value size after applying the update. When the value shrinks, this is the previous stored value size + before truncation. +minimum: 0 +maximum: 65535 +examples: + - 6 diff --git a/spec/schemas/MetadataValueSizeDelta.yml b/spec/schemas/MetadataValueSizeDelta.yml new file mode 100644 index 00000000..1be5c8fd --- /dev/null +++ b/spec/schemas/MetadataValueSizeDelta.yml @@ -0,0 +1,9 @@ +type: integer +description: | + Change in metadata value size, in bytes. + Positive values increase the stored value size, negative values decrease it. +minimum: -32768 +maximum: 32767 +examples: + - 6 + - -2 diff --git a/spec/schemas/Order.yml b/spec/schemas/Order.yml index e95cd1cf..6b106751 100644 --- a/spec/schemas/Order.yml +++ b/spec/schemas/Order.yml @@ -6,4 +6,3 @@ description: | enum: - asc - desc -default: desc diff --git a/spec/schemas/TransactionMetaHeight.yml b/spec/schemas/TransactionMetaHeight.yml new file mode 100644 index 00000000..ab5b5937 --- /dev/null +++ b/spec/schemas/TransactionMetaHeight.yml @@ -0,0 +1,10 @@ +type: string +description: | + Height of the block containing the referenced transaction or parent aggregate transaction. + Returned as a decimal string. The value is ``"0"`` when the transaction is not included in a + block yet, for example for unconfirmed transactions and partial aggregate transactions. +pattern: '^(0|[1-9][0-9]*)$' +examples: + - "0" + - "1" + - "17592" diff --git a/spec/schemas/VotingKey.yml b/spec/schemas/VotingKey.yml index ced238fc..bda72f43 100644 --- a/spec/schemas/VotingKey.yml +++ b/spec/schemas/VotingKey.yml @@ -1,4 +1,8 @@ type: string format: hex -description: 32 bytes voting public key. -example: 4EDDA97C991A0BF44E0570B0BA0E0F7F1CE821A799726888734F28DDCCE8C591 +description: 32-byte voting public key used for finalization voting. +minLength: 64 +maxLength: 64 +pattern: '^[0-9a-fA-F]{64}$' +examples: + - 4EDDA97C991A0BF44E0570B0BA0E0F7F1CE821A799726888734F28DDCCE8C591 diff --git a/spec/tags.yml b/spec/tags.yml index 01ffa525..a2342570 100644 --- a/spec/tags.yml +++ b/spec/tags.yml @@ -222,6 +222,19 @@ receipt-specific criteria. [Merkle proofs](https://docs.symbol.dev/concepts/data-validation.html#merkle-proof) for receipt statements are available under Block routes. - name: Transaction routes + description: | + Transaction announcement, lookup, and search. [Transactions](https://docs.symbol.dev/concepts/transaction.html) + are signed payloads announced to the network and, after validation, may become part of the chain. + + - **Transaction hash**: 64-character hexadecimal identifier used for status lookup and as one way + to retrieve a transaction record. + - **Transaction ID**: node database record identifier used by some lookup and pagination flows. + - **Confirmed transaction**: a transaction included in a block. + - **Unconfirmed transaction**: a transaction accepted by a node but not yet included in a block. + - **Partial transaction**: an aggregate bonded transaction waiting for the remaining cosignatures. + + These endpoints announce serialized transactions, retrieve single or multiple transaction + records, and search paginated transaction collections. - name: Transaction status routes description: | Transaction status endpoints return the current processing state of a transaction identified by its hash. From 7ffd59e11d88d5f209b58c0bd3c129534ea912cf Mon Sep 17 00:00:00 2001 From: cryptoBeliever Date: Thu, 2 Apr 2026 08:44:27 +0200 Subject: [PATCH 2/3] feat: improve OpenAPI docs for transaction endpoints - minor fixes --- .../finalization/routes/getFinalizationProofAtEpoch.yml | 2 +- .../finalization/routes/getFinalizationProofAtHeight.yml | 2 +- spec/core/network/routes/getNetworkInflationAtHeight.yml | 2 +- spec/core/network/routes/getRentalFees.yml | 2 +- spec/core/network/routes/getTransactionFees.yml | 4 ++-- spec/core/transaction/routes/getPartialTransactions.yml | 2 +- .../core/transaction/routes/getUnconfirmedTransactions.yml | 2 +- spec/plugins/namespace/routes/getNamespaceMerkle.yml | 7 ++++--- .../receipt/routes/searchAddressResolutionStatements.yml | 2 +- .../receipt/routes/searchMosaicResolutionStatements.yml | 2 +- .../plugins/receipt/routes/searchTransactionStatements.yml | 6 +++--- spec/tags.yml | 2 +- 12 files changed, 18 insertions(+), 17 deletions(-) diff --git a/spec/core/finalization/routes/getFinalizationProofAtEpoch.yml b/spec/core/finalization/routes/getFinalizationProofAtEpoch.yml index 5fce953b..7344ccb9 100644 --- a/spec/core/finalization/routes/getFinalizationProofAtEpoch.yml +++ b/spec/core/finalization/routes/getFinalizationProofAtEpoch.yml @@ -1,6 +1,6 @@ tags: - Finalization routes -summary: Get finalization proof +summary: Get finalization proof at epoch description: Returns the finalization proof for the greatest block height associated with the given finalization epoch. operationId: getFinalizationProofAtEpoch parameters: diff --git a/spec/core/finalization/routes/getFinalizationProofAtHeight.yml b/spec/core/finalization/routes/getFinalizationProofAtHeight.yml index b03b5858..06a31cc2 100644 --- a/spec/core/finalization/routes/getFinalizationProofAtHeight.yml +++ b/spec/core/finalization/routes/getFinalizationProofAtHeight.yml @@ -1,6 +1,6 @@ tags: - Finalization routes -summary: Get finalization proof +summary: Get finalization proof at height description: Returns the finalization proof for the block at the given height. operationId: getFinalizationProofAtHeight parameters: diff --git a/spec/core/network/routes/getNetworkInflationAtHeight.yml b/spec/core/network/routes/getNetworkInflationAtHeight.yml index feda09ee..fe6292b6 100644 --- a/spec/core/network/routes/getNetworkInflationAtHeight.yml +++ b/spec/core/network/routes/getNetworkInflationAtHeight.yml @@ -1,6 +1,6 @@ tags: - Network routes -summary: Returns the inflation distribution data at specific height +summary: Returns the inflation distribution data at a specific height description: | Retrieves network inflation parameters at a given block height. operationId: getNetworkInflationAtHeight diff --git a/spec/core/network/routes/getRentalFees.yml b/spec/core/network/routes/getRentalFees.yml index 921d6594..a456a5fc 100644 --- a/spec/core/network/routes/getRentalFees.yml +++ b/spec/core/network/routes/getRentalFees.yml @@ -4,7 +4,7 @@ summary: Get rental fees information description: | Returns the estimated effective rental fees for namespaces and mosaics. This endpoint is only available if the REST instance has access to catapult-server ``resources/config-network.properties`` file. - To activate this feature, add the setting "network.propertiesFilePath" in the configuration file (rest/resources/rest.json). + To activate this feature, add the setting ``network.propertiesFilePath`` in the configuration file (``rest/resources/rest.json``). operationId: getRentalFees responses: "200": diff --git a/spec/core/network/routes/getTransactionFees.yml b/spec/core/network/routes/getTransactionFees.yml index 26781072..eb12a7ff 100644 --- a/spec/core/network/routes/getTransactionFees.yml +++ b/spec/core/network/routes/getTransactionFees.yml @@ -2,8 +2,8 @@ tags: - Network routes summary: Get transaction fees information description: | - Returns the average, median, highest and lower fee multiplier over the last "numBlocksTransactionFeeStats". - The setting "numBlocksTransactionFeeStats" is adjustable via the configuration file (rest/resources/rest.json) per REST instance. + Returns the average, median, highest, and lowest fee multiplier over the last ``numBlocksTransactionFeeStats`` blocks. + The setting ``numBlocksTransactionFeeStats`` is adjustable in the REST configuration file (``rest.json``) per REST instance. operationId: getTransactionFees responses: "200": diff --git a/spec/core/transaction/routes/getPartialTransactions.yml b/spec/core/transaction/routes/getPartialTransactions.yml index cd1819d4..1c41ba8f 100644 --- a/spec/core/transaction/routes/getPartialTransactions.yml +++ b/spec/core/transaction/routes/getPartialTransactions.yml @@ -1,6 +1,6 @@ tags: - Transaction routes -summary: Get partial transactions information +summary: Get information about partial transactions description: | Returns partial transactions for the list of identifiers in the request body. diff --git a/spec/core/transaction/routes/getUnconfirmedTransactions.yml b/spec/core/transaction/routes/getUnconfirmedTransactions.yml index 396607a8..86d806cb 100644 --- a/spec/core/transaction/routes/getUnconfirmedTransactions.yml +++ b/spec/core/transaction/routes/getUnconfirmedTransactions.yml @@ -1,6 +1,6 @@ tags: - Transaction routes -summary: Get unconfirmed transactions information +summary: Get information about unconfirmed transactions description: | Returns unconfirmed transactions for the list of identifiers in the request body. diff --git a/spec/plugins/namespace/routes/getNamespaceMerkle.yml b/spec/plugins/namespace/routes/getNamespaceMerkle.yml index ed579f48..af08e41d 100644 --- a/spec/plugins/namespace/routes/getNamespaceMerkle.yml +++ b/spec/plugins/namespace/routes/getNamespaceMerkle.yml @@ -2,8 +2,11 @@ tags: - Namespace routes summary: Get namespace Merkle information description: | - Returns the Merkle state proof for a namespace. + Returns the [Merkle proof](https://docs.symbol.dev/concepts/data-validation.html#merkle-proof) for a namespace. + Clients can use this information to verify that the namespace state is included in the node's state Merkle tree. + If the supplied namespace ID does not exist, the endpoint still returns a Merkle proof response, + but it is a negative proof showing that no namespace state entry exists for the requested namespace ID. See [Data Validation](https://docs.symbol.dev/concepts/data-validation.html) for an overview of Patricia Merkle trees and state proofs on Symbol. operationId: getNamespaceMerkle @@ -40,7 +43,5 @@ responses: nibbleCount: 62 value: "F48F12376B7C72F97E1533DE6DDB6F957DAB4F9031F959261AA2C5B655C864AA" leafHash: "85AA375FCF9F46F82E71126195A6DA0C0DD2F00378C16C7B986C5DDDA15192C6" - "404": - $ref: "../../../responses/ResourceNotFound.yml" "409": $ref: "../../../responses/InvalidArgument.yml" diff --git a/spec/plugins/receipt/routes/searchAddressResolutionStatements.yml b/spec/plugins/receipt/routes/searchAddressResolutionStatements.yml index 620d7850..ad1be8b0 100644 --- a/spec/plugins/receipt/routes/searchAddressResolutionStatements.yml +++ b/spec/plugins/receipt/routes/searchAddressResolutionStatements.yml @@ -16,7 +16,7 @@ parameters: - $ref: "../../../parameters/query/orderQuery.yml" responses: "200": - description: success + description: Paginated list of address resolution statements. content: application/json: schema: diff --git a/spec/plugins/receipt/routes/searchMosaicResolutionStatements.yml b/spec/plugins/receipt/routes/searchMosaicResolutionStatements.yml index 718dac48..3c6c574b 100644 --- a/spec/plugins/receipt/routes/searchMosaicResolutionStatements.yml +++ b/spec/plugins/receipt/routes/searchMosaicResolutionStatements.yml @@ -16,7 +16,7 @@ parameters: - $ref: "../../../parameters/query/orderQuery.yml" responses: "200": - description: success + description: Paginated list of mosaic resolution statements. content: application/json: schema: diff --git a/spec/plugins/receipt/routes/searchTransactionStatements.yml b/spec/plugins/receipt/routes/searchTransactionStatements.yml index b28af323..5eed09d4 100644 --- a/spec/plugins/receipt/routes/searchTransactionStatements.yml +++ b/spec/plugins/receipt/routes/searchTransactionStatements.yml @@ -3,11 +3,11 @@ tags: summary: Search transaction statements description: | Returns a paginated list of transaction statements generated while confirmed transactions - changed on-chain state. + change on-chain state. Each statement is grouped by block height and source and contains the receipts produced by transaction execution, including balance transfers, balance changes, expirations, and inflation. Results can be filtered by block height, receipt type, related addresses, and artifact IDs. -operationId: searchReceipts +operationId: searchTransactionStatements parameters: - $ref: "../../../parameters/query/heightQuery.yml" - $ref: "../../../parameters/query/fromHeightQuery.yml" @@ -23,7 +23,7 @@ parameters: - $ref: "../../../parameters/query/orderQuery.yml" responses: "200": - description: success + description: Paginated list of transaction statements. content: application/json: schema: diff --git a/spec/tags.yml b/spec/tags.yml index a2342570..b66ee27d 100644 --- a/spec/tags.yml +++ b/spec/tags.yml @@ -53,7 +53,7 @@ - `Harvester`: [account](https://docs.symbol.dev/concepts/account.html) that created the block; receives transaction [fees](https://docs.symbol.dev/concepts/fees.html) and [inflation](https://docs.symbol.dev/concepts/inflation.html) rewards. - - `Beneficiary address`: optional account designated by the harvester to receive a + - `Beneficiary address`: optional account designated by the harvester to receive [the block reward](https://docs.symbol.dev/concepts/harvesting.html#rewards). - `Fee multiplier`: multiplier applied to transaction size to calculate the [effective fee](https://docs.symbol.dev/concepts/fees.html). From 0dd90c819012817077b8533268f7c0c8de196bb9 Mon Sep 17 00:00:00 2001 From: cryptoBeliever Date: Thu, 2 Apr 2026 09:47:05 +0200 Subject: [PATCH 3/3] feat: improve OpenAPI docs for transaction endpoints - minor fixes --- spec/core/transaction/schemas/TransactionStatusEnum.yml | 4 ++-- .../aggregate/routes/announceCosignatureTransaction.yml | 2 ++ 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/spec/core/transaction/schemas/TransactionStatusEnum.yml b/spec/core/transaction/schemas/TransactionStatusEnum.yml index 2a5b1719..f609b1ef 100644 --- a/spec/core/transaction/schemas/TransactionStatusEnum.yml +++ b/spec/core/transaction/schemas/TransactionStatusEnum.yml @@ -324,8 +324,8 @@ description: | because specified previous value is nonzero. - `Failure_RestrictionMosaic_Max_Restrictions_Exceeded`: Validation failed because the maximum number of restrictions would be exceeded. - * Failure_RestrictionMosaic_Cannot_Delete_Nonexistent_Restriction - - Validation failed because nonexistent restriction cannot be deleted. + - `Failure_RestrictionMosaic_Cannot_Delete_Nonexistent_Restriction` - Validation failed + because nonexistent restriction cannot be deleted. - `Failure_RestrictionMosaic_Unknown_Global_Restriction`: Validation failed because required global restriction does not exist. - `Failure_RestrictionMosaic_Invalid_Global_Restriction`: Validation failed because mosaic has invalid global restriction. - `Failure_RestrictionMosaic_Account_Unauthorized`: Validation failed because account lacks proper permissions to move mosaic. diff --git a/spec/plugins/aggregate/routes/announceCosignatureTransaction.yml b/spec/plugins/aggregate/routes/announceCosignatureTransaction.yml index 40976a59..1bec80ff 100644 --- a/spec/plugins/aggregate/routes/announceCosignatureTransaction.yml +++ b/spec/plugins/aggregate/routes/announceCosignatureTransaction.yml @@ -6,6 +6,8 @@ description: | The request must contain the detached cosignature fields: cosignature version, signer public key, cosignature signature, and the parent aggregate transaction hash. + Detached cosignatures are normally created client-side with a [Symbol SDK](https://docs.symbol.dev/sdk.html) + and then announced with this endpoint. To verify the effect of the cosignature, query the **parent aggregate bonded transaction**, for example with [`GET /transactionStatus/{hash}`](/transactionStatus/{hash}) using the