[CAP-72] - Bringing auth customisation to G accounts

[leighmcculloch]

This proposal is a modification of what I previously posted in #1751, but achieves the same goal.

I propose that the protocol accept changes that bring auth customisation to G accounts:

• Allowing the actions of G accounts to be authorised by C accounts.
• Allowing G accounts to be configured via Soroban.

Context:

Contract accounts on Stellar are fully customisable, but wallets get access to more of the ecosystem today with a G account.

One type of functionality that some wallets want to adopt is passkeys, and specifically, the recovery processes available to pass keys on modern phones where they get backed up to Apple and Google accounts. However, to adopt passkeys is to adopt a contract account and step away from everything the ecosystem has only for G accounts.

In the past we’ve discussed the possibility of a C account being a signer for a G account. The problem with a C account being an account signer of transactions is that the contract runtime would have to execute arbitrary logic during pre-apply checks without a guarantee of being paid for the resource usage.

G accounts can have up to 20 signer sub-entries. The signers can be a variety of types, but the most common are G keys. Each sub-entry must be sponsored with a reserve amount of XLM. Sub-entries can be sponsored by other accounts, but removing a sponsored entry and replacing it requires the sponsor to re-authorise the new sponsorship.

Proposed changes:

1️⃣ Add support for contracts being signers of a G account.

The signer would be able to sign Soroban Auths, but not Transactions. The contract signer would be able to authorize any operation that a G account can perform on Soroban.

2️⃣ G accounts becoming a built-in contract, with functions for changing the state of the account, specifically: adding/removing signers.

3️⃣ Optional: Add a function to the SAC for a G account to trust / distrust the asset (manage their trust line).

4️⃣ Allow the addition of a sub-entry to reuse sponsorship or a matching deletion in the same operation without requiring authorisation from the sponsor.

This would allow a contract invocation replacing a signer to reuse existing sponsorship, without needing to resolve the issue of sponsorship on the soroban side, or finding a way to bring sponsorship operations to Soroban.

Use cases:

Device key wallets with passkey recovery

[Dependent on changes 1️⃣ 2️⃣ 4️⃣]

A wallet where a device key is the regular signer, and a passkey is a backup used for recovery.

• Wallet deploys contract C that will become the passkey signer for the G account.
• G account adds C as a signer with weight to satisfy high threshold.
• G account has created a G device key for day-to-day ops.
• G account adds G device key signer with weight to satisfy day-to-day op thresholds.
• G account can transfer, trust an asset via Classic or Soroban, all authorised by the G device key signer.
• G account can change signers if they lose their device, via a Soroban call, authorised by the C account.

This device key model is the same model described and used by SEP-30.

This use case can be added as an add-on to any existing G account wallet, without that wallet adopting Soroban for anything other than for the backup and recovery flow.

Passkey wallets

[Dependent on changes 1️⃣ 2️⃣ 3️⃣ 4️⃣]

A wallet where the only signer is a passkey.

• Wallet deploys contract C that will become the passkey signer for the G account.
• G account adds C as a signer with weight to satisfy high threshold (or lower if appropriate).
• G account can transfer, trust an asset, or change signers via Soroban calls, all authorised by the C account.

Why:

• To enable fully independent G accounts that utilise passkeys for account recovery, and/or passkeys for day-to-day operations.

• To enable any other custom auth to be available to G account, either as a way to auth day-to-day operations, or just for account recovery.

• The problem of who needs to sponsor the new signer does not need to come into play as long as the rule is that replacement of the signer reuses existing sponsorship. It allows wallets to use sponsorship or not, without sponsorship needing to be a complexity on the contract side and keeps the contract side complexities of implementation to a minimum.

[marcelosalloum]

I absolutely love this idea. When chatting with partners, I often heard existing businesses that wanted to support passkeys without having to walk away from G-accounts, which is exactly what you're proposing here

[marcelosalloum]

3️⃣ Optional: Add a function to the SAC for a G account to trust / distrust the asset (manage their trust line).

What is the purpose of this change? Although useful, I don't see it as a requirement for the auth customization.

