Classic Wrapper for extended asset behavior

[fazzatti]

Hey everyone!

I've been sitting on this concept for a while and took the opportunity of the 'Build Better on Stellar: Smart Contract Challenge' to implement these ideas and test out in practice to validate feasibility as well as to get a sense of how it could mature to benefit the ecosystem.

Below you'll find the draft I've been writing on it and I would like to get some feedback before moving forward, especially to brainstorm how such a standard could benefit both asset issuers and other builders in the ecosystem.

I would love to further discuss and experiment with these ideas. If you'd like to dive a bit deeper on the experimentation We've been doing, you can have a look at:

• Git repository : Here I've implemented different viewpoints to explore the use cases. There contracts for each wrapper type as well as different asset controller and a node project to experiment with them in testnet.

• Interactive demos: Here we have two demos that explore this standard, one that implements Probation rules with an Enforced Wrapper and another one with a fun Campaign combined with an Optional Wrapper to distribute prizes. These control every aspect in a simple way, from initializing accounts, configuring the contracts, testing everything from scratch, and keeping track of the historical transactions to analyze each step of the use case.

• Videos: As part of the challenge, we recorded this series, in which we produced four videos. The first one covers the overall idea of the proposed standard. The second one explores the probation demo and implementation in depth. The third one explores the campaign demo and implementation in depth. The last one implements from scratch a very simple controller contract of a counter that integrates with this standard approach.

I'm looking forward to getting some feedback and discussing potential ways for these ideas to evolve into a broader standard.

DRAFT:

Summary:

The object of this proposal is to discuss a standardized approach to extending capabilities for classic assets to:

• Implement granular custom behavior that can be either enforced by the asset issuers or made optional by builders
• Leverage standard interfaces and implementation to benefit the ecosystem
• Provide information upfront in a transparent manner to facilitate integration

Motivation:

Classic assets are versatile in nature, and with the release of Soroban, they have become more flexible. They can act as the critical bridge between Classic and Soroban, using the SAC contract. Since the SAC contracts are a default implementation that follows the classic native behavior, they can’t be customized by design, which raises some limitations on how much the asset capabilities can be customized with on-chain logic.

Currently, asset issuers have two main options when looking for more granular control:

• Implement a pure soroban token with custom logic.
• Extend classic behavior through SEP8.

Both are valid approaches but have some downsides. While the first approach limits the asset to be used only through soroban, asset holders won’t have access to other classic advantages such as higher throughput, cheaper transactions, and native decentralized markets. The second approach relies on a centralized external(off-chain) service to verify and approve each individual transaction, jeopardizing transparency and creating a bottleneck. It also introduces a central point of vulnerability for the asset operation, such as the server being down, which could render the asset unusable no matter the state of the network.

With scenarios like these in mind, there is room for a third hybrid approach, which could be helpful in certain specific scenarios. By combining certain classic configurations with a standardized soroban implementation, it would be possible to greatly extend classic assets' capabilities with on-chain granular control while still keeping the classic nature and capabilities of the asset when the desired transaction doesn't require the programmability layer.

With a well-defined standard for this approach, builders in the ecosystem can benefit by ensuring a clear integration of these assets in their solutions, leveraging common implementation among the ecosystem, and providing a way for programmatic verification of an asset implementation on-chain(through contract functions) and off-chain(through the .toml file)

Approach

The proposal is divided into two different approaches, aiming at both use cases that require a tight set of rules to be enforced upon an asset and more flexible and simple logic to be applied as an optional way of interacting with the asset.

Enforced Wrapper

Inspired by SEP08, the enforced approach is focused on entities, DAOs, and/or consortiums that control an asset and desire to enforce more custom and granular behavior upon their asset usage. It would contain the following main characteristics:

• Classic control flags enabled for auth_required and auth_revocable.
• The 'Wrapper' is set as the asset admin in the 'SAC' contract.
• Programmatically manage trustline authorization per transaction according to a custom logic, managed by a separate pluggable contract.

With this approach, by default, any account that creates a trustline won’t be able to transact with the asset using both classic and SAC. The wrapper contract will manage this authorization by transaction similarly to SEP8 but fully on-chain. This would introduce a transaction execution flow like the following:

