Starknet.js v3 - human readable interfaces

[janek26]

Hey all,
today I'll propose new interfaces for Provider, Signer and especially Contract.

Provider and Signer

A Provider should stay similar to an ethers.js Provider, allowing for interactions with the blockchain without signing. Traditionally these are reading states from the blockchain, but due to how StarkNet is build you can do a little more with it in starknet.js, like sending contract deployment transactions etc.

A Signer extends a Provider and inherits/implements all of its methods. It also introduces some methods which are just possible with a Signer, eg creating/verifying signatures. It's primarily interacting with an account contract on starknet.

Signer

Signer should get an additional method verifyMessage(typedData: TypedData, signature: Signature): Promise<boolean>, which allows the signer to check if the given signature signs the given message using the signers pub key.
There should also be a verifyMessageHash(typedDataHash: BigNumberish, signature: Signature): Promise<boolean>, which allows the signer to check if the given signature is valid for the account by calling is_valid_signature on the account contract.

Method inputs

Instance methods like invokeFunction should do more preprocessing and not expect results from helper functions like getSelectorFromName or compileCalldata.
This will allow other actors in the ecosystem to implement their own Provider or Signer, with the ability to show human readable data to the user. This is very important for wallets, but also Hardware wallets like Ledger, so we don't just approve hashes and hex values like we do in Ethereum today.

entry_point_selector

It should always be the human readable string, like "mint" or "transfer". It should not be a pre-computed address like the result of getSelectorFromName or any other hex value.

calldata

This one is a little bit more complicated. Basically there are 2 difference appearances of calldata. In Providers and Signers the calldata normally isn't aware of any ABI or context. In these cases, like addTransaction there should be a 2nd parameter which accepts an ABI. This way signers like Argent X, Ledger or whatever, can show relevant information to the user approving. This parameter should be optional, and wallets can handle it differently if it's not provided (deny signing, display warning etc).

signature

Signatures should not assume that there's just one signing party. Signature is always a flat array of BigNumberish with variable length n.

Contract

Contracts can do data transforming in JS based on an ABI. They can also call and invoke to starknet through a provided Signer.
We should split between Contract and ContractFactory (which is also able to deploy contracts) like they do with ethers.js

Contracts should be able to transform most common Cairo values, like Uint256, to JS objects like BigNumber. It could also allow the user to pass there own transformers, similar to how JSON.parse does it.

[0xs34n]

As I've told you in private, think ethers.js has the right abstractions. Glad we're following it. Thank you for writing this!

Background on ethers.js API architecture:

https://docs.ethers.io/v5/api/

[dhruvkelawala]

I agree. We should follow the ethers.js API architecture. Currently, it's difficult to adapt traditional Web3 dApps that used ethers.js to starknet.js.

[janek26]

that's the goal of this proposal :) but we'll never be able to have a 1:1 api, just because of how starknet is different to eve chains (account abstraction etc)

[dhruvkelawala]

Yes, 1:1 API is not possible. I understand that. But having interfaces as close as ethers.js might help I think. I am not sure if it's possible, but For example,

In ether.js, you can do something like

contract.methodName(...args) // Here, We do not need to explicitly define if it's a call or invoke method. Also, args are positional parameters instead of key-value pairs.
In starknet.js, same thing would go like

contract.call('methodName', { address: account })

[fracek]

I think the Contract class should also be implemented in such a way that it can be used as base class once someone implements a tool like TypeChain for Cairo.

[janek26]

Fully agree!

[0xs34n]

One point mentioned by @juniset, we should probably document somewhere that verifyMessage and verifyMessageHash are done on chain through the account contract. Either through comments in the code itself or in our (future) documentation, or both.

Developers coming from ETH will assume this is done through local private/public keys, like how it works with MetaMask.

[0xs34n]

Essentially, there should be somewhere to learn this new paradigm, which I have learned through this process. Perhaps I will point it to Perama's blogs.

[tabaktoni]

Legacy