PoC wallet contract

[bobbinth]

I think it would be beneficial to sketch out (even if in pseudocode for now) some simple contracts, and a basic wallet could be a good one to start with. My intention is that by going through this we could identify any gaps in the current design that need to be filled in.

This first post in the discussion describes requirements of what I think could be interesting to support, and then we can figure out how to support it in the comments.

A simple wallet

The simplest wallet could have just two external interface procedures:

• receive_asset(Asset) which would add the specified asset to the account's vault.
• send_asset(Asset, Recipient) which would remove the specified asset from the account's vault and create a note sending the asset to the specified recipient.
  • One open question is what exactly is the recipient. It could be as simple as code root of the note to be created. But it might make sense to include some other (e.g., a "tag") which would make the note easy for the recipient to identify.

Within the send_asset procedure, we need to make sure that whoever is trying to invoke it, has the permission to do so, and that a transaction cannot be replayed. To support the former, the contract probably will need to store a public key of the user who owns the wallet.

Variations on the simple wallet

We could also extend the wallet with the following variations:

• Ability to change wallet owner (i.e., by updating the internally stored public key). This could be done by adding set_owner(PubKey) procedure.
• Multi-sig capabilities, where the wallet is controlled not by a single public key, but by 2-of-3 or similar multisig.

A wallet with atomic swaps

Another interesting variation on a simple wallet could be a wallet which support exchanging one asset for another. Thus, in addition to receive_asset and send_asset, the contract could have an additional external interface procedure:

• swap_assets(a: Asset, b: Asset, Recipient) - this procedure would add asset a to the account's vault, remove asset b from the account's vault and create a note sending asset b to the specified recipient.

It might also be good to sketch out how a note invoking this procedure could look like. My initial thinking is that it is the note which will need to specify what is asset a and what is asset b, and then it would be up to the owner of the wallet to decided whether they want to take this "trade".

A safe wallet

Given the recent private key hacks, it would be good to come up with a wallet design which would be as safe as possible while still being easily usable. Maybe this could be a reference wallet design for Miden right from the start. Here are my very preliminary thoughts on how this could work:

There are 3 keys which control the wallet: a hot key, a cold key, and an external key. Public keys for these are stored in the account. The expectations is that these keys have different levels of protection/accessibility. Specifically:

• hot key is expected to be easily accessible (e.g., via mobile phone or browser extension).
• cold key is expected to be stored in something like an air-gapped hardware wallet or an offline storage device.
• external key is expected to be stored with an external custodian or accessible via social recovery or something similar.

These keys can be used for different actions within the wallet. Specifically:

Procedure	Key required	Description
receive_asset	hot key?	Receiving assets into an account may require a hot key. Or maybe anyone can do it (that's how it works in most blockchains now).
send_asset	hot key	Sending assets out of the account requires a hot key, but outgoing transfers are throttled as described below.
freeze_account	hot key	A hot key can be used to freeze the account. Meaning, no outgoing transfers will be possible until the hot key is reset.
reset_hot_key	cold key	A cold key can be used to reset the hot key. But a cold key cannot be used to make outgoing transfers.
set_send_limit	cold key	A cold key can be used to set a spend limit on per asset basis. This works only for fungible assets. More thinking is needed on what to do with NFTs.
reset_cold_key	external key + more	A cold key can be reset either by: (1) a multi-sig of a cold key and an external key, or (2) using only an external key but with a significant time delay.

Outgoing transfer throttling

Sending funds out of the account would be throttled based on the spending limits for each asset. The limit could be set for some period of time - e.g., weekly spending limit (it would be interesting to see if there could be an overall spending limit, but that would require somehow figuring out relative worths of different assets). Once the asset reaches its spending limit, no more of this asset can be transferred out from the account until the period expires.

Reseting a hot key exhausts spending limit for the current period. That is, if the hot key is reset, no assets can be sent out of the account until the period expires.

Benefits of this setup

• If the hot key is compromised, it can be disabled using either the hot key itself (by freezing the account) or by the cold key (by resetting the hot key).
• If the hot key is lost, it can be reset with the cold key.
• If the cold key is compromised, the account can still be frozen using the hot key. And then the cold key can be reset with the help of the external key.
• If the cold key is lost, it can be reset using the external key. The delay mentioned above should be pretty long - e.g., on the order of several months or maybe even a year.
• If the external key is compromised, the only possible action is to reset the cold key after a long delay. By the time this happens, the user should be able to move the founds out of the account.

Basically, catastrophic loss of account funds is possible only under the following scenarios:

• Hot key is compromised and cold key is lost.
• Cold key is both compromised and lost.
• Cold key and external keys are both compromised.

There could also be a variation on the above where there is only a hot key and an external key. This probably would simplify the design quite a bit without giving up much safety.

[frisitano]

I think your proposal makes a lot of sense and exemplifies the power of account abstraction.

• send_asset(Asset, Recipient) which would remove the specified asset from the account's vault and create a note sending the asset to the specified recipient.

  • One open question is what exactly is the recipient. It could be as simple as code root of the note to be created. But it might make sense to include some other (e.g., a "tag") which would make the note easy for the recipient to identify.

Maybe something to consider here is that code logic may change over time as improved versions emerge as we gain more experience. This could result in a different code root. I wonder if it would be beneficial to include some metadata / a tag which does not change as code logic changes and can be easily indexed and searched for. For example you could have a "recipient" tag as you mention. I'm not sure if this should be embedded in the state tree or if instead it should be emitted as part of an event that is included in a block and then dropped e.g. "NoteCreated(CodeRoot, Recipient, ...)".

[bobbinth]

Maybe something to consider here is that code logic may change over time as improved versions emerge as we gain more experience. This could result in a different code root.

This is actually a bigger and still open question: should it be possible for accounts to update their code. In most current blockchains, that is not usually possible - but I think there might be value in allowing it in some situations (i.e., I should be able to change code of my personal wallet). I guess the questions on this would be:

• Do we allow updating code of accounts at all?
• If so, should it be restricted to some accounts and not others?
• Should there be some restrictions on how the code could change (e.g., you can add new procedures but not remove already existing ones)?
• Should the VM manage this process? Or should it be left to the user logic to define if the account code is updatable and how.

[frisitano]

That's a great point and certainly something to consider! I'm more focused on the infrastructure layer than I am smart contracts, so I am not best experienced talk on this point however I think it's quite typical for smart contract updates to take place on Ethereum. This does not come without security trade offs of course, we recently saw the nomad exploit as a result of a smart contract update. Having said that there have been many successful updates. The benefit of contract updates is that you do not have to migrate your user base to a new contract to deploy a new version of a protocol. Given the fact there is significant appetite for contract upgrades it could be beneficial to natively support them. I guess this could work by exposing an update_code(new_code) kernel method. It would then be the responsibility of the smart contract dev to decide if they implement an update function on their contract that invokes this kernel method. If they don't then the contract is immutable, if they do then it's up-gradable.

[maxgillett]

I agree with @frisitano, and think we should expose such an update function to allow the code hash to be changed, and leave it up to the account to decide the degree of mutability, not the VM. While I'm not a fan of mutable smart contracts, I'd also agree that this is a very common pattern in the developer community right now, and I do see clear utility in allowing wallets that can upgrade their functionality, and save users the time and cost of transferring assets to a new wallet. Adding restrictions to how this code could change seems like something that can be specified in the account code itself, and a block explorer can be used to audit verified code, as is done today in Ethereum and other L2s.

Regarding the recipient, this raises the question of whether we want to support logs/events for easier indexing. I'm not sure if this was mentioned in a previous discussion, and what the consensus was, but I can imagine many scenarios in which this can be useful outside of just keeping track of notes. It also may be a necessity given that indexers may not be able to replay transactions fast enough (without large investments in hardware) to extract potentially useful data that is not reflected in the final output of the transaction (e.g. repeated storage updates to a leaf occurring during transaction execution) while still keeping up with the tip of the chain. Another question is whether we want to bake in certain log events (e.g. asset transfers when notes are consumed) that can be exposed by the user in public transactions, instead of asking accounts to adopt a particular standard and emit an event of a particular format (as is the case with ERC20).

[grjte]

I also agree on the upgradability. Once people are seriously using the system there's going to be a demand for some upgradeability pattern, so it's better if we provide it by design.

I think supporting some kind of events / logging is important as well. It probably does make sense to have some default events to minimize overhead for users in common scenarios like public asset transfers, although I don't feel as strongly about this.

[bobbinth]

In general, I'm also in favor of upgradability, and similar to @maxgillett, I think it should be largely left to the user to decide how exactly a given account/contract should behave. I do think, however, that one or two "guard rails" might be a good idea.

For example, I think it might be a good idea to make it super easy to figure out whether a given account has mutable or immutable code. One way to enforce this could be by grinding account ID to some pattern. For example, if an account ID has 8 least significant bits set to all zeros, account code cannot be modified (and the VM will enforce it). Otherwise, the user can decide how and when to update account code.

Another potential guard rail could be that asset-issuing accounts must always have immutable code.

[bobbinth]

Some thoughts about the case with the simple wallet. In this post I'll cover only public transactions because there is much more complexity around private transactions, and I'd rather handle the simple case first.

Receiving assets

The receive_asset(Asset) procedure could be relatively straightforward. Pseudocode for it could look something like this:

receive_asset(a: Asset)
  account.vault.add_asset(a)
  account.increment_nonce
end

The above assumes that vault::add_asset and account::increment_nonce are standard procedures available from account context (which internally call some kernel procedures).

I'm also assuming that transaction kernel enforces the following rule:

If a transaction modifies account state (i.e., account's vault, storage, or code change), account's nonce must be incremented. Otherwise, the transaction fails.

Technically, this rule is not needed for receiving assets, but it will be handy for sending and swapping assets.

The receive_asset procedure is not super interesting. What I think is more interesting is how a note's script can invoke it. One option would be to hard-code both the account ID and the asset into the note's script.

note_script
  assert(account.get_id() == <my account id>)
  let a = <some_asset>
  account.receive_asset(a)
end

The above assumes that the sender includes the specified asset in the note's vault and nothing else.

While the above works, it makes the script asset-specific: meaning, any time the asset changes (e.g., same fungible asset but with a different amount), the root of the script changes. We can make the script more generic like so:

note_script
  assert(account.get_id() == <my account id>)
  for a in note.assets
    account.receive_asset(a)
  end
end

Now, regardless of which asset is sent, the script of the note is the same. This is convenient because, as the recipient, I can just scan the chain looking for this script to see if anything was sent to me. To make this task simpler, we could require that each note includes a tag. In case of the note above, the tag could be just the root of the script.

The full flow for sending-receiving funds could then look as follows:

1. The recipient would share root of their receive script. This could be done synchronously or asynchronously (e.g., via QR code).
   a. Sharing of account ID may or may not be required depending on how we want to structure notes. For example, if a note does not have to include the full script, sharing of account ID would not be needed. For purposes of this post, let's assume that that's the case.
2. The sender would create a note with script root set to the root of this receive script and tag set to the same root (or maybe these could be combined into a single field). How this is done is discussed in the next section.
3. The recipient would scan the chain (or delegates this task to someone else) to see if some transaction produces a note with the tag set to the root of their receive script.
4. Once such note is found, the recipient would create a transaction which executes this note against their account.

Sending assets

When sending assets we need to make sure that whoever is trying to initiate the transfer has the permission to do so. Let's assume that this is done by verifying a Falcon signature against a public key stored in the account. The procedure for sending assets out of an account could look like so:

send_asset(a: Asset, r: Recipient)
  let a = account.vault.remove_asset(a)
  let n = create_note(r, a)
  let aid = account.get_id()
  let nonce = account.get_nonce()

  // build a message over which we'll verify the signature
  let m = hash(aid, nonce, a, n)

  // verify the signature against account's public key
  let k = account.get_pub_key()
  falcon::verify_sig(k, m)

  account.increment_nonce
end

In the above, we sign the message which consists of hashing asset, recipient, account ID, and nonce to make sure that the same signature could not be used again in a different context. Also, falcon::verify_sig procedure is assumed to read the actual signature from the advice provider.

While the above works, it is actually quite inefficient. Specifically, if we wanted to send assets to multiple recipients within the same transaction, we'd have to verify signature multiple times. A better approach would be to split authentication and note creation into different procedures. For example:

send_asset(a: Asset, r: Recipient)
  let a = account.vault.remove_asset(a)
  create_note(r, a)
end

auth_tx()
  // get arrays of input and output note hashes
  let i_notes = tx.get_input_notes();
  let o_notes = tx.get_output_notes();

  let aid = account.get_id()
  let nonce = account.get_nonce()

  let m = hash(aid, nonce, i_notes, o_notes)
  let k = account.get_pub_key()
  falcon::verify_sig(k, m)

  account.increment_nonce
end

This way, if we wanted to send assets to multiple recipients, a tx script included with a transaction could look like so:

tx_script
  account.send_asset(<asset1>, <recipient1>)
  account.send_asset(<asset2>, <recipient2>)
  account.auth_tx()
end

Thus, we only need to call auth_tx procedure once, and it will authenticate all actions executed as part of the tx script.

Summary of supporting procedures

I've assumed that we have quite a few procedures available to us in the scripts above. Below I've put them all into a single list.

Procedure	Description	Context
get account ID	Returns ID of the account in the current transaction.	account, note
get account nonce	Returns nonce of the account in the current transaction.	account, note
increment account nonce	Increments the account's nonce by 1.	account
add asset to vault	Adds the specified asset to the account's vault.	account
remove asset from vault	Removes the specified asset from the account's vault.	account
get note assets	Returns all assets in the current note.	note
create note	Creates a note with the specified recipient and asset.	account
get input notes	Returns hashes of all inputs notes for this transaction.	account
get output notes	Returns hashes of output notes creates so far in this transaction.	account

All of the above will need to make kernel calls. I've omitted such procedures as hash as it is just a convenience procedure which does not require a kernel call. Also, get_pub_key procedure is assumed to be a user-defined procedure rather than something that is provided by the kernel.

Lastly, I've oversimplified how notes are created. Specifically, we probably want to have a way of creating notes with multiple assets, and also be able to specify what type of a note it is (e.g., how to set the tag).

[bobbinth]

Separating asset sending from authentication is also convenient for atomic swaps. For example, we could have a note with the following script:

note_script
  let a = <some_asset>
  account.receive_asset(a)

  let b = <some_other_asset>
  let r = <some recipient>
  account.send_asset(b, r)
end

Since the note does not specify target account ID, anyone can execute this note in the context of their account as long as the account exposes receive_asset and send_asset procedures. Executing the note would mean that the account adds asset a to their vault, but would also need to send asset b to the recipient specified by the note. Except for hard-coded assets and the recipient of asset b, this note is generic. That is, it does not assume anything about how the account would authenticate this swap (e.g., which signature algorithm is to be used).

So, to execute this note, the user would include the following tx script with their transaction:

tx_script
  account.auth_tx()
end

Recall, that when executing a transaction, tx kernel first executes scripts of all input notes, and then execute the tx script included with the transaction. So, any user who likes this trade (i.e., is interested in swapping asset a for b) would be able to execute this transaction. If multiple people want to take the trade, the consensus layer would pick one and discard others.