1. Account invokes the asset function (e.g. 'transfer') through the Wrapper contract.
2. The Wrapper contract triggers the 'Asset Controller' contract to review the transfer arguments and apply custom logic. The logic may panic in case a restrictive custom rule isn't met. After the revision, if the transaction doesn't fail, the 'Wrapper' proceeds to execute the transaction.
3. The Wrapper triggers the SAC to approve the accounts' trustlines temporarily.
4. The Wrapper triggers the target transaction(e.g. 'transfer') through the SAC contract.
5. The Wrapper triggers the SAC to revoke the temporary authorization from the accounts.

Such a workflow enables the implementation of use cases such as:

• Applying limits to accounts that KYC hasn't verified, approving the trustline, and completely removing the limits once the verification goes through.
• Implementing custom mandatory lists for blocked or allowed contracts and accounts to transact.
• Providing different tiers of capabilities for client accounts according to a plan subscription.

Optional Wrapper

Borrowing from the approach above while simplifying the implementation, any builder that would like to provide custom integrated behavior to a classic asset can offer an optional route for users or specific clients. This approach still implements a Wrapper contract and an Asset Controller contract, although no flag customization or locks are set for the underlying classic asset, rendering the Wrapper optional. Specific limits to which accounts can access the Wrapper can be applied to limit this custom behavior to a group of clients or accounts but wouldn't affect the ability to use the classic asset or SAC directly.

The objective of the Optional Wrapper is to focus on an on-chain approach to share custom rules across different applications as well as standardized implementation for the common portions of the solution. This would introduce a transaction execution flow like the following:

1. Account invokes the asset function (e.g. 'transfer') through the Wrapper contract.
2. The Wrapper contract triggers the 'Asset Controller' contract to review the transfer arguments and apply custom logic. The logic may panic in case a restrictive custom rule isn't met. After the revision, if the transaction doesn't fail, the 'Wrapper' proceeds to execute the transaction.
3. The Wrapper triggers the target transaction(e.g. 'transfer') through the SAC contract.

In step 2, we can still consider restrictive rules that asset holders or applications such as wallets choose to be subject to. Such a workflow enables the implementation of use cases such as:

• Verifying a shared standard and collectively-curated list of suspicious or malicious applications that wallet builders utilize with their users.
• Running a gamified campaign based on asset usage and engagement to automatically attribute points and distribute prizes.
• Implement an automated cash-back system for wallet users, rewarding tokens per transaction.

Specification

Here, I see the most room for discussion. There are multiple key points that might be very helpful, but at the same time, I believe that a minimal requirement with optional variations is always preferred. Here are a few selected items so far for discussion

Wrapper:

• Native asset functions accessible by the wrapper should maintain the same identifier and arguments.
• The wrapper should not carry business logic. Instead, it should delegate all or most of the custom behavior to the Asset Controller.
• Enforced only The wrapper should have mechanisms/functions that can be safely activated and deactivated. This means making it operant while delegating the asset administration to it or recovering from it. It also means adding administration capabilities to the Wrapper for safe maintainability.

Asset Controller:

• Provide a 1:1 mapping of functions to match the supported asset functions with a standardized structure. E.g. To support 'transfer', the asset controller could implement a review_transfer function that processes the exact same arguments.
• Whenever a transaction doesn't meet the custom criteria, it should be the responsibility of the asset controller to panic and stop the transaction.
• Whenever the asset controller tracks states based on the transactions, it should enforce that its mapped functions can only be invoked by a wrapper integrated into it.

Informational:

• Builders and asset issuers should provide upfront information in their toml files(SEP1) about the wrappers they maintain and some key characteristics.
• Wrappers and Asset controllers should have embedded metadata about its core characteristics for integration, such as:
  • is_enforced: boolean
  • wrapped_asset: address
  • wrapper: address
  • admin: address
  • asset_controller: address

[tomerweller]

On custom tokens you say:

asset holders won’t have access to other classic advantages such as higher throughput, cheaper transactions, and native decentralized markets.

