Signing transactions and off-chain messages

[juniset]

This is an attempt to specify an encoding and signing standard for transactions and off-chain messages in Starknet.

Context

Wallets have to generate signatures for 2 different types of data: transactions that will be sent to an Account Contract (AC) via the sequencer, and off-chain messages that will be returned to the requesting dapp for verification by calling the is_valid_signature method on the AC.

It is essential that there is no collision between the two sets of signatures, or, in other words, we must ensure that a signature generated on the encoded data of an off-chain message can never be a valid signature on the encoded data of a transaction.

In Ethereum the encoded data of a transaction is clearly defined as RLP<nonce, gasPrice, startGas, to, value, data> and one can easily satisfy the no-collision requirement by starting the encoded data of an off-chain message by 0x19 since it can never be the first byte of RLP encoded data. This is specified in EIP-191.

In addition, a good encoding scheme should make it easy for the wallet to clearly display to the user what he is signing. In Ethereum, this is specified in EIP-712.

On Starknet we have Account Abstraction, which means that the data to be signed for a transaction is (at least for now) completely open.

Proposition

We define the 2 short string prefixes:

• PREFIX_TRANSACTION = 'StarkNet Transaction'
• PREFIX_MESSAGE = 'StarkNet Message'

and the encoding:

Enc[X=(x₀, x₁, ..., x_n-1)] = Enc[Enc[x₀], Enc[x₁], ..., Enc[x_n-1]] = h(....h(h(0,Enc[x₀]), Enc[x₁]), ...), n)

when X is an array, and:

Enc[x] = x

when x is a felt, where

h(a,b)

is the Pedersen hash on 2 field elements.

We also define

selector(str) = starknet_keccak(str)

as defined in https://github.com/starkware-libs/cairo-lang/blob/master/src/starkware/starknet/public/abi.py

Transaction

As part of the discussions around the Account Contract interface, it was decided that AC will expose a single entry point for the execution of a sequence of transactions (multicall):

@external
func __execute__(
        calls_len: felt,
        calls: Call*
    ) -> (response : felt):
end

where Call is the struct:

struct Call:
    member to: felt
    member selector: felt
    member calldata_len: felt
    member calldata: felt
end

We note that this is not yet the interface of AC since Cairo does not support passing array of structs containing arrays in external method. But for signing purpose we will use the target interface.

The account has also access to 3 additional parameters handled by the OS: nonce, max_fee and version. These parameters must be included in the data being signed.

Based on the above, the data to sign for an AC executing an array of calls can be defined as:

signed_data = Enc[PREFIX_TRANSACTION, account, Enc[calls], nonce, max_fee, version]

For the moment there exists 2 implementations of Account Contracts:

• Account.sol in https://github.com/OpenZeppelin/cairo-contracts
• ArgentAccount.sol in https://github.com/argentlabs/argent-contracts-starknet

Off-chain message

Inspired by EIP-712 we can define the encoding of an off-chain message as:

signed_data = Enc[PREFIX_MESSAGE, domain_separator, account, hash_struct(message)]

where

• domain_separator is defined below.
• account is the Account Contract for which the signing is executed
• hash_struct(message) is defined below.

hash_struct:

The message to be hashed is represented as a struct:

struct MyStruct:
    member param1: felt
    member param2: felt*
   ...
end

and we define its encoding as

hash_struct(message) = Enc[type_hash(MyStruct), Enc[param1], Enc[param2], ..., Enc[paramN]]

where type_hash is defined as in EIP-712 (but using selector instead of keccak):

type_hash(MyStruct) = selector('MyStruct(params1:felt, params2:felt*,...)')

If MyStruct references other struct types (and these in turn reference even more struct types), then the set of referenced struct types is collected, sorted by name and appended to the encoding. See EIP-712 for more details

domain_separator:

The domain_separator is defined as the hash_struct of the StarkNetDomain struct:

struct StarkNetDomain:
    member name: felt = 'www.myDapp.com'
    member version: felt = 1
    member chain_id: felt = 'SN_GOERLI'
end

where chain_id is one of ['SN_GOERLI', 'SN_MAIN'] in short strings.

Reference implementation

