From e0b5c4648e0d2412eae90c58fd13461c60ade039 Mon Sep 17 00:00:00 2001 From: James Hiew Date: Fri, 1 Jul 2022 12:31:41 +0100 Subject: [PATCH 1/8] Add specs/openapi.yml --- specs/openapi.yml | 130 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 130 insertions(+) create mode 100644 specs/openapi.yml diff --git a/specs/openapi.yml b/specs/openapi.yml new file mode 100644 index 0000000000..7533c14431 --- /dev/null +++ b/specs/openapi.yml @@ -0,0 +1,130 @@ +openapi: 3.0.3 +info: + title: Anoma + description: Interacting with an Anoma blockchain via Tendermint RPC + version: 0.6.1 +servers: + - url: http://127.0.0.1:26657 + description: Tendermint RPC endpoint for an Anoma ledger +paths: + /: + post: + summary: Interact with the Anoma blockchain via Tendermint RPC + operationId: abci_query + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + id: + description: Should be unique between requests + type: integer + example: 58392 + method: + description: The Tendermint RPC method being called which in this case should always be abci_query + type: string + enum: + - "abci_query" + params: + type: object + required: + - path + properties: + path: + description: Path as will be recognized by the ledger + oneOf: + - type: string + enum: + - "epoch" + - "dry_run_tx" + description: > + * `epoch` - Epoch at the given block height + * `dry_run_tx` - Dry run a transaction + - type: string + description: Read a storage value with exact storage key + pattern: r"^value\/(\w|\/)+$" + - type: string + description: Read a range of storage values with a matching key prefix + pattern: r"^prefix\/(\w|\/)+$" + - type: string + description: Check if the given storage key exists + pattern: r"^has_key\/(\w|\/)+$" + data: + description: Optional data to go along with the query (base64-encoded if necessary) + type: string + example: "abcd" + default: "" + height: + description: Height as a base64 encoded integer (0 means latest) + type: string + example: "1" + default: "0" + prove: + description: Include proofs of the transaction's inclusion in the block + type: boolean + example: true + default: false + examples: + epoch_latest: + summary: Get the latest epoch + value: + { + "id": 2, + "method": "abci_query", + "params": { "path": "epoch" }, + } + epoch_at_height: + summary: Get the epoch at a given height + value: + { + "id": 2, + "method": "abci_query", + "params": { "path": "epoch", "height": 2 }, + } + responses: + "200": + description: Response of the submitted query + content: + application/json: + schema: + $ref: "https://docs.tendermint.com/v0.34/rpc/openapi.yaml#/components/schemas/ABCIQueryResponse" + examples: + epoch_latest: + value: + { + "jsonrpc": "2.0", + "id": 2, + "result": + { + "response": + { + "code": 0, + "log": "", + "info": "", + "index": "0", + "key": null, + "value": "lQAAAAAAAAA=", + "proofOps": null, + "height": "0", + "codespace": "", + }, + }, + } + "500": + description: Error + content: + application/json: + schema: + $ref: "https://docs.tendermint.com/v0.34/rpc/openapi.yaml#/components/schemas/ErrorResponse" + example: + { + "jsonrpc": "2.0", + "error": + { + "code": -32700, + "message": "Parse error. Invalid JSON", + "data": "error unmarshaling request: invalid character 'd' after object key:value pair", + }, + } From 42bfb42d5d79af1fc0ad8fceecc45343d26599c8 Mon Sep 17 00:00:00 2001 From: James Hiew Date: Fri, 8 Jul 2022 15:13:23 +0100 Subject: [PATCH 2/8] A key can contain any ASCII, not just alphabetical characters --- specs/openapi.yml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/specs/openapi.yml b/specs/openapi.yml index 7533c14431..e8bf5259d3 100644 --- a/specs/openapi.yml +++ b/specs/openapi.yml @@ -44,13 +44,13 @@ paths: * `dry_run_tx` - Dry run a transaction - type: string description: Read a storage value with exact storage key - pattern: r"^value\/(\w|\/)+$" + pattern: r"^value\/([\x00-\x7F]|\/)+$" - type: string description: Read a range of storage values with a matching key prefix - pattern: r"^prefix\/(\w|\/)+$" + pattern: r"^prefix\/([\x00-\x7F]|\/)+$" - type: string description: Check if the given storage key exists - pattern: r"^has_key\/(\w|\/)+$" + pattern: r"^has_key\/([\x00-\x7F]|\/)+$" data: description: Optional data to go along with the query (base64-encoded if necessary) type: string From a374fd2bb5f8985273b4e7dceff8d507307e74e7 Mon Sep 17 00:00:00 2001 From: James Hiew Date: Fri, 8 Jul 2022 15:13:34 +0100 Subject: [PATCH 3/8] Add example for getting an account's public key --- specs/openapi.yml | 48 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 48 insertions(+) diff --git a/specs/openapi.yml b/specs/openapi.yml index e8bf5259d3..52acc7fab5 100644 --- a/specs/openapi.yml +++ b/specs/openapi.yml @@ -83,6 +83,18 @@ paths: "method": "abci_query", "params": { "path": "epoch", "height": 2 }, } + get_account_public_key: + summary: Get the public key for an account which has been initialized with a validity predicate, with proof + value: + { + "id": 2, + "method": "abci_query", + "params": + { + "path": "value/#atest1v4ehgw36g4pyg3j9x3qnjd3cxgmyz3fk8qcrys3hxdp5xwfnx3zyxsj9xgunxsfjg5u5xvzyzrrqtn/public_key", + "prove": true, + }, + } responses: "200": description: Response of the submitted query @@ -112,6 +124,42 @@ paths: }, }, } + get_account_public_key: + value: + { + "jsonrpc": "2.0", + "id": 2, + "result": + { + "response": + { + "code": 0, + "log": "", + "info": "", + "index": "0", + "key": null, + "value": "ABdruiwJLZ4w4Z/MoD+aW3fH4vkc9+QhGOCGmDr1oVz+", + "proofOps": + { + "ops": + [ + { + "type": "ics23_CommitmentProof", + "key": "I2F0ZXN0MXY0ZWhndzM2ZzRweWczajl4M3FuamQzY3hnbXl6M2ZrOHFjcnlzM2h4ZHA1eHdmbngzenl4c2o5eGd1bnhzZmpnNXU1eHZ6eXpycnF0bi9wdWJsaWNfa2V5", + "data": "Cu0CCmAjYXRlc3QxdjRlaGd3MzZnNHB5ZzNqOXgzcW5qZDNjeGdteXozZms4cWNyeXMzaHhkcDV4d2ZueDN6eXhzajl4Z3VueHNmamc1dTV4dnp5enJycXRuL3B1YmxpY19rZXkSIQAXa7osCS2eMOGfzKA/mlt3x+L5HPfkIRjghpg69aFc/hooCAEQARgBKiAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAACIkCAESIOQIgEOVb0Hv2eOTmYDks2uP4L4gs0RgmV2wUisInkbQIiQIARog04WfgQqfT2X9aD9qhA/fWy6LS6JjdmkpmUfkK9hoKOwiJAgBEiB+tFAPUElWCcCpAL4khjoihfs19F7tfdagbWWE44kCESIkCAEaIBtq2MVGbblK4zgD3h5vxQNKiCU+dmaHLQSpzWvBT3lwIiQIARogwl8LV3ECHOBxasQriaEAE/dgSZnKZ6vBm6Zm7vTED0Y=", + }, + { + "type": "ics23_CommitmentProof", + "key": "I2F0ZXN0MXY0ZWhndzM2ZzRweWczajl4M3FuamQzY3hnbXl6M2ZrOHFjcnlzM2h4ZHA1eHdmbngzenl4c2o5eGd1bnhzZmpnNXU1eHZ6eXpycnF0bi9wdWJsaWNfa2V5", + "data": "CnkKB2FjY291bnQSIMMIWmruLiaYEqu6LGhBd6QS74N0WncwSIe+tIux4F+BGiYIARABKiAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAACIkCAESIG3BkVXL0ICjUIY1bV7YSPruEfFZLIB2vlL7lpwQ3ycX", + }, + ], + }, + "height": "0", + "codespace": "", + }, + }, + } "500": description: Error content: From ce036b0a8459c2a0b6b0bd9272afb42e273fd447 Mon Sep 17 00:00:00 2001 From: James Hiew Date: Fri, 8 Jul 2022 15:16:32 +0100 Subject: [PATCH 4/8] Add invalid storage key error response example --- specs/openapi.yml | 25 +++++++++++++++++++++++-- 1 file changed, 23 insertions(+), 2 deletions(-) diff --git a/specs/openapi.yml b/specs/openapi.yml index 52acc7fab5..40b15751f0 100644 --- a/specs/openapi.yml +++ b/specs/openapi.yml @@ -97,7 +97,7 @@ paths: } responses: "200": - description: Response of the submitted query + description: Response of the submitted query, which may have been successful or may have errored at the application level. content: application/json: schema: @@ -160,8 +160,29 @@ paths: }, }, } + invalid_storage_key: + value: + { + "jsonrpc": "2.0", + "id": 2, + "result": + { + "response": + { + "code": 1, + "log": "", + "info": "RPC error: Invalid storage key: Error parsing address: Error decoding address from Bech32m: invalid length", + "index": "0", + "key": null, + "value": null, + "proofOps": null, + "height": "0", + "codespace": "", + }, + }, + } "500": - description: Error + description: Tendermint-level error content: application/json: schema: From 4efd4613a98ed39c594cf14bf2efa2ad2cfada80 Mon Sep 17 00:00:00 2001 From: James Hiew Date: Tue, 19 Jul 2022 12:05:17 +0100 Subject: [PATCH 5/8] Storage key regexes should permit any UTF-8 string --- specs/openapi.yml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/specs/openapi.yml b/specs/openapi.yml index 40b15751f0..f7f2f53e0c 100644 --- a/specs/openapi.yml +++ b/specs/openapi.yml @@ -44,13 +44,13 @@ paths: * `dry_run_tx` - Dry run a transaction - type: string description: Read a storage value with exact storage key - pattern: r"^value\/([\x00-\x7F]|\/)+$" + pattern: r"^value\/.+$" - type: string description: Read a range of storage values with a matching key prefix - pattern: r"^prefix\/([\x00-\x7F]|\/)+$" + pattern: r"^prefix\/.+$" - type: string description: Check if the given storage key exists - pattern: r"^has_key\/([\x00-\x7F]|\/)+$" + pattern: r"^has_key\/.+$" data: description: Optional data to go along with the query (base64-encoded if necessary) type: string From 959737d1046fa9086c3b68da7cb841bcab5cd3d3 Mon Sep 17 00:00:00 2001 From: James Date: Tue, 19 Jul 2022 12:14:34 +0100 Subject: [PATCH 6/8] Apply suggestions from code review Co-authored-by: Tomas Zemanovic --- specs/openapi.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specs/openapi.yml b/specs/openapi.yml index f7f2f53e0c..d207b42a11 100644 --- a/specs/openapi.yml +++ b/specs/openapi.yml @@ -40,7 +40,7 @@ paths: - "epoch" - "dry_run_tx" description: > - * `epoch` - Epoch at the given block height + * `epoch` - Get the epoch of the last block (the height argument is not yet supported ) * `dry_run_tx` - Dry run a transaction - type: string description: Read a storage value with exact storage key From d758b1ba12077f367a7877a9ef86173263d0ff5a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tom=C3=A1=C5=A1=20Zemanovi=C4=8D?= Date: Wed, 17 Aug 2022 08:53:50 +0200 Subject: [PATCH 7/8] docs: move and link to openAPI spec from Ledger RPC --- {specs => documentation/dev/src/specs/ledger}/openapi.yml | 0 documentation/dev/src/specs/ledger/rpc.md | 4 ++++ 2 files changed, 4 insertions(+) rename {specs => documentation/dev/src/specs/ledger}/openapi.yml (100%) diff --git a/specs/openapi.yml b/documentation/dev/src/specs/ledger/openapi.yml similarity index 100% rename from specs/openapi.yml rename to documentation/dev/src/specs/ledger/openapi.yml diff --git a/documentation/dev/src/specs/ledger/rpc.md b/documentation/dev/src/specs/ledger/rpc.md index d0b6c37b6b..2a839ce886 100644 --- a/documentation/dev/src/specs/ledger/rpc.md +++ b/documentation/dev/src/specs/ledger/rpc.md @@ -4,6 +4,10 @@ The ledger provides an RPC interface for submitting transactions to the mempool, The RPC interface is provided as [specified](https://github.com/tendermint/spec/tree/4566f1e3028278c5b3eca27b53254a48771b152b/spec/rpc) from Tendermint and most of the requests are routed to the Namada ledger via ABCI. +## OpenAPI spec + +The [OpenAPI specification](./openapi.yml) is provided. + ## Transactions A [transaction](../ledger.md#transactions) can be submitted to the [mempool](../ledger.md#mempool) via Tendermint's [`BroadCastTxSync`](https://github.com/tendermint/spec/tree/4566f1e3028278c5b3eca27b53254a48771b152b/spec/rpc#broadcasttxsync) or [`BroadCastTxAsync`](https://github.com/tendermint/spec/tree/4566f1e3028278c5b3eca27b53254a48771b152b/spec/rpc#broadcasttxasync). The `CheckTx` result of these requests is success only if the transaction passes [mempool validation rules](../ledger.md#mempool). In case of `BroadCastTxAsync`, the `DeliverTx` is not indicative of the transaction's result, it's merely a result of the transaction being added to the [transaction queue](../ledger.md#outer-transaction-processing). The actual result of the outer transaction and the inner transaction can be found from via the [ABCI events](https://github.com/tendermint/spec/blob/4566f1e3028278c5b3eca27b53254a48771b152b/spec/abci/abci.md#events). From 881e5ca41405f307b942cb34fea8f52bd206fe38 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tom=C3=A1=C5=A1=20Zemanovi=C4=8D?= Date: Wed, 17 Aug 2022 08:57:12 +0200 Subject: [PATCH 8/8] changelog: add #322 --- .changelog/unreleased/docs/322-openapi-spec.md | 1 + 1 file changed, 1 insertion(+) create mode 100644 .changelog/unreleased/docs/322-openapi-spec.md diff --git a/.changelog/unreleased/docs/322-openapi-spec.md b/.changelog/unreleased/docs/322-openapi-spec.md new file mode 100644 index 0000000000..9af416a990 --- /dev/null +++ b/.changelog/unreleased/docs/322-openapi-spec.md @@ -0,0 +1 @@ +- Added OpenAPI spec ([#322](https://github.com/anoma/namada/pull/322)) \ No newline at end of file