Private State Manager integration

[MCarlomagno]

Summary

I would like to share and collect feedback about a proposed integration of the private state manager (PSM) with Miden client.

This is part of the efforts for solving: 0xMiden/miden-proposals#3

The main goal is to define what are the integration areas and how the APIs will look like from the developers standpoint using miden-client as a library (web and rust) and the CLI.

PSM Overview

Private State Manager consists of a server-side app and a client library. The server exposes both an HTTP and gRPC APIs including:

Syncronization Layer

• GetPubkey(GetPubkeyRequest) -> (GetPubkeyResponse)
  Fetches the PSM public key for further configuration.

• Configure(ConfigureRequest) -> ConfigureResponse
  Creates/Configures the miden account in the Private state manager server, sending the full state of the account.

• PushDelta(PushDeltaRequest) -> PushDeltaResponse
  When a participant of the account wants to send a new transaction modifying the state, the change (transaction summary) is sent to the PSM server, then the PSM acknowledges the change by signing its commitment and sending the signature as a response, in the context of Multisigs the client will use this signature as an advice of the transaction execution for on-chain verification.

• GetDeltaSince(GetDeltaSinceRequest) -> GetDeltaSinceResponse
  Pulls all the deltas since the specified nonce (local nonce) - the deltas are merged in the server, so locally the client must apply the delta into the local account

• GetState(GetStateRequest) -> GetStateResponse
  Pulls the full state of the account from the PSM server, passing the account id as parameter.

Coordinator Layer (Multisig)

• PushDeltaProposal(PushDeltaProposalRequest) -> PushDeltaProposalResponse
  Sends a TransactionSummary object to PSM for collecting signatures for further execution.

• GetDeltaProposals(GetDeltaProposalsRequest) -> GetDeltaProposalsResponse
  Loads all the TransactionSummary objects proposed in PSM, including the signatures collected for each.

• SignDeltaProposal(SignDeltaProposalRequest) -> SignDeltaProposalResponse
  Attaches a new signature to a proposed TransactionSummary and sends it to PSM.

miden-client requirements

Syncronization

• When creating accounts/wallets, there must be an extra option to also configure a PSM for it (Configure API). miden-client must load the public key of the PSM and add it as part of the account configs.
• When sending a new transaction, if the account has a configured PSM, miden-client must first simulate it, then send the tx summary to to PSM (PushDelta API) and optionally (if multisig), use the signature in the response and as an advice of the transaction.
• New API for syncronizing the state (update local state) from the PSM server (GetDeltaSince API), and applying the missing deltas to the local account.
• New API for downloading the full account from a given PSM server (GetState API)
• New API for proposing a new multisig transaction, simulating some specific type of transaction, like P2ID, or any other. and then propose the transaction in PSM (PushDeltaProposal API).

Coordinator

• New API for loading and listing all the proposed transactions from PSM (GetDeltaProposals API)
• New API for signing a TransactionSummary after pulling it from server (GetDeltaProposals API) and then send the signature to the PSM (SignDeltaProposal API).
• New API for executing a proposed transaction

General

• Add private state manager client client as a dependency
• For all the interactions with PSM, the account must sign over AccountId and add the signature as part of the request.

In all requirements described above we must add new APIs or arguments to rust and web Libraries + some new command or flag to CLI

Proposed API changes (illustrative)

CLI

Configure PSM endpoint

miden-client init --network testnet \
  --psm-endpoint https://psm.testnet.miden.network \

configure a wallet

miden-client psm configure --account 0xabc123 --cosigner 0xpubA,0xpubB

sync deltas

miden-client psm sync --account alice --psm-url https://psm.testnet.miden.io
miden-client psm sync --account alice --psm-url https://psm.testnet.miden.io --full   # force GetState as fallback

transaction submission with PSM acknowledgement

miden-client tx send ... --psm

coordinator flow

miden-client psm proposals create \
  --account alice \
  --template p2id \
  --target 0xrecipient \
  --amount 10

