A comprehensive guide on using authorization in soroban contracts.

[silence48]

A guide on making a multi-sig custom account contract, that allows for a dynamic authorization policy

Completed for bounty #624

[briwylde08]

This is great! Thank you @silence48! This one will be a bit delayed in review, but we'll have it done by 7/5.

[Shaptic]

Couldn't alloc the time to finish reviewing but here's a partial first pass

[Shaptic]

This is an incredibly solid guide, I learned a lot tbh 👏 just a coupla small comments below and I think this can be merged!

[Shaptic]

Suggested change

If you omit the `require_auth` call in your contract functions, the function can be executed without any authorization from the specified address. This means that anyone could potentially invoke these functions, leading to unauthorized actions. For example, without `require_auth`, an unauthorized user could increment a value or transfer tokens without the owner's consent. Therefore, it is important to include `require_auth` wherever authorization is needed to prevent unauthorized access and maintain the security of your smart contract.

If you omit the `require_auth` call in your contract functions, the function can be executed without any authorization from the specified address. This means that anyone could potentially invoke these functions, leading to unauthorized actions. For example, without `require_auth`, an unauthorized user could increment a value or transfer tokens without the owner's consent. Therefore, it is important to include `require_auth` wherever authorization is needed to prevent unauthorized access and maintain the security of your smart contract.

For example, without require_auth, an unauthorized user could increment a value or transfer tokens without the owner's consent.

This isn't true for the SAC because it does require_auth internally, so maybe clarify that?

[kalepail]

I second this. It's important to understand the footprint side of auth and sub invocations. I would actually like to see a whole section probably prior to the contract side of this doc on how the footprint plays into this. Both for root invocations as well as sub invocations like in the case of SACs or other cross contract calls which implement auth.

[silence48]

I second this. It's important to understand the footprint side of auth and sub invocations. I would actually like to see a whole section probably prior to the contract side of this doc on how the footprint plays into this. Both for root invocations as well as sub invocations like in the case of SACs or other cross contract calls which implement auth.

I thought I had covered the footprint in the part called authorization vector but ill revisit it. Thanks.

[Shaptic]

I need a little more clarity for myself honestly since I've never seen/used this variant 😅 do you mean to say that you are authorizing a call in advance that a subcontract will make that would otherwise be unauthorized?

[silence48]

I need a little more clarity for myself honestly since I've never seen/used this variant 😅 do you mean to say that you are authorizing a call in advance that a subcontract will make that would otherwise be unauthorized?

Say I contract c needs contract a auth to complete some function, but contract b will be called by contract a and contract b will call c on a behalf. In this case you'd want to authorize as current contract a during the call to b for its sub invocation to c. I struggled to find a irl example to use.

[Shaptic]

Ah yeah, that (sorta) makes sense! Maybe a Mermaid diagram would be helpful here? This is incomplete, but something like:

flowchart 

C -- needs auth from --> A
B -- calls --> A -- calls --> C

Loading

?

[Shaptic]

This is just an example, right?

[Shaptic]

If yes lets put it into its own ## section

[silence48]

It's step one of maybe 5 or 6 that I did ### on. I'll make sure they're in correct order and correct headings. Will be fixing everything today.

If yes lets put it into its own ## section

[Shaptic]

suggestion: let's be even bolder here

Suggested change

	**A Caveat** - Let's be clear, custom auth is highly complicated and VERY easy to mess up. It requires security audits before use in production, and should only be used if you can't accomplish your goals in another way. The goal of this guide is to give you some experience with each feature of sorobans authentication framework, and that is why we cover it here.
	**Warning**: Let's be clear, custom auth is highly complicated and VERY easy to mess up. It requires security audits before use in production, and should only be used if you can't accomplish your goals in another way. The goal of this guide is to give you some experience with each feature of sorobans authentication framework, and that is why we cover it here.

[kalepail]

We have callout boxes for this as well. I'd use one of those for this section.

[silence48]

We have callout boxes for this as well. I'd use one of those for this section.

Can you show me an example of what you mean

[Shaptic]

I think he's referring to the <Alert> box described in the README here. I thought we could style them in red as warnings, too, but I can't seem to find an example of that right now.

[Shaptic]

Aha, found one! There's a caution one on the Smart Wallets page and it's styled like this:

:::caution

Your content goes here

:::

.No need for <Alert> at all.

[kalepail]

Overall a great tutorial! A few small nits and one major one. I really think we should talk about the footprint side of this so folks understand what and how to actually sign data. The require auth bits in the contract are actually just "hints" or constructer clues for simulation to build the right signature payload for the consensus verifier logic. We should talk about that and provide a least a basic example showcasing how auth moves from a contract to a footprint to a signature to the final tx submission. (https://kalepail.com/blockchain/understanding-soroban-auth)

[kalepail]

What's this? Seems like some cruft from a previous edit or comment?

[Shaptic]

Lollll this sounds like GPT

[silence48]

Lollll this sounds like GPT

Lol it seems it was. Will fix.

[kalepail]

You should include somewhere in here that by default require_auth is signing against the args of the invocation. This is important for why you'd want to use require_auth vs require_auth_for_args as an insufficiently verbose require_auth call could produce a scenario with unintended consequences where a valid signature could match for two different calls. The payload of an auth request is important and require_auth just assumes the values of the invocation.

[kalepail]

I second this. It's important to understand the footprint side of auth and sub invocations. I would actually like to see a whole section probably prior to the contract side of this doc on how the footprint plays into this. Both for root invocations as well as sub invocations like in the case of SACs or other cross contract calls which implement auth.

[kalepail]

Given my comments from above you should call out some for instances for why you might choose require_auth vs require_auth_for_args

[kalepail]

We have callout boxes for this as well. I'd use one of those for this section.

[kalepail]

I'd also add the custom account tutorial https://github.com/stellar/soroban-examples/tree/main/account

[silence48]

Bumping this to keep it from going stale while i finish