• In Cairo: https://github.com/argentlabs/argent-contracts-starknet/blob/main/contracts/StructHash.cairo
• in Js: Feature/typed structured data hashing and signing starknet-io/starknet.js#87

Some rationale elements

• The 2 prefixes PREFIX_TRANSACTION and PREFIX_MESSAGE ensure that there will be no collisions between signatures for transactions and off-chain messages.
• The domain_separator in the signed data of off-chain messages ensures that the signatures requested by a dapp cannot be used on another dapp, or on the same dapp but on another deployment (e.g. from Goërli to mainnet).
• The account in the signed data of off-chain messages ensures that if several Account Contracts use the same key, the signature requested by a dapp for an account cannot be used to authenticate another account.

Notes on Dapp to Wallet interaction

• When requesting a wallet to send a transaction, the dapp should provide the information in a structured format with as much user readable information as possible. For example methods should be provided as strings with named parameters, and the encoding should be left to the wallet.
• Based on the above, the security of transaction signing would probably be improved if the selector of a method was applied on its name and the name (+ type?) of its parameters, e.g. selector('my_method(params1,params2,params3)') instead of selector('my_method').

EDIT

• Edited to include multicalls and support Cairo 0.7.1

[martriay]

Looks really good! I like execute as a single entrypoint (let's see how feasible that is in the long run) therefore removing it from the signature sounds good. I wonder what do you think about this three concepts and how should we name them:

• foo: a smart contract call (Account calling transfer on ERC20)
• bar an account call (sending a set of potentially multiple foo to an Account for execution, through execute)
• baz: an "offchain call" (sending a read-only foo with no onchain impact)

I used to call them

• foo -> Message
• bar -> Transaction
• baz -> Call (analogous to eth_call)

But I see you call them

• foo -> ???
• bar -> Transaction
• baz -> Message

I don't have strong opinions. Thoughts?

[juniset]

Yeah, I noticed that too :-). I usually think of it as:

• foo -> Call
• bar -> Transaction
• baz -> Message

But my definition of baz is that of a message used for off-chain signing, as in the \x19Ethereum Signed Message string pre-pended e.g. in EIP-3361. I also see a Transaction as on or more Call s (hence the use of multicall).

[martriay]

For the record, to me message means a communication between two parties (at least under the OOP model, which inspires Solidity's contract-oriented paradigm language), that's why I called foo a Message.

That being said, no strong opinions! We can settle on those :)

[juniset]

I've updated the spec to provide more details on how to compute hash_struct and domain_separator. In particular I've added a version and a chain_id to the domain_separator which is needed as there will be soon 2 deployments (Goërli and mainnet).

[juniset]

We've decided that Account Contracts will have only a single entry point for the execution of transactions. I've dropped the selector('execute') from the encoding of transactions.

[corbt]

I like this!

One question: at some point in the future it may be necessary to introduce changes to the message schema (adding more elements to the domain separator, dropping the selector('execute') from transaction messages, etc).

When that happens, what is the migration path? Perhaps the easiest thing when the time comes would be to introduce a new prefix, eg. PREFIX_MESSAGE = 'StarkNet Message 2' that implementors can then build support for? The alternative would probably be to introduce a version field somewhere, which probably adds unnecessary overhead.

[juniset]

Good question!

For off-chain messages there is already a version number in the StarknetDomain so I think that should be sufficient.

For transactions, I think the dapp should only ask the wallet to send a transaction with to, selector, calldata, and the wallet will know how to encode based on the Account Contract it will send the transaction to. So I don't think it needs to be specified as it is transparent to the dapp.

[CremaFR]

In the current specs/implementation there is no way to do delegate call on a argent-x contract.
Is that something that was not made possible on purpose or could we imagine a way to support it?

The goal of my question is to prepare validate and execute separation and using delegate call will allow more complex validation logic which are limited to the contract own state (to support multsig contract extension that would store signers inside the base contract, or session keys for example)

I propose to extend current Call struct with delegate

struct Call:
    member to: felt
    member selector: felt
    member calldata_len: felt
    member calldata: felt*
    member delegate: felt 
end

And in execute_list a check

if this_call.delegate == 1:
        let res = delegate_call( ... )
else:
        let res = call_contract( ... )
end

in order to maintain the single entry point and easily mix call and delegate call in a multicall

On my fork you can find an example implementation github