Wrt the enforced wrapper approach (I'm still trying to wrap my head around the value prop of the optional variant) it seems to me that all of this still holds because to do anything meaningful with the asset you need to call the wrapper.

The only advantage I can think of is that legacy systems that only know stellar assets (and no soroban) will be able to view balances of this wrapped asset, but not really do anything with it. Am I missing anything?

[fazzatti]

Great point! I agree to a certain point, yet I believe there is more to it.

I really believe there will be plenty of use cases in which either pure classic assets or pure soroban tokens will be a perfect fit and, using hybrid assets should be a deliberate choice based on the use case needs.

this still holds because to do anything meaningful with the asset you need to call the wrapper.

The key here is how the builder applies it. If the wrapper is used to simply encapsulate everything with no conscious usage of classic, yes, you would be just introducing unnecessary complexity.

The only advantage I can think of is that legacy systems that only know stellar assets (and no soroban) will be able to view balances of this wrapped asset, but not really do anything with it. Am I missing anything?

I belive that in order for this approach to make sense, the builders must aim at having soroban and classic being applied at different moments of their use case with intended benefits.
Not every use case would need both but I think that keeping the option of leveraging classic at certain moments can bring great benefits at scale(assuming the network design doesn't change a lot)

It could vary from:

• Start with Soroban and tight rules until KYC is performed or any arbitrary event, and you fully transition the account to classic.
• Soroban and classic are used for different accounts based on attributes like holder identity or region. For example, Brazilian verified users have specific sanctions applied due to the local regulation, while US-based users don't.
• Soroban and classic are being applied to specific workflows such as normal day-to-day transactions versus bulk payments.

Imagine the following scenario:

A regulated asset (SEP8) with very custom and granular rules.
You can combine both classic and soroban for different moments:

Soroban:

• Day-to-day transactions runnign with a fully on-chain transparent logic.
• Removing the SEP8 external service need and ensuring the asset is available along with the network availability. There is not a centralized week point that could render the asset unusable in the event of a crash.

Classic:

• Reserved for institutional bulk payments when you need to run a huge payroll and can coordinate with a SEP8 service.

Thinking about a huge number of payments over a long period, this could mean a big reduction in cost.

Hypothetical Classic Transfer with trustline ops:

• Up to ~330 per block ( 1k op/ledger divided by 3 ops/tx )
• around 0.00003 base fee + inclusion variant per payment

Hypothetical Soroban Transfer:

• Less than 100 payments per ledger if we look to the more ristrictive resources. See numbers below.
• around 0.0042119 resource fees + inclusion variant per payment

Values from SAC transfer in this testnet example
(doesn't really reflect a pure soroban token but I believe it comes close as a baseline)

SAC Transfer	Resource Used	Theoretical Max Number of Transactions per Block
CPU instructions	170572	586.2626926
RAM	55446	721.4226455
minResourceFee	89568
ledgerReadBytes	612	326.7973856
ledgerWriteBytes	124	524.1935484
ledgerEntryReads	1	40
ledgerEntryWrites	1	25
eventSize	252	31.74603175
returnValueSize	4
transactionSize	172	406.9767442

Taking this example comparison alone, when using the classic side to process a massive amount of transactions, we're talking about fitting roughly more than x3 times the number of payments per ledger while paying x100 less in base/resource fees. By extending this over a very long period, you can greatly reduce costs. The benefit in this case would be keeping tight control but still benefiting from low fees at scale.

Others could be that while a regulation at a specific region is not mature, an asset issuer could take a safer approach by using this wrapper to apply certain on-chain rules and then if the rules get more flexible, they can fully migrate to classic with a low effort of removing the auth flags and disbaling the wrapper. Which could be harder for a pure soroban token.

I'll stop here for a moment as this is just one of the possible lines I'm seeing here, and I want to hear other people's opinions and possible flaws in my viewpoint. It is probably best for the discussion to go in small steps as we move forward so other people can join easily and contribute.

[orbitlens]

Nice idea. Would love to see this implemented as a standard contract.
I've seen similar approaches implemented based on multisig + temporary asset authorization/deauthorization by the issuer within the same transaction. For example, in Aqua liquidity voting.

However, the contract-based approach expands this idea further, making it possible to define and execute the logic on-chain.

[fazzatti]

Is the Aqual liquidity voting system open source or public somewhere?
I would love to have a look at how it was implemented and find ways to translate it to an on-chain approach.

[JakeUrban]

I'm a big fan of this idea because removes the need for read-only applications such as block explorers like stellar.expert and data analytics platforms like rwa.xyz to update their implementations in order to support custom tokens. I would like to make some suggestions though.

Wrapper Interface

SEP-41 Compatibility

In order to maximize the chances of this proposal getting adopted by read-write applications (wallets, exchanges, defi protocols, etc.), I think the wrapper interface (enforced & optional) needs to be SEP41-compatible, meaning, clients shouldn't need to know they're interacting with an SAC wrapper to use the token contract.

The only difference between interacting with an SAC and a SAC wrapper should be that the functions that update state (transfer(), allow(), etc.) require the wrapper's admin's authorization in addition to the authorizations required by the underlying SAC.

Activate / Deactivate

I'm not sure I totally understand the purpose of having activate / deactivate functions. The wrapper contract's admin should have the ability to allow or reject any transaction that updates the SAC's state from within the relevant SEP41-compatible function, so these functions seem redundant.

Metadata

In the spirit of wrappers being indistinguishable from their underlying SAC's, I'm not sure if we need the metadata function. Why would a client need to know the information returned from the proposed function? Clients should either be required to use the wrapper, in which case it doesn't matter what the underlying SAC address is, or want to use the wrapper, in which case they also don't care about the underlying SAC address. Clients also wouldn't call the admin/controller contract directly so I don't see why the wrapper would need to provide that info.

Wrapper Implementation

I'm not sure we need to standardize how these wrapper contracts are implemented as long as they're SEP41-compatible. Wrappers could contain all the business logic themselves if they wanted to. For example, if transfers above a certain amount should be disallowed, that validation could be implemented within the transfer() function rather than a review_transfer() function on another contract.

I think the only thing we need to be opinionated about is authorization. Wrapper contracts should make use of the soroban auth framework by calling require_auth() on the wrapper's admin/controller address whenever an invocation requires the admin's approval. The admin can either choose to implement the built-in __check_auth() function to evaluate authorization onchain or chose to sign the auth payload off-chain after reviewing the transaction sent by the client (similar to the SEP-8 flow).

Discovery

I do think we need to standardize how clients determine that an SAC has a required wrapper. Providing the wrapper address in the CURRENCIES entry in the issuer's toml file could work, but how would they know that they need to check a toml file or figure out what home domain hosts it?

[fazzatti]

Hey Jake! Great points!

I agree with many of the items you mentioned, but there is a portion I would love to discuss further.

First, one the ones I agree entirely with:

Activate/deactivate: Add no specific value. I ended up adding those while exemplifying arbitrary functions that could go in the interface.
So, agreed to disregard.

Metadata: This is similar to the above with a difference. Depending on the direction we take, if we end up with a difference in the contract interface, perhaps something similar to this EIP-165 could be useful to consider in the future.
So again, for now, agreed to disregard.

Wrapper implementation:
"Wrappers could contain all the business logic themselves if they wanted to"
Again, great point! A SEP shouldn't specify where you implement the business logic. I followed that approach based on my biased perspective of what I believed to be a good approach. Still, it should definitely be up to the person implementing it, as it shouldn't interfere with the overall goal.

Now, on the other portion:

Although I agree that being SEP41-compatible is a great objective, I don't know if we can confidently ensure the next part without sacrificing a portion of the proposed value:

"clients shouldn't need to know they're interacting with an SAC wrapper to use the token contract."

This might be because I'm not fully aware of the entire extension of the Soroban auth framework, so pardon me if I'm overseeing something here. The best approach I found when implementing was directly using the Wrapper to interact with the asset instead of the SAC.

Let's focus on the 'enforced' approach for now. I see it as an evolution of the pure SEP08 implementation to solve some of the original downsides that I believe could, in the process, add value to the end-users and builders:

• Remove the need for an additional signer at each transaction, removing the need to go through an off-chain approval service to collect the issuer or multi-sig approval. The wrapper contract is the admin.

• The business rules are on-chain and transparent, ensuring the asset availability is exactly the same as the network with removing the off-chain approval service.

Integrating with the Wrapper can be exactly equal to integrating with the SAC without requiring additional signatures and workflows. This way, I, as a user, can use a fully regulated asset in the same way I would use an open asset with Soroban through SAC. From a client perspective, this only requires you to use a different contract ID than the original SAC.

Providing the wrapper address in the CURRENCIES entry in the issuer's toml file could work, but how would they know they need to check a toml file or figure out what home domain hosts it?

Thinking of the 'enforced' approach as an evolution of SEP8, this seems like a natural step as any SEP8 asset has to perform this step. So it wouldn't differ a lot from what SEP8 covers and could even be extended in the original sep. Builders would have to look into the toml in a similar way unless we agree to provide some mechanism in the contract itself as part of the standard (see the EIP example above)

It seems like a small trade-off if we consider it a requirement for SEP8 assets already. Also, being able to fully authorize the transaction just with the user signature while being compliant with the business rules and integrating in the exact same way as a SAC is especially powerful from my perspective.

Is it possible to achieve this with the Soroban auth framework by interacting directly with the SAC contract? Wouldn't that sacrifice some of those key benefits?