[leighmcculloch]

That's correct that step 3️⃣ is not required for the case that the C signer is only used for signer updates / recovery, but it’s a logical step towards using a C signer to sign for anything a G account wants to do, and sign for it directly instead of using a G signer device key to sign those transactions.

[leighmcculloch]

Step 3️⃣ is marked as optional, because it depends how far we want to go with the protocol change here. Steps 1️⃣, 2️⃣, 4️⃣ are sufficient at using passkeys for key management and recovery, but without 3️⃣ a wallet would still need to use a G signer to manage trust lines.

[JakeUrban]

Can you clarify how the C account would authorize the actions taken for the G account?

stellar-core doesn't have awareness of how contracts authorize transactions, so it has to call __check_auth on the account's contract signer right? Would this be possible in classic operations like SetOptions or only for contract invocations that call require_auth on the G address or maybe also its contract signer?

[leighmcculloch]

As part of 1️⃣ the C account wouldn't be able to sign transactions, only soroban authorisations. That means it would only be able to authorise actions taking place inside contract invocations, not classic operations which are signed by a transaction. It would allow a C account to authorise anything that can be done on Soroban, so transfers primarily, not set options, not trust line management, which is why the proposal includes the additional steps 2️⃣ and 3️⃣ where we expose the ability to modify signers (what you can do with SetOptions) and modify trust lines (another classic op) through contract calls.

[JakeUrban]

So does the G address have a contract? Or does stellar-core see that a contract address is a signer, and calls its __check_auth function when G.require_auth() is called?

[leighmcculloch]

see that a contract address is a signer, and calls its __check_auth function when G.require_auth() is called?

This ☝🏻

[JakeUrban]

Gotcha, makes sense. Overall I'm very supportive of all proposals, 1 - 4.

I'm thinking through if this approach would be viable for Freighter users, with the goal of improving onboarding and recovery UX. The challenge is that we still need to generate a seed phrase for the Stellar private key. We could simply not display or require the user to copy the seed phrase, so its treated like an internal implementation detail, but until the user funds the account with enough XLM to pay for the reserves and fees of adding a contract signer that uses a device passkey, it would be possible for the user to delete the app and we'd have to generate a new account address because we lost the seed phrase. That seems like an acceptable UX though.

[leighmcculloch]

Yeah it's still definitely reasonable to offer up a seed phrase, even for use afterwards too, and think of it as a backup "paper" key. That can be the master key at the outset to keep reserve costs low, but if they lose the master key, and then use the passkey for recovery, you'll be generating a new paper key that'd be an additional signer. There's a lot of flexibility.

[dmkozh]

I think the proposal makes sense for the most part.

The only immediate issue that I see is that I don't think we want to mess with the classic semantics much (i.e. sponsorships, reserves etc.). I think we should be able to add the new signers on the Soroban side via a ContractData entry and not deal with the classic signers at all. There are a few technical nuances that we'll need to figure out, but overall that seems achievable. I think the main downside of that approach is the fact that some account interactions (like merge) won't be possible unless the Soroban signers are restored, but this should be solvable, given that it's not too hard to restore any entry.

[leighmcculloch]

Using contract data for the signer is a nice idea, conveniently avoids the sponsoring issue in a better way than I suggested above.

Iirc there are already odd edge cases where you actually can't merge an account until a certain ledger has been reached, to ensure that when recreated the account sequence number, derived from the current ledger, can't go backwards and repeat an account sequence number the account saw before. So I think adding more edge cases on merge while unfortunate is still not such a big deal. Especially if there's some future where accounts get archived too.

[dmkozh]

Yes, I agree that the simplicity for the majority of the use cases seems to outweigh the downsides. I still need to do a bit more research and thinking on the implementation details though.

[dmkozh]

I've sketched an initial CAP corresponding to this proposal: CAP-72 (#1786).

While working on it, I've realized that this is a good opportunity to cleanup the delegated auth developer experience and came up with a CAP that helps with that: CAP-71 (#1785). I've opened a separate discussion for it as well: https://github.com/orgs/stellar/discussions/1784. I'll update the discussion soon.