miden-client psm proposals list --account alice
miden-client psm proposals sign --account alice --proposal 0xabc 
miden-client psm proposals execute --account alice --commitment 0xabc123

Library

Initialize

let mut client = ClientBuilder::new();
client = client.with_psm(PsmConfig {
    url: "https://psm.miden.io".into(),
    auth_signer: Arc::new(keystore_signer("alice")),
});

configure account on PSM

client.psm().configure(ConfigureParams {
    account_id: account.id(),
    auth: AuthConfig::falcon(vec![cosigner_commitments]),
    initial_state: serde_json::to_string(&account_state),
    storage_type: "Filesystem",
}).await?;

sync missing deltas

client.psm().sync_account(&account).await?;

load full account from psm

client.psm().load_account(&account_id, keystore_id).await?;

sending transactions

let tx = client.new_transaction(account_id, request).await?;
client
    .submit_transaction(tx, account_id, Some(&mut psm_client))
    .await?;

multisig proposal helpers

let proposal = client.psm().propose(&account, &tx_summary).await?;
let proposals = client.psm().list_proposals(&account).await?;
client.psm().sign_proposal(&account, &proposal.commitment).await?;

---

I would like to get opinions on this, I might be missing some details or overlooking important things about the integration as I'm not super familiar with the miden-client codebase

[igamigo]

Add private state manager client client as a dependency

