diff --git a/tips/TIP-0048/asyncapi3.yaml b/tips/TIP-0048/asyncapi3.yaml new file mode 100644 index 000000000..3c89fb32e --- /dev/null +++ b/tips/TIP-0048/asyncapi3.yaml @@ -0,0 +1,1312 @@ +asyncapi: 2.4.0 +info: + title: Node Event API + contact: + email: contact@iota.org + version: 3.0.0 + description: >- + The node event API is in charge of publishing information about events + within the node software. +externalDocs: + description: Find out more about IOTA + url: 'https://iota.org' +tags: + - name: commitments + description: Everything about commitments. + - name: blocks + description: Everything about blocks. + - name: outputs + description: Everything about outputs. + - name: transactions + description: Everything about transactions. +channels: + commitment-info/latest: + subscribe: + operationId: commitmentInfoLatest + tags: + - name: commitments + description: Publishes the latest known commitment slot index and its identifier. + message: + $ref: '#/components/messages/CommitmentInfoResponse' + commitment-info/finalized: + subscribe: + tags: + - name: commitments + operationId: commitmentInfoFinalized + description: Publishes the newly finalized commitment slot index and its identifier. + message: + $ref: '#/components/messages/CommitmentInfoResponse' + commitments: + subscribe: + tags: + - name: commitments + operationId: commitments + description: Publishes newly created commitment. + message: + $ref: '#/components/messages/CommitmentPayloadSerialized' + blocks: + subscribe: + tags: + - name: blocks + operationId: blocks + description: Publishes newly received blocks in their serialized binary form. + message: + $ref: '#/components/messages/Block' + blocks/transaction: + subscribe: + tags: + - name: blocks + - name: transactions + operationId: blocksTransaction + description: >- + Publishes newly received blocks containing a transaction payload in + their serialized binary form. + message: + $ref: '#/components/messages/Block' + blocks/transaction/tagged-data: + subscribe: + tags: + - name: blocks + - name: transactions + operationId: blocksTransactionsWithTaggedData + description: >- + Publishes newly received blocks containing a Tagged Data payload inside + transactions. + message: + $ref: '#/components/messages/Block' + 'blocks/transaction/tagged-data/{tag}': + parameters: + tag: + description: >- + Hex encoded tag of the Tagged Data Payload inside the Transaction + Payload. + schema: + type: string + examples: + - '0xe45' + subscribe: + tags: + - name: blocks + - name: transactions + operationId: blocksTransactionsWithTag + description: >- + Publishes newly received blocks containing a Tagged Data payload inside + transactions with a specific tag. + message: + $ref: '#/components/messages/Block' + blocks/tagged-data: + subscribe: + tags: + - name: blocks + operationId: blocksWithTaggedData + description: >- + Publishes newly received blocks which contain tagged data payloads + (encoded in hex) in their serialized binary form. + message: + $ref: '#/components/messages/Block' + 'blocks/tagged-data/{tag}': + parameters: + tag: + description: Hex encoded tag of the Tagged Data Payload. + schema: + type: string + examples: + - '0xe45' + subscribe: + tags: + - name: blocks + operationId: blocksWithSpecificTag + description: >- + Publishes newly received blocks which contain tagged data payloads with + the specified tag parameter (encoded in hex) in their serialized binary + form. Untagged data blocks do not get published. + message: + $ref: '#/components/messages/Block' + 'block-metadata/{blockId}': + parameters: + blockId: + description: Hex encoded identifier of the block. + schema: + type: string + examples: + - '0xdbf86c778d69f413296c2d4d3086d76c74bf4d719e6e95c03a3d9a955ed39bcf3e00000000000000' + subscribe: + tags: + - name: blocks + operationId: blockSpecificMetadata + description: Publishes metadata of a particular block whenever its metadata changes. + message: + $ref: '#/components/messages/BlockMetadata' + block-metadata/accepted: + subscribe: + tags: + - name: blocks + operationId: blockMetadataAccepted + description: Publishes metadata of a block whenever it gets accepted. + message: + $ref: '#/components/messages/BlockMetadata' + block-metadata/confirmed: + subscribe: + tags: + - name: blocks + operationId: blockMetadataConfirmed + description: Publishes metadata of a block whenever it gets confirmed. + message: + $ref: '#/components/messages/BlockMetadata' + 'transactions/{transactionId}/included-block': + parameters: + transactionId: + description: Hex encoded identifier of the transaction. + schema: + type: string + examples: + - '0xd026f8b1c856d4e844cc734bbe095429fb880ec4d93f3ccffe3b292a7de17be7' + subscribe: + tags: + - name: transactions + - name: blocks + operationId: transactionIncludedBlock + description: >- + Publishes the earliest confirmed block which carried the transaction with the + specified transaction ID. + message: + $ref: '#/components/messages/Block' + 'outputs/{outputId}': + parameters: + outputId: + description: Hex encoded identifier of the output. + schema: + type: string + examples: + - '0xd026f8b1c856d4e844cc734bbe095429fb880ec4d93f3ccffe3b292a7de17be70000' + subscribe: + tags: + - name: outputs + operationId: output + description: >- + Publishes the given wanted output on subscriptions. + message: + $ref: '#/components/messages/OutputPayload' + + 'outputs/account/{accountId}': + parameters: + accountId: + description: The unique identifier of the account chain. Hex encoded with 0x prefix. + schema: + type: string + examples: + - '0x1505ec099896ab05d9e08fbc7101ae4dff0093b3943b28f789ed2ca728bcc8d6' + subscribe: + tags: + - name: outputs + operationId: accountOutputByAccountId + description: Publishes the newly created account output of an account chain. + message: + $ref: '#/components/messages/OutputPayload' + + 'outputs/anchor/{anchorId}': + parameters: + anchorId: + description: The unique identifier of the anchor output. Hex encoded with 0x prefix. + schema: + type: string + examples: + - '0x1505ec099896ab05d9e08fbc7101ae4dff0093b3943b28f789ed2ca728bcc8d6' + subscribe: + tags: + - name: outputs + operationId: anchorOutputByAnchorId + description: Publishes the newly created anchor output. + message: + $ref: '#/components/messages/OutputPayload' + + 'outputs/nft/{nftId}': + parameters: + nftId: + description: The unique identifier of the nft chain. Hex encoded with 0x prefix. + schema: + type: string + examples: + - '0x19c82b32761fd8729a1a6c77f7c17597e4b9b01759794e52381f6a0050b0c11f' + subscribe: + tags: + - name: outputs + operationId: nftOutputByNftId + description: Publishes the newly created nft output of an nft chain. + message: + $ref: '#/components/messages/OutputPayload' + 'outputs/foundry/{foundryId}': + parameters: + foundryId: + description: >- + The unique identifier of the foundry chain. Hex encoded with 0x + prefix. + schema: + type: string + examples: + - '0x081505ec099896ab05d9e08fbc7101ae4dff0093b3943b28f789ed2ca728bcc8d60100000000' + subscribe: + tags: + - name: outputs + operationId: foundryOutputByFoundryId + description: Publishes the newly created foundry output of a foundry chain. + message: + $ref: '#/components/messages/OutputPayload' + 'outputs/unlock/{condition}/{address}': + parameters: + condition: + description: Type of unlock condition of the output to look for. + schema: + type: string + enum: + - address + - storage-return + - expiration + - state-controller + - governor + - immutable-account + - + + address: + description: Bech32 encoded address. + schema: + type: string + examples: + - 'iota1qrwfnskm4f7utdrxqnkfntfqxehtpj8s0kf68zkcwm0yrhuemzjp5sjfw5v' + subscribe: + tags: + - name: outputs + operationId: outputByUnlockAndAddress + description: >- + Publishes newly created outputs that have a specific address in a + specific unlock condition. + message: + $ref: '#/components/messages/OutputPayload' + 'outputs/unlock/{condition}/{address}/spent': + parameters: + condition: + description: Type of unlock condition of the output to look for. + schema: + type: string + enum: + - address + - storage-return + - expiration + - state-controller + - governor + - immutable-account + - + + address: + description: Bech32 encoded address. + schema: + type: string + examples: + - 'iota1qrwfnskm4f7utdrxqnkfntfqxehtpj8s0kf68zkcwm0yrhuemzjp5sjfw5v' + subscribe: + tags: + - name: outputs + operationId: outputByUnlockAndAddressSpent + description: >- + Publishes newly spent outputs that have a specific address in a specific + unlock condition. + message: + $ref: '#/components/messages/OutputPayload' +components: + messages: + CommitmentPayload: + contentType: application/json + payload: + type: object + required: + - protocolVersion + - slot + - previousCommitmentId + - rootsId + - cumulativeWeight + - referenceManaCost + properties: + protocolVersion: + type: integer + description: The protocol version of the node. + example: 1 + slot: + type: integer + description: The slot index of the commitment. + example: 200 + previousCommitmentId: + type: string + description: The commitment identifier of the previous slot. + example: "0x8fb6cbb1ecf02c6b5a6a5a6a5f6c5a6a5f6c5a6a5a6a5a6a5f6c5a6a5a6a5f6c50000000000000000" + rootsId: + type: string + description: The digest of multiple merkle roots within this slot. + example: "0xa4dd36465af63d495d35a05f592d42a51511c153e1bae8fad00453c8cbb48727" + cumulativeWeight: + type: string + description: + The sum of previous slot commitment cumulative weight and + weight of issuers of accepted blocks within this slot. + It is just an indication of "committed into" this slot, + and can not strictly be used for evaluating the switching of a chain. + example: '78901' + referenceManaCost: + type: string + description: The reference mana cost of the slot. + example: '12345' + + CommitmentPayloadSerialized: + contentType: application/vnd.iota.serializer-v2 + description: The commitment in its serialized form. + payload: + type: string + format: binary + example: >- + 0x0312000000075b05e0a8fd4b9c7e7bc165b62c48945292f7d76d23f76525f886c416dc0e364089b57c32ddb8c614ed1d2c844401d2a5325b4d153c7f94464bbda3a8d14289b203f96759000000000000009000000000000000 + CommitmentInfoResponse: + contentType: application/json + payload: + type: object + required: + - commitmentIndex + properties: + commitmentIndex: + type: number + description: The slot index of the commitment. + example: 242412 + commitmentId: + type: string + description: Hex encoded identifier of the slot commitment. + example: '0x507d5c7d7105022b661e2c755173785f11707b7a6b3369111d000d1f145e652d5f436f26' + Block: + contentType: application/vnd.iota.serializer-v2 + description: The block in its serialized binary form. + payload: + type: string + format: binary + example: >- + 03490443ee9f5955c4bb2ab676df2c9e1796f8ae1c96f769d56d883bdf3dbed2261413a0ae8e281d17822be093cb3ddcdf202a60b2f4010000a371f6fb9f7d201d80bdd55fe7d1d64e713066e1bca1a6e6f5bd0120473530790006002d31ee96475d45115d600bc9321a36a067e0e8c46d0e910deeaf3a96a7893eec906b2402b9d83256d47058ecd186e2349cce2846a07454470e4d921b3dbc5c58ef781af5b06a8b12382bac13c80a7d809b86211818b9f1b59a6a7f59ada12c6708a37d3ad0d39a31e9786067f086718e65229cf610927fd0bbac8d26a9c38d4829d1151023e7f2b09cc2a04adb0888b89b9cc4b217f3b6f7161a15e3a772a8b465e130d1aa8fe62f97e47a7cb17663f6b496a7e29fd91b415db4664ddbd31b9f48f7f8f853fc83996907efe6358cca1061c9903925dda200001800000000037461670f000000d7377ed316f02780a8a7e4b1f69e2aa70200000000000000d62233f3240753d4f14a1cff3e6a6c126dc85854e34f5754babcf229f02707ce2958bd23a1c2ccf10123456d33211b98b751f99b791eb6d9737bc0dfd7f0ac09532599c32757ad2fd4bd906bd9ea2bf4c8f3682c015cf9068c914d1cb04ad80b + + OutputPayload: + contentType: application/json + payload: + type: object + properties: + metadata: + oneOf: + - $ref: '#/components/schemas/OutputMetadata' + output: + anyOf: + - $ref: '#/components/schemas/BasicOutput' + - $ref: '#/components/schemas/AccountOutput' + - $ref: '#/components/schemas/AnchorOutput' + - $ref: '#/components/schemas/FoundryOutput' + - $ref: '#/components/schemas/NFTOutput' + - $ref: '#/components/schemas/DelegationOutput' + outputIdProof: + oneOf: + - $ref: '#/components/schemas/OutputIdProof' + + BlockMetadata: + contentType: application/json + payload: + type: object + required: + - blockId + - strongParents + properties: + blockId: + type: string + description: The ID of the block. + example: '0xdbf86c778d69f413296c2d4d3086d76c74bf4d719e6e95c03a3d9a955ed39bcf3e00000000000000' + blockState: + type: string + description: If `pending`, the block is stored but not confirmed. If `confirmed`, the block is confirmed with the first level of knowledge. If `finalized`, the block is included and cannot be reverted anymore. If `rejected`, the block is rejected by the node, and user should reissue payload if it contains one. If `failed`, the block is not successfully issued due to failure reason. + enum: + - pending + - confirmed + - finalized + - rejected + - failed + transactionState: + type: string + description: The inclusion state of the transaction. + enum: + - pending + - confirmed + - finalized + - failed + example: failed + blockFailureReason: + type: integer + enum: [1,2,3,4,5,6,7,8,9,10,11,12,255] + description: | + Values: + * `1` - denotes that the block is too old to issue. + * `2` - denotes that the block's parents are too old. + * `3` - denotes that one of block's parents does not exist. + * `4` - denotes that one of block's parents is invalid. + * `5` - denotes that the issuer account could not be found. + * `6` - denotes that the block version is invalid to retrieve the corresponding protocol information. + * `7` - denotes that the Mana cost could not be calculated. + * `8` - denotes that the issuer account burned insufficient Mana for the block. + * `9` - denotes that the account is invalid, e.g. the account has negative Block Issuance Credits, or the account has expired. + * `10` - denotes that the signature is invalid. + * `11` - denotes that the block is dropped due to congestion. + * `12` - denotes that the payload is invalid. + * `255` - denotes that the block is invalid. + transactionFailureReason: + type: integer + enum: [1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,255] + description: | + Values: + * `1` - denotes that the referenced UTXO was already spent. + * `2` - denotes that the transaction is conflicting with another transaction. Conflicting specifically means a double spend situation that both transaction pass all validation rules, eventually losing one(s) should have this reason. + * `3` - denotes that the referenced UTXO is invalid. + * `4` - denotes that the transaction is invalid. + * `5` - denotes that the sum of the inputs and output base token amount does not match. + * `6` - denotes that the unlock block signature is invalid. + * `7` - denotes that the configured timelock is not yet expired. + * `8` - denotes that the given native tokens are invalid. + * `9` - denotes that the return amount in a transaction is not fulfilled by the output side. + * `10` - denotes that the input unlock is invalid. + * `11` - denotes that an output contains a Sender with an ident (address) which is not unlocked. + * `12` - denotes that the chain state transition is invalid. + * `13` - denotes that the referenced input is created after transaction issuing time. + * `14` - denotes that the mana amount is invalid. + * `15` - denotes that the Block Issuance Credits Input is invalid. + * `16` - denotes that Reward Context Input is invalid. + * `17` - denotes that Commitment Context Input is invalid. + * `18` - denotes that Staking Feature is not provided in account output when claiming rewards. + * `19` - denotes that fail to claim staking reward. + * `20` - denotes that fail to claim delegation reward. + * `21` - denotes that the burning of native tokens was not allowed in the transaction capabilities. + * `22` - denotes that the burning of mana was not allowed in the transaction capabilities. + * `23` - denotes that the destruction of accounts was not allowed in the transaction capabilities. + * `24` - denotes that the destruction of anchors was not allowed in the transaction capabilities. + * `25` - denotes that the destruction of foundries was not allowed in the transaction capabilities. + * `26` - denotes that the destruction of nfts was not allowed in the transaction capabilities. + * `255` - denotes that the semantic validation failed. + example: 1 + + schemas: + Ed25519Address: + description: The Ed25519 address. + properties: + type: + type: integer + description: Set to value 0 to denote an Ed25519 Address. + example: 0 + pubKeyHash: + type: string + description: The hex-encoded BLAKE2b-256 hash of the Ed25519 public key. + example: '0x713c3e879b53398431f67312254101ffdd23067febc77f4949de57ee279c8bee' + required: + - type + - pubKeyHash + AccountAddress: + description: Address of an account. + properties: + type: + type: integer + description: Set to value 8 to denote an Account Address. + example: 1 + accountId: + type: string + description: >- + The hex-encoded BLAKE2b-256 hash of the Output ID that created the + account. + example: '0x1505ec099896ab05d9e08fbc7101ae4dff0093b3943b28f789ed2ca728bcc8d6' + required: + - type + - accountId + NFTAddress: + description: Address of an NFT account. + properties: + type: + type: integer + description: Set to value 16 to denote an NFT Address. + example: 1 + nftId: + type: string + description: >- + The hex-encoded BLAKE2b-256 hash of the Output ID that created the + NFT. + example: '0x19c82b32761fd8729a1a6c77f7c17597e4b9b01759794e52381f6a0050b0c11f' + required: + - type + - nftId + AccountUnlockCondition: + description: Can be unlocked by unlocking the address. + properties: + type: + type: integer + description: Set to value 0 to denote an Address Unlock Condition. + example: 0 + address: + oneOf: + - $ref: '#/components/schemas/Ed25519Address' + - $ref: '#/components/schemas/AccountAddress' + - $ref: '#/components/schemas/NFTAddress' + required: + - type + - address + ImmutableAccountAddressUnlockCondition: + description: >- + Can be unlocked by unlocking the permanent account address. The unlock + condition has to be kept in future state transitions of the UTXO state + machine. + properties: + type: + type: integer + description: >- + Set to value 6 to denote an Immutable Account Address Unlock + Condition. + example: 6 + address: + oneOf: + - $ref: '#/components/schemas/AccountAddress' + required: + - type + - address + StorageDepositReturnUnlockCondition: + description: >- + Can be unlocked by depositing return amount to return address via an + output that only has Address Unlock Condition. + properties: + type: + type: integer + description: Set to value 1 to denote a Storage Deposit Return Unlock Condition. + example: 1 + returnAddress: + oneOf: + - $ref: '#/components/schemas/Ed25519Address' + - $ref: '#/components/schemas/AccountAddress' + - $ref: '#/components/schemas/NFTAddress' + amount: + type: string + description: >- + Amount of IOTA tokens the consuming transaction should deposit to + the address defined in Return Address. + example: "50" + required: + - type + - returnAddress + - amount + + AddressUnlockCondition: + description: Can be unlocked by unlocking the address. + properties: + type: + type: integer + description: Set to value 0 to denote an Address Unlock Condition. + example: 0 + address: + oneOf: + - $ref: '#/components/schemas/Ed25519Address' + - $ref: '#/components/schemas/AccountAddress' + - $ref: '#/components/schemas/NFTAddress' + required: + - type + - address + + TimelockUnlockCondition: + description: Can be unlocked if the confirming commitment has a >= Unix Timestamp. + properties: + type: + type: integer + description: Set to value 2 to denote a Timelock Unlock Condition. + example: 2 + slot: + type: integer + description: >- + The slot index until which the timelock applies (inclusive) + example: 16 + exclusiveMinimum: 0 + required: + - type + - slot + + ExpirationUnlockCondition: + description: >- + Defines a unix time until which only Address, defined in Address Unlock + Condition, is allowed to unlock the output. After the slot index, only + Return Address can unlock it. + properties: + type: + type: integer + description: Set to value 3 to denote an Expiration Unlock Condition. + example: 3 + returnAddress: + oneOf: + - $ref: '#/components/schemas/Ed25519Address' + - $ref: '#/components/schemas/AccountAddress' + - $ref: '#/components/schemas/NFTAddress' + slot: + type: integer + description: >- + The slot index at which the expiration happens. + example: 16 + exclusiveMinimum: 0 + required: + - type + - returnAddress + - slot + + StateControllerAddressUnlockCondition: + description: Can be unlocked by unlocking the address. + properties: + type: + type: integer + description: Set to value 4 to denote a Sate Controller Address Unlock Condition. + example: 4 + address: + oneOf: + - $ref: '#/components/schemas/Ed25519Address' + - $ref: '#/components/schemas/AccountAddress' + - $ref: '#/components/schemas/NFTAddress' + required: + - type + - address + + GovernorAddressUnlockCondition: + description: Can be unlocked by unlocking the address. + properties: + type: + type: integer + description: Set to value 5 to denote a Governor Address Unlock Condition. + example: 5 + address: + oneOf: + - $ref: '#/components/schemas/Ed25519Address' + - $ref: '#/components/schemas/AccountAddress' + - $ref: '#/components/schemas/NFTAddress' + required: + - type + - address + SenderFeature: + description: Identifies the validated sender of the output. + properties: + type: + type: integer + description: Set to value 0 to denote a Sender Feature. + example: 0 + address: + oneOf: + - $ref: '#/components/schemas/Ed25519Address' + - $ref: '#/components/schemas/AccountAddress' + - $ref: '#/components/schemas/NFTAddress' + required: + - type + - address + + IssuerFeature: + description: Identifies the validated issuer of the UTXO state machine (account/NFT). + properties: + type: + type: integer + description: Set to value 1 to denote an Issuer Feature. + example: 1 + address: + oneOf: + - $ref: '#/components/schemas/Ed25519Address' + - $ref: '#/components/schemas/AccountAddress' + - $ref: '#/components/schemas/NFTAddress' + required: + - type + - address + + BlockIssuerFeature: + description: >- + A feature which indicates that this account can issue blocks. + properties: + type: + type: integer + description: Set to value 6 to denote a Block Issuer Feature. + example: 6 + blockIssuerKeys: + type: array + description: The keys allowed to issue blocks from an account with a BlockIssuerFeature. + items: + oneOf: + - $ref: '#/components/schemas/Ed25519PublicKey' + expirySlot: + type: integer + description: Indicates when the BlockIssuerKeys are expired. + required: + - type + - blockIssuerKeys + - expirySlot + + StakingFeature: + description: A feature which indicates that this account can issue blocks. + properties: + type: + type: integer + description: Set to value 7 to denote a Staking Feature. + example: 7 + stakedAmount: + type: string + description: The amount of IOTA coins that are locked and staked in the containing account. + fixedCost: + type: string + description: Indicates when the BlockIssuerKeys are expired. + startEpoch: + type: integer + description: The epoch index at which the staking starts. + endEpoch: + type: integer + description: The epoch index at which the staking ends. + required: + - type + - stakedAmount + - fixedCost + - startEpoch + - endEpoch + + MetadataFeature: + description: >- + Defines metadata (arbitrary binary data) that will be stored in the + output. + properties: + type: + type: integer + description: Set to value 2 to denote a Metadata Feature. + example: 2 + entries: + type: object + additionalProperties: + type: string + example: + - 'did:iota': '0x68656c6c6f206469676974616c206175746f6e6f6d79' + - 'hello': '0x776f726c64' + required: + - type + - entries + StateMetadataFeature: + description: >- + Defines a map of key-value pairs. The keys must consist of ASCII characters only and the values are arbitrary byte slices. + properties: + type: + type: integer + description: Set to value 3 to denote a State Metadata Feature. + example: 3 + entries: + type: object + additionalProperties: + type: string + description: Hex-encoded binary data. + example: + - 'did:iota': '0x68656c6c6f206469676974616c206175746f6e6f6d79' + - 'hello': '0x776f726c64' + required: + - type + - entries + NativeTokenFeature: + description: Defines a native token which represents a token that resides natively on the ledger. + properties: + type: + type: integer + description: Set to value 5 to denote a Native Token Feature. + example: 5 + id: + type: string + description: The ID of the native token. + example: "0x082d3860307d320f3a167a225b031b6b043941562b0c18797938584f603f69425375617a4900" + amount: + type: string + description: The amount of native token. Hex-encoded number with 0x prefix. + example: "0x3e8" + required: + - type + - id + - amount + TagFeature: + description: >- + Defines an indexation tag to which the output can be indexed by + additional node plugins. + properties: + type: + type: integer + description: Set to value 4 to denote a Tag Feature. + example: 4 + tag: + type: string + description: Hex-encoded binary indexation tag. + example: '0xfa0de75' + required: + - type + - tag + SimpleTokenScheme: + description: >- + Defines the simple supply control scheme of native tokens. Tokens can be + minted by the foundry without additional restrictions as long as maximum + supply is requested and circulating supply is not negative. + properties: + type: + type: integer + description: Set to value 0 to denote an Simple Token Scheme. + example: 0 + mintedTokens: + type: string + description: Minted tokens controlled by this foundry. Hex encoded number. + example: '0x2710' + meltedTokens: + type: string + description: Melted tokens controlled by this foundry. Hex encoded number. + example: '0x1388' + maxSupply: + type: string + description: >- + Maximum supply of tokens controlled by this foundry. Hex encoded + number. + example: '0x186a0' + required: + - type + - mintedTokens + - meltedTokens + - maxSupply + BasicOutput: + description: Describes a basic output with optional features. + properties: + type: + type: integer + description: Set to value 0 to denote a Basic Output. + example: 0 + amount: + type: string + description: >- + The amount of IOTA tokens to deposit with this BasicOutput output. + Encoded as plain string. + example: '100' + mana: + type: string + description: The stored mana held by the output. + example: '3000' + unlockConditions: + type: array + description: >- + Unlock conditions that define how the output can be unlocked in a + transaction. + items: + anyOf: + - $ref: '#/components/schemas/AddressUnlockCondition' + - $ref: '#/components/schemas/StorageDepositReturnUnlockCondition' + - $ref: '#/components/schemas/TimelockUnlockCondition' + - $ref: '#/components/schemas/ExpirationUnlockCondition' + features: + type: array + description: >- + Features that add utility to the output but do not impose unlocking + conditions. + items: + anyOf: + - $ref: '#/components/schemas/SenderFeature' + - $ref: '#/components/schemas/MetadataFeature' + - $ref: '#/components/schemas/TagFeature' + - $ref: '#/components/schemas/NativeTokenFeature' + required: + - type + - amount + - mana + + AccountOutput: + description: >- + Describes an account in the ledger that can be controlled by the + state and governance controllers. + properties: + type: + type: integer + description: Set to value 1 to denote an Account Output. + example: 1 + amount: + type: string + description: >- + The amount of IOTA tokens to deposit with this output. Encoded as + plain string. + example: '100' + mana: + type: string + description: The stored mana held by the output. + example: '3000' + accountId: + type: string + description: >- + Unique identifier of the account, which is the BLAKE2b-256 hash of the + Output ID that created it. Account Address = Account Address Type || + Account ID + example: '0x1505ec099896ab05d9e08fbc7101ae4dff0093b3943b28f789ed2ca728bcc8d6' + foundryCounter: + type: integer + description: >- + A counter that denotes the number of foundries created by this account. + example: 3 + unlockConditions: + type: array + description: >- + Unlock conditions that define how the output can be unlocked in a + transaction. + items: + anyOf: + - $ref: '#/components/schemas/AddressUnlockCondition' + features: + type: array + description: >- + Features that add utility to the output but do not impose unlocking + conditions. + items: + anyOf: + - $ref: '#/components/schemas/SenderFeature' + - $ref: '#/components/schemas/MetadataFeature' + - $ref: '#/components/schemas/BlockIssuerFeature' + - $ref: '#/components/schemas/StakingFeature' + immutableFeatures: + type: array + description: >- + Immutable features that add utility to the output but do not impose + unlocking conditions. These blocks need to be kept in future + transitions of the UTXO state machine. + items: + anyOf: + - $ref: '#/components/schemas/IssuerFeature' + - $ref: '#/components/schemas/MetadataFeature' + required: + - type + - amount + - accountId + - foundryCounter + - mana + + AnchorOutput: + description: >- + Describes an anchor output. + properties: + type: + type: integer + description: Set to value 2 to denote an Anchor Output. + example: 1 + amount: + type: string + description: >- + The amount of IOTA tokens to deposit with this output. Encoded as + plain string. + example: '100' + mana: + type: string + description: The stored mana held by the output. + example: '3000' + anchorId: + type: string + description: The identifier of the anchor. + example: '0x1505ec099896ab05d9e08fbc7101ae4dff0093b3943b28f789ed2ca728bcc8d6' + stateIndex: + type: integer + description: A counter that must increase by 1 every time the account is state transitioned. + example: 3 + unlockConditions: + type: array + description: >- + Unlock conditions that define how the output can be unlocked in a + transaction. + items: + anyOf: + - $ref: '#/components/schemas/StateControllerAddressUnlockCondition' + - $ref: '#/components/schemas/GovernorAddressUnlockCondition' + features: + type: array + description: >- + Features that add utility to the output but do not impose unlocking + conditions. + items: + anyOf: + - $ref: '#/components/schemas/MetadataFeature' + - $ref: '#/components/schemas/StateMetadataFeature' + immutableFeatures: + type: array + description: >- + Immutable features that add utility to the output but do not impose + unlocking conditions. These blocks need to be kept in future + transitions of the UTXO state machine. + items: + anyOf: + - $ref: '#/components/schemas/IssuerFeature' + - $ref: '#/components/schemas/MetadataFeature' + required: + - type + - amount + - anchorId + - stateIndex + - mana + + DelegationOutput: + description: >- + Describes an delegation output in the ledger that can be controlled by the + state and governance controllers. + properties: + type: + type: integer + description: Set to value 5 to denote a Delegation Output. + example: 5 + amount: + type: string + description: >- + The amount of IOTA tokens held by the output. Encoded as + plain string. + example: '100' + delegatedAmount: + type: string + description: The amount of IOTA tokens that were delegated when the output was created. + delegationId: + type: string + description: >- + The identifier for this delegation output. + example: '0x1505ec099896ab05d9e08fbc7101ae4dff0093b3943b28f789ed2ca728bcc8d6' + validatorAddress: + type: string + description: >- + The Account Address of the validator to which this output is delegating. + example: '0x1505ec099896ab05d9e08fbc7101ae4dff0093b3943b28f789ed2ca728bcc8d6' + startEpoch: + type: integer + description: >- + The index of the first epoch for which this output delegates. + example: 10 + endEpoch: + type: integer + description: >- + The index of the last epoch for which this output delegates. + example: 12 + unlockConditions: + type: array + description: >- + Unlock conditions that define how the output can be unlocked in a + transaction. + items: + anyOf: + - $ref: '#/components/schemas/AddressUnlockCondition' + required: + - type + - amount + - delegatedAmount + - delegationId + - validatorAddress + - startEpoch + - endEpoch + + FoundryOutput: + description: Describes a foundry output that is controlled by an account. + properties: + type: + type: integer + description: Set to value 5 to denote a Foundry Output. + example: 5 + amount: + type: string + description: >- + The amount of IOTA tokens to deposit with this output. Encoded as + plain string. + example: '100' + serialNumber: + type: integer + description: >- + The serial number of the foundry with respect to the controlling + account. + example: 2 + tokenScheme: + type: array + description: >- + Defines the supply control scheme of the tokens controlled by the + foundry. + items: + oneOf: + - $ref: '#/components/schemas/SimpleTokenScheme' + unlockConditions: + type: array + description: >- + Unlock conditions that define how the output can be unlocked in a + transaction. + items: + anyOf: + - $ref: '#/components/schemas/ImmutableAccountAddressUnlockCondition' + features: + type: array + description: >- + Features that add utility to the output but do not impose unlocking + conditions. + items: + anyOf: + - $ref: '#/components/schemas/MetadataFeature' + - $ref: '#/components/schemas/NativeTokenFeature' + immutableFeatures: + type: array + description: >- + Immutable features that add utility to the output but do not impose + unlocking conditions. These blocks need to be kept in future + transitions of the UTXO state machine. + items: + anyOf: + - $ref: '#/components/schemas/MetadataFeature' + required: + - type + - amount + - serialNumber + - tokenScheme + + NFTOutput: + description: 'Describes an NFT output, a globally unique token with metadata attached.' + properties: + type: + type: integer + description: Set to value 6 to denote a NFT Output. + amount: + type: string + description: >- + The amount of IOTA tokens to deposit with this output. Encoded as + plain string. + example: '100' + mana: + type: string + description: The stored mana held by the output + example: '3000' + nftId: + type: string + description: >- + Unique identifier of the NFT, which is the BLAKE2b-256 hash of the + Output ID that created it. NFT Address = NFT Address Type || NFT ID + example: '0x19c82b32761fd8729a1a6c77f7c17597e4b9b01759794e52381f6a0050b0c11f' + unlockConditions: + type: array + description: >- + Unlock conditions that define how the output can be unlocked in a + transaction. + items: + anyOf: + - $ref: '#/components/schemas/AddressUnlockCondition' + - $ref: '#/components/schemas/StorageDepositReturnUnlockCondition' + - $ref: '#/components/schemas/TimelockUnlockCondition' + - $ref: '#/components/schemas/ExpirationUnlockCondition' + features: + type: array + description: >- + Features that add utility to the output but do not impose unlocking + conditions. + items: + anyOf: + - $ref: '#/components/schemas/SenderFeature' + - $ref: '#/components/schemas/MetadataFeature' + - $ref: '#/components/schemas/TagFeature' + immutableFeatures: + type: array + description: >- + Immutable features that add utility to the output but do not impose + unlocking conditions. + + These blocks need to be kept in future transitions of the UTXO state + machine. + items: + anyOf: + - $ref: '#/components/schemas/IssuerFeature' + - $ref: '#/components/schemas/MetadataFeature' + required: + - type + - amount + - nftId + - mana + + OutputIdProof: + description: The proof of the output identifier. + properties: + slot: + type: integer + description: The slot index of the output. + example: 20 + outputIndex: + type: integer + description: The index of the output. + example: 0 + transactionCommitment: + type: string + description: The commitment of the transaction that created the output. Hex-encoded with 0x prefix. + example: '0x897dr69bfa60c8cf80afd730741862d200405d5df7cabfe9b564361dce1f7036' + outputCommitmentProof: + type: string + description: The proof of the output commitment. Hex-encoded with 0x prefix. + example: '0xd3a0a0c76ab2d9b406a32c30c43e102fe0f39a12a3f6c1e3b19d239db2f18d75' + required: + - slot + - outputIndex + - transactionCommitment + - outputCommitmentProof + + Ed25519Signature: + description: Ed25519Signature defines an Ed25519 signature. + properties: + type: + type: number + description: Defines the type for an Ed255199Signature (0). + example: 0 + publicKey: + type: string + description: The public key used to verify the given signature. + example: '0x5368c0c1ee386222966ceca9a0029be32527959b9fd2a8a6d61388bcee6d66c1' + signature: + type: string + description: The signature. + example: '0x8e78a5e701e530365594aefb43a3219b6aa8bea214425847c654797a46ce1967528d2e6714f469ca308ee96a08319a4135fdc84923c04f784de414a840e4020e' + required: + - type + - publicKey + - signature + + Ed25519PublicKey: + description: The Ed25519 public key. + properties: + type: + type: integer + description: Set to value 0 to denote an Ed25519 Public key. + publicKey: + type: string + description: Ed25519 public key in Hex. + required: + - type + - publicKey + + OutputMetadata: + description: Metadata of an output. + properties: + blockId: + type: string + description: The ID of the block. + example: '0xdbf86c778d69f413296c2d4d3086d76c74bf4d719e6e95c03a3d9a955ed39bcf3e00000000000000' + transactionId: + type: string + description: The ID of the transaction which created this output. + example: '0xd026f8b1c856d4e844cc734bbe095429fb880ec4d93f3ccffe3b292a7de17be7' + outputIndex: + type: integer + description: The index of the output within its transaction. + example: 0 + isSpent: + type: boolean + description: Whether the output is spent or not. + example: true + commitmentIdSpent: + type: string + description: The commitment ID of the slot at which this output was spent. + example: '0xe526f8b1c856d4e844cc734bbe095429fb880ec4d93f3ccffe3b292a7de17be7' + transactionIdSpent: + type: string + description: The transaction this output was spent with. + example: '0xe526f8b1c856d4e844cc734bbe095429fb880ec4d93f3ccffe3b292a7de17be7' + includedCommitmentId: + type: string + description: The commitment ID at which the output was included into the ledger. + example: '0xe526f8b1c856d4e844cc734bbe095429fb880ec4d93f3ccffe3b292a7de17be7' + latestCommitmentId: + type: string + description: The current latest commitment id for which the request was made. + example: '0xe526f8b1c856d4e844cc734bbe095429fb880ec4d93f3ccffe3b292a7de17be7' + required: + - blockId + - transactionId + - outputIndex + - isSpent + - latestCommitmentId diff --git a/tips/TIP-0048/openapi3-core.yaml b/tips/TIP-0048/openapi3-core.yaml new file mode 100644 index 000000000..3f5b10689 --- /dev/null +++ b/tips/TIP-0048/openapi3-core.yaml @@ -0,0 +1,3805 @@ +openapi: 3.0.3 +info: + title: IOTA CORE REST API + description: This document specifies the REST API for IOTA CORE node software. + contact: + email: contact@iota.org + license: + name: Apache 2.0 + url: 'http://www.apache.org/licenses/LICENSE-2.0.html' + version: 3.0.0 +externalDocs: + description: Find out more about IOTA + url: 'https://iota.org' +servers: + - url: 'http://127.0.0.1:14265' +tags: + - name: node + description: Everything about the node itself. + - name: accounts + description: Everything about the accounts. + - name: rewards + description: Everything about Mana rewards. + - name: validators + description: Everything about validators and staking. + - name: committee + description: Everything about the committee. + - name: blocks + description: Everything about blocks. + - name: UTXO + description: Everything about UTXOs. + - name: commitments + description: Everything about commitments. + +paths: + /health: + get: + tags: + - node + summary: Returns the health of the node. + description: >- + Returns the health of the node. A node considers itself healthy if it is bootstrapped and its Accepted Tangle Time (ATT) is not + further behind its local clock than BootstrapWindow. + responses: + '200': + description: "Successful operation: indicates that the node is healthy." + '403': + description: "Unsuccessful operation: indicates that the endpoint is not available for public use." + '500': + description: "Unsuccessful operation: indicates that an unexpected, internal server error happened which prevented the node from fulfilling the request." + '503': + description: "Unsuccessful operation: indicates that the node isn't healthy." + + /api/routes: + get: + tags: + - node + summary: Returns the available API route groups of the node. + description: >- + Returns the available API route groups of the node. + responses: + '200': + description: "Successful operation" + content: + application/json: + schema: + $ref: '#/components/schemas/RoutesResponse' + examples: + default: + $ref: '#/components/examples/get-routes-response-example' + '403': + description: "Unsuccessful operation: indicates that the endpoint is not available for public use." + '500': + description: "Unsuccessful operation: indicates that an unexpected, internal server error happened which prevented the node from fulfilling the request." + + /api/core/v3/info: + get: + tags: + - node + summary: Returns general information about the node. + description: Returns general information about the node. + responses: + '200': + description: "Successful operation." + content: + application/json: + schema: + $ref: '#/components/schemas/InfoResponse' + examples: + default: + $ref: '#/components/examples/get-info-response-example' + '403': + description: "Unsuccessful operation: indicates that the endpoint is not available for public use." + content: + application/json: + schema: + $ref: '#/components/schemas/ForbiddenResponse' + '500': + description: "Unsuccessful operation: indicates that an unexpected, internal server error happened which prevented the node from fulfilling the request." + content: + application/json: + schema: + $ref: '#/components/schemas/InternalErrorResponse' + + '/api/core/v3/accounts/{bech32Address}/congestion': + get: + tags: + - accounts + summary: Check if the account is ready to issue a block. + description: >- + Check the readiness of the node to issue a new block, the reference mana cost based on the rate setter and current network congestion, and the block issuance credits of the requested account. + parameters: + - in: path + name: bech32Address + schema: + type: string + example: "rms1pqm4xk8e9ny5w5rxjkvtp249tfhlwvcshyr3pc0665jvp7g3hc875k538hl" + required: true + description: The Account Address in bech32. + responses: + '200': + description: "Successful operation." + content: + application/json: + schema: + $ref: '#/components/schemas/CongestionResponse' + examples: + CongestionResponse: + $ref: '#/components/examples/get-congestion-estimate-response-example' + '400': + description: "Unsuccessful operation: indicates that the provided data is invalid." + content: + application/json: + schema: + $ref: '#/components/schemas/BadRequestResponse' + '403': + description: "Unsuccessful operation: indicates that the endpoint is not available for public use." + content: + application/json: + schema: + $ref: '#/components/schemas/ForbiddenResponse' + '500': + description: "Unsuccessful operation: indicates that an unexpected, internal server error happened which prevented the node from fulfilling the request." + content: + application/json: + schema: + $ref: '#/components/schemas/InternalErrorResponse' + '503': + description: "Unsuccessful operation: indicates that the node is not synced." + content: + application/json: + schema: + $ref: '#/components/schemas/ServiceUnavailableResponse' + + '/api/core/v3/rewards/{outputId}': + get: + tags: + - rewards + summary: Returns all the available Mana rewards of an account or delegation output in the returned range of epochs. + description: >- + Returns all the available Mana rewards of an account or delegation output in the returned range of epochs. Note that rewards for an epoch only become available when the last slot of an epoch is committed. If the end epoch of a staking feature is equal or greater than the current epoch, the rewards response will thus not include the potential future rewards for those epochs. startEpoch and endEpoch indicate the actual epoch range in which rewards are available. Callers that use this API to build a transaction are highly advised to set the slot index parameter explicitly. The returned startEpoch can be used to check the first epoch for which rewards are available. Together with the retention period of rewards, applications can warn users to claim their rewards before their oldest rewards are beyond the retention period. + parameters: + - in: path + name: outputId + schema: + type: string + example: "0xf532a53545103276b46876c473846d98648ee418468bce76df4868648dd73e5d" + required: true + description: Output ID of an account or delegation output. + - in: query + name: slot + schema: + type: integer + example: 50 + description: A client can specify a slot index explicitly, which should be equal to the slot it uses as the commitment input for the claiming transaction to ensure the node calculates the rewards identically as during transaction execution. Rewards are decayed up to the epoch corresponding to the given slot + MinCommittableAge. For a Delegation Output in delegating state (i.e. when Delegation ID is zeroed), that epoch - 1 is also used as the last epoch for which rewards are fetched. Callers that do not build transactions with the returned values may omit this value in which case it defaults to the latest committed slot, which is good enough to, e.g. display estimated rewards to users. + responses: + '200': + description: "Successful operation." + content: + application/json: + schema: + $ref: '#/components/schemas/ManaRewardsResponse' + examples: + ManaRewardsResponse: + $ref: '#/components/examples/get-mana-rewards-example' + '400': + description: "Unsuccessful operation: indicates that the provided data is invalid." + content: + application/json: + schema: + $ref: '#/components/schemas/BadRequestResponse' + '403': + description: "Unsuccessful operation: indicates that the endpoint is not available for public use." + content: + application/json: + schema: + $ref: '#/components/schemas/ForbiddenResponse' + '500': + description: "Unsuccessful operation: indicates that an unexpected, internal server error happened which prevented the node from fulfilling the request." + content: + application/json: + schema: + $ref: '#/components/schemas/InternalErrorResponse' + '503': + description: "Unsuccessful operation: indicates that the node is not synced." + content: + application/json: + schema: + $ref: '#/components/schemas/ServiceUnavailableResponse' + + /api/core/v3/committee: + get: + tags: + - committee + summary: Return the information of committee members. + # TODO: Revisit when committee selection is implemented, maybe also includes the selected committee of next epoch, if it's selected + description: Return the information of committee members at the given epoch index. If epoch index is not provided, the current committee members are returned. + parameters: + - in: query + name: epochIndex + schema: + type: integer + example: 20 + required: false + description: The epoch index to query. + responses: + '200': + description: "Successful operation." + content: + application/json: + schema: + $ref: '#/components/schemas/CommitteeResponse' + examples: + CommitteeResponse: + $ref: '#/components/examples/get-committee-example' + '400': + description: "Unsuccessful operation: indicates that the provided data is invalid." + content: + application/json: + schema: + $ref: '#/components/schemas/BadRequestResponse' + '403': + description: "Unsuccessful operation: indicates that the endpoint is not available for public use." + content: + application/json: + schema: + $ref: '#/components/schemas/ForbiddenResponse' + '500': + description: "Unsuccessful operation: indicates that an unexpected, internal server error happened which prevented the node from fulfilling the request." + content: + application/json: + schema: + $ref: '#/components/schemas/InternalErrorResponse' + '503': + description: "Unsuccessful operation: indicates that the node is not synced." + content: + application/json: + schema: + $ref: '#/components/schemas/ServiceUnavailableResponse' + + /api/core/v3/validators: + get: + tags: + - validators + summary: Returns information of all stakers (registered validators) and if they are active, ordered by their holding stake. + parameters: + - in: query + name: pageSize + schema: + type: integer + example: 1 + required: false + description: The page number of stakers. + - in: query + name: cursor + schema: + type: string + example: "16,20" + required: false + description: Starts the search from the cursor (requested slot index+start index). + responses: + '200': + description: "Successful operation." + content: + application/json: + schema: + $ref: '#/components/schemas/ValidatorsResponse' + examples: + ValidatorsResponse: + $ref: '#/components/examples/get-validators-example' + '400': + description: "Unsuccessful operation: indicates that the provided data is invalid." + content: + application/json: + schema: + $ref: '#/components/schemas/BadRequestResponse' + '403': + description: "Unsuccessful operation: indicates that the endpoint is not available for public use." + content: + application/json: + schema: + $ref: '#/components/schemas/ForbiddenResponse' + '500': + description: "Unsuccessful operation: indicates that an unexpected, internal server error happened which prevented the node from fulfilling the request." + content: + application/json: + schema: + $ref: '#/components/schemas/InternalErrorResponse' + '503': + description: "Unsuccessful operation: indicates that the node is not synced." + content: + application/json: + schema: + $ref: '#/components/schemas/ServiceUnavailableResponse' + + /api/core/v3/validators/{bech32Address}: + get: + tags: + - validators + summary: Return information about a staker (registered validator). + parameters: + - in: path + name: bech32Address + schema: + type: string + example: "rms1pqm4xk8e9ny5w5rxjkvtp249tfhlwvcshyr3pc0665jvp7g3hc875k538hl" + required: true + description: The Account Address of the staker. + responses: + '200': + description: "Successful operation." + content: + application/json: + schema: + $ref: '#/components/schemas/Validator' + examples: + AccountStakingResponse: + $ref: '#/components/examples/get-validator-example' + '400': + description: "Unsuccessful operation: indicates that the provided data is invalid." + content: + application/json: + schema: + $ref: '#/components/schemas/BadRequestResponse' + '403': + description: "Unsuccessful operation: indicates that the endpoint is not available for public use." + content: + application/json: + schema: + $ref: '#/components/schemas/ForbiddenResponse' + '500': + description: "Unsuccessful operation: indicates that an unexpected, internal server error happened which prevented the node from fulfilling the request." + content: + application/json: + schema: + $ref: '#/components/schemas/InternalErrorResponse' + '503': + description: "Unsuccessful operation: indicates that the node is not synced." + content: + application/json: + schema: + $ref: '#/components/schemas/ServiceUnavailableResponse' + + /api/core/v3/blocks/issuance: + get: + tags: + - blocks + summary: Return information that is used to attach a block in the network. + description: >- + Return information that is used to attach a block in the network, which includes parents, last finalized slot index and the latest commitment the node created. + responses: + '200': + description: "Successful operation." + content: + application/json: + schema: + $ref: '#/components/schemas/IssuanceBlockHeaderResponse' + examples: + default: + $ref: '#/components/examples/get-buildingBlock-response-example' + '403': + description: "Unsuccessful operation: indicates that the endpoint is not available for public use." + content: + application/json: + schema: + $ref: '#/components/schemas/ForbiddenResponse' + '500': + description: "Unsuccessful operation: indicates that an unexpected, internal server error happened which prevented the node from fulfilling the request." + content: + application/json: + schema: + $ref: '#/components/schemas/InternalErrorResponse' + '503': + description: "Unsuccessful operation: indicates that there are no tips available or the node isn´t synced." + content: + application/json: + schema: + $ref: '#/components/schemas/ServiceUnavailableResponse' + + /api/core/v3/blocks: + post: + tags: + - blocks + summary: Submit a block. + description: >- + Submit a block or a payload. This endpoint will return the identifier of the built block. Only full block is accepted. + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/SubmitBlockRequest' + examples: + Full block with Tagged Data Payload: + $ref: >- + #/components/examples/tagged-data-block-example + Full block with Transaction Payload: + $ref: >- + #/components/examples/transaction-block-example + application/vnd.iota.serializer-v2: + schema: + type: string + format: binary + description: block in raw binary format + required: true + responses: + '201': + description: "Successful operation." + content: + application/json: + schema: + $ref: '#/components/schemas/SubmitBlockResponse' + examples: + default: + $ref: '#/components/examples/post-blocks-response-example' + headers: + Location: + description: The blockId of the newly created block. + schema: + type: string + '400': + description: "Unsuccessful operation: indicates that the provided data is invalid." + content: + application/json: + schema: + $ref: '#/components/schemas/BadRequestResponse' + '403': + description: "Unsuccessful operation: indicates that the endpoint is not available for public use." + content: + application/json: + schema: + $ref: '#/components/schemas/ForbiddenResponse' + '500': + description: "Unsuccessful operation: indicates that an unexpected, internal server error happened which prevented the node from fulfilling the request." + content: + application/json: + schema: + $ref: '#/components/schemas/InternalErrorResponse' + '503': + description: "Unsuccessful operation: indicates that the node can´t auto-fill the parents or perform Proof-of-Work." + content: + application/json: + schema: + $ref: '#/components/schemas/ServiceUnavailableResponse' + /api/core/v3/blocks/{blockId}: + get: + tags: + - blocks + summary: Returns block data as JSON by its identifier. + description: >- + Find a block by its identifier. This endpoint returns the given block + as JSON. + parameters: + - in: path + name: blockId + schema: + type: string + example: "0x2de585533d9c9684747e49f70e5e620a4e6c3fd1c7d8b73520c198c7def29a050200000000000000" + required: true + description: Identifier of the block. + responses: + '200': + description: "Successful operation." + content: + application/json: + schema: + $ref: '#/components/schemas/BlockResponse' + examples: + Basic Block - Empty Payload: + $ref: >- + #/components/examples/get-block-by-id-empty-response-example + Basic Block - Transaction Payload: + $ref: >- + #/components/examples/transaction-block-example + Basic Block - Tagged Data Payload: + $ref: >- + #/components/examples/tagged-data-block-example + Validation Block: + $ref: >- + #/components/examples/get-block-by-id-validation-response-example + application/vnd.iota.serializer-v2: + schema: + type: string + format: binary + description: block in raw binary format + example: >- + 0100000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000eb000000000000000000000001000000000000000000000000000000000000000000000000000000000000000000000000020000016920b176f613ec7be59e68fc68f597eb3393af80f74c7c3db78198147d5f1f92640000000000000000018afe1f314622cc1ef52f16d619d1baccff81816b7e4e35fe268dc247b730acd65d5d2dd3f7df09000000000001000001f7868ab6bb55800b77b8b74191ad8285a9bf428ace579d541fda47661803ff44e0af5c34ad4edf475a01fb46e089a7afcab158b4a0133f32e889083e1c77eef65548933e0c6d2c3b0ac006cd77e77d778bf37b8d38d219fb62a9a2f718d4c9095100000000000000 + '400': + description: "Unsuccessful operation: indicates that the provided data is invalid." + content: + application/json: + schema: + $ref: '#/components/schemas/BadRequestResponse' + '403': + description: "Unsuccessful operation: indicates that the endpoint is not available for public use." + content: + application/json: + schema: + $ref: '#/components/schemas/ForbiddenResponse' + '404': + description: "Unsuccessful operation: indicates that the requested data was not found." + content: + application/json: + schema: + $ref: '#/components/schemas/NotFoundResponse' + '500': + description: "Unsuccessful operation: indicates that an unexpected, internal server error happened which prevented the node from fulfilling the request." + content: + application/json: + schema: + $ref: '#/components/schemas/InternalErrorResponse' + '/api/core/v3/blocks/{blockId}/metadata': + get: + tags: + - blocks + summary: Find the metadata of a given block. + description: >- + Find the metadata of a given block. + parameters: + - in: path + name: blockId + schema: + type: string + example: "0x2de585533d9c9684747e49f70e5e620a4e6c3fd1c7d8b73520c198c7def29a050200000000000000" + required: true + description: Identifier of the block. + responses: + '200': + description: "Successful operation." + content: + application/json: + schema: + $ref: '#/components/schemas/BlockMetadataResponse' + examples: + New Block with Transaction Payload: + $ref: '#/components/examples/get-block-by-id-response-example-new-transaction' + New Block without Transaction Payload: + $ref: '#/components/examples/get-block-by-id-response-example-new' + Confirmed with Transaction Payload: + $ref: >- + #/components/examples/get-block-by-id-response-example-confirmed-transaction + Confirmed without Transaction Payload: + $ref: >- + #/components/examples/get-block-by-id-response-example-confirmed + Conflicting with Transaction Payload: + $ref: >- + #/components/examples/get-block-by-id-response-example-conflicting-transaction + '400': + description: "Unsuccessful operation: indicates that the provided data is invalid." + content: + application/json: + schema: + $ref: '#/components/schemas/BadRequestResponse' + '403': + description: "Unsuccessful operation: indicates that the endpoint is not available for public use." + content: + application/json: + schema: + $ref: '#/components/schemas/ForbiddenResponse' + '404': + description: "Unsuccessful operation: indicates that the requested data was not found." + content: + application/json: + schema: + $ref: '#/components/schemas/NotFoundResponse' + '500': + description: "Unsuccessful operation: indicates that an unexpected, internal server error happened which prevented the node from fulfilling the request." + content: + application/json: + schema: + $ref: '#/components/schemas/InternalErrorResponse' + '503': + description: "Unsuccessful operation: indicates that the node is not synced." + content: + application/json: + schema: + $ref: '#/components/schemas/ServiceUnavailableResponse' + '/api/core/v3/blocks/{blockId}/full': + get: + tags: + - blocks + summary: Find the metadata of a given block. + description: >- + Find the metadata of a given block. + parameters: + - in: path + name: blockId + schema: + type: string + example: "0x2de585533d9c9684747e49f70e5e620a4e6c3fd1c7d8b73520c198c7def29a050200000000000000" + required: true + description: Identifier of the block. + responses: + '200': + description: "Successful operation." + content: + application/json: + schema: + $ref: '#/components/schemas/BlockFullResponse' + examples: + default: + $ref: '#/components/examples/get-full-block-by-id-tagged-data-response-example' + '400': + description: "Unsuccessful operation: indicates that the provided data is invalid." + content: + application/json: + schema: + $ref: '#/components/schemas/BadRequestResponse' + '403': + description: "Unsuccessful operation: indicates that the endpoint is not available for public use." + content: + application/json: + schema: + $ref: '#/components/schemas/ForbiddenResponse' + '404': + description: "Unsuccessful operation: indicates that the requested data was not found." + content: + application/json: + schema: + $ref: '#/components/schemas/NotFoundResponse' + '500': + description: "Unsuccessful operation: indicates that an unexpected, internal server error happened which prevented the node from fulfilling the request." + content: + application/json: + schema: + $ref: '#/components/schemas/InternalErrorResponse' + '503': + description: "Unsuccessful operation: indicates that the node is not synced." + content: + application/json: + schema: + $ref: '#/components/schemas/ServiceUnavailableResponse' + + '/api/core/v3/outputs/{outputId}': + get: + tags: + - UTXO + summary: Find an output by its identifier. + description: Find an output by its identifier. + parameters: + - in: path + name: outputId + schema: + type: string + required: true + description: >- + Identifier of the output encoded in hex. An output is identified by + the concatenation of `transactionId+outputIndex` where `outputIndex` needs to be converted to little endian first. + Hex-encoded with 0x prefix. + example: "0xfa0de75d225cca2799395e5fc340702fc7eac821d2bdd79911126f131ae097a20100" + responses: + '200': + description: "Successful operation." + content: + application/json: + schema: + $ref: '#/components/schemas/OutputResponse' + examples: + default: + $ref: '#/components/examples/get-outputs-by-id-response-example' + application/vnd.iota.serializer-v2: + schema: + type: string + format: binary + description: output in raw binary format + example: >- + 0440420f00000000000004056b0c542e18ac5f44a1c13c5922564b7accba030000000000010000000204007ffec9e1233204d9c6dce6812b1539ee96af691ca2e4d9065daa85907d33e5d305007ffec9e1233204d9c6dce6812b1539ee96af691ca2e4d9065daa85907d33e5d30200007ffec9e1233204d9c6dce6812b1539ee96af691ca2e4d9065daa85907d33e5d30203000102030101007ffec9e1233204d9c6dce6812b1539ee96af691ca2e4d9065daa85907d33e5d3 + '400': + description: "Unsuccessful operation: indicates that the provided data is invalid." + content: + application/json: + schema: + $ref: '#/components/schemas/BadRequestResponse' + '403': + description: "Unsuccessful operation: indicates that the endpoint is not available for public use." + content: + application/json: + schema: + $ref: '#/components/schemas/ForbiddenResponse' + '404': + description: "Unsuccessful operation: indicates that the requested data was not found." + content: + application/json: + schema: + $ref: '#/components/schemas/NotFoundResponse' + '500': + description: "Unsuccessful operation: indicates that an unexpected, internal server error happened which prevented the node from fulfilling the request." + content: + application/json: + schema: + $ref: '#/components/schemas/InternalErrorResponse' + '/api/core/v3/outputs/{outputId}/metadata': + get: + tags: + - UTXO + summary: Returns metadata about an output by its identifier. + description: Returns metadata about an output by its identifier. + parameters: + - in: path + name: outputId + schema: + type: string + required: true + description: >- + Identifier of the output encoded in hex. An output is identified by + the concatenation of `transactionId+outputIndex` where `outputIndex` (u16) needs to be converted to little endian first. + Hex-encoded with 0x prefix. + example: "0xfa0de75d225cca2799395e5fc340702fc7eac821d2bdd79911126f131ae097a20100" + responses: + '200': + description: "Successful operation." + content: + application/json: + schema: + $ref: '#/components/schemas/OutputMetadataResponse' + examples: + unspent: + $ref: '#/components/examples/get-output-metadata-by-id-response-unspent-example' + spent: + $ref: '#/components/examples/get-output-metadata-by-id-response-spent-example' + '400': + description: "Unsuccessful operation: indicates that the provided data is invalid." + content: + application/json: + schema: + $ref: '#/components/schemas/BadRequestResponse' + '403': + description: "Unsuccessful operation: indicates that the endpoint is not available for public use." + content: + application/json: + schema: + $ref: '#/components/schemas/ForbiddenResponse' + '404': + description: "Unsuccessful operation: indicates that the requested data was not found." + content: + application/json: + schema: + $ref: '#/components/schemas/NotFoundResponse' + '500': + description: "Unsuccessful operation: indicates that an unexpected, internal server error happened which prevented the node from fulfilling the request." + content: + application/json: + schema: + $ref: '#/components/schemas/InternalErrorResponse' + '/api/core/v3/outputs/{outputId}/full': + get: + tags: + - UTXO + summary: Returns metadata about an output and the output structure by its identifier. + description: Returns the output structure and metadata by its identifier. + parameters: + - in: path + name: outputId + schema: + type: string + required: true + description: >- + Identifier of the output encoded in hex. An output is identified by + the concatenation of `transactionId+outputIndex` where `outputIndex` (u16) needs to be converted to little endian first. + Hex-encoded with 0x prefix. + example: "0xfa0de75d225cca2799395e5fc340702fc7eac821d2bdd79911126f131ae097a20100" + responses: + '200': + description: "Successful operation." + content: + application/json: + schema: + $ref: '#/components/schemas/OutputWithMetadataResponse' + examples: + spent: + $ref: '#/components/examples/get-full-output-metadata-example' + '400': + description: "Unsuccessful operation: indicates that the provided data is invalid." + content: + application/json: + schema: + $ref: '#/components/schemas/BadRequestResponse' + '403': + description: "Unsuccessful operation: indicates that the endpoint is not available for public use." + content: + application/json: + schema: + $ref: '#/components/schemas/ForbiddenResponse' + '404': + description: "Unsuccessful operation: indicates that the requested data was not found." + content: + application/json: + schema: + $ref: '#/components/schemas/NotFoundResponse' + '500': + description: "Unsuccessful operation: indicates that an unexpected, internal server error happened which prevented the node from fulfilling the request." + content: + application/json: + schema: + $ref: '#/components/schemas/InternalErrorResponse' + + '/api/core/v3/transactions/{transactionId}/included-block': + get: + tags: + - UTXO + summary: Returns the earliest block containing the transaction that was confirmed. + description: Returns the earliest block containing the transaction that was confirmed. + parameters: + - in: path + name: transactionId + schema: + type: string + example: "0xaf7579fb57746219561072c2cc0e4d0fbb8d493d075bd21bf25ae81a450c11ef" + required: true + description: Identifier of the transaction to look up. + responses: + '200': + description: "Successful operation." + content: + application/json: + schema: + $ref: '#/components/schemas/BlockResponse' + examples: + default: + $ref: '#/components/examples/transaction-block-example' + application/vnd.iota.serializer-v2: + schema: + type: string + format: binary + description: block in raw binary format + example: >- + 0204174e3151f6ce2cfb7f00829ac4a96a35caa2078cc20eba99359867cd21aad0d65807bb4ad068e6cdadd103218e4e24ed55b62c985d4f64e97808d9f09180f89c7a09324557e9200f39bf493fc8fd6ac43e9ca750c6f6d884cc72386ddcb7d695de9e9d780ba7ebeebc38da16cb53b2a8991d38eee94bcdc3f3ef99aa8c345652530100000600000001c9b000b41dc00400010000af7579fb57746219561072c2cc0e4d0fbb8d493d075bd21bf25ae81a450c11ef00000e6c2998f5177834ecb3bae1596d5056af76e487386eecb19727465b4be86a79010003a08601000000000000010000a18996d96163405e3c0eb13fa3459a07f68a89e8cf7cc239c89e7192344daa5b0069000000050000000b68656c6c6f20776f726c64550000005370616d6d696e6720646174612e0a436f756e743a203037323935320a54696d657374616d703a20323032312d30322d31315431303a32333a34392b30313a30300a54697073656c656374696f6e3a203934c2b57301000000ee26ac07834c603c22130fced361ca58552b0dbfc63e4b73ba24b3b59d9f40500492a353f96883c472e2686a640e77eda30be8fcc417aa9fc1c15eae854661e0253287be6ea68f649f19ca590de0a6c57fb88635ef0e013310e0be2b8360950350390000000000f0 + '400': + description: "Unsuccessful operation: indicates that the provided data is invalid." + content: + application/json: + schema: + $ref: '#/components/schemas/BadRequestResponse' + '403': + description: "Unsuccessful operation: indicates that the endpoint is not available for public use." + content: + application/json: + schema: + $ref: '#/components/schemas/ForbiddenResponse' + '404': + description: "Unsuccessful operation: indicates that the requested data was not found." + content: + application/json: + schema: + $ref: '#/components/schemas/NotFoundResponse' + '500': + description: "Unsuccessful operation: indicates that an unexpected, internal server error happened which prevented the node from fulfilling the request." + content: + application/json: + schema: + $ref: '#/components/schemas/InternalErrorResponse' + '/api/core/v3/transactions/{transactionId}/included-block/metadata': + get: + tags: + - UTXO + summary: Find the metadata of the earliest block containing the transaction that was confirmed. + description: >- + Find the metadata of the earliest block containing the transaction that was confirmed. + parameters: + - in: path + name: transactionId + schema: + type: string + example: "0xaf7579fb57746219561072c2cc0e4d0fbb8d493d075bd21bf25ae81a450c11ef" + required: true + description: Identifier of the transaction to look up. + responses: + '200': + description: "Successful operation." + content: + application/json: + schema: + $ref: '#/components/schemas/BlockMetadataResponse' + examples: + default: + $ref: '#/components/examples/get-block-by-id-response-example-confirmed-transaction' + '400': + description: "Unsuccessful operation: indicates that the provided data is invalid." + content: + application/json: + schema: + $ref: '#/components/schemas/BadRequestResponse' + '403': + description: "Unsuccessful operation: indicates that the endpoint is not available for public use." + content: + application/json: + schema: + $ref: '#/components/schemas/ForbiddenResponse' + '404': + description: "Unsuccessful operation: indicates that the requested data was not found." + content: + application/json: + schema: + $ref: '#/components/schemas/NotFoundResponse' + '500': + description: "Unsuccessful operation: indicates that an unexpected, internal server error happened which prevented the node from fulfilling the request." + content: + application/json: + schema: + $ref: '#/components/schemas/InternalErrorResponse' + '503': + description: "Unsuccessful operation: indicates that the node is not synced." + content: + application/json: + schema: + $ref: '#/components/schemas/ServiceUnavailableResponse' + + '/api/core/v3/transactions/{transactionId}/metadata': + get: + tags: + - UTXO + summary: Find the metadata of the transaction. + description: >- + Find the metadata of the transaction. + parameters: + - in: path + name: transactionId + schema: + type: string + example: "0xaf7579fb57746219561072c2cc0e4d0fbb8d493d075bd21bf25ae81a450c11ef" + required: true + description: Identifier of the transaction to look up. + responses: + '200': + description: "Successful operation." + content: + application/json: + schema: + $ref: '#/components/schemas/TransactionMetadataResponse' + examples: + default: + $ref: '#/components/examples/get-transaction-metadata-by-id-response-example' + '400': + description: "Unsuccessful operation: indicates that the provided data is invalid." + content: + application/json: + schema: + $ref: '#/components/schemas/BadRequestResponse' + '403': + description: "Unsuccessful operation: indicates that the endpoint is not available for public use." + content: + application/json: + schema: + $ref: '#/components/schemas/ForbiddenResponse' + '404': + description: "Unsuccessful operation: indicates that the requested data was not found." + content: + application/json: + schema: + $ref: '#/components/schemas/NotFoundResponse' + '500': + description: "Unsuccessful operation: indicates that an unexpected, internal server error happened which prevented the node from fulfilling the request." + content: + application/json: + schema: + $ref: '#/components/schemas/InternalErrorResponse' + '503': + description: "Unsuccessful operation: indicates that the node is not synced." + content: + application/json: + schema: + $ref: '#/components/schemas/ServiceUnavailableResponse' + + '/api/core/v3/commitments/{commitmentId}': + get: + tags: + - commitments + summary: Look up a commitment by a given commitment ID. + description: Look up a commitment by a given commitment ID. + parameters: + - in: path + name: commitmentId + schema: + type: string + example: "0x7a09324557e9200f39bf493fc8fd6ac43e9ca750c6f6d884cc72386ddcb7d695" + required: true + description: Commitment ID of the commitment to look up. + responses: + '200': + description: "Successful operation." + content: + application/json: + schema: + $ref: '#/components/schemas/Commitment' + examples: + default: + $ref: >- + #/components/examples/get-commitment-response-example + application/vnd.iota.serializer-v2: + schema: + type: string + format: binary + description: Commitment in raw binary format + examples: + default: + $ref: >- + #/components/examples/get-commitment-response-binary-example + '400': + description: "Unsuccessful operation: indicates that the provided data is invalid." + content: + application/json: + schema: + $ref: '#/components/schemas/BadRequestResponse' + '403': + description: "Unsuccessful operation: indicates that the endpoint is not available for public use." + content: + application/json: + schema: + $ref: '#/components/schemas/ForbiddenResponse' + '404': + description: "Unsuccessful operation: indicates that the requested data was not found." + content: + application/json: + schema: + $ref: '#/components/schemas/NotFoundResponse' + '500': + description: "Unsuccessful operation: indicates that an unexpected, internal server error happened which prevented the node from fulfilling the request." + content: + application/json: + schema: + $ref: '#/components/schemas/InternalErrorResponse' + '/api/core/v3/commitments/{commitmentId}/utxo-changes': + get: + tags: + - commitments + summary: Get all UTXO changes of a given slot by commitment ID. + description: Get all UTXO changes of a given slot by Commitment ID. + parameters: + - in: path + name: commitmentId + schema: + type: string + example: "0x7a09324557e9200f39bf493fc8fd6ac43e9ca750c6f6d884cc72386ddcb7d695" + required: true + description: Commitment ID of the commitment to look up. + responses: + '200': + description: "Successful operation." + content: + application/json: + schema: + $ref: '#/components/schemas/UTXOChangesResponse' + examples: + default: + $ref: >- + #/components/examples/get-utxo-changes-response-example + '400': + description: "Unsuccessful operation: indicates that the provided data is invalid." + content: + application/json: + schema: + $ref: '#/components/schemas/BadRequestResponse' + '403': + description: "Unsuccessful operation: indicates that the endpoint is not available for public use." + content: + application/json: + schema: + $ref: '#/components/schemas/ForbiddenResponse' + '404': + description: "Unsuccessful operation: indicates that the requested data was not found." + content: + application/json: + schema: + $ref: '#/components/schemas/NotFoundResponse' + '500': + description: "Unsuccessful operation: indicates that an unexpected, internal server error happened which prevented the node from fulfilling the request." + content: + application/json: + schema: + $ref: '#/components/schemas/InternalErrorResponse' + '/api/core/v3/commitments/{commitmentId}/utxo-changes/full': + get: + tags: + - commitments + summary: Get all UTXO changes of a given slot by commitment ID. + description: Get all UTXO changes of a given slot by Commitment ID. + parameters: + - in: path + name: commitmentId + schema: + type: string + example: "0x7a09324557e9200f39bf493fc8fd6ac43e9ca750c6f6d884cc72386ddcb7d695" + required: true + description: Commitment ID of the commitment to look up. + responses: + '200': + description: "Successful operation." + content: + application/json: + schema: + $ref: '#/components/schemas/UTXOChangesFullResponse' + examples: + default: + $ref: >- + #/components/examples/get-utxo-changes-full-response-example + '400': + description: "Unsuccessful operation: indicates that the provided data is invalid." + content: + application/json: + schema: + $ref: '#/components/schemas/BadRequestResponse' + '403': + description: "Unsuccessful operation: indicates that the endpoint is not available for public use." + content: + application/json: + schema: + $ref: '#/components/schemas/ForbiddenResponse' + '404': + description: "Unsuccessful operation: indicates that the requested data was not found." + content: + application/json: + schema: + $ref: '#/components/schemas/NotFoundResponse' + '500': + description: "Unsuccessful operation: indicates that an unexpected, internal server error happened which prevented the node from fulfilling the request." + content: + application/json: + schema: + $ref: '#/components/schemas/InternalErrorResponse' + + '/api/core/v3/commitments/by-slot/{slot}': + get: + tags: + - commitments + summary: Look up a commitment by a given commitment index. + description: Look up a commitment by a given commitment index. + parameters: + - in: path + name: slot + schema: + type: integer + example: 154862 + required: true + description: Index of the commitment to look up. + responses: + '200': + description: "Successful operation." + content: + application/json: + schema: + $ref: '#/components/schemas/Commitment' + examples: + default: + $ref: >- + #/components/examples/get-commitment-response-example + application/vnd.iota.serializer-v2: + schema: + type: string + format: binary + description: Commitment in raw binary format + examples: + default: + $ref: >- + #/components/examples/get-commitment-response-binary-example + '400': + description: "Unsuccessful operation: indicates that the provided data is invalid." + content: + application/json: + schema: + $ref: '#/components/schemas/BadRequestResponse' + '403': + description: "Unsuccessful operation: indicates that the endpoint is not available for public use." + content: + application/json: + schema: + $ref: '#/components/schemas/ForbiddenResponse' + '404': + description: "Unsuccessful operation: indicates that the requested data was not found." + content: + application/json: + schema: + $ref: '#/components/schemas/NotFoundResponse' + '500': + description: "Unsuccessful operation: indicates that an unexpected, internal server error happened which prevented the node from fulfilling the request." + content: + application/json: + schema: + $ref: '#/components/schemas/InternalErrorResponse' + '/api/core/v3/commitments/by-slot/{slot}/utxo-changes': + get: + tags: + - commitments + summary: Get all UTXO changes of a given slot by commitment index. + description: Get all UTXO changes of a given slot by commitment index. + parameters: + - in: path + name: slot + schema: + type: integer + example: 154862 + required: true + description: Index of the commitment to look up. + responses: + '200': + description: "Successful operation." + content: + application/json: + schema: + $ref: '#/components/schemas/UTXOChangesResponse' + examples: + default: + $ref: >- + #/components/examples/get-utxo-changes-response-example + '400': + description: "Unsuccessful operation: indicates that the provided data is invalid." + content: + application/json: + schema: + $ref: '#/components/schemas/BadRequestResponse' + '403': + description: "Unsuccessful operation: indicates that the endpoint is not available for public use." + content: + application/json: + schema: + $ref: '#/components/schemas/ForbiddenResponse' + '404': + description: "Unsuccessful operation: indicates that the requested data was not found." + content: + application/json: + schema: + $ref: '#/components/schemas/NotFoundResponse' + '500': + description: "Unsuccessful operation: indicates that an unexpected, internal server error happened which prevented the node from fulfilling the request." + content: + application/json: + schema: + $ref: '#/components/schemas/InternalErrorResponse' + '/api/core/v3/commitments/by-slot/{slot}/utxo-changes/full': + get: + tags: + - commitments + summary: Get all UTXO changes of a given slot index. + description: Get all UTXO changes of a given slot index. + parameters: + - in: path + name: slot + schema: + type: integer + example: 154862 + required: true + description: Index of the commitment to look up. + responses: + '200': + description: "Successful operation." + content: + application/json: + schema: + $ref: '#/components/schemas/UTXOChangesFullResponse' + examples: + default: + $ref: >- + #/components/examples/get-utxo-changes-full-response-example + '400': + description: "Unsuccessful operation: indicates that the provided data is invalid." + content: + application/json: + schema: + $ref: '#/components/schemas/BadRequestResponse' + '403': + description: "Unsuccessful operation: indicates that the endpoint is not available for public use." + content: + application/json: + schema: + $ref: '#/components/schemas/ForbiddenResponse' + '404': + description: "Unsuccessful operation: indicates that the requested data was not found." + content: + application/json: + schema: + $ref: '#/components/schemas/NotFoundResponse' + '500': + description: "Unsuccessful operation: indicates that an unexpected, internal server error happened which prevented the node from fulfilling the request." + content: + application/json: + schema: + $ref: '#/components/schemas/InternalErrorResponse' + +components: + examples: + get-routes-response-example: + value: + routes: + - "core/v3" + - "dashboard-metrics/v2" + - "debug/v2" + get-info-response-example: + value: + name: test + version: 2.0.0 + status: + isHealthy: false + acceptedTangleTime: "1690879505000000000" + relativeAcceptedTangleTime: "1690879505000000000" + confirmedTangleTime: "1690879505000000000" + relativeConfirmedTangleTime: "1690879505000000000" + latestCommitmentId: "0xf35c9c906190e9fb02b7969ea69567e5a4bbfdbcc389f93e2b5d0c105e03979aed5b248e" + latestFinalizedSlot: 1 + latestAcceptedBlockSlot: 2 + latestConfirmedBlockSlot: 3 + pruningEpoch: 4 + metrics: + blocksPerSecond: "1.1E+00" + confirmedBlocksPerSecond: "2.2E+00" + confirmationRate: "3.3E+00" + protocolParameters: + - startEpoch: 0 + parameters: + type: 0 + version: 3 + networkName: testnet + bech32Hrp: rms + storageScoreParameters: + storageCost: "100" + factorData: 1 + offsetOutputOverhead: "10" + offsetEd25519BlockIssuerKey: "100" + offsetStakingFeature: "100" + offsetDelegation: "100" + workScoreParameters: + dataByte: 1 + block: 2 + input: 3 + contextInput: 4 + output: 5 + nativeToken: 6 + staking: 7 + blockIssuer: 8 + allotment: 9 + signatureEd25519: 10 + manaParameters: + bitsCount: 63 + generationRate: 1 + generationRateExponent: 17 + decayFactors: + - 10 + - 20 + decayFactorsExponent: 32 + decayFactorEpochsSum: 2262417561 + decayFactorEpochsSumExponent: 21 + annualDecayFactorPercentage: 70 + tokenSupply: "1813620509061365" + genesisSlot: 0 + genesisUnixTimestamp: "1695275822" + slotDurationInSeconds: 10 + slotsPerEpochExponent: 13 + stakingUnbondingPeriod: 10 + validationBlocksPerSlot: 10 + punishmentEpochs: 10 + livenessThresholdLowerBound: 15 + livenessThresholdUpperBound: 30 + minCommittableAge: 10 + maxCommittableAge: 20 + epochNearingThreshold: 60 + congestionControlParameters: + minReferenceManaCost: "1" + increase: "0" + decrease: "0" + increaseThreshold: 800000 + decreaseThreshold: 500000 + schedulerRate: 100000 + maxBufferSize: 1000 + maxValidationBufferSize: 100 + versionSignalingParameters: + windowSize: 7 + windowTargetRatio: 5 + activationOffset: 7 + rewardsParameters: + profitMarginExponent: 8 + bootstrappingDuration: 1079 + rewardToGenerationRatio: 5 + initialTargetRewardsRate: "10" + finalTargetRewardsRate: "20" + poolCoefficientExponent: 11 + retentionPeriod: 384 + targetCommitteeSize: 32 + chainSwitchingThreshold: 3 + baseToken: + name: Shimmer + tickerSymbol: SMR + unit: SMR + subunit: glow + decimals: 6 + + get-buildingBlock-response-example: + value: + strongParents: + - "0x0482f0eba39a23c9a13072c93d828b55543132c47f5f57514d9e55535e9d4f4f35000000" + - "0xae7c4f55a6db8bf4841e4a38f06d32ab9bd88b927a6ba0bc19bcb19c625ff8b63c000000" + weakParents: + - "0x2e65c319e9a2c4a6ff7195f9a1ed896c43d0dded1b906979316d502b158965c23d000000" + - "0x67e57f7446b5a6f152afabb17c6077c26512278a275310a7ff2fa513f4e0b7383d000000" + shallowLikeParents: + - "0xe5fe5231630afaaba609af76787ff1ec9c6088dd17e9cf922152b3facd7bd5883e000000" + - "0xed4b771b5413f5118dd80021ca07fb727e4c54eec9d28d6566c28cc81e7d267c3f000000" + latestParentBlockIssuingTime: "1690879505000000000" + latestFinalizedSlot: 1422 + latestCommitment: + protocolVersion: 3 + slot: 1432 + previousCommitmentId: "0xc0300d55fe2cdc93191e52685da009f53d40883ae111291e550eed4e7eb7752746010000" + rootsId: "0x6a8f424929e1f08d87a204efc8a60499b789465aaa28178b77debe75cc2915d3" + cumulativeWeight: '45678' + referenceManaCost: '12345' + + post-blocks-response-example: + value: + blockId: "0x0482f0eba39a23c9a13072c93d828b55543132c47f5f57514d9e55535e9d4f4f35000000" + + get-block-by-id-response-example-new-transaction: + value: + blockId: "0x0482f0eba39a23c9a13072c93d828b55543132c47f5f57514d9e55535e9d4f4f35000000" + blockState: "pending" + transactionMetadata: + transactionId: "0x72f0dfa9ad116ade8bdac8ef291ed2fb8065c6c75d5d3666e8b2053696c94a9e00001000" + transactionState: "pending" + + get-block-by-id-response-example-new: + value: + blockId: "0x0482f0eba39a23c9a13072c93d828b55543132c47f5f57514d9e55535e9d4f4f35000000" + blockState: "pending" + + get-block-by-id-response-example-confirmed-transaction: + value: + blockId: "0xf7ac0552041789a3931ae76eafa47df063632cddd3f8b11bd0bfffba1bc8c46800000000" + blockState: "confirmed" + transactionMetadata: + transactionId: "0x72f0dfa9ad116ade8bdac8ef291ed2fb8065c6c75d5d3666e8b2053696c94a9e00001000" + transactionState: "confirmed" + + get-transaction-metadata-by-id-response-example: + value: + transactionId: "0x72f0dfa9ad116ade8bdac8ef291ed2fb8065c6c75d5d3666e8b2053696c94a9e00001000" + transactionState: "confirmed" + + get-block-by-id-response-example-confirmed: + value: + blockId: "0x3848a6d17070830206e5032fbce2ae3939e60eec0816546e074316b1f66977d04d010000" + blockState: "confirmed" + + get-block-by-id-response-example-conflicting-transaction: + value: + blockId: "0x3848a6d17070830206e5032fbce2ae3939e60eec0816546e074316b1f66977d04d010000" + blockState: "confirmed" + transactionMetadata: + transactionId: "0x72f0dfa9ad116ade8bdac8ef291ed2fb8065c6c75d5d3666e8b2053696c94a9e00001000" + transactionState: "failed" + transactionFailureReason: 2 + + tagged-data-block-example: + value: + header: + protocolVersion: 3 + networkId: "8342982141227064571" + issuingTime: "1695275852000000000" + slotCommitmentId: "0x3a1e3b617060146e0362361a4b752833186108395f3b2b3d3e6c655e287d70767ea58d2a" + latestFinalizedSlot: 500 + issuerId: "0x17432c5a7a672503480241125e3952414a7a320441080c624c264b004e09614a" + body: + type: 0 + strongParents: + - "0x27e0461873f37040c9e59c35ad8a106fa1b94f5ec9ef89499b31904f9a3de59be58dd44a" + - "0x714821f8f257e0a502b71ac7ee57530bb9dc29fe12ff3936f925b835a297680400b76948" + - "0x9951e512546cd9c9fbdab348b6cba91a601a29b50854e55a6e14f6803ca1d81ac7eff5ce" + - "0xaaa7bacf26f1aa4754d42edeab45d6169ea723b7fdf0f6ff3b6ebe90d09dbff6bc553936" + - "0xba75a143de4ac932986fbe7b1d78f639bc6ee8aee10d510d41572851530be884778052aa" + - "0xea5315941f4337752905599710b55e64018c71f4d8f299d0636d50484d05e6ac5667b503" + payload: + type: 0 + tag: "0x746167" + data: "0x6c754128356c071e5549764a48427b" + maxBurnedMana: "864" + signature: + type: 0 + publicKey: "0x2daefbcbadd044da470acd2f7fcf6fcb04b873cc801e7ee408018e1dfa0257ac" + signature: "0xc2982c2476379db0c8d39a204801163fc05dc1c7aa7df537e6041f91491943ab1de29a2dfe6076588c53b8d2ccf5eabe49f2cb64198303682859fd0c58348b0d" + + transaction-block-example: + value: + header: + protocolVersion: 3 + networkId: "8342982141227064571" + issuingTime: "1695275942000000000" + slotCommitmentId: "0x3a1e3b617060146e0362361a4b752833186108395f3b2b3d3e6c655e287d707601000000" + latestFinalizedSlot: 0 + issuerId: "0x17432c5a7a672503480241125e3952414a7a320441080c624c264b004e09614a" + body: + type: 0 + strongParents: + - "0x27e0461873f37040c9e59c35ad8a106fa1b94f5ec9ef89499b31904f9a3de59be58dd44a" + - "0x714821f8f257e0a502b71ac7ee57530bb9dc29fe12ff3936f925b835a297680400b76948" + - "0x9951e512546cd9c9fbdab348b6cba91a601a29b50854e55a6e14f6803ca1d81ac7eff5ce" + - "0xaaa7bacf26f1aa4754d42edeab45d6169ea723b7fdf0f6ff3b6ebe90d09dbff6bc553936" + - "0xba75a143de4ac932986fbe7b1d78f639bc6ee8aee10d510d41572851530be884778052aa" + - "0xea5315941f4337752905599710b55e64018c71f4d8f299d0636d50484d05e6ac5667b503" + payload: + type: 1 + transaction: + networkId: "8342982141227064571" + creationSlot: 11 + contextInputs: + - type: 0 + commitmentId: "0x3a1e3b617060146e0362361a4b752833186108395f3b2b3d3e6c655e287d707601000000" + - type: 1 + accountId: "0x17432c5a7a672503480241125e3952414a7a320441080c624c264b004e09614a" + - type: 2 + index: 0 + inputs: + - type: 0 + transactionId: "0xf09d3cd648a7246c7c1b2ba2f9182465ae5742b78c592392b4b455ab8ed7195200000000" + transactionOutputIndex: 0 + - type: 0 + transactionId: "0xd2c5ccba12b6fad51652131289867492799c9fc5710244418aa6e955f8fa826100000000" + transactionOutputIndex: 0 + allotments: + - accountId: "0x476820096e7038107d071a4e473f1e295f346e2d0824263e5e3e7d004f6b6915" + mana: "2189" + - accountId: "0x7e0d0a5848362b23120f55115b096774036d7610137a631413221f5573344507" + mana: "2285" + capabilities: "0x01" + outputs: + - type: 0 + amount: "100000" + mana: "0" + unlockConditions: + - type: 0 + address: + type: 0 + pubKeyHash: "0xed1484f4d1f7d8c037087fed661dd92faccae1eed3c01182d6fdd6828cea144a" + features: + - type: 5 + id: "0x086372557616532f714f104e5f44297b7a286d077956291a6d4f59081f484463712a64300c00" + amount: "0x14be8149371263f4" + - type: 1 + amount: "100000" + mana: "5000" + accountId: "0x0000000000000000000000000000000000000000000000000000000000000000" + foundryCounter: 0 + unlockConditions: + - type: 0 + address: + type: 0 + pubKeyHash: "0xed1484f4d1f7d8c037087fed661dd92faccae1eed3c01182d6fdd6828cea144a" + features: + - type: 2 + entries: + hello: "0x776f726c64" + - type: 6 + expirySlot: 4294967295 + blockIssuerKeys: + - type: 0 + pubKeyHash: "0x295409de79016133647d4078cb01618a4ba018eb74ff613138d8ff8dc05de73c" + - type: 0 + pubKeyHash: "0x868f4c6ef7b5b1d55838cbfb8ae4f3a9776c53cdd3e3d33000094d72acab5a2f" + - type: 7 + stakedAmount: "10000" + fixedCost: "400" + startEpoch: 0 + endEpoch: 4294967295 + unlocks: + - type: 0 + signature: + type: 0 + publicKey: "0x2daefbcbadd044da470acd2f7fcf6fcb04b873cc801e7ee408018e1dfa0257ac" + signature: "0x5bb409d59e01d2ea9f1a1fb67feb681d0d3ecb05787cadad2f89fdf13ef7ff03ad5cebf28df5dddd8510992596d98b133f86e14f76824e6ccc369a8f5df44806" + - type: 1 + reference: 0 + maxBurnedMana: "864" + signature: + type: 0 + publicKey: "0x2daefbcbadd044da470acd2f7fcf6fcb04b873cc801e7ee408018e1dfa0257ac" + signature: "0xb4300837bafda6e0e590124b367a1beb87abd9afbde50bc2afe5e335c7118c13ba59ba58d082eb329c84f527a536bf2c1943b3bcf0444d770dcf7b05f135f50a" + + get-committee-example: + value: + epoch: 10 + totalStake: '900000000' + totalValidatorStake: '60000000' + committee: + - address: "rms1pqm4xk8e9ny5w5rxjkvtp249tfhlwvcshyr3pc0665jvp7g3hc875k538hl" + poolStake: '200000' + validatorStake: '100000' + fixedCost: '50000' + - address: "rms1pp4wuuz0y42caz48vv876qfpmffswsvg40zz8v79sy8cp0jfxm4kunflcgt" + poolStake: '205000' + validatorStake: '90000' + fixedCost: '52000' + + get-validators-example: + value: + validators: + - address: "rms1pp4wuuz0y42caz48vv876qfpmffswsvg40zz8v79sy8cp0jfxm4kunflcgt" + stakingEndEpoch: 100 + poolStake: '200000' + validatorStake: '100000' + fixedCost: '50000' + active: false + latestSupportedProtocolVersion: 3 + latestSupportedProtocolHash: "0x0c00425134785bf2dbe42e4ec7e288009ebdc38ced797beaa45d5213092021cb" + - address: "rms1pqm4xk8e9ny5w5rxjkvtp249tfhlwvcshyr3pc0665jvp7g3hc875k538hl" + stakingEndEpoch: 10 + poolStake: '205000' + validatorStake: '90000' + fixedCost: '52000' + active: true + latestSupportedProtocolVersion: 3 + latestSupportedProtocolHash: "0x0c00425134785bf2dbe42e4ec7e288009ebdc38ced797beaa45d5213092021cb" + pageSize: 50 + + get-validator-example: + value: + address: "rms1pqm4xk8e9ny5w5rxjkvtp249tfhlwvcshyr3pc0665jvp7g3hc875k538hl" + stakingEndEpoch: 100 + poolStake: '205000' + validatorStake: '90000' + fixedCost: '52000' + active: true + latestSupportedProtocolVersion: 3 + latestSupportedProtocolHash: "0x0c00425134785bf2dbe42e4ec7e288009ebdc38ced797beaa45d5213092021cb" + + get-mana-rewards-example: + value: + startEpoch: 60 + endEpoch: 80 + rewards: '800000' + latestCommittedEpochPoolRewards: '0' + + get-congestion-estimate-response-example: + value: + slot: 20 + ready: true + referenceManaCost: '50000' + blockIssuanceCredits: '10000000' + + get-block-by-id-empty-response-example: + value: + header: + protocolVersion: 3 + networkId: "8342982141227064571" + issuingTime: "1695275852000000000" + slotCommitmentId: "0x3a1e3b617060146e0362361a4b752833186108395f3b2b3d3e6c655e287d70767ea58d2a" + latestFinalizedSlot: 500 + issuerId: "0x17432c5a7a672503480241125e3952414a7a320441080c624c264b004e09614a" + body: + type: 0 + strongParents: + - "0x27e0461873f37040c9e59c35ad8a106fa1b94f5ec9ef89499b31904f9a3de59be58dd44a" + - "0x714821f8f257e0a502b71ac7ee57530bb9dc29fe12ff3936f925b835a297680400b76948" + - "0x9951e512546cd9c9fbdab348b6cba91a601a29b50854e55a6e14f6803ca1d81ac7eff5ce" + - "0xaaa7bacf26f1aa4754d42edeab45d6169ea723b7fdf0f6ff3b6ebe90d09dbff6bc553936" + - "0xba75a143de4ac932986fbe7b1d78f639bc6ee8aee10d510d41572851530be884778052aa" + - "0xea5315941f4337752905599710b55e64018c71f4d8f299d0636d50484d05e6ac5667b503" + maxBurnedMana: "864" + signature: + type: 0 + publicKey: "0x2daefbcbadd044da470acd2f7fcf6fcb04b873cc801e7ee408018e1dfa0257ac" + signature: "0x74e57aa62358bb91ee931c05337a3af2e624fa9b20b04fcb4e15da0a9a4b4281a50ef6384ab7977179d16bd326cebb714c4653e1711447f18cefe1066aa1610d" + + + get-full-block-by-id-tagged-data-response-example: + value: + block: + header: + protocolVersion: 3 + networkId: "8342982141227064571" + issuingTime: "1695275852000000000" + slotCommitmentId: "0x3a1e3b617060146e0362361a4b752833186108395f3b2b3d3e6c655e287d70767ea58d2a" + latestFinalizedSlot: 500 + issuerId: "0x17432c5a7a672503480241125e3952414a7a320441080c624c264b004e09614a" + body: + type: 0 + strongParents: + - "0x27e0461873f37040c9e59c35ad8a106fa1b94f5ec9ef89499b31904f9a3de59be58dd44a" + - "0x714821f8f257e0a502b71ac7ee57530bb9dc29fe12ff3936f925b835a297680400b76948" + - "0x9951e512546cd9c9fbdab348b6cba91a601a29b50854e55a6e14f6803ca1d81ac7eff5ce" + - "0xaaa7bacf26f1aa4754d42edeab45d6169ea723b7fdf0f6ff3b6ebe90d09dbff6bc553936" + - "0xba75a143de4ac932986fbe7b1d78f639bc6ee8aee10d510d41572851530be884778052aa" + - "0xea5315941f4337752905599710b55e64018c71f4d8f299d0636d50484d05e6ac5667b503" + payload: + type: 0 + tag: "0x746167" + data: "0x6c754128356c071e5549764a48427b" + maxBurnedMana: "864" + signature: + type: 0 + publicKey: "0x2daefbcbadd044da470acd2f7fcf6fcb04b873cc801e7ee408018e1dfa0257ac" + signature: "0xc2982c2476379db0c8d39a204801163fc05dc1c7aa7df537e6041f91491943ab1de29a2dfe6076588c53b8d2ccf5eabe49f2cb64198303682859fd0c58348b0d" + metadata: + blockId: "0x1d5f495c0f4b883cf2c79cafd382c73484c65651099329e3b0b4c969c35d620004000000" + blockState: "confirmed" + + + get-block-by-id-validation-response-example: + value: + header: + protocolVersion: 3 + networkId: "8342982141227064571" + issuingTime: "1695275852000000000" + slotCommitmentId: "0x3a1e3b617060146e0362361a4b752833186108395f3b2b3d3e6c655e287d70767ea58d2a" + latestFinalizedSlot: 500 + issuerId: "0x17432c5a7a672503480241125e3952414a7a320441080c624c264b004e09614a" + body: + type: 1 + strongParents: + - "0x27e0461873f37040c9e59c35ad8a106fa1b94f5ec9ef89499b31904f9a3de59be58dd44a" + - "0x714821f8f257e0a502b71ac7ee57530bb9dc29fe12ff3936f925b835a297680400b76948" + - "0x9951e512546cd9c9fbdab348b6cba91a601a29b50854e55a6e14f6803ca1d81ac7eff5ce" + - "0xaaa7bacf26f1aa4754d42edeab45d6169ea723b7fdf0f6ff3b6ebe90d09dbff6bc553936" + - "0xba75a143de4ac932986fbe7b1d78f639bc6ee8aee10d510d41572851530be884778052aa" + - "0xea5315941f4337752905599710b55e64018c71f4d8f299d0636d50484d05e6ac5667b503" + highestSupportedVersion: 3 + protocolParametersHash: "0x0c0a5be47669365426b3e34ecd68f8fe6c70656a54139a1e1cd6fd779bfb476f" + signature: + type: 0 + publicKey: "0x2daefbcbadd044da470acd2f7fcf6fcb04b873cc801e7ee408018e1dfa0257ac" + signature: "0x3b6185bb5757d5e7fd576eeedf0c765c44cbcfe148261b8558a942867528f2cfe5a39a6ecd7bf7e82e134867a75df05385624be8c4102b3b77b397163459460b" + + get-outputs-by-id-response-example: + value: + output: + type: 0 + amount: "1000" + unlockConditions: + - type: 0 + address: + type: 0 + pubKeyHash: "0x8eaf87ac1f52eb05f2c7c0c15502df990a228838dc37bd18de9503d69afd257d" + mana: "2000" + outputIdProof: + slot: 429632486 + outputIndex: 2 + transactionCommitment: "0x46934d8c62df21e94553f6686a7f9368d9ab4159bcb96f598a94883a866467da" + outputCommitmentProof: + type: 0 + l: + type: 0 + l: + type: 1 + hash: "0x193a27f187c46a386f0e2a25a884351692b7378aae5e7dd78433f2be85106219" + r: + type: 0 + l: + type: 2 + hash: "0x19e4cdd6b17223a935883ddbb80ee6d239a48ea214c29b8b593cc7b3152d15aa" + r: + type: 1 + hash: "0xf1faa521d1b1e85393efd63a6ed1f33bb851bfc90a681e011989d9c6056948cc" + r: + type: 1 + hash: "0xe9cef2152da49d2a78a490bb7e42c6bcd1c96b41ebe156ba90a5b22cb78e3229" + + + get-output-metadata-by-id-response-unspent-example: + value: + outputId: "0x3477de28a45c565eed3603ab9e90ce0f0d38e8860a3c5ff64ccc70252aab7c9d000000004600" + blockId: "0x1aaaa9ad9c15c6cd601a5aa5bd61b85428263978a26343949dad9ff89635e7104f1f271b" + included: + slot: 5 + transactionId: "0xfdd9e96bac5e4f029b3261c00cd3c74fb4c389184a2018c979d4f31fc1ef53c99add5c74" + commitmentId: "0xd20959ac38938fddee472bbfd47644da3087a39499cd04e86c9c70fa9c8c0516a81b8aea" + latestCommitmentId: "0xba4456279dce23cfca37938685c039ea7c72001c1cd8becf72b195a8727cdfd07949d697" + + get-full-output-metadata-example: + value: + output: + type: 0 + amount: "1000" + unlockConditions: + - type: 0 + address: + type: 0 + pubKeyHash: "0x8eaf87ac1f52eb05f2c7c0c15502df990a228838dc37bd18de9503d69afd257d" + mana: "2000" + outputIdProof: + slot: 1893592032 + outputIndex: 0 + transactionCommitment: "0xa0687905318860e64db6932d8423bf7a4418627baee62be8089d5f48aaa1af3a" + outputCommitmentProof: + type: 2 + hash: "0x7f9289b104a55e6fb93d60d70f6e85c9706c761b05ccc034f76b465837ca6070" + metadata: + outputId: "0x3130f21c723fa597805763739f3a2a40b674af6b4071ef0494331b644a7e4d52000000001300" + blockId: "0x19e589687082d8f535779df3244908ad6a7b380906fb7ae24efb5fad8a5cfb92a8f8d9a3" + included: + slot: 5 + transactionId: "0x3e766157614a3a0e13dbb937b5fb1ef5d1555479c19df80445d03a6710f39d75668bd326" + commitmentId: "0x7387ebe23a3ac1732fcdb6cef77fc003e1fa6e2dad89dd664df249d6aa2dbdc157dec2c6" + spent: + slot: 8 + transactionId: "0x3896f1ede7cbdacbbb4b17f13e953ad45ce0969ea34cc766b5dafe2a15b3e46f998ef4e5" + commitmentId: "0x26fa9fcbddcf944ced3fd16a73d9c8b2b49dc54dba7629b02da69f7e01249063e7398b2c" + latestCommitmentId: "0x42a88617c2c4ba2b58f82c8b85524720cdbe3642401e7c613f215658d617c569d1219909" + + get-output-metadata-by-id-response-spent-example: + value: + outputId: "0x3130f21c723fa597805763739f3a2a40b674af6b4071ef0494331b644a7e4d52000000001300" + blockId: "0x19e589687082d8f535779df3244908ad6a7b380906fb7ae24efb5fad8a5cfb92a8f8d9a3" + included: + slot: 5 + transactionId: "0x3e766157614a3a0e13dbb937b5fb1ef5d1555479c19df80445d03a6710f39d75668bd326" + commitmentId: "0x7387ebe23a3ac1732fcdb6cef77fc003e1fa6e2dad89dd664df249d6aa2dbdc157dec2c6" + spent: + slot: 8 + transactionId: "0x3896f1ede7cbdacbbb4b17f13e953ad45ce0969ea34cc766b5dafe2a15b3e46f998ef4e5" + commitmentId: "0x26fa9fcbddcf944ced3fd16a73d9c8b2b49dc54dba7629b02da69f7e01249063e7398b2c" + latestCommitmentId: "0x42a88617c2c4ba2b58f82c8b85524720cdbe3642401e7c613f215658d617c569d1219909" + + get-commitment-response-example: + value: + protocolVersion: 3 + slot: 986 + previousCommitmentId: "0xd91549dbf441da4c7e50063b58c05d5b2bfb1d33b346a2f9a18220ce6207f7a289010000" + rootsId: "0x6a8f424929e1f08d87a204efc8a60499b789465aaa28178b77debe75cc2915d3" + cumulativeWeight: '78901' + referenceManaCost: '600' + + get-commitment-response-binary-example: + value: "0312000000075b05e0a8fd4b9c7e7bc165b62c48945292f7d76d23f76525f886c416dc0e364089b57c32ddb8c614ed1d2c844401d2a5325b4d153c7f94464bbda3a8d14289b203f96759000000000000009000000000000000" + + get-utxo-changes-response-example: + value: + commitmentId: "0x3b264c038283c30094e0cb5d22eaa52c9959bfda084ace3980b30d4be588fa0012000000" + createdOutputs: + - "0x2628fd7c1ad5dd635fa76c6f4c2272fbdb658cc3437dbed07f9984580b227b63f0a3e4d40000" + - "0xfa3d71ea93849b317c2b29c928b726b6d3bd2131c7ad560c9e28952f117fd50c35d6e0890000" + consumedOutputs: + - "0xfa3d71ea93849b317c2b29c928b726b6d3bd2131c7ad560c9e28952f117fd50c35d6e0890100" + - "0x9c40a07de878863fbda03caeb68875254c49199e6b55740f78a4bab3686f89957b1249130000" + + get-utxo-changes-full-response-example: + value: + commitmentId: "0x7387ebe23a3ac1732fcdb6cef77fc003e1fa6e2dad89dd664df249d6aa2dbdc157dec2c6" + createdOutputs: + - outputId: "0x3130f21c723fa597805763739f3a2a40b674af6b4071ef0494331b644a7e4d52000000001300" + output: + type: 0 + amount: "1000" + unlockConditions: + - type: 0 + address: + type: 0 + pubKeyHash: "0x8eaf87ac1f52eb05f2c7c0c15502df990a228838dc37bd18de9503d69afd257d" + mana: "2000" + consumedOutputs: [] + + schemas: + + Block: + description: A block is the object nodes gossip around in the network. It always references other blocks that are known as parents. It is stored as a vertex on the tangle data structure that the nodes maintain. A block can have a maximum size of 32Kb. + properties: + header: + properties: + protocolVersion: + type: number + description: Protocol version identifier. It also tells which protocol rules apply to the block. + networkId: + type: string + description: Network version identifier. It also tells which network the node is running. + issuingTime: + type: string + description: The timestamp of issuing this block, a uint64 string in nanosecond-precision. + slotCommitmentId: + type: string + description: The slot commitment ID contains in this block. + latestFinalizedSlot: + type: integer + description: The latest finalized slot of issuing node. + issuerId: + type: string + description: The identifier of the issuer. + required: + - protocolVersion + - networkId + - issuingTime + - slotCommitmentId + - latestFinalizedSlot + - issuerId + body: + description: The block content. + oneOf: + - $ref: '#/components/schemas/BasicBlock' + - $ref: '#/components/schemas/ValidationBlock' + signature: + type: object + description: The signature of entire block, signed by the issuer. + oneOf: + - $ref: '#/components/schemas/Ed25519Signature' + required: + - header + - body + - signature + + BasicBlock: + description: A basic block is the object that can carry arbitrary payload, such as a tagged data payload or a transaction. + properties: + type: + type: integer + description: Set to value 0 to denote a Basic Block. + strongParents: + type: array + description: The identifiers of the blocks this block references. Hex-encoded data with 0x prefix. + items: + type: string + weakParents: + type: array + description: The identifiers of the blocks this block references. Hex-encoded data with 0x prefix. + items: + type: string + shallowLikeParents: + type: array + description: The identifiers of the blocks this block references. Hex-encoded data with 0x prefix. + items: + type: string + payload: + description: The inner payload of the block. Can be nil. + oneOf: + - $ref: '#/components/schemas/SignedTransactionPayload' + - $ref: '#/components/schemas/TaggedDataPayload' + maxBurnedMana: + type: string + description: The mana burned in this block. + required: + - type + - strongParents + - maxBurnedMana + + ValidationBlock: + description: A validation block is the object that issued by validators. + properties: + type: + type: integer + description: Set to value 1 to denote a Validation Block. + strongParents: + type: array + description: The identifiers of the blocks this block references. Hex-encoded data with 0x prefix. + items: + type: string + weakParents: + type: array + description: The identifiers of the blocks this block references. Hex-encoded data with 0x prefix. + items: + type: string + shallowLikeParents: + type: array + description: The identifiers of the blocks this block references. Hex-encoded data with 0x prefix. + items: + type: string + highestSupportedVersion: + type: integer + description: The highest supported version of the protocol. + protocolParametersHash: + type: string + description: The hash of the protocol parameters for the highestSupportedVersion. + required: + - type + - strongParents + - highestSupportedVersion + - protocolParametersHash + + SignedTransactionPayload: + description: The Signed Transaction Payload to be embedded into a block. + properties: + type: + type: integer + description: Set to value 1 to denote a Signed Transaction Payload. + transaction: + type: object + oneOf: + - $ref: '#/components/schemas/Transaction' + unlocks: + type: array + items: + oneOf: + - $ref: '#/components/schemas/SignatureUnlock' + - $ref: '#/components/schemas/ReferenceUnlock' + - $ref: '#/components/schemas/AccountUnlock' + - $ref: '#/components/schemas/NFTUnlock' + required: + - type + - transaction + - unlocks + + Transaction: + description: The Transaction to be embedded into a block. + properties: + networkId: + type: string + description: Network identifier. Plain string encoded number. This field signals for which network the block is meant for. It is computed out of the first 8 bytes of the `BLAKE2b-256` hash of the concatenation of the network name and protocol version string. + creationSlot: + type: integer + description: The slot index in which the transaction was created. + contextInputs: + type: array + items: + anyOf: + - $ref: '#/components/schemas/CommitmentInput' + - $ref: '#/components/schemas/BlockIssuanceCreditInput' + - $ref: '#/components/schemas/RewardInput' + inputs: + type: array + description: The inputs of this transaction. + items: + oneOf: + - $ref: '#/components/schemas/UTXOInput' + allotments: + type: array + description: The accounts map with corresponding allotment values. + items: + oneOf: + - $ref: '#/components/schemas/Allotment' + capabilities: + type: string + description: The capabilities of this transaction. + payload: + description: The optional embedded payload. + oneOf: + - $ref: '#/components/schemas/TaggedDataPayload' + outputs: + type: array + description: The outputs of this transaction. + items: + anyOf: + - $ref: '#/components/schemas/BasicOutput' + - $ref: '#/components/schemas/AccountOutput' + - $ref: '#/components/schemas/AnchorOutput' + - $ref: '#/components/schemas/FoundryOutput' + - $ref: '#/components/schemas/NFTOutput' + - $ref: '#/components/schemas/DelegationOutput' + required: + - networkId + - creationSlot + - contextInputs + - inputs + - allotments + - capabilities + - outputs + + Allotment: + description: Allotment is a struct that represents a list of account IDs and an allotted value. + properties: + accountId: + type: string + description: The account ID to allot the mana to. + mana: + type: string + description: The amount of mana to allot. + + CommitmentInput: + description: Allows to reference commitment to a certain slot. It is used to provide the VM with the necessary context information from the node, to prove that the time at the transaction execution is past certain slot in the past, as it indicates that the slot has been already committed. + properties: + type: + type: integer + description: Set to value 1 to denote a Commitment Input. + commitmentId: + type: string + description: The commitment identifier to reference. + required: + - type + - commitmentId + + # TODO: Consider rename it to CreditsInput, need to be aligned to implementaion. + BlockIssuanceCreditInput: + description: Allows to provide the VM with context for the value of the BIC vector for a specific slot. It is necessary information needed for any Account transitions, and account destroying. + properties: + type: + type: integer + description: Set to value 2 to denote an BIC Input. + accountId: + type: string + description: The account identifier. + required: + - type + - accountId + + RewardInput: + description: Allows to claim Mana rewards for a referenced account or delegation input in a transaction. This enables the transaction to add the Mana rewards on the output side if the claiming rules of the staking feature or delegation output are adhered to. + properties: + type: + type: integer + description: Set to value 3 to denote a Reward Input. + index: + type: integer + description: The index of the transaction input for which to claim rewards. + required: + - type + - index + + UTXOInput: + description: Describes an input which references an unspent transaction output to consume. + properties: + type: + type: integer + description: Set to value 0 to denote a UTXO Input. + transactionId: + type: string + description: The BLAKE2b-256 hash of the transaction from which the UTXO comes from. Hex-encoded data with 0x prefix. + transactionOutputIndex: + type: integer + description: The index of the output on the referenced transaction to consume. + required: + - type + - transactionId + - transactionOutputIndex + + BasicOutput: + description: Describes a basic output with optional features. + properties: + type: + type: integer + description: Set to value 0 to denote a Basic Output. + amount: + type: string + description: The amount of IOTA tokens to deposit with this BasicOutput output. Plain string encoded number. + mana: + type: string + description: The stored mana held by the output. + unlockConditions: + type: array + description: Unlock conditions that define how the output can be unlocked in a transaction. + items: + anyOf: + - $ref: '#/components/schemas/AddressUnlockCondition' + - $ref: '#/components/schemas/StorageDepositReturnUnlockCondition' + - $ref: '#/components/schemas/TimelockUnlockCondition' + - $ref: '#/components/schemas/ExpirationUnlockCondition' + features: + type: array + description: The features on the output + items: + anyOf: + - $ref: '#/components/schemas/SenderFeature' + - $ref: '#/components/schemas/MetadataFeature' + - $ref: '#/components/schemas/TagFeature' + - $ref: '#/components/schemas/NativeTokenFeature' + required: + - type + - amount + - mana + + AccountOutput: + description: Describes an account in the ledger that can be controlled by the state and governance controllers. + properties: + type: + type: integer + description: Set to value 1 to denote an Account Output. + amount: + type: string + description: The amount of IOTA tokens to deposit with this output. Plain string encoded number. + mana: + type: string + description: The stored mana held by the output. + accountId: + type: string + description: The identifier of the account. + foundryCounter: + type: integer + description: A counter that denotes the number of foundries created by this account. + unlockConditions: + type: array + description: Unlock conditions that define how the output can be unlocked in a transaction. + items: + anyOf: + - $ref: '#/components/schemas/AddressUnlockCondition' + features: + type: array + description: Features that add utility to the output but do not impose unlocking conditions. + items: + anyOf: + - $ref: '#/components/schemas/SenderFeature' + - $ref: '#/components/schemas/MetadataFeature' + - $ref: '#/components/schemas/BlockIssuerFeature' + - $ref: '#/components/schemas/StakingFeature' + immutableFeatures: + type: array + description: Immutable features that add utility to the output but do not impose unlocking conditions. + These features need to be kept in future transitions of the UTXO state machine. + items: + anyOf: + - $ref: '#/components/schemas/IssuerFeature' + - $ref: '#/components/schemas/MetadataFeature' + required: + - type + - amount + - accountId + - foundryCounter + - mana + + AnchorOutput: + description: Describes an anchor output. + properties: + type: + type: integer + description: Set to value 2 to denote an Anchor Output. + amount: + type: string + description: The amount of IOTA tokens to deposit with this output. Plain string encoded number. + mana: + type: string + description: The stored mana held by the output. + anchorId: + type: string + description: The identifier of the anchor. + stateIndex: + type: integer + description: A counter that must increase by 1 every time the account is state transitioned. + unlockConditions: + type: array + description: Unlock conditions that define how the output can be unlocked in a transaction. + items: + anyOf: + - $ref: '#/components/schemas/StateControllerAddressUnlockCondition' + - $ref: '#/components/schemas/GovernorAddressUnlockCondition' + features: + type: array + description: Features that add utility to the output but do not impose unlocking conditions. + items: + anyOf: + - $ref: '#/components/schemas/MetadataFeature' + - $ref: '#/components/schemas/StateMetadataFeature' + immutableFeatures: + type: array + description: Immutable features that add utility to the output but do not impose unlocking conditions. + These features need to be kept in future transitions of the UTXO state machine. + items: + anyOf: + - $ref: '#/components/schemas/IssuerFeature' + - $ref: '#/components/schemas/MetadataFeature' + required: + - type + - amount + - anchorId + - stateIndex + - mana + + DelegationOutput: + description: >- + Describes an delegation output. + properties: + type: + type: integer + description: Set to value 5 to denote a Delegation Output. + example: 5 + amount: + type: string + description: >- + The amount of IOTA tokens held by the output. Encoded as a + plain string. + example: '100' + delegatedAmount: + type: string + description: The amount of IOTA tokens that were delegated when the output was created. + delegationId: + type: string + description: >- + The identifier for this delegation output. + example: '0x1505ec099896ab05d9e08fbc7101ae4dff0093b3943b28f789ed2ca728bcc8d6' + validatorAddress: + type: string + description: >- + The Account Address of the validator to which this output is delegating. + example: '0x1505ec099896ab05d9e08fbc7101ae4dff0093b3943b28f789ed2ca728bcc8d6' + startEpoch: + type: integer + description: >- + The index of the first epoch for which this output delegates. + example: '10' + endEpoch: + type: integer + description: >- + The index of the last epoch for which this output delegates. + example: '12' + unlockConditions: + type: array + description: >- + Unlock conditions that define how the output can be unlocked in a + transaction. + items: + anyOf: + - $ref: '#/components/schemas/AddressUnlockCondition' + required: + - type + - amount + - delegatedAmount + - delegationId + - validatorAddress + - startEpoch + - endEpoch + + FoundryOutput: + description: Describes a foundry output that is controlled by an account. + properties: + type: + type: integer + description: Set to value 3 to denote a Foundry Output. + amount: + type: string + description: The amount of IOTA tokens to deposit with this output. Plain string encoded number. + serialNumber: + type: integer + description: The serial number of the foundry with respect to the controlling account. + tokenScheme: + type: array + description: Defines the supply control scheme of the tokens controlled by the foundry. + items: + oneOf: + - $ref: '#/components/schemas/SimpleTokenScheme' + unlockConditions: + type: array + description: Unlock conditions that define how the output can be unlocked in a transaction. + items: + anyOf: + - $ref: '#/components/schemas/ImmutableAccountAddressUnlockCondition' + features: + type: array + description: Features that add utility to the output but do not impose unlocking conditions. + items: + anyOf: + - $ref: '#/components/schemas/MetadataFeature' + - $ref: '#/components/schemas/NativeTokenFeature' + immutableFeatures: + type: array + description: Immutable features that add utility to the output but do not impose unlocking conditions. + These features need to be kept in future transitions of the UTXO state machine. + items: + anyOf: + - $ref: '#/components/schemas/MetadataFeature' + required: + - type + - amount + - serialNumber + - tokenScheme + + NFTOutput: + description: Describes an NFT output, a globally unique token with metadata attached. + properties: + type: + type: integer + description: Set to value 4 to denote a NFT Output. + amount: + type: string + description: The amount of IOTA tokens to deposit with this output. Plain string encoded number. + mana: + type: string + description: The stored mana held by the output + nftId: + type: string + description: Unique identifier of the NFT, which is the BLAKE2b-256 hash of the Output ID that created it. NFT Address = NFT Address Type || NFT ID. Hex-encoded data with 0x prefix. + unlockConditions: + type: array + description: Unlock conditions that define how the output can be unlocked in a transaction. + items: + anyOf: + - $ref: '#/components/schemas/AddressUnlockCondition' + - $ref: '#/components/schemas/StorageDepositReturnUnlockCondition' + - $ref: '#/components/schemas/TimelockUnlockCondition' + - $ref: '#/components/schemas/ExpirationUnlockCondition' + features: + type: array + description: Features that add utility to the output but do not impose unlocking conditions. + items: + anyOf: + - $ref: '#/components/schemas/SenderFeature' + - $ref: '#/components/schemas/MetadataFeature' + - $ref: '#/components/schemas/TagFeature' + immutableFeatures: + type: array + description: Immutable features that add utility to the output but do not impose unlocking conditions. + These features need to be kept in future transitions of the UTXO state machine. + items: + anyOf: + - $ref: '#/components/schemas/IssuerFeature' + - $ref: '#/components/schemas/MetadataFeature' + required: + - type + - amount + - nftId + - mana + + Ed25519Address: + description: The Ed25519 address. + properties: + type: + type: integer + description: Set to value 0 to denote an Ed25519 Address. + pubKeyHash: + type: string + description: The hex-encoded, 0x prefixed BLAKE2b-256 hash of the Ed25519 public key + required: + - type + - pubKeyHash + + AccountAddress: + description: Address of an account output. + properties: + type: + type: integer + description: Set to value 8 to denote an Account Address. + accountId: + type: string + description: The hex-encoded, 0x prefixed BLAKE2b-256 hash of the Output ID that created the account. + required: + - type + - accountId + + NFTAddress: + description: Address of an NFT account. + properties: + type: + type: integer + description: Set to value 16 to denote an NFT Address. + nftId: + type: string + description: The hex-encoded, 0x prefixed BLAKE2b-256 hash of the Output ID that created the NFT. + required: + - type + - nftId + + AddressUnlockCondition: + description: Can be unlocked by unlocking the address. + properties: + type: + type: integer + description: Set to value 0 to denote an Address Unlock Condition. + address: + oneOf: + - $ref: '#/components/schemas/Ed25519Address' + - $ref: '#/components/schemas/AccountAddress' + - $ref: '#/components/schemas/NFTAddress' + required: + - type + - address + + ImmutableAccountAddressUnlockCondition: + description: Can be unlocked by unlocking the permanent account. + The unlock condition has to be kept in future state transitions of the UTXO state machine. + properties: + type: + type: integer + description: Set to value 6 to denote an Immutable Account Address Unlock Condition. + address: + oneOf: + - $ref: '#/components/schemas/AccountAddress' + required: + - type + - address + + StorageDepositReturnUnlockCondition: + description: Can be unlocked by depositing return amount to return address via an output that only has Address Unlock Condition. + properties: + type: + type: integer + description: Set to value 1 to denote a Storage Deposit Return Unlock Condition. + returnAddress: + oneOf: + - $ref: '#/components/schemas/Ed25519Address' + - $ref: '#/components/schemas/AccountAddress' + - $ref: '#/components/schemas/NFTAddress' + amount: + type: string + description: Amount of IOTA tokens the consuming transaction must deposit to the address defined in Return Address. Plain string encoded number. + required: + - type + - returnAddress + - amount + + TimelockUnlockCondition: + description: Can be unlocked if the CTT (Confirmed Tangle Time) has a >= Unix Timestamp. + properties: + type: + type: integer + description: Set to value 2 to denote a Timelock Unlock Condition. + slot: + type: integer + description: The slot index until which the timelock applies (inclusive). + required: + - type + + ExpirationUnlockCondition: + description: Defines a unix time until which only Address, defined in Address Unlock Condition, is allowed to unlock the output. After the unix time, only Return Address can unlock it. + properties: + type: + type: integer + description: Set to value 3 to denote an Expiration Unlock Condition. + returnAddress: + oneOf: + - $ref: '#/components/schemas/Ed25519Address' + - $ref: '#/components/schemas/AccountAddress' + - $ref: '#/components/schemas/NFTAddress' + slot: + type: integer + description: The slot index at which the expiration happens. + required: + - type + - returnAddress + + StateControllerAddressUnlockCondition: + description: Can be unlocked by unlocking the address. + properties: + type: + type: integer + description: Set to value 4 to denote a State Controller Address Unlock Condition. + address: + oneOf: + - $ref: '#/components/schemas/Ed25519Address' + - $ref: '#/components/schemas/AccountAddress' + - $ref: '#/components/schemas/NFTAddress' + required: + - type + - address + + GovernorAddressUnlockCondition: + description: Can be unlocked by unlocking the address. + properties: + type: + type: integer + description: Set to value 5 to denote a Governor Address Unlock Condition. + address: + oneOf: + - $ref: '#/components/schemas/Ed25519Address' + - $ref: '#/components/schemas/AccountAddress' + - $ref: '#/components/schemas/NFTAddress' + required: + - type + - address + + SenderFeature: + description: Identifies the validated sender of the output. + properties: + type: + type: integer + description: Set to value 0 to denote a Sender Feature. + address: + oneOf: + - $ref: '#/components/schemas/Ed25519Address' + - $ref: '#/components/schemas/AccountAddress' + - $ref: '#/components/schemas/NFTAddress' + required: + - type + - address + + IssuerFeature: + description: Identifies the validated issuer of the UTXO state machine (account/NFT). + properties: + type: + type: integer + description: Set to value 1 to denote an Issuer Feature. + address: + oneOf: + - $ref: '#/components/schemas/Ed25519Address' + - $ref: '#/components/schemas/AccountAddress' + - $ref: '#/components/schemas/NFTAddress' + required: + - type + - address + + BlockIssuerFeature: + description: A feature which indicates that this account can issue blocks. + properties: + type: + type: integer + description: Set to value 6 to denote a Block Issuer Feature. + example: 6 + blockIssuerKeys: + type: array + description: The keys allowed to issue blocks from an account with a BlockIssuerFeature. + items: + oneOf: + - $ref: '#/components/schemas/Ed25519PublicKey' + expirySlot: + type: string + description: Indicates when the BlockIssuerKeys are expired. + required: + - type + - blockIssuerKeys + - expirySlot + + Ed25519PublicKey: + description: The Ed25519 public key. + properties: + type: + type: integer + description: Set to value 0 to denote an Ed25519 Public key. + publicKey: + type: string + description: Ed25519 public key in Hex. + required: + - type + - publicKey + + StakingFeature: + description: A feature which indicates that this account can issue blocks. + properties: + type: + type: string + description: Set to value 7 to denote a Staking Feature. + example: 7 + stakedAmount: + type: string + description: The amount of IOTA coins that are locked and staked in the containing account. + fixedCost: + type: string + description: The fixed cost that the validator receives from the total pool reward. + startEpoch: + type: integer + description: The epoch index at which the staking starts. + endEpoch: + type: integer + description: The epoch index at which the staking ends. + required: + - type + - stakedAmount + - fixedCost + - startEpoch + - endEpoch + + MetadataFeature: + description: Defines metadata (arbitrary binary data) that will be stored in the output. + properties: + type: + type: integer + description: Set to value 2 to denote a Metadata Feature. + entries: + type: object + additionalProperties: + type: string + example: + - 'did:iota': '0x68656c6c6f206469676974616c206175746f6e6f6d79' + - 'hello': '0x776f726c64' + required: + - type + - entries + + StateMetadataFeature: + description: >- + Defines a map of key-value pairs. The keys must consist of ASCII characters only and the values are arbitrary byte slices (encoded in Hex). + properties: + type: + type: integer + description: Set to value 3 to denote a State Metadata Feature. + example: 3 + entries: + type: object + additionalProperties: + type: string + example: + - 'did:iota': '0x68656c6c6f206469676974616c206175746f6e6f6d79' + - 'hello': '0x776f726c64' + required: + - type + - entries + + TagFeature: + description: Defines an indexation tag to which the output can be indexed by additional node plugins. + properties: + type: + type: integer + description: Set to value 4 to denote a Tag Feature. + tag: + type: string + description: Hex-encoded binary indexation tag with 0x prefix. + required: + - type + - tag + + NativeTokenFeature: + description: Defines a native token which represents a token that resides natively on the ledger. + properties: + type: + type: integer + description: Set to value 5 to denote a Native Token Feature. + id: + type: string + description: The ID of the native token. + amount: + type: string + description: The amount of native token. Hex-encoded number with 0x prefix. + required: + - type + - id + - amount + + SimpleTokenScheme: + description: Defines the simple supply control scheme of native tokens. Tokens can be minted by the foundry without additional restrictions as long as maximum supply is requested and circulating supply is not negative. + properties: + type: + type: integer + description: Set to value 0 to denote a Simple Token Scheme. + mintedTokens: + type: string + description: Minted tokens controlled by this foundry. Hex-encoded number with 0x prefix. + meltedTokens: + type: string + description: Melted tokens controlled by this foundry. Hex-encoded number with 0x prefix. + maxSupply: + type: string + description: Maximum supply of tokens controlled by this foundry. Hex-encoded number with 0x prefix. + required: + - type + - mintedTokens + - meltedTokens + - maxSupply + + SignatureUnlock: + description: Defines an unlock containing a signature to unlock an input. + properties: + type: + type: integer + description: Denotes a Signature Unlock. + signature: + type: object + oneOf: + - $ref: '#/components/schemas/Ed25519Signature' + required: + - type + - signature + + Ed25519Signature: + description: The Ed25519 signature. + properties: + type: + type: integer + description: Set to value 0 to denote an Ed25519 Signature. + publicKey: + type: string + description: The public key of the Ed25519 keypair which is used to verify the signature. Hex-encoded with 0x prefix. + signature: + type: string + description: The signature signing the serialized Transaction Essence. Hex-encoded with 0x prefix. + required: + - type + - publicKey + - signature + + ReferenceUnlock: + description: ReferenceUnlock is an Unlock which references a previous unlock. + properties: + type: + type: integer + description: Set to value 1 to denote a Reference Unlock. + reference: + type: integer + description: Represents the index of a previous unlock. + required: + - type + - reference + + AccountUnlock: + description: References a previous unlock that unlocks an Account Output. + properties: + type: + type: integer + description: Set to value 2 to denote an Account Unlock. + reference: + type: integer + description: Represents the index of a previous unlock. + required: + - type + - reference + + NFTUnlock: + description: References a previous unlock that unlocks an NFT Output. + properties: + type: + type: integer + description: Set to value 3 to denote an NFT Unlock. + reference: + type: integer + description: Represents the index of a previous unlock. + required: + - type + - reference + + TaggedDataPayload: + description: The Tagged Data Payload to be embedded into a block. + properties: + type: + type: integer + description: Set to value 0 to denote a Tagged Data Payload. + tag: + type: string + description: The tag to allow external tools to find/look up this block. It has a size between 0 and 64 bytes and must be encoded as a hex-string with 0x prefix. Network nodes do not index blocks with Tagged Data Payload by the tag field by default. + data: + type: string + description: The optional data to attach. This may have a length of 0. Hex-encoded with 0x prefix. + required: + - type + - data + + ErrorResponse: + description: The error format. + properties: + error: + type: object + properties: + code: + type: string + description: The application error code. + message: + type: string + description: The error reason. + required: + - code + - message + required: + - error + + ForbiddenResponse: + description: Indicates that this endpoint is not available for public use. + allOf: + - $ref: '#/components/schemas/ErrorResponse' + example: + error: + code: 403 + message: not available for public use + + ServiceUnavailableResponse: + description: Indicates that the service is unavailable. + allOf: + - $ref: '#/components/schemas/ErrorResponse' + example: + error: + code: 503 + message: service unavailable + + BadRequestResponse: + description: Indicates that the request was bad. + allOf: + - $ref: '#/components/schemas/ErrorResponse' + example: + error: + code: 400 + message: invalid data provided + + NotFoundResponse: + description: Indicates that the data was not found. + allOf: + - $ref: '#/components/schemas/ErrorResponse' + example: + error: + code: 404 + message: could not find data + + InternalErrorResponse: + description: Indicates that the server encountered an unexpected condition, which prevented it from fulfilling the request by the client. + allOf: + - $ref: '#/components/schemas/ErrorResponse' + example: + error: + code: 500 + message: internal server error + + RoutesResponse: + description: Contains the available API routes of the node. + properties: + routes: + type: array + items: + type: string + required: + - routes + + InfoResponse: + description: Returns general information about the node. + properties: + name: + type: string + description: The name of the node. + version: + type: string + description: The semantic version of the node. + status: + description: Status of the node. + properties: + isHealthy: + type: boolean + description: Tells whether the node is healthy or not. + acceptedTangleTime: + description: A notion of time that is anchored to the latest accepted block. It's in nanosecond-precision. + type: string + relativeAcceptedTangleTime: + description: The time after Accepted Tangle Time has advanced with the system clock. It's in nanosecond-precision. + type: string + confirmedTangleTime: + description: A notion of time that is anchored to the latest confirmed block. It's in nanosecond-precision. + type: string + relativeConfirmedTangleTime: + description: The time after Confirmed Tangle Time has advanced with the system clock. It's in nanosecond-precision. + type: string + latestCommitmentId: + type: string + description: The latest slot that the node has committed to. + latestFinalizedSlot: + description: The index of the latest finalized slot. + type: integer + latestAcceptedBlockSlot: + description: The slot index of the latest accepted block. + type: integer + latestConfirmedBlockSlot: + description: The slot index of the latest confirmed block. + type: integer + pruningEpoch: + type: integer + description: The index of the slot before which the tangle history is pruned. + required: + - isHealthy + - acceptedTangleTime + - relativeAcceptedTangleTime + - confirmedTangleTime + - relativeConfirmedTangleTime + - latestCommitmentId + - latestFinalizedSlot + - latestAcceptedBlockSlot + - latestConfirmedBlockSlot + - pruningEpoch + metrics: + description: Node metrics. + properties: + blocksPerSecond: + description: The current rate of new blocks per second. + type: string + format: float + confirmedBlocksPerSecond: + description: The current rate of confirmed blocks per second. + type: string + format: float + confirmationRate: + description: The ratio of confirmed blocks to new blocks of the last confirmed slot. + type: string + format: float + required: + - blocksPerSecond + - confirmedBlocksPerSecond + - confirmationRate + protocolParameters: + type: array + items: + allOf: + - $ref: '#/components/schemas/ProtocolParameters' + baseToken: + description: Gives info about the base token the network uses. + properties: + name: + type: string + description: The name of the base token of the network. + tickerSymbol: + type: string + description: Ticker symbol of the token to be displayed on trading platforms. + unit: + type: string + description: The primary unit of the token. + subunit: + type: string + description: The name of the smallest possible denomination of the primary unit. subunit * 10^decimals = unit + decimals: + type: integer + description: Number of decimals the primary unit is divisible up to. + required: + - name + - tickerSymbol + - unit + - decimals + required: + - name + - version + - status + - metrics + - protocolParameters + - baseToken + + ProtocolParameters: + description: Protocol parameters. + properties: + startEpoch: + description: The start epoch of the set of protocol parameters. + type: integer + parameters: + description: The protocol parameters. + properties: + type: + type: integer + description: Set to value 0 to denote a IOTA 2.0 protocol parameter. + version: + type: integer + description: Protocol version used by the network. + networkName: + type: string + description: The Name of the network from which the networkId is derived. + bech32Hrp: + type: string + description: Tells whether the node supports mainnet or testnet addresses. Value `iota` indicates that the node supports mainnet addresses. Value `atoi` indicates that the node supports testnet addresses. + storageScoreParameters: + description: The storage score structure according to TIP-47. + properties: + storageCost: + description: Defines the number of IOTA tokens required per unit of storage score. + type: string + factorData: + description: Defines the factor to be used for data only fields. + type: integer + offsetOutputOverhead: + description: Defines the offset to be used for key/lookup generating fields. + type: string + offsetEd25519BlockIssuerKey: + description: Defines the offset to be used for block issuer feature public keys. + type: string + offsetStakingFeature: + description: Defines the offset to be used for staking feature. + type: string + offsetDelegation: + description: Defines the offset to be used for delegation output. + type: string + required: + - storageCost + - factorData + - offsetOutputOverhead + - offsetEd25519BlockIssuerKey + - offsetStakingFeature + - offsetDelegation + workScoreParameters: + description: Work Score Parameters defines the work score parameters used by given node/network. + properties: + dataByte: + description: DataByte accounts for the network traffic per byte. + type: integer + block: + description: Block accounts for work done to process a block in the node software. + type: integer + input: + description: Input accounts for loading the UTXO from the database and performing the mana calculations. + type: integer + contextInput: + description: contextInput accounts for loading and checking the context input. + type: integer + output: + description: Output accounts for storing the UTXO in the database. + type: integer + nativeToken: + description: NativeToken accounts for calculations done with native tokens. + type: integer + staking: + description: Staking accounts for the existence of a staking feature in the output. + type: integer + blockIssuer: + description: BlockIssuer accounts for the existence of a block issuer feature in the output. + type: integer + allotment: + description: Allotment accounts for accessing the account based ledger to transform the mana to block issuance credits. + type: integer + signatureEd25519: + description: SignatureEd25519 accounts for an Ed25519 signature check. + type: integer + required: + - dataByte + - block + - input + - contextInput + - output + - nativeToken + - staking + - blockIssuer + - allotment + - signatureEd25519 + manaParameters: + description: Mana Structure defines the parameters used by mana calculation. + properties: + bitsCount: + type: integer + description: The number of bits used to represent Mana. + generationRate: + type: integer + description: The amount of potential Mana generated by 1 IOTA in 1 slot. + generationRateExponent: + type: integer + description: The scaling of GenerationRate expressed as an exponent of 2. + decayFactors: + type: array + description: a lookup table of epoch index diff to mana decay factor (slice index 0 = 1 epoch). + items: + type: integer + decayFactorsExponent: + type: integer + description: The scaling of DecayFactors expressed as an exponent of 2. + decayFactorEpochsSum: + type: integer + description: An integer approximation of the sum of decay over epochs. + decayFactorEpochsSumExponent: + type: integer + description: The scaling of DecayFactorEpochsSum expressed as an exponent of 2. + annualDecayFactorPercentage: + type: integer + description: the decay factor for 1 year. + required: + - bitsCount + - generationRate + - generationRateExponent + - decayFactors + - decayFactorsExponent + - decayFactorEpochsSum + - decayFactorEpochsSumExponent + - annualDecayFactorPercentage + tokenSupply: + type: string + description: Current supply of base token. Plain string encoded number. + genesisSlot: + type: integer + description: The slot index of the genesis. + genesisUnixTimestamp: + type: string + description: The genesis timestamp at which the slots start to count. It's in second-precision. + slotDurationInSeconds: + type: integer + description: The duration of a slot, in seconds. + slotsPerEpochExponent: + type: integer + description: The number of slots in an epoch expressed as an exponent of 2. + stakingUnbondingPeriod: + type: integer + description: The unbonding period in epochs before an account can stop staking. + validationBlocksPerSlot: + type: integer + description: The number of validation blocks per slot. + punishmentEpochs: + type: integer + description: The number of epochs worth of Mana that a node is punished with for each additional validation block it issues. + livenessThresholdLowerBound: + type: integer + description: Determine if a block is eligible by evaluating issuingTimes and commitments in its past-cone to Accepted Tangle Time and lastCommittedSlot respectively. + livenessThresholdUpperBound: + type: integer + description: Determine if a block is eligible by evaluating issuingTimes and commitments in its past-cone to Accepted Tangle Time and lastCommittedSlot respectively. + minCommittableAge: + type: integer + description: MinCommittableAge is the minimum age relative to the accepted tangle time slot index that a slot can be committed. + maxCommittableAge: + type: integer + description: MaxCommittableAge is the maximum age for a slot commitment to be included in a block relative to the slot index of the block issuing time. + epochNearingThreshold: + type: integer + description: Determine the slot that should trigger a new committee selection for the next and upcoming epoch. + congestionControlParameters: + description: Congestion Control Parameters defines the parameters used to calculate the Reference Mana Cost (RMC). + properties: + minReferenceManaCost: + description: Min Reference Mana Cost is the minimum value of the reference Mana cost. + type: string + increase: + description: Increase is the increase step size of the reference Mana cost. + type: string + decrease: + description: Decrease is the decrease step size of the reference Mana cost. + type: string + increaseThreshold: + description: IncreaseThreshold is the threshold for increasing the reference Mana cost. + type: integer + decreaseThreshold: + description: DecreaseThreshold is the threshold for decreasing the reference Mana cost. + type: integer + schedulerRate: + description: SchedulerRate is the rate at which the scheduler runs in workscore units per second. + type: integer + maxBufferSize: + description: MaxBufferSize is the maximum size of the buffer. + type: integer + maxValidationBufferSize: + description: MaxValidationBufferSize is the maximum size of the validation buffer. + type: integer + required: + - minReferenceManaCost + - increase + - decrease + - increaseThreshold + - decreaseThreshold + - schedulerRate + - maxBufferSize + versionSignalingParameters: + description: The version signaling parameters. + properties: + windowSize: + type: integer + description: The size of the window in epochs to find which version of protocol parameters was most signaled, from currentEpoch - windowSize to currentEpoch. + windowTargetRatio: + type: integer + description: The target number of supporters for a version to win in a windowSize. + activationOffset: + type: integer + description: The offset in epochs to activate the new version of protocol parameters. + required: + - windowSize + - windowTargetRatio + - activationOffset + rewardsParameters: + description: Rewards Parameters defines the parameters that are used to calculate the rewards. + properties: + profitMarginExponent: + type: integer + description: ProfitMarginExponent is used for shift operation for calculation of profit margin. + bootstrappingDuration: + type: integer + description: The length in epochs of the bootstrapping phase. + rewardToGenerationRatio: + type: integer + description: RewardToGenerationRatio is the ratio of the final rewards rate to the generation rate of Mana. + initialTargetRewardsRate: + type: string + description: InitialTargetRewardsRate is the rate of Mana rewards at the start of the bootstrapping phase. + finalTargetRewardsRate: + type: string + description: FinalTargetRewardsRate is the rate of Mana rewards after the bootstrapping phase. + poolCoefficientExponent: + type: integer + description: PoolCoefficientExponent is the exponent used for shifting operation in the pool rewards calculations. + retentionPeriod: + type: integer + description: The number of epochs for which rewards are retained. + required: + - profitMarginExponent + - bootstrappingDuration + - rewardToGenerationRatio + - initialTargetRewardsRate + - finalTargetRewardsRate + - poolCoefficientExponent + - retentionPeriod + targetCommitteeSize: + type: integer + description: The target size of the committee. + chainSwitchingThreshold: + type: integer + description: The number of heavier slots that a chain needs to be ahead of the current chain to be considered for switching. + required: + - version + - networkName + - bech32Hrp + - tokenSupply + - storageScoreParameters + - workScoreParameters + - manaParameters + - genesisSlot + - genesisUnixTimestamp + - slotDurationInSeconds + - slotsPerEpochExponent + - stakingUnbondingPeriod + - validationBlocksPerSlot + - punishmentEpochs + - livenessThresholdLowerBound + - livenessThresholdUpperBound + - minCommittableAge + - maxCommittableAge + - epochNearingThreshold + - congestionControlParameters + - versionSignalingParameters + - rewardsParameters + - targetCommitteeSize + - chainSwitchingThreshold + required: + - startEpoch + - parameters + + ValidatorsResponse: + description: Returns a paginated list of all registered validators ready for the next epoch and indicates if they were active recently (are eligible for committee selection). + properties: + validators: + type: array + items: + oneOf: + - $ref: '#/components/schemas/Validator' + pageSize: + type: integer + description: The number of registerd validators returned per one API request with pagination. + cursor: + type: string + description: The cursor that needs to be provided as cursor query parameter to request the next page. Cursor is absent if the last page is returned. + + ManaRewardsResponse: + description: Returns the mana rewards of an account or delegation output. + properties: + startEpoch: + type: integer + description: The starting epoch index for which the mana rewards are returned. + endEpoch: + type: integer + description: The ending epoch index for which the mana rewards are returned, the decay is applied up to this point (inclusive). + rewards: + type: string + description: The amount of totally available rewards the requested output may claim. + latestCommittedEpochPoolRewards: + type: string + description: The rewards of the latest committed epoch of the staking pool to which this validator or delegator belongs. The ratio of this value and the maximally possible rewards for the latest committed epoch can be used to determine how well the validator of this staking pool performed in that epoch. Note that if the pool was not part of the committee in the latest committed epoch, this value is 0. + + CommitteeResponse: + description: Returns the validator information of the committee. + properties: + epoch: + type: integer + description: The epoch index of the committee. + totalStake: + type: string + description: The total amount of delegated and staked IOTA tokens in the selected committee. + totalValidatorStake: + type: string + description: The total amount of staked IOTA tokens in the selected committee. + committee: + type: array + description: The validators of the committee. + items: + oneOf: + - $ref: '#/components/schemas/CommitteeMember' + + CommitteeMember: + description: Returns information of a validator (committee member). + properties: + address: + type: string + description: The account address of the validator. + poolStake: + type: string + description: The total stake of the pool, including delegators. + validatorStake: + type: string + description: The stake of a validator. + fixedCost: + type: string + description: The fixed cost of the validator, which it receives as part of its Mana rewards. + + Validator: + description: Returns information of a staker (registered validator). + properties: + address: + type: string + description: The account address of the staker. + stakingEndEpoch: + type: integer + description: The epoch index until which the staker registered to stake. + poolStake: + type: string + description: The total stake of the pool, including delegators. + validatorStake: + type: string + description: The stake of a staker. + fixedCost: + type: string + description: The fixed cost of the staker, which it receives as part of its Mana rewards. + active: + type: boolean + description: Shows whether staker was active recently. + latestSupportedProtocolVersion: + type: integer + description: The latest protocol version the staker supported. + latestSupportedProtocolHash: + type: string + description: The latest protocol hash the staker supported. + required: + - address + - stakingEndEpoch + - poolStake + - validatorStake + - fixedCost + - active + - latestSupportedProtocolVersion + - latestSupportedProtocolHash + + IssuanceBlockHeaderResponse: + description: Return information that is used to attach a block in the network. + properties: + strongParents: + type: array + items: + type: string + description: The block identifiers that can be used to a attach a block to. Hex-encoded with 0x prefix. + weakParents: + type: array + items: + type: string + description: The block identifiers that can be used to a attach a block to. Hex-encoded with 0x prefix. + shallowLikeParents: + type: array + items: + type: string + description: The block identifiers that can be used to a attach a block to. Hex-encoded with 0x prefix. + latestParentBlockIssuingTime: + type: string + description: The latest issuing time of the returned parents. + latestFinalizedSlot: + type: integer + description: The latest finalized slot index. + latestCommitment: + $ref: '#/components/schemas/Commitment' + + CongestionResponse: + description: Provides the cost and readiness to issue estimates. + properties: + slot: + type: integer + description: The slot index for which the congestion estimate is provided. + ready: + type: boolean + description: > + Indicates if a node is ready to issue a block in a current congestion or should wait. + referenceManaCost: + type: string + description: The cost in mana for issuing a block in a current congestion estimated based on RMC and slot index. + blockIssuanceCredits: + type: string + description: The Block Issuance Credits of the requested account. + required: + - slot + - ready + - referenceManaCost + - blockIssuanceCredits + + + Commitment: + description: An object embedded to a block, containing a summary of a slot. + properties: + protocolVersion: + type: integer + description: The version of the protocol running. + slot: + type: integer + description: The slot index of the commitment. + previousCommitmentId: + type: string + description: The commitment identifier of the previous slot. + rootsId: + type: string + description: The digest of multiple merkle roots within this slot. + cumulativeWeight: + type: string + description: + The sum of previous slot commitment cumulative weight and + weight of issuers of accepted blocks within index minus Maximum Committable Age. It indicates the weight of the chain at index minus Maximum Committable Age committed at index slot. + referenceManaCost: + type: string + description: This field provides the Reference Mana Cost (RMC) to be used in the slot with index Index + Max Committable Age. + required: + - protocolVersion + - slot + - previousCommitmentId + - rootsId + - cumulativeWeight + - referenceManaCost + + SubmitBlockRequest: + description: Submits a block to the node. + properties: + allOf: + $ref: '#/components/schemas/Block' + + SubmitBlockResponse: + description: Returns the block identifier of the submitted block. + properties: + blockId: + type: string + description: The block identifier of the submitted block. Hex-encoded with 0x prefix. + required: + - blockId + + BlockFullResponse: + description: Returns the block structure and the metadata of a given block. + properties: + block: + $ref: '#/components/schemas/Block' + description: The requested block structure. + metadata: + $ref: '#/components/schemas/BlockMetadataResponse' + description: The metadata of the requested block. + required: + - block + - metadata + + BlockMetadataResponse: + description: Returns the metadata of a given block. + properties: + blockId: + type: string + description: The identifier of the block. Hex-encoded with 0x prefix. + blockState: + type: string + enum: + - pending + - confirmed + - finalized + - rejected + - failed + description: If `pending`, the block is stored but not confirmed. If `confirmed`, the block is confirmed with the first level of knowledge. If `finalized`, the block is included and cannot be reverted anymore. If `rejected`, the block is rejected by the node, and user should reissue payload if it contains one. If `failed`, the block is not successfully issued due to failure reason. + blockFailureReason: + type: integer + enum: [1,2,3,4,5,6,7,8,9,10,11,12,255] + description: | + Values: + * `1` - denotes that the block is too old to issue. + * `2` - denotes that the block's parents are too old. + * `3` - denotes that one of block's parents does not exist. + * `4` - denotes that one of block's parents is invalid. + * `5` - denotes that the issuer account could not be found. + * `6` - denotes that the block version is invalid to retrieve the corresponding protocol information. + * `7` - denotes that the Mana cost could not be calculated. + * `8` - denotes that the issuer account burned insufficient Mana for the block. + * `9` - denotes that the account is invalid, e.g. the account has negative Block Issuance Credits, or the account has expired. + * `10` - denotes that the signature is invalid. + * `11` - denotes that the block is dropped due to congestion. + * `12` - denotes that the payload is invalid. + * `255` - denotes that the block is invalid. + transactionMetadata: + description: The metadata of the transactions in the block. + $ref: '#/components/schemas/TransactionMetadataResponse' + required: + - blockId + - blockState + + TransactionMetadataResponse: + description: Returns the metadata of a given transaction. + properties: + transactionId: + type: string + description: The identifier of the transaction. Hex-encoded with 0x prefix. + transactionState: + type: string + enum: + - pending + - accepted + - confirmed + - finalized + - failed + description: If 'pending', the transaction is not included yet. If 'accepted', the transaction is included. If 'confirmed' means transaction is included and its included block is confirmed. If 'finalized' means transaction is included, its included block is finalized and cannot be reverted anymore. If 'failed' means transaction is issued but failed due to the transaction failure reason. + transactionFailureReason: + type: integer + enum: [1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,255] + description: > + Values: + * `1` - denotes that the referenced UTXO was already spent. + * `2` - denotes that the transaction is conflicting with another transaction. Conflicting specifically means a double spend situation that both transaction pass all validation rules, eventually losing one(s) should have this reason. + * `3` - denotes that the referenced UTXO is invalid. + * `4` - denotes that the transaction is invalid. + * `5` - denotes that the sum of the inputs and output base token amount does not match. + * `6` - denotes that the unlock block signature is invalid. + * `7` - denotes that the configured timelock is not yet expired. + * `8` - denotes that the given native tokens are invalid. + * `9` - denotes that the return amount in a transaction is not fulfilled by the output side. + * `10` - denotes that the input unlock is invalid. + * `11` - denotes that an output contains a Sender with an ident (address) which is not unlocked. + * `12` - denotes that the chain state transition is invalid. + * `13` - denotes that the referenced input is created after transaction issuing time. + * `14` - denotes that the mana amount is invalid. + * `15` - denotes that the Block Issuance Credits Input is invalid. + * `16` - denotes that Reward Context Input is invalid. + * `17` - denotes that Commitment Context Input is invalid. + * `18` - denotes that Staking Feature is not provided in account output when claiming rewards. + * `19` - denotes that fail to claim staking reward. + * `20` - denotes that fail to claim delegation reward. + * `21` - denotes that the burning of native tokens was not allowed in the transaction capabilities. + * `22` - denotes that the burning of mana was not allowed in the transaction capabilities. + * `23` - denotes that the destruction of accounts was not allowed in the transaction capabilities. + * `24` - denotes that the destruction of anchors was not allowed in the transaction capabilities. + * `25` - denotes that the destruction of foundries was not allowed in the transaction capabilities. + * `26` - denotes that the destruction of nfts was not allowed in the transaction capabilities. + * `255` - denotes that the semantic validation failed. + required: + - transactionId + - transactionState + + BlockResponse: + description: Returns a given block. + properties: + allOf: + $ref: '#/components/schemas/Block' + + OutputResponse: + description: Returns an output. + properties: + output: + anyOf: + - $ref: '#/components/schemas/BasicOutput' + - $ref: '#/components/schemas/AccountOutput' + - $ref: '#/components/schemas/AnchorOutput' + - $ref: '#/components/schemas/FoundryOutput' + - $ref: '#/components/schemas/NFTOutput' + - $ref: '#/components/schemas/DelegationOutput' + outputIdProof: + allOf: + - $ref: '#/components/schemas/OutputIdProof' + required: + - output + - outputIdProof + + OutputIdProof: + description: The proof of the output identifier. + properties: + slot: + type: integer + description: The slot index of the output. + outputIndex: + type: integer + description: The index of the output within the corresponding transaction. + transactionCommitment: + type: string + description: The commitment of the transaction that created the output. Hex-encoded with 0x prefix. + outputCommitmentProof: + description: The proof of the output commitment. Hex-encoded with 0x prefix. + anyOf: + - $ref: '#/components/schemas/HashableNode' + - $ref: '#/components/schemas/LeafHash' + - $ref: '#/components/schemas/ValueHash' + required: + - slot + - outputIndex + - transactionCommitment + - outputCommitmentProof + + HashableNode: + description: Node contains the hashes of the left and right children of a node in the tree. + properties: + type: + type: integer + description: Set to value 0 to denote a Hashable Node. + l: + description: The left node. Hex-encoded with 0x prefix. + anyOf: + - $ref: '#/components/schemas/HashableNode' + - $ref: '#/components/schemas/LeafHash' + - $ref: '#/components/schemas/ValueHash' + r: + description: The right node. Hex-encoded with 0x prefix. + anyOf: + - $ref: '#/components/schemas/HashableNode' + - $ref: '#/components/schemas/LeafHash' + - $ref: '#/components/schemas/ValueHash' + required: + - type + - node + + LeafHash: + description: Leaf Hash contains the hash of a leaf in the tree. + properties: + type: + type: integer + description: Set to value 1 to denote a Leaf Hash. + hash: + type: string + description: The hash of a leaf in the tree. Hex-encoded with 0x prefix. + required: + - type + - hash + + ValueHash: + description: Value Hash contains the hash of the value for which the proof is being computed. + properties: + type: + type: integer + description: Set to value 2 to denote a Value Hash. + hash: + type: string + description: the hash of the value for which the proof is being computed. Hex-encoded with 0x prefix. + required: + - type + - hash + + + OutputWithMetadataResponse: + description: Returns an output. + properties: + output: + anyOf: + - $ref: '#/components/schemas/BasicOutput' + - $ref: '#/components/schemas/AccountOutput' + - $ref: '#/components/schemas/AnchorOutput' + - $ref: '#/components/schemas/FoundryOutput' + - $ref: '#/components/schemas/NFTOutput' + - $ref: '#/components/schemas/DelegationOutput' + outputIdProof: + allOf: + - $ref: '#/components/schemas/OutputIdProof' + metadata: + allOf: + - $ref: '#/components/schemas/OutputMetadataResponse' + required: + - output + - outputIdProof + - metadata + + OutputMetadataResponse: + description: Returns metadata about an output. + properties: + outputId: + type: string + description: The output identifier of requested output. Hex-encoded with 0x prefix. + blockId: + type: string + description: The block identifier that references the output. Hex-encoded with 0x prefix. + included: + properties: + slot: + type: integer + description: The slot index in which the output is included. + transactionId: + type: string + description: The identifier of the transaction. Hex-encoded with 0x prefix. + commitmentId: + type: string + description: The commitment ID at which the output was included into the ledger. + required: + - slot + - transactionId + spent: + properties: + slot: + type: integer + description: The slot index in which the output is spent. + transactionId: + type: string + description: The transaction ID that spent the output. Hex-encoded with 0x prefix. + commitmentId: + type: string + description: The commitment ID that includes the spending of the output. + required: + - slot + - transactionId + latestCommitmentId: + type: string + description: The current latest commitment id for which the request was made. + required: + - outputId + - blockId + - included + - latestCommitmentId + + UTXOChangesResponse: + description: Returns all UTXO changes of the given slot. + properties: + commitmentId: + type: string + description: The commitment ID of the requested slot that contains the changes. Hex-encoded with 0x prefix. + createdOutputs: + description: The created outputs of the given slot. + type: array + items: + type: string + description: Hex-encoded with 0x prefix. + consumedOutputs: + description: The consumed outputs of the given slot. + type: array + items: + type: string + description: Hex-encoded with 0x prefix. + required: + - slot + - createdOutputs + - consumedOutputs + + UTXOChangesFullResponse: + description: Returns all UTXO changes of the given slot. + properties: + commitmentId: + type: string + description: The commitment ID of the requested slot that contains the changes. Hex-encoded with 0x prefix. + createdOutputs: + description: The created outputs of the given slot. + type: array + items: + oneOf: + - $ref: '#/components/schemas/OutputWithId' + consumedOutputs: + description: The consumed outputs of the given slot. + type: array + items: + oneOf: + - $ref: '#/components/schemas/OutputWithId' + required: + - slot + - createdOutputs + - consumedOutputs + + OutputWithId: + description: Returns an output with its identifier. + properties: + outputId: + type: string + description: The output identifier of requested output. Hex-encoded with 0x prefix. + output: + anyOf: + - $ref: '#/components/schemas/BasicOutput' + - $ref: '#/components/schemas/AccountOutput' + - $ref: '#/components/schemas/AnchorOutput' + - $ref: '#/components/schemas/FoundryOutput' + - $ref: '#/components/schemas/NFTOutput' + - $ref: '#/components/schemas/DelegationOutput' + required: + - output + - outputId diff --git a/tips/TIP-0048/openapi3-indexer.yaml b/tips/TIP-0048/openapi3-indexer.yaml new file mode 100644 index 000000000..5da13b488 --- /dev/null +++ b/tips/TIP-0048/openapi3-indexer.yaml @@ -0,0 +1,1159 @@ +openapi: 3.0.3 +info: + title: IOTA UTXO Indexer REST API + description: This document specifies the REST API for IOTA UTXO indexers. + contact: + email: contact@iota.org + license: + name: Apache 2.0 + url: 'http://www.apache.org/licenses/LICENSE-2.0.html' + version: 3.0.0 +externalDocs: + description: Find out more about IOTA + url: 'https://iota.org' +servers: + - url: 'http://127.0.0.1:14265' +tags: + - name: outputs + description: Query all types of Outputs. + - name: basic outputs + description: Query Basic Outputs. + - name: account outputs + description: Query Account Outputs. + - name: anchor outputs + description: Query Anchor Outputs. + - name: delegation outputs + description: Query Delegation Outputs. + - name: foundry outputs + description: Query Foundry Outputs. + - name: nft outputs + description: Query NFT Outputs. +paths: + /api/indexer/v2/outputs: + get: + tags: + - outputs + summary: Returns all types of outputs filtered based on parameters. + description: Returns basic, foundry, account, delegation and nft outputs filtered based on parameters. + parameters: + - in: query + name: hasNativeTokens + schema: + type: boolean + example: true + description: Filters outputs based on the presence of native tokens. + - in: query + name: nativeToken + schema: + type: string + example: "0x4e16190b6f3076120c685b1d554d28443b12203e5b424d4e366230623b7b165a222250175d29" + description: Filters outputs that have the given native token ID. + - in: query + name: createdBefore + schema: + type: integer + example: 200 + description: Return outputs that were created before a certain slot index. + - in: query + name: createdAfter + schema: + type: integer + example: 200 + description: Return outputs that were created after a certain slot index. + - in: query + name: unlockableByAddress + schema: + type: string + example: iota1qrhacyfwlcnzkvzteumekfkrrwks98mpdm37cj4xx3drvmjvnep6xqgyzyx + description: The address unlock related query parameters. + - in: query + name: pageSize + schema: + type: integer + example: 10 + description: The maximum amount of items returned in one call. If there are more items, a cursor to the next page is returned too. + The parameter is ignored when pageSize is defined via the cursor parameter. + - in: query + name: cursor + schema: + type: string + example: 0c78e998f5177834ecb3bae1596d5056af76e487386eecb19727465b4be86a790200.10 + description: Starts the search from the cursor (createdSlotIndex+outputId.pageSize). + responses: + '200': + description: "Successful operation." + content: + application/json: + schema: + $ref: '#/components/schemas/OutputsResponse' + examples: + Query results in 3 outputs: + $ref: >- + #/components/examples/get-outputs-response-three-example + No matching Output IDs found: + $ref: >- + #/components/examples/get-outputs-empty-response-example + Paging - more items found than it can fit on single page: + $ref: >- + #/components/examples/get-outputs-pagesize2-response-example + '400': + description: "Unsuccessful operation: indicates that the provided data is invalid." + content: + application/json: + schema: + $ref: '#/components/schemas/BadRequestResponse' + '403': + description: "Unsuccessful operation: indicates that the endpoint is not available for public use." + content: + application/json: + schema: + $ref: '#/components/schemas/ForbiddenResponse' + '500': + description: "Unsuccessful operation: indicates that an unexpected, internal server error happened which prevented the node from fulfilling the request." + content: + application/json: + schema: + $ref: '#/components/schemas/InternalErrorResponse' + + /api/indexer/v2/outputs/basic: + get: + tags: + - basic outputs + summary: Returns basic outputs filtered based on parameters. + description: Returns basic outputs filtered based on parameters. + parameters: + - in: query + name: address + schema: + type: string + example: iota1qrhacyfwlcnzkvzteumekfkrrwks98mpdm37cj4xx3drvmjvnep6xqgyzyx + description: The Bech32-encoded address that should be searched for in the Address Unlock Condition of outputs. + - in: query + name: hasNativeTokens + schema: + type: boolean + example: true + description: Filters outputs based on the presence of native tokens. + - in: query + name: nativeToken + schema: + type: string + example: "0x4e16190b6f3076120c685b1d554d28443b12203e5b424d4e366230623b7b165a222250175d29" + description: Filters outputs that have the given native token ID. + - in: query + name: hasStorageDepositReturn + schema: + type: boolean + example: true + description: Filters outputs based on the presence of storage deposit return unlock condition. + - in: query + name: storageDepositReturnAddress + schema: + type: string + example: iota1qrhacyfwlcnzkvzteumekfkrrwks98mpdm37cj4xx3drvmjvnep6xqgyzyx + description: Filter outputs based on the presence of a specific return address in the storage deposit return + unlock condition. + - in: query + name: hasTimelock + schema: + type: boolean + example: true + description: Filters outputs based on the presence of timelock unlock condition. + - in: query + name: timelockedBefore + schema: + type: integer + example: 150 + description: Return outputs that are timelocked before a certain slot index. + - in: query + name: timelockedAfter + schema: + type: integer + example: 200 + description: Return outputs that are timelocked after a certain slot index. + - in: query + name: hasExpiration + schema: + type: boolean + example: true + description: Filters outputs based on the presence of expiration unlock condition. + - in: query + name: expiresBefore + schema: + type: integer + example: 200 + description: Return outputs that expire before a certain slot index. + - in: query + name: expiresAfter + schema: + type: integer + example: 200 + description: Return outputs that expire after a certain slot index. + - in: query + name: expirationReturnAddress + schema: + type: string + example: iota1qrhacyfwlcnzkvzteumekfkrrwks98mpdm37cj4xx3drvmjvnep6xqgyzyx + description: Filter outputs based on the presence of a specific return address in the expiration unlock + condition. + - in: query + name: sender + schema: + type: string + example: iota1qrhacyfwlcnzkvzteumekfkrrwks98mpdm37cj4xx3drvmjvnep6xqgyzyx + description: Filters outputs based on the presence of validated Sender (bech32 encoded). + - in: query + name: tag + schema: + type: string + example: "0x4ec7f23" + description: Filters outputs based on matching Tag Feature. + - in: query + name: createdBefore + schema: + type: integer + example: 200 + description: Return outputs that were created before a certain slot index. + - in: query + name: createdAfter + schema: + type: integer + example: 200 + description: Return outputs that were created after a certain slot index. + - in: query + name: unlockableByAddress + schema: + type: string + example: iota1qrhacyfwlcnzkvzteumekfkrrwks98mpdm37cj4xx3drvmjvnep6xqgyzyx + description: The address unlock related query parameters. + - in: query + name: pageSize + schema: + type: integer + example: 10 + description: The maximum amount of items returned in one call. If there are more items, a cursor to the next page is returned too. + The parameter is ignored when pageSize is defined via the cursor parameter. + - in: query + name: cursor + schema: + type: string + example: 0c78e998f5177834ecb3bae1596d5056af76e487386eecb19727465b4be86a790200.10 + description: Starts the search from the cursor (createdSlotIndex+outputId.pageSize). + responses: + '200': + description: "Successful operation." + content: + application/json: + schema: + $ref: '#/components/schemas/OutputsResponse' + examples: + Query results in 3 outputs: + $ref: >- + #/components/examples/get-outputs-response-three-example + No matching Output IDs found: + $ref: >- + #/components/examples/get-outputs-empty-response-example + Paging - more items found than it can fit on single page: + $ref: >- + #/components/examples/get-outputs-pagesize2-response-example + '400': + description: "Unsuccessful operation: indicates that the provided data is invalid." + content: + application/json: + schema: + $ref: '#/components/schemas/BadRequestResponse' + '403': + description: "Unsuccessful operation: indicates that the endpoint is not available for public use." + content: + application/json: + schema: + $ref: '#/components/schemas/ForbiddenResponse' + '500': + description: "Unsuccessful operation: indicates that an unexpected, internal server error happened which prevented the node from fulfilling the request." + content: + application/json: + schema: + $ref: '#/components/schemas/InternalErrorResponse' + + /api/indexer/v2/outputs/account: + get: + tags: + - account outputs + summary: Returns account outputs filtered based on parameters. + description: Returns account outputs filtered based on parameters. + parameters: + - in: query + name: issuer + schema: + type: string + example: iota1qrhacyfwlcnzkvzteumekfkrrwks98mpdm37cj4xx3drvmjvnep6xqgyzyx + description: Filters outputs based on bech32-encoded issuer address. + - in: query + name: sender + schema: + type: string + example: iota1qrhacyfwlcnzkvzteumekfkrrwks98mpdm37cj4xx3drvmjvnep6xqgyzyx + description: Filters outputs based on bech32-encoded sender address. + - in: query + name: createdBefore + schema: + type: integer + example: 200 + description: Return outputs that were created before a certain slot index. + - in: query + name: createdAfter + schema: + type: integer + example: 200 + description: Return outputs that were created after a certain slot index. + - in: query + name: address + schema: + type: string + example: iota1qrhacyfwlcnzkvzteumekfkrrwks98mpdm37cj4xx3drvmjvnep6xqgyzyx + description: The Bech32-encoded address that should be searched for in the Address Unlock Condition of outputs. + - in: query + name: pageSize + schema: + type: integer + example: 10 + description: The maximum amount of items returned in one call. If there are more items, a cursor to the next page is returned too. + The parameter is ignored when pageSize is defined via the cursor parameter. + - in: query + name: cursor + schema: + type: string + example: 0c78e998f5177834ecb3bae1596d5056af76e487386eecb19727465b4be86a790200.10 + description: Starts the search from the cursor (createdSlotIndex+outputId.pageSize). + responses: + '200': + description: "Successful operation." + content: + application/json: + schema: + $ref: '#/components/schemas/OutputsResponse' + examples: + Query results in 3 outputs: + $ref: >- + #/components/examples/get-outputs-response-three-example + No matching Output IDs found: + $ref: >- + #/components/examples/get-outputs-empty-response-example + Paging - more items found than it can fit on single page: + $ref: >- + #/components/examples/get-outputs-pagesize2-response-example + '400': + description: "Unsuccessful operation: indicates that the provided data is invalid." + content: + application/json: + schema: + $ref: '#/components/schemas/BadRequestResponse' + '403': + description: "Unsuccessful operation: indicates that the endpoint is not available for public use." + content: + application/json: + schema: + $ref: '#/components/schemas/ForbiddenResponse' + '500': + description: "Unsuccessful operation: indicates that an unexpected, internal server error happened which prevented the node from fulfilling the request." + content: + application/json: + schema: + $ref: '#/components/schemas/InternalErrorResponse' + + /api/indexer/v2/outputs/account/{accountId}: + get: + tags: + - account outputs + summary: Returns the Output ID of the current unspent account output for accountId. + description: Returns the Output ID of the current unspent account output for accountId. + parameters: + - in: path + name: accountId + schema: + type: string + example: "0x1505ec099896ab05d9e08fbc7101ae4dff0093b3943b28f789ed2ca728bcc8d6" + description: Unique identifier of the account. + required: true + responses: + '200': + description: "Successful operation." + content: + application/json: + schema: + $ref: '#/components/schemas/OutputsResponse' + examples: + Query results in single output: + $ref: >- + #/components/examples/get-outputs-response-single-example + '400': + description: "Unsuccessful operation: indicates that the provided data is invalid." + content: + application/json: + schema: + $ref: '#/components/schemas/BadRequestResponse' + '403': + description: "Unsuccessful operation: indicates that the endpoint is not available for public use." + content: + application/json: + schema: + $ref: '#/components/schemas/ForbiddenResponse' + '404': + description: "Unsuccessful operation: indicates that the requested data was not found." + content: + application/json: + schema: + $ref: '#/components/schemas/NotFoundResponse' + '500': + description: "Unsuccessful operation: indicates that an unexpected, internal server error happened which prevented the node from fulfilling the request." + content: + application/json: + schema: + $ref: '#/components/schemas/InternalErrorResponse' + + /api/indexer/v2/outputs/anchor: + get: + tags: + - anchor outputs + summary: Returns anchor outputs filtered based on parameters. + description: Returns anchor outputs filtered based on parameters. + parameters: + - in: query + name: issuer + schema: + type: string + example: iota1qrhacyfwlcnzkvzteumekfkrrwks98mpdm37cj4xx3drvmjvnep6xqgyzyx + description: Filters outputs based on bech32-encoded issuer address. + - in: query + name: sender + schema: + type: string + example: iota1qrhacyfwlcnzkvzteumekfkrrwks98mpdm37cj4xx3drvmjvnep6xqgyzyx + description: Filters outputs based on bech32-encoded sender address. + - in: query + name: createdBefore + schema: + type: integer + example: 200 + description: Return outputs that were created before a certain slot index. + - in: query + name: createdAfter + schema: + type: integer + example: 200 + description: Return outputs that were created after a certain slot index. + - in: query + name: unlockableByAddress + schema: + type: string + example: iota1qrhacyfwlcnzkvzteumekfkrrwks98mpdm37cj4xx3drvmjvnep6xqgyzyx + description: The address unlock related query parameters. + - in: query + name: stateController + schema: + type: string + example: iota1qrhacyfwlcnzkvzteumekfkrrwks98mpdm37cj4xx3drvmjvnep6xqgyzyx + description: Filter outputs based on bech32-encoded state controller address. + - in: query + name: governor + schema: + type: string + example: iota1qrhacyfwlcnzkvzteumekfkrrwks98mpdm37cj4xx3drvmjvnep6xqgyzyx + description: Filter outputs based on bech32-encoded governor (governance controller) address. + - in: query + name: pageSize + schema: + type: integer + example: 10 + description: The maximum amount of items returned in one call. If there are more items, a cursor to the next page is returned too. + The parameter is ignored when pageSize is defined via the cursor parameter. + - in: query + name: cursor + schema: + type: string + example: 0c78e998f5177834ecb3bae1596d5056af76e487386eecb19727465b4be86a790200.10 + description: Starts the search from the cursor (createdSlotIndex+outputId.pageSize). + responses: + '200': + description: "Successful operation." + content: + application/json: + schema: + $ref: '#/components/schemas/OutputsResponse' + examples: + Query results in 3 outputs: + $ref: >- + #/components/examples/get-outputs-response-three-example + No matching Output IDs found: + $ref: >- + #/components/examples/get-outputs-empty-response-example + Paging - more items found than it can fit on single page: + $ref: >- + #/components/examples/get-outputs-pagesize2-response-example + '400': + description: "Unsuccessful operation: indicates that the provided data is invalid." + content: + application/json: + schema: + $ref: '#/components/schemas/BadRequestResponse' + '403': + description: "Unsuccessful operation: indicates that the endpoint is not available for public use." + content: + application/json: + schema: + $ref: '#/components/schemas/ForbiddenResponse' + '500': + description: "Unsuccessful operation: indicates that an unexpected, internal server error happened which prevented the node from fulfilling the request." + content: + application/json: + schema: + $ref: '#/components/schemas/InternalErrorResponse' + + /api/indexer/v2/outputs/anchor/{anchorId}: + get: + tags: + - anchor outputs + summary: Returns the Output of the given anchor ID. + description: Returns the Output of the given anchorID. + parameters: + - in: path + name: anchorId + schema: + type: string + example: "0x1505ec099896ab05d9e08fbc7101ae4dff0093b3943b28f789ed2ca728bcc8d6" + description: Unique identifier of the anchor output. + required: true + responses: + '200': + description: "Successful operation." + content: + application/json: + schema: + $ref: '#/components/schemas/OutputsResponse' + examples: + Query results in single output: + $ref: >- + #/components/examples/get-outputs-response-single-example + '400': + description: "Unsuccessful operation: indicates that the provided data is invalid." + content: + application/json: + schema: + $ref: '#/components/schemas/BadRequestResponse' + '403': + description: "Unsuccessful operation: indicates that the endpoint is not available for public use." + content: + application/json: + schema: + $ref: '#/components/schemas/ForbiddenResponse' + '404': + description: "Unsuccessful operation: indicates that the requested data was not found." + content: + application/json: + schema: + $ref: '#/components/schemas/NotFoundResponse' + '500': + description: "Unsuccessful operation: indicates that an unexpected, internal server error happened which prevented the node from fulfilling the request." + content: + application/json: + schema: + $ref: '#/components/schemas/InternalErrorResponse' + + /api/indexer/v2/outputs/delegation: + get: + tags: + - delegation outputs + summary: Returns basic outputs filtered based on parameters. + description: Returns basic outputs filtered based on parameters. + parameters: + - in: query + name: address + schema: + type: string + example: iota1qrhacyfwlcnzkvzteumekfkrrwks98mpdm37cj4xx3drvmjvnep6xqgyzyx + description: The Bech32-encoded address that should be searched for in the Address Unlock Condition of outputs. + - in: query + name: validator + schema: + type: string + example: "0xf532a53545103276b46876c473846d98648ee418468bce76df4868648dd73e5d" + description: Filters outputs based on the account of the validator to which the output is delegating. + - in: query + name: createdBefore + schema: + type: integer + example: 200 + description: Return outputs that were created before a certain slot index. + - in: query + name: createdAfter + schema: + type: integer + example: 200 + description: Return outputs that were created after a certain slot index. + - in: query + name: pageSize + schema: + type: integer + example: 10 + description: The maximum amount of items returned in one call. If there are more items, a cursor to the next page is returned too. + The parameter is ignored when pageSize is defined via the cursor parameter. + - in: query + name: cursor + schema: + type: string + example: 0c78e998f5177834ecb3bae1596d5056af76e487386eecb19727465b4be86a790200.10 + description: Starts the search from the cursor (createdSlotIndex+outputId.pageSize). + responses: + '200': + description: "Successful operation." + content: + application/json: + schema: + $ref: '#/components/schemas/OutputsResponse' + examples: + Query results in 3 outputs: + $ref: >- + #/components/examples/get-outputs-response-three-example + No matching Output IDs found: + $ref: >- + #/components/examples/get-outputs-empty-response-example + Paging - more items found than it can fit on single page: + $ref: >- + #/components/examples/get-outputs-pagesize2-response-example + '400': + description: "Unsuccessful operation: indicates that the provided data is invalid." + content: + application/json: + schema: + $ref: '#/components/schemas/BadRequestResponse' + '403': + description: "Unsuccessful operation: indicates that the endpoint is not available for public use." + content: + application/json: + schema: + $ref: '#/components/schemas/ForbiddenResponse' + '500': + description: "Unsuccessful operation: indicates that an unexpected, internal server error happened which prevented the node from fulfilling the request." + content: + application/json: + schema: + $ref: '#/components/schemas/InternalErrorResponse' + + /api/indexer/v2/outputs/delegation/{delegationId}: + get: + tags: + - delegation outputs + summary: Returns the delegations for the delegationId. + description: Returns the delegations for the delegationId. + parameters: + - in: path + name: delegationId + schema: + type: string + example: "0x1505ec099896ab05d9e08fbc7101ae4dff0093b3943b28f789ed2ca728bcc8d6" + description: Unique identifier of the delegationId. + required: true + responses: + '200': + description: "Successful operation." + content: + application/json: + schema: + $ref: '#/components/schemas/OutputsResponse' + examples: + Query results in single output: + $ref: >- + #/components/examples/get-outputs-response-single-example + '400': + description: "Unsuccessful operation: indicates that the provided data is invalid." + content: + application/json: + schema: + $ref: '#/components/schemas/BadRequestResponse' + '403': + description: "Unsuccessful operation: indicates that the endpoint is not available for public use." + content: + application/json: + schema: + $ref: '#/components/schemas/ForbiddenResponse' + '404': + description: "Unsuccessful operation: indicates that the requested data was not found." + content: + application/json: + schema: + $ref: '#/components/schemas/NotFoundResponse' + '500': + description: "Unsuccessful operation: indicates that an unexpected, internal server error happened which prevented the node from fulfilling the request." + content: + application/json: + schema: + $ref: '#/components/schemas/InternalErrorResponse' + + /api/indexer/v2/outputs/foundry: + get: + tags: + - foundry outputs + summary: Returns foundry outputs filtered based on parameters. + description: Returns foundry outputs filtered based on parameters. + parameters: + - in: query + name: account + schema: + type: string + example: iota1prlgpsht03ekmghhex8v7y67a835uns8dtlxu807hj0v279c74kj76j6rev + description: Filter foundry outputs based on bech32-encoded address of the controlling account. + - in: query + name: hasNativeTokens + schema: + type: boolean + example: true + description: Filters outputs based on the presence of native tokens. + - in: query + name: nativeToken + schema: + type: string + example: "0x4e16190b6f3076120c685b1d554d28443b12203e5b424d4e366230623b7b165a222250175d29" + description: Filters outputs that have the given native token ID. + - in: query + name: createdBefore + schema: + type: integer + example: 200 + description: Return outputs that were created before a certain slot index. + - in: query + name: createdAfter + schema: + type: integer + example: 200 + description: Return outputs that were created after a certain slot index. + - in: query + name: pageSize + schema: + type: integer + example: 10 + description: The maximum amount of items returned in one call. If there are more items, a cursor to the next page is returned too. + The parameter is ignored when pageSize is defined via the cursor parameter. + - in: query + name: cursor + schema: + type: string + example: 0c78e998f5177834ecb3bae1596d5056af76e487386eecb19727465b4be86a790200.10 + description: Starts the search from the cursor (createdSlotIndex+outputId.pageSize). + responses: + '200': + description: "Successful operation." + content: + application/json: + schema: + $ref: '#/components/schemas/OutputsResponse' + examples: + Query results in 3 outputs: + $ref: >- + #/components/examples/get-outputs-response-three-example + No matching Output IDs found: + $ref: >- + #/components/examples/get-outputs-empty-response-example + Paging - more items found than it can fit on single page: + $ref: >- + #/components/examples/get-outputs-pagesize2-response-example + '400': + description: "Unsuccessful operation: indicates that the provided data is invalid." + content: + application/json: + schema: + $ref: '#/components/schemas/BadRequestResponse' + '403': + description: "Unsuccessful operation: indicates that the endpoint is not available for public use." + content: + application/json: + schema: + $ref: '#/components/schemas/ForbiddenResponse' + '500': + description: "Unsuccessful operation: indicates that an unexpected, internal server error happened which prevented the node from fulfilling the request." + content: + application/json: + schema: + $ref: '#/components/schemas/InternalErrorResponse' + + /api/indexer/v2/outputs/foundry/{foundryId}: + get: + tags: + - foundry outputs + summary: Returns the Output ID of the current unspent foundry output for foundryId. + description: Returns the Output ID of the current unspent foundry output for foundryId. + parameters: + - in: path + name: foundryId + schema: + type: string + example: "0x081505ec099896ab05d9e08fbc7101ae4dff0093b3943b28f789ed2ca728bcc8d60100000000" + description: Unique identifier of the foundry. + required: true + responses: + '200': + description: "Successful operation." + content: + application/json: + schema: + $ref: '#/components/schemas/OutputsResponse' + examples: + Query results in single output: + $ref: >- + #/components/examples/get-outputs-response-single-example + '400': + description: "Unsuccessful operation: indicates that the provided data is invalid." + content: + application/json: + schema: + $ref: '#/components/schemas/BadRequestResponse' + '403': + description: "Unsuccessful operation: indicates that the endpoint is not available for public use." + content: + application/json: + schema: + $ref: '#/components/schemas/ForbiddenResponse' + '404': + description: "Unsuccessful operation: indicates that the requested data was not found." + content: + application/json: + schema: + $ref: '#/components/schemas/NotFoundResponse' + '500': + description: "Unsuccessful operation: indicates that an unexpected, internal server error happened which prevented the node from fulfilling the request." + content: + application/json: + schema: + $ref: '#/components/schemas/InternalErrorResponse' + + /api/indexer/v2/outputs/nft: + get: + tags: + - nft outputs + summary: Returns nft outputs filtered based on parameters. + description: Returns nft outputs filtered based on parameters. + parameters: + - in: query + name: address + schema: + type: string + example: iota1qrhacyfwlcnzkvzteumekfkrrwks98mpdm37cj4xx3drvmjvnep6xqgyzyx + description: The Bech32-encoded address that should be searched for in the Address Unlock Condition of outputs. + - in: query + name: issuer + schema: + type: string + example: iota1qrhacyfwlcnzkvzteumekfkrrwks98mpdm37cj4xx3drvmjvnep6xqgyzyx + description: Filters outputs based on bech32-encoded issuer address. + - in: query + name: sender + schema: + type: string + example: iota1qrhacyfwlcnzkvzteumekfkrrwks98mpdm37cj4xx3drvmjvnep6xqgyzyx + description: Filters outputs based on the presence of validated Sender (bech32 encoded). + - in: query + name: hasNativeTokens + schema: + type: boolean + example: true + description: Filters outputs based on the presence of native tokens. + - in: query + name: nativeToken + schema: + type: string + example: "0x4e16190b6f3076120c685b1d554d28443b12203e5b424d4e366230623b7b165a222250175d29" + description: Filters outputs that have the given native token ID. + - in: query + name: hasStorageDepositReturn + schema: + type: boolean + example: true + description: Filters outputs based on the presence of storage deposit return unlock condition. + - in: query + name: storageDepositReturnAddress + schema: + type: string + example: iota1qrhacyfwlcnzkvzteumekfkrrwks98mpdm37cj4xx3drvmjvnep6xqgyzyx + description: Filter outputs based on the presence of a specific return address in the storage deposit return + unlock condition. + - in: query + name: hasTimelock + schema: + type: boolean + example: true + description: Filters outputs based on the presence of timelock unlock condition. + - in: query + name: timelockedBefore + schema: + type: integer + example: 200 + description: Return outputs that are timelocked before a certain slot index. + - in: query + name: timelockedAfter + schema: + type: integer + example: 200 + description: Return outputs that are timelocked after a certain slot index. + - in: query + name: hasExpiration + schema: + type: boolean + example: true + description: Filters outputs based on the presence of expiration unlock condition. + - in: query + name: expiresBefore + schema: + type: integer + example: 200 + description: Return outputs that expire before a certain slot index. + - in: query + name: expiresAfter + schema: + type: integer + example: 200 + description: Return outputs that expire after a certain slot index. + - in: query + name: expirationReturnAddress + schema: + type: string + example: iota1qrhacyfwlcnzkvzteumekfkrrwks98mpdm37cj4xx3drvmjvnep6xqgyzyx + description: Filter outputs based on the presence of a specific return address in the expiration unlock + condition. + - in: query + name: tag + schema: + type: string + example: "0x4ec7f23" + description: Filters outputs based on matching Tag Feature. + - in: query + name: createdBefore + schema: + type: integer + example: 200 + description: Return outputs that were created before a certain slot index. + - in: query + name: createdAfter + schema: + type: integer + example: 200 + description: Return outputs that were created after a certain slot index. + - in: query + name: unlockableByAddress + schema: + type: string + example: iota1qrhacyfwlcnzkvzteumekfkrrwks98mpdm37cj4xx3drvmjvnep6xqgyzyx + description: The address unlock related query parameters. + - in: query + name: pageSize + schema: + type: integer + example: 10 + description: The maximum amount of items returned in one call. If there are more items, a cursor to the next page is returned too. + The parameter is ignored when pageSize is defined via the cursor parameter. + - in: query + name: cursor + schema: + type: string + example: 0c78e998f5177834ecb3bae1596d5056af76e487386eecb19727465b4be86a790200.10 + description: Starts the search from the cursor (createdSlotIndex+outputId.pageSize). + responses: + '200': + description: "Successful operation." + content: + application/json: + schema: + $ref: '#/components/schemas/OutputsResponse' + examples: + Query results in 3 outputs: + $ref: >- + #/components/examples/get-outputs-response-three-example + No matching Output IDs found: + $ref: >- + #/components/examples/get-outputs-empty-response-example + Paging - more items found than it can fit on single page: + $ref: >- + #/components/examples/get-outputs-pagesize2-response-example + '400': + description: "Unsuccessful operation: indicates that the provided data is invalid." + content: + application/json: + schema: + $ref: '#/components/schemas/BadRequestResponse' + '403': + description: "Unsuccessful operation: indicates that the endpoint is not available for public use." + content: + application/json: + schema: + $ref: '#/components/schemas/ForbiddenResponse' + '500': + description: "Unsuccessful operation: indicates that an unexpected, internal server error happened which prevented the node from fulfilling the request." + content: + application/json: + schema: + $ref: '#/components/schemas/InternalErrorResponse' + + /api/indexer/v2/outputs/nft/{nftId}: + get: + tags: + - nft outputs + summary: Returns the Output ID of the current unspent nft output for nftId. + description: Returns the Output ID of the current nft output for nftId. + parameters: + - in: path + name: nftId + schema: + type: string + example: "0x19c82b32761fd8729a1a6c77f7c17597e4b9b01759794e52381f6a0050b0c11f" + description: Unique identifier of the nft. + required: true + responses: + '200': + description: "Successful operation." + content: + application/json: + schema: + $ref: '#/components/schemas/OutputsResponse' + examples: + Query results in single output: + $ref: >- + #/components/examples/get-outputs-response-single-example + '400': + description: "Unsuccessful operation: indicates that the provided data is invalid." + content: + application/json: + schema: + $ref: '#/components/schemas/BadRequestResponse' + '403': + description: "Unsuccessful operation: indicates that the endpoint is not available for public use." + content: + application/json: + schema: + $ref: '#/components/schemas/ForbiddenResponse' + '404': + description: "Unsuccessful operation: indicates that the requested data was not found." + content: + application/json: + schema: + $ref: '#/components/schemas/NotFoundResponse' + '500': + description: "Unsuccessful operation: indicates that an unexpected, internal server error happened which prevented the node from fulfilling the request." + content: + application/json: + schema: + $ref: '#/components/schemas/InternalErrorResponse' +components: + examples: + get-outputs-response-three-example: + value: + committedSlot: 101 + items: + - "0x0c78e998f5177834ecb3bae1596d5056af76e487386eecb19727465b4be86a790000" + - "0x0c78e998f5177834ecb3bae1596d5056af76e487386eecb19727465b4be86a790100" + - "0x0c78e998f5177834ecb3bae1596d5056af76e487386eecb19727465b4be86a790200" + get-outputs-response-single-example: + value: + committedSlot: 101 + items: + - "0x0c78e998f5177834ecb3bae1596d5056af76e487386eecb19727465b4be86a790000" + get-outputs-empty-response-example: + value: + committedSlot: 101 + items: + - + get-outputs-pagesize2-response-example: + value: + committedSlot: 101 + cursor: 61fa44a14d35ce14b9d0e7ee6ac9af70c0af156be269f69348be6d6f83c80a3a8a44ce440000.2 + items: + - "0x0c78e998f5177834ecb3bae1596d5056af76e487386eecb19727465b4be86a790000" + - "0x0c78e998f5177834ecb3bae1596d5056af76e487386eecb19727465b4be86a790100" + + get-account-response-example: + value: + + schemas: + ErrorResponse: + description: The error format. + properties: + error: + type: object + properties: + code: + type: string + description: The application error code. + message: + type: string + description: The error reason. + required: + - code + - message + required: + - error + + ForbiddenResponse: + description: Indicates that this endpoint is not available for public use. + allOf: + - $ref: '#/components/schemas/ErrorResponse' + example: + error: + code: 403 + message: not available for public use + + ServiceUnavailableResponse: + description: Indicates that the service is unavailable. + allOf: + - $ref: '#/components/schemas/ErrorResponse' + example: + error: + code: 503 + message: service unavailable + + BadRequestResponse: + description: Indicates that the request was bad. + allOf: + - $ref: '#/components/schemas/ErrorResponse' + example: + error: + code: 400 + message: invalid data provided + + NotFoundResponse: + description: Indicates that the data was not found. + allOf: + - $ref: '#/components/schemas/ErrorResponse' + example: + error: + code: 404 + message: could not find data + + InternalErrorResponse: + description: Indicates that the server encountered an unexpected condition, which prevented it from fulfilling the request by the client. + allOf: + - $ref: '#/components/schemas/ErrorResponse' + example: + error: + code: 500 + message: internal server error + + OutputsResponse: + description: Returns a list of Output IDs. + properties: + committedSlot: + type: integer + description: The committed slot at which these outputs were available at. + pageSize: + type: integer + description: The maximum amount of items returned in one call. If there are more items, a cursor to the next page is returned too. + cursor: + type: string + description: The cursor to use for getting the next page of results. + nullable: true + items: + type: array + description: The Output IDs (transaction hash + output index) of the outputs satisfying the query. Hex-encoded with 0x prefix. + items: + type: string + required: + - committedSlot + - pageSize + - items +