Note, that both CAPs focus on the account-related functionality, neither one of them is covering the trustline modification, as I'm not sure yet how exactly this should look like.

Discussion point: the initial version of CAP-72 that I came up with is using a contract data entry to store the new signers introduced from Soroban. I think that will work fine. But if we'll end up adding trustlines from Soroban as well, then we'll need to figure out the base reserves/sponsorships anyways, so the exact storage approach to take for this CAP is still up to debate.

[leighmcculloch]

Some elements of the proposal do not interact well with strkeys:

fn update_ed25519_signer(env: Env, key: BytesN<32>, weight: u32);
fn remove_ed25519_signer(env: Env, key: BytesN<32>);

This will surface ed25519 in a form not as strkeys into developer tooling and user workflows. We should go to the effort of defining a new ScVal type, Signer, that supports the strkeys of signers. Even if we limit that Signer to just the G signer in this change.

A new type of G-account signer SIGNER_KEY_TYPE_SC_DELEGATED is added.

Adding this signer type will require adding a new strkey for it, which unfortunately will represent the G-account in a form that doesn't look like a G-account. We can assign a new strkey prefix, but I'm wondering if there's some other solution here where we can avoid the need to do that. I think if we limit delegation to contracts only would prevent the need to solve this problem. So the signer can only be a C.

[dmkozh]

This will surface ed25519 in a form not as strkeys into developer tooling and user workflows.

I'm not sure if that's an issue, and I'm also not sure if that statement is true in the first place. BytesN is the standard format for the public keys in the smart contracts, we use it e.g. in the signature for the G-account. Ledger entries store 32-byte keys as well. It is up to the client to perform strkey->bytes conversion, if necessary.

We should go to the effort of defining a new ScVal type, Signer, that supports the strkeys of signers.

I disagree here, this is definitely not an issue that should be solved with the ScVal extension. This could in theory be just a contractype enum that accepts either BytesN or String for strkey, but even that seems wrong to me because of the reasons mentioned above. I don't think we should move the presentation layer logic into contracts.

Adding this signer type will require adding a new strkey for it, which unfortunately will represent the G-account in a form that doesn't look like a G-account.

Do we actually need a new strkey for this at all? I guess there is some ambiguity if you wanted to display all the account signers as just strkeys... But is that something that is actually happening?

I think if we limit delegation to contracts only would prevent the need to solve this problem. So the signer can only be a C.

I think we can consider this option. I'm not sure if strkey issues are a sufficient argument for this, but I can see us dropping delegated G-signer support in case if we think it would never be necessary. If we think there are valid use cases for it, then we should figure out the solutions downstream.

Revisiting all the issues raised, an option to consider would be to modify the interface to just have a pair of update_signer(address, weight)/remove_signer(address) functions and treat G-address as ed25519 crypto signer and C-address as a delegated signer. The precondition to this is whether the assumption above is true (i.e. whether we think that G-accounts would never be useful as delegated signers).

[tupui]

In the past we’ve discussed the possibility of a C account being a signer for a G account. The problem with a C account being an account signer of transactions is that the contract runtime would have to execute arbitrary logic during pre-apply checks without a guarantee of being paid for the resource usage.

Without knowing the details. That would have been very handy though. You could basically manage fully a G address with a smart contract. E.g. make a full custodial solution with set of signers depending on rules like amount, time, recent volume, allow list. Etc.

We can argue that at that point we can just use the C addresses, but exchanges, custodial solutions (like Fireblocks), etc. do not really support C addresses and it's going to take a long time until this happens (cf muxed account.)

[dmkozh]

I don't disagree that allowing contract signers for transaction would be neat, but that's much more complicated than what's proposed here due to the risks of running VM for transaction validation 'for free'. I think what's proposed here (and in CAP-72) is a much more realistic next step for bridging the gap between G and C accounts. If we ever allow C-signers for tx signing, then thanks to CAP-72 G-accounts will be compatible with custom auth as well.