I would suggest that the dependencies with the state manager are over more generic interfaces as opposed to over crates. We do something like this with the node for example, where we import a crate to generate Rust types based on protobuf definitions (that do come from the node's codebase) at build time and use those to construct clients.

I haven't deeply looked at the proposal yet but the high-level API and changes look good!

[MCarlomagno]

So one example of how this would be integrated in miden client

use private_state_manager_client::{PsmClient, signature::Signer};

// creates a signer from local account
let signer = Signer::new(secret_key);

// instantiates the PSM client with authenticated (signed) requests
let client = PsmClient::connect("https://testnet-psm.miden.network:50051")
    .await?
    .with_signer(signer);

//...

// When sending a new transaction, uses a private state manager for syncing first, then submitting
let push_response = client.push_delta(&account_id, 1, prev_commitment, tx_summary).await?;

What you mean is creating a new layer of abstraction on top to hide all that logic as the internal implementation of some struct, like

use crate::...::PSM;

let psm = PSM::new("https://testnet-psm.miden.network:50051").with_sk(secret_key);

psm.push_delta(...);

Then we only use "PSM" as the interface for this dependency?

[bobbinth]

Also a fairly high-level look - but overall looks great! Thank you for writing this up. Some preliminary thoughts:

I think there are 3 levels/stages of integration:

1. Using PSM as a simple backup solution. This could work with our basic wallet (or other similar accounts). Here, before the transaction is submitted to the network, the client would send the summary to the PSM. This would not prevent a malicious client from skipping the PSM update - but it should be good enough for a large number of use cases.
2. Using PSM as a single user. We could think of this as a "BasicWallet+". The user still has a single key, but now every transaction needs to be signed by PSM as well. From the user's standpoint this still feels like basic wallet, but under the hood PSM signs transactions as well. To implement this, we'd need:
   a. Create an account using PSM-aware multisig authentication component. One question here is where the MASM code for this component should live. Right now, miden-client imports MASM code only from miden-base - so, either the code would need to go into miden-base or we'll need to bring other dependencies into miden-client. Another question is how we want to configure the account component for this use case. The user should still be able to replace the PSM if the PSM becomes malicious (so that the account remains non-custodial), but if we do this naively, this is not too much different from the first approach. Once we have the timelock abilities, we could make PSM rotation an action that requires a delay, and then this would work better.
   b. We'd also need to update the default authenticator (or maybe have a new one), which is PSM aware and would forward signature requests to the PSM immediately somehow. This may require modifying the authenticator interface os that we could get multiple signatures for a single signature request (same tx summary signed by multiple keys).
3. Enabling true multisig capabilities in the client. This probably requires some significant refactoring, and we should evaluate whether we want to have this as a part of a "reference client" or maybe this should be done separately somehow.

[MCarlomagno]

Sounds good, thanks for scoping the integration,

Now that you mentioned this, I think the best option consider 1. as part of miden-client and 3. as a separated miden-multisig-client (which is a layer on top of miden-client).
Then for 2. I want to make a distinction, I think the separation should be mono-device (miden-client) vs multi-device (miden-multisig-client).

The main reason is that all the features related to coordination and syncronization are the same either for solo-users that need extra features, like account recovery using an extra key, or setups of multiple users running a multisig.

Then it makes sense to use the miden-multisig-client for all the cases of multi-device setups and keep miden-client only for single-device setups.

• for cases of mono-device (miden-client), the PSM signature should not be required, just the "backup" feature is what we need. And in case the psm becomes malicious, just changing the PSM RPC endpoint should work as there is no attachment on-chain (no psm signature verification).
• for cases of multi-device (miden-multisig-client), we can separate:
  • solo-accounts with recovery
  • solo-accounts with recovery + timelock
  • multisig accounts
  • others?

One question here is where the MASM code for this component should live

I think integrating it into miden-base is the most practical approach, even if we run things in a separated miden-multisig-client

The user should still be able to replace the PSM if the PSM becomes malicious (so that the account remains non-custodial)

So as I said, this would become something to worry about in the miden-multisig-client (using coordination with multiple devices) but not in the miden-client side as there is no on-chain attachment with PSM.

We'd also need to update the default authenticator (or maybe have a new one), which is PSM aware and would forward signature requests to the PSM immediately somehow. This may require modifying the authenticator interface os that we could get multiple signatures for a single signature request (same tx summary signed by multiple keys).

If we do this as part of miden-multisig-client, this coordination logic should not be necessary in miden-client

WDYT? My original thought was integrating it all into miden-client, but I'm realizing this is the most practical approach and with less risks of breaking changes. The only caveat is DX, so for example "BasicWallet+" won't be possible just using miden-client, but using miden-multisig-client

[mmagician]

Nice, I think @bobbinth's 3 levels/stages of integration are accurately describing what we discussed in the last call. Regarding how we integrate this, let me recap to make sure we're aligned on the split: miden-client vs. miden-multisig-client:

1. Using PSM as a simple backup solution.

• There is no multisig
• Client implementation is trusted
  • If we assume a malicious client, then I think it makes sense to assume it can not only avoid sending the deltas to the PSM, which can lead to unrecoverable account (missing state), but in fact can compromise the key and perform unwanted transactions
• PSM is trusted only for storage, can be rotated at the client level
• can be easily integrated into miden-client

2. Using PSM as a single user. We could think of this as a "BasicWallet+". The user still has a single key, but now every transaction needs to be signed by PSM as well.

• This is effectively a 2-of-2 multisig (mono-device multisig)
• If the client implementation is compromised, the PSM can block suspicious tx's depending on how the guards are configured
• If the PSM is compromised, the client can rotate it out, ideally with a timelock
• Some configuration on the client is needed, but a BasicWallet+ might just use reasonable defaults:
  • PSM pubkey can be configured with a default key of the "official" PSM operator
  • some guards should be set in place
    • amount per period could be using reasonable defaults (e.g. 1000 / day)
    • whitelisting addresses needs manual configuration, but they might be exposed to advanced users only
• Integration already requires miden-multisig-client-like capabilities, with tx simulation & sharing with the PSM. I think this is what you mean @MCarlomagno with:

The main reason is that all the features related to coordination and syncronization are the same either for solo-users that need extra features, like account recovery using an extra key, or setups of multiple users running a multisig.

3. Enabling true multisig capabilities in the client.

• M-of-N multisig
• I think not much different than Approach 2. in terms of integration:
  • configuration is needed and must be explicit (co-signer set)
• If the wallet offers a choice between creating BasicWallet & BasicWallet+, it might as well offer MultisigWallet
  • I'm not saying this is necessarily a good idea (compared to a separate multisig app like the one we have on testnet), but for a wallet to do something like this it won't be much different if it already integrates BasicWallet+
• Integration requires miden-multisig-client-like capabilities, with tx simulation & sharing with the PSM (as for 2. above)

---

So all in all, IIUC, this aligns with what @MCarlomagno wrote...

Note

Begin bikeshedding
...on all but the terminology :)
When I hear multi-device, I think of my own devices that I want synced with each other, not my own device + cloud backup. So the following gets confusing:

for cases of multi-device (miden-multisig-client), we can separate:

• solo-accounts with recovery

Here there is no second (user) device, only the PSM (akin to the cloud backup).

Some proposed naming for the three stages scenarios above:

1. PSM-Assisted / PSM-Backup
2. PSM-Cosigned
3. (Full) Multisig
   End bikeshedding

[MCarlomagno]

Thanks @mmagician! I just saw this response, some comments:

2. Using PSM as a single user. We could think of this as a "BasicWallet+". The user still has a single key, but now every transaction needs to be signed by PSM as well.

Actually this is not better than just having PSM as backup layer, because "...the PSM can block suspicious tx's depending on how the guards are configured" =>I find it hard to tell what is a suspicious transaction, and still this a feature that we haven't considered yet.
By "BasicWallet+" I mean having extra features like account recovery, where you need an extra signer, (Multisig 2/3: main signer + recovery signer + PSM signer), where this is effectively a Multisig/Multi-device setup, and so part of miden-multisig-client scope (in my proposal).

But still I'm open to challenges on this idea, maybe still the best is to integrate it all as part of miden-client, I'm also proposing moving most things to miden-multisig-client because is the easiest/fastest to implement and with less risks breaking changes

[mmagician]

Actually this is not better than just having PSM as backup layer, because "...the PSM can block suspicious tx's depending on how the guards are configured" =>I find it hard to tell what is a suspicious transaction, and still this a feature that we haven't considered yet.

I agree that until the "tx-guards" feature is in place, using PSM as a single user is not much different than using it as a backup.

[mmagician]

Interface and flow

I have a few questions on the specific items:

---

New API for downloading the full account from a given PSM server (GetState API)

What is the scenario for needing to download the full account state? You mention this CLI command:

miden-client psm sync --account alice --psm-url https://psm.testnet.miden.io --full   # force GetState as fallback

But I wonder in which particular scenarios we'd need the fallback, as opposed to only downloading the delta(s) and applying to whichever account state the client currently holds.

---

For the coordinator, you mention:

• New API for signing a TransactionSummary after pulling it from server ?

Why does the coordinator have to sign? My understanding (which is based on how this is done currently in the https://github.com/0xMiden/MultiSig/ design) is that the coordinator role does not involve participation beyond collecting the signatures. One could make one of the signers assume the coordinator role, but it's not strictly required and I think easier to reason about them as separate entities. Let me know if the trust assumptions on the coordinator and their role are different to what I envisioned.

---

I understand the lib interface might still be in draft mode, so maybe this is a premature comment:

client.submit_transaction(tx, account_id, Some(&mut psm_client))

Do we explicitly need to pass psm_client? Since we initialized the client to be PSM-aware, the client should be able to automatically detect whether the PSM is set. Ideally, the submission interface would not be altered in the presence/absence of the PSM.

[MCarlomagno]

What is the scenario for needing to download the full account state? You mention this CLI command:

When a new signer is added to the mulsitig, the new signer doesn't have any local "base" account state to apply the deltas, then it needs to download the full account

Why does the coordinator have to sign?

Ah sorry maybe I expressed it incorrectly, what I meant was:

1. the cosigner pulls the TransactionSummary from the coordinator server
2. the cosigner signs over it
3. the cosigners sends back to the server the TransactionSummary + its signature

So the "sign" action is done by the cosigner, not the coordinator

Do we explicitly need to pass psm_client? Since we initialized the client to be PSM-aware, the client should be able to automatically detect whether the PSM is set. Ideally, the submission interface would not be altered in the presence/absence of the PSM.

Yes I think you are right, if we somehow persist the client instance across calls we don't need to pass it each time, just a flag should work -

let use_psm = true;
client.submit_transaction(tx, account_id, use_psm)

but the flag is needed as some transactions might use PSM and others not, another apporach could be splitting into 2 methods like:

client.submit_transaction(tx, account_id)
client.submit_transaction_with_psm(tx, account_id)

[mmagician]

but the flag is needed as some transactions might use PSM and others not

Why is that?

[MCarlomagno]

In the case the PSM becomes unavailable, the multisig signers will need to switch the PSM provider without requiring the PSM acknowledgement / signature. So they would be able send a transaction for changing the PSM on-chain public key skipping the PSM check.

But now that you asking this, I realized this is the only case, so we can design a "smarter" API that detects this type of transaction and skips the PSM step without requiring any flag 🙂

[mmagician]

we can design a "smarter" API that detects this type of transaction

That would be nice - although it would introduce a bit of custom logic. I don't think we have this sort of differentiation anywhere in the miden client (but we do in multisig client), so we'd need a clean way to do that. But I agree it would be desirable.

[Keinberger]

Hey guys, just wanted to share some things I have in regards to UX, since the discussion was leaning towards implementing a separate psm-client (separate from the normal rust crate): would integrating multisig functionality directly into the main client be better for users? It would keep things to a single crate import; the recent store split from the main client crate caused some confusion for pioneers upgrading to v12.

If PSM / multisig live in a dedicated crate, how does that translate to the web client? I imagine everything would still be exposed from one SDK package (as is now) with an opt-in multisig / PSM module?

I don’t have a strong position yet, just want to make sure we weigh DX and upgrade friction alongside the architectural separation.

[mmagician]

It would keep things to a single crate import

From my own perspective as a builder, I don't find additional imports necessarily annoying. It's a rather standard practice to have multiple crates within the same library/ecosystem tailored for different purposes which the users import as and when needed.

If PSM / multisig live in a dedicated crate, how does that translate to the web client? I imagine everything would still be exposed from one SDK package (as is now) with an opt-in multisig / PSM module?

No, there would likely be a separate multisig-client-web package.

---

Overall, this circles back to a similar root reason as for keeping mint out of the client: it's not really a protocol-level feature. Multisig is inherently nothing but a special defined authentication procedure (for which we currently provide a reasonable "standard" multisig with Falcon & ECDSA, but devs could define their own custom functionality - as an example, a multisig auth component that combines Falcon + ECDSA). And while yes, we had built some features (e.g., Unauthenticated event) into the protocol that enable multisig functionality, there isn't an explicit notion of multisig in the kernel.

[MCarlomagno]

Agree with @mmagician, the idea is to have a miden-mutltisig-client (rust) and miden-multisig-web (typescript) packages separated from miden-client,

though I would de-attach the concept of PSM from Multisig.

• Multisig functionality will be wrapped up in these new packages/sdks, powered by PSM.
• but, PSM should also be available for some miden-client functionalities, like account state backup

[MCarlomagno]

I'm coming back to this conversation with some updates and plans for integration with PSM.

• We already implemented a miden-multisig-client SDK separated from miden-client.
• The initial plan is to start supporting PSM as a backup layer for accounts in miden-client, features to support:
  • ability to configure a PSM endpoint when creating an account (optionally passing a "recovery" public key (*)).
  • ability to send TransactionSummary's to PSM before executing transactions (this should be automatic and likely hidden from the user).
  • ability to recover account from a different client using a "recovery" public key in case the account state was lost.

(*) this is essentually a 1-of-2 multisig (**) where either the main and recovery key can send valid transactions and fetch the account state from PSM - this covers the use case of LOST key, in cases of COMPROMISED key we might need to think more about some extra security constraints.

(**) we will need to create rust bindings of multisig + psm account components in miden-base for a cleaner integration.

@bobbinth I think of this as the "minimal valuable integration" with PSM, we can expand the feature set down the road