archive/call: Synchronize the return type with sudo/sessionsKeys

[lexnv]

This PR simplifies the return type of the archive_unstable_call method.

This effectively changes the return object from success: true, value: ... to result:... and success: false, error:... to error:... to keep consistency with the sudo_sessionsKeys format.

The notes have been adjusted to reflect feedback from: #94.

@paritytech/subxt-team @tomaka @josepot @jsdw

[tomaka]

Throughout the entire API, JSON-RPC errors are only ever used in situations where the API is misused. This is intentional so that JSON-RPC client developers don't need to worry about these errors.

[lexnv]

Just to be sure I got this right:
The result of the archive_call method is returned similar to:

// Ok result wrapped in JSON-RPC Ok response
{
    "jsonrpc": "2.0",
    "id": 1, 
    "result": { "success": true, "value": ... },
}

// Error result wrapped in JSON-RPC Ok response
{
    "jsonrpc": "2.0",
    "id": 1, 
    "result": { "success": false, "error": ... },
}

And we are only returning a JSON-RPC error object {"jsonrpc": "2.0", "error": {"code": -32601, "message": ".."}, "id": "1"} for the possible error section?

[josepot]

I'm not entirely certain if this is the appropriate forum for this suggestion, but I believe it would be beneficial if archive methods could accept either a hash or a block-number. My rationale for this is:

1. Binary searches are frequently employed when interacting with archive nodes. By allowing for block-number input, these searches could be facilitated and made more efficient.

2. While I don't claim expertise in this domain, it appears logical to me that archive nodes would have block numbers thoroughly indexed. If this assumption holds, then accessing data using a block number should be just as quick and efficient as using a block hash.

I hope my intuition aligns with the technical realities, and I'd appreciate any insight or clarification on this matter.

[tomaka]

Just to be sure I got this right: The result of the archive_call method is returned similar to:

// Ok result wrapped in JSON-RPC Ok response
{
    "jsonrpc": "2.0",
    "id": 1, 
    "result": { "success": true, "value": ... },
}

// Error result wrapped in JSON-RPC Ok response
{
    "jsonrpc": "2.0",
    "id": 1, 
    "result": { "success": false, "error": ... },
}

And we are only returning a JSON-RPC error object {"jsonrpc": "2.0", "error": {"code": -32601, "message": ".."}, "id": "1"} for the possible error section?

Yes

[lexnv]

Have modified the resulting object to align with sudo_sessionKeys, such that we could reuse it across the implementation methods.

Let me know what you think of it since it removes the success flag 🙏

// Error
{
    "jsonrpc": "2.0",
    "id": 1, 
    "result": { "error": ... },
}

// Ok
{
    "jsonrpc": "2.0",
    "id": 1, 
    "result": { "result": ... },
}

Introducing this object seems oddly similar to a json-rpc object (https://github.com/paritytech/polkadot-sdk/pull/1682/files#r1335584309). Was this extension also motivated by json-rpc clients dropping / ignoring the error component? 🤔

[jsdw]

LGTM with the rationale that it makes the method more consistent with https://paritytech.github.io/json-rpc-interface-spec/api/sudo_sessionKeys_unstable_generate.html

(if there was a desire to go the other way and add success to both I'd also be happy).

@tomaka any remaining objections to merging this?

[tomaka]

Let me know what you think of it since it removes the success flag

I included this success more or less by reflex, because it's easier to write TypeScript definitions with such a flag that unambiguously distinguishes between situations.
But I don't care either way.

[jsdw]

I included this success more or less by reflex, because it's easier to write TypeScript definitions with such a flag that unambiguously distinguishes between situations.

I'm sortof the same; I don't care strongly either way but happy for a touch of extra consistency across the spec

[jsdw]

@lexnv perhaps we should just keep the success bool for both cases since it does help writing TS types a little, and then this is good to merge I think!

[jsdw]

Works for me!