From b2d694be259c3cea5f5fad14ad994480625f1543 Mon Sep 17 00:00:00 2001 From: Jane Wang Date: Thu, 15 Feb 2024 12:08:01 -0500 Subject: [PATCH] Update RPC docs for clarify on deprecation of postional array and costs (#721) * Update RPC docs for clarify on deprecation of postional array and costs * Update description on costs * Update in JSON-RPC info * Update transaction desc * Add build file * remove an extra file * modify the patch for the openrpc react package this will display our custom note following the parameters heading and before any of the named parameters are listed * remove the notes about by-name parameters in transaction params * add `deprecated` to the `cost` object in the tx simulation result * add the built `openrpc.json` file --------- Co-authored-by: Jane Wang Co-authored-by: Elliot Voris --- api/json-rpc.mdx | 8 ++++ openrpc/src/methods/simulateTransaction.json | 3 +- .../@metamask+open-rpc-docs-react+0.1.2.patch | 38 ++++++++++++++++++- static/openrpc.json | 3 +- 4 files changed, 49 insertions(+), 3 deletions(-) diff --git a/api/json-rpc.mdx b/api/json-rpc.mdx index d2004ce3..d78265a8 100644 --- a/api/json-rpc.mdx +++ b/api/json-rpc.mdx @@ -12,6 +12,14 @@ To interact with soroban-rpc from inside a JavaScript application, use the [Java When XDR is passed as a parameter or returned, it is always a string encoded using standard base64. +:::info + +Please note that parameter structure must contain named parameters as a by-name +object, and not as positional arguments as a by-position array. Positional +arguments as a by-position array will be deprecated in future RPC releases. + +::: + ## Open-RPC Specification Soroban-RPC provides an [OpenRPC] specification document that can be used to mock, build, and/or validate both server and client software implementations. This document is used to generate all of our [methods] documentation pages. You can view the full [specification document here]. Additionally, you can experiment with this specificaiton document in the [OpenRPC Playground]. diff --git a/openrpc/src/methods/simulateTransaction.json b/openrpc/src/methods/simulateTransaction.json index 0265feb8..cdf2bbc6 100644 --- a/openrpc/src/methods/simulateTransaction.json +++ b/openrpc/src/methods/simulateTransaction.json @@ -30,7 +30,8 @@ }, "cost": { "type": "object", - "description": "(optional) - Information about instructions used, etc. Not present in case of error.", + "description": "(optional) - The cost object is legacy, inaccurate, and will be deprecated in future RPC releases. Please decode transactionData XDR to retrieve the correct resources.", + "deprecated": true, "properties": { "cpuInsns": { "type": "string", diff --git a/patches/@metamask+open-rpc-docs-react+0.1.2.patch b/patches/@metamask+open-rpc-docs-react+0.1.2.patch index e87c94c4..61e8f0de 100644 --- a/patches/@metamask+open-rpc-docs-react+0.1.2.patch +++ b/patches/@metamask+open-rpc-docs-react+0.1.2.patch @@ -1,5 +1,5 @@ diff --git a/node_modules/@metamask/open-rpc-docs-react/dist/ExamplePairing/ExamplePairing.js b/node_modules/@metamask/open-rpc-docs-react/dist/ExamplePairing/ExamplePairing.js -index 354ce73..5e07a7f 100644 +index 354ce73..129371f 100644 --- a/node_modules/@metamask/open-rpc-docs-react/dist/ExamplePairing/ExamplePairing.js +++ b/node_modules/@metamask/open-rpc-docs-react/dist/ExamplePairing/ExamplePairing.js @@ -45,10 +45,37 @@ class ExamplePairing extends react_1.Component { @@ -93,3 +93,39 @@ index b8b0f3d..9a49549 100644 }; onExamplePairingChange?: (examplePairing: ExamplePairingObject | undefined) => void; reactJsonOptions?: object; +diff --git a/node_modules/@metamask/open-rpc-docs-react/dist/Params/Params.js b/node_modules/@metamask/open-rpc-docs-react/dist/Params/Params.js +index 4b059a6..b5dafce 100644 +--- a/node_modules/@metamask/open-rpc-docs-react/dist/Params/Params.js ++++ b/node_modules/@metamask/open-rpc-docs-react/dist/Params/Params.js +@@ -34,17 +34,20 @@ class Params extends react_1.Component { + if (!params || params.length === 0) { + return null; + } +- return (params.map((row, i) => react_1.default.createElement("section", null, +- react_1.default.createElement("h3", null, +- i + 1, +- ". ", +- row.name, +- (row.required === undefined || +- row.required === true) && +- react_1.default.createElement("span", { className: "content-descriptor-summary" }, +- react_1.default.createElement("i", null, +- react_1.default.createElement("small", null, " (required)")))), +- react_1.default.createElement(ContentDescriptor_1.default, { key: row.name, contentDescriptor: row, uiSchema: uiSchema })))); ++ return ( ++ [react_1.default.createElement("p", { key: "param-structure", className: "param-structure-requirement" }, "Please note that parameter structure within the request must contain named parameters as a by-name object, and not as positional arguments in a by-position array"), ++ ...params.map((row, i) => react_1.default.createElement("section", null, ++ react_1.default.createElement("h3", null, ++ i + 1, ++ ". ", ++ row.name, ++ (row.required === undefined || ++ row.required === true) && ++ react_1.default.createElement("span", { className: "content-descriptor-summary" }, ++ react_1.default.createElement("i", null, ++ react_1.default.createElement("small", null, " (required)")))), ++ react_1.default.createElement(ContentDescriptor_1.default, { key: row.name, contentDescriptor: row, uiSchema: uiSchema })))] ++ ); + } + } + exports.default = Params; diff --git a/static/openrpc.json b/static/openrpc.json index dd91ba16..64f86389 100644 --- a/static/openrpc.json +++ b/static/openrpc.json @@ -1049,7 +1049,8 @@ }, "cost": { "type": "object", - "description": "(optional) - Information about instructions used, etc. Not present in case of error.", + "description": "(optional) - The cost object is legacy, inaccurate, and will be deprecated in future RPC releases. Please decode transactionData XDR to retrieve the correct resources.", + "deprecated": true, "required": [ "cpuInsns", "memBytes"