Support trait method default implementations for `#[contractimpl]` macro

[ozgunozerk]

What problem does your feature solve?

Currently, say we have a trait, and we want to provide default implementations for some of its methods. We can do that, but when implementing the trait for our contract, the default implementations are not parsed by the #[contractimpl] macro (since, these methods are not mentioned in the impl block), making these methods unavailable to the generated client.

What would you like to see?

Methods with default implementations to be available for the client as well.

I know that this may be hard to achieve due to macro scopes, but it would really help us design better architecture for our libraries.

[ozgunozerk]

I think this may be technically impossible, because afaik we cannot establish communication between macros, and I can't see a way for #[contractimpl] macro to parse the default implementations.

Maybe, to improve developer experience, one may add custom errors to #[contractimpl] macro. Say, there is a default implementation for the method transfer_from(), and it was simply not present under #[contractimpl]. When someone tries to call client.transfer_from(), we can do something like this:

transfer_from() is not found on MyClient. contractimpl macro can only see the methods defined under it. If this was a default implementation from a trait, please include the default implementation under contractimpl macro as well.

[leighmcculloch]

I've been reviewing a few different approaches to resolving this issue.

The solutions I've looked at are:

• @axelarnetwork's derive(...) https://docs.rs/stellar-axelar-std-derive/1.1.2/stellar_axelar_std_derive/derive.Pausable.html
• @ozgunozerk's default_impl https://github.com/OpenZeppelin/stellar-contracts/blob/main/packages/contract-utils/default-impl-macro/src/lib.rs
• @willemneal's contracttrait and derive_macro that is being implemented over at: feat: contracttrait macro theahaco/rs-soroban-sdk#1

All the approaches above address the issue of how to surface a contractimpl macro call across the default functions. The first two solutions do so with hand crafted code which are simple and quite easy to understand, following common Rust patterns, but requires everyone to hand write the proc-macros. The third solution does so with a declarative macro which is portable to any contract, although it comes with additional features (a requirement to use associated types, extensions, derives).

I think the SDK can leverage the declarative macro idea, whilst narrowly focusing on a similar scope as the first two solutions, without associated types. I think this would resolve this issue almost invisibly to a developer, whilst leaning heavily on standard Rust trait patterns. By focusing on a solution that looks like standard Rust, it keeps the learning curve flat for Rust devs and keeps Soroban Rust closer to common Rust.

This is the idea:

• a #[contracttrait] macro, similar to feat: contracttrait macro theahaco/rs-soroban-sdk#1, that generates a declarative macro for the trait that emits the underlying infrastructure for the trait's functions that have default implementations.
• When a #[contactimpl] is used on an impl Trait for Struct the declarative macro would be called with a list of functions that have been implemented.
• The declarative macro, through pattern matching, would emit code hooking up exported functions and contract specs only for the default functions that were not overriddenn.
  • Skipping default functions that have been overriddenn is important, because that's a natural thing that Rust devs can do today in plain Rust.
  • This requires some experimentation to figure out if it is indeed possible.
• Trait developers who wish to provide default implementations would probably still create a helper type that contains the logic, and have the trait call out to that helper function. For any existing traits, such as the OpenZeppelin contracts, they would just need to add the default fn implementations to the trait functions calling those helper functions.

The goal is to make it as much as possible look and work like regular Rust. The only difference would be the use of the #[contracttrait] on the trait.

The idea doesn't attempt to solve any other problems like how to increase code reusability in other ways, which it looks like is what theahaco#1 is doing. But I think it is worth solving the issue of trait impls as simply as possible, because likely other extensibility solutions that aren't found in common Rust should be able to layer on top.

Example:

Define trait:

#[contracttrait]
pub trait Token {
    fn allowance(env: Env, from: Address, spender: Address) -> i128 { TokenDefault::allowance(...) }
    fn approve(env: Env, from: Address, spender: Address, amount: i128, live_until_ledger: u32) { TokenDefault::approve(...) }
    fn balance(env: Env, id: Address) -> i128 { TokenDefault::balance(...) }
    fn transfer(env: Env, from: Address, to: Address, amount: i128) { TokenDefault::transfer(...) }
    fn transfer_from(env: Env, spender: Address, from: Address, to: Address, amount: i128) { TokenDefault::transfer_from(...) }
    fn burn(env: Env, from: Address, amount: i128) { TokenDefault::burn(...) }
    fn burn_from(env: Env, spender: Address, from: Address, amount: i128) { TokenDefault::burn_from(...) }
    fn decimals(env: Env) -> u32 { TokenDefault::decimals(...) }
    fn name(env: Env) -> String { TokenDefault::name(...) }
    fn symbol(env: Env) -> String { TokenDefault::symbol(...) }
}

Implement on contract, using default implementation:

#[contract]
pub struct Contract;

#[contractimpl]
impl Token for Contract {}

Implement on contract, using default and overridden implementations:

#[contract]
pub struct Contract;

#[contractimpl]
impl Token for Contract {
    // decimals is overriden, but all other functions are used as their defaults
    fn decimals(env: &Env) -> u32 { 18 }
}

This is something I'm still thinking about, and I'm sharing the above without having done any experimentation to prove it out.

Thoughts?

[ozgunozerk]

Hi @leighmcculloch, thanks a lot!

Here are my 2 cents:

I still think:

this may be technically impossible, because afaik we cannot establish communication between macros, and I can't see a way for #[contractimpl] macro to parse the default implementations.

In the referenced PR by AhaLabs, this very problem is tackled with declarative macros which have the default methods embedded into them.

From what I quickly glanced, what is common in all 3 approaches you mentioned is: the macros have all the necessary information for the default methods.

I think that is (embedding the default methods into the macro) the only way to workaround the technical limitations of macros. This means:

• we either have a declarative macro specific for the trait -> 1-1 mapping (Aha Labs apprioach),
• or we use a proc-macro, and derive the necessary default methods from somewhere else (our approach)

Hence, I don't see a way to make the proposed example work, unless we hardcode the default implementations of all the relevant traits into the #[contractimpl] macro itself, (as we did for our #[default_impl] macro):

Implement on contract, using default implementation:

#[contract]
pub struct Contract;

#[contractimpl]
impl Token for Contract {}

Implement on contract, using default and overridden implementations:

#[contract]
pub struct Contract;

#[contractimpl]
impl Token for Contract {
    // decimals is overriden, but all other functions are used as their defaults
    fn decimals(env: &Env) -> u32 { 18 }
}

[willemneal]

@leighmcculloch Thank you for looking into this.

Currently the derive_contract can implement what you describe.

#[contract]
#[derive_contract(Token(default = Contract))]
pub struct Contract;

impl Token for Contract {
    // If the contracttrait can provides a default implementation you can access it via the default case of the `macro_rule`
    type Impl = Token!();
    // decimals is overriden, but all other functions are used as their defaults
    fn decimals(env: &Env) -> u32 { 18 }
}

This will generate

#[contractimpl]
impl Contract {
  pub fn decimals(env: &Env) -> u32 {
    <Contract as Token>::decimals(e)
}
/// Rest of the methods are here
}

Current contracttrait only accepts traits, but it could operate on impl blocks too; allowing for:

#[contract]
pub struct Contract;

#[contracttrait]
impl Token for Contract {
    // decimals is overriden, but all other functions are used as their defaults
    fn decimals(env: &Env) -> u32 { 18 }
}
``` or

```rust
#[contract]
pub struct Contract;

#[contracttrait( default = OtherTokenImpl)]
impl Token for Contract {
    // decimals is overriden, but all other functions are used as their defaults
    fn decimals(env: &Env) -> u32 { 18 }
}

This looks very similar to what you propose.

I agree with @ozgunozerk we need to automate the default methods of the trait. The contracttrait macro already does this, though it will skip any default methods already defined. For example:

#[contracttrait(default = Admin, is_extension = true)]
pub trait Adminstratable {
    fn admin(env: &Env) -> soroban_sdk::Address;
    fn set_admin(env: &Env, new_admin: soroban_sdk::Address);
    #[internal]
    fn require_admin(env: &Env) {
        Self::admin(env).require_auth();
    }
}

Becomes:

#[contracttrait(default = Admin, is_extension = true)]
pub trait Adminstratable {
    type Impl: Administratable;
    fn admin(env: &Env) -> soroban_sdk::Address {
        Self::Impl::admin(env)
    }
    fn set_admin(env: &Env, new_admin: soroban_sdk::Address) {
    //
    }
    fn require_admin(env: &Env) {
        Self::admin(env).require_auth();
    }
}

[leighmcculloch]

Currently the derive_contract can implement what you describe.

#[contract]
#[derive_contract(Token(default = Contract))]
pub struct Contract;

...

@willemneal Yup, I see that theahaco#1 provides all those features. I'm looking for a reduced solution that resolves this issue of default trait function support, while maintaining the common pattern of code sharing through traits without requiring associated types, and the other features.

Why: So that Rust devs don't need to learn anything new, or at least very little new, to use this. So that default functions just work.

I don't see a way to make the proposed example work, unless we hardcode the default implementations

@ozgunozerk I think in theory it's possible to embed and call a declarative macro without predefining all the impls inside contractimpl, but I acknowledge I haven't tried what I described above. Some spiking and validation is needed.

[willemneal]

As I see it. If we provide default trait methods which call some default implementation, you can either hard code the default or provide some way to overwrite it. It could be a generic or it could be the associated type.

And in my proposed refactor (shown again below), the top level devs will never see or need to know about the associated type (it doesn't appear in the trait definition since it's generated):

#[contract]
pub struct Contract;

#[contracttrait]
impl Token for Contract {
    // decimals is overriden, but all other functions are used as their defaults
    fn decimals(env: &Env) -> u32 { 18 }
}

#[contract]
pub struct Contract;

#[contracttrait( default = OtherTokenImpl)]
impl Token for Contract {
    // decimals is overriden, but all other functions are used as their defaults
    fn decimals(env: &Env) -> u32 { 18 }
}

In your proposal, Token would provide the default implementation through a declarative macro correct? If so, how would it be set and how could the developer overwrite what the default would be?

#[contractimpl]
impl Token for Contract {
    // decimals is overriden, but all other functions are used as their defaults
    fn decimals(env: &Env) -> u32 { 18 }
}

One solution I found was to use generics allowing the default to appear in the trait definition:

trait Token<T: Token = Base> 

then your example would work as expected:

#[contractimpl]
impl Token for Contract {
    // decimals is overriden, but all other functions are used as their defaults
    fn decimals(env: &Env) -> u32 { 18 }
}

Even still this would rely on the declarative macro to figure out not to generate the decimals and insert the rest of the methods. I tried to do this is several different ways with no success but it became much easier when taking advantage of the fact that Contract will implement the traitand we can use the fact that it will also inherit the default methods. So it is much simpler to just generate all methods in an impl block and forward them to themContract`.

I understand that adding an associated type or generic adds an additional complexity burden to the developer, however, I really don't presently see another way to provide a way to overwrite the default implementations.

[leighmcculloch]

I think there's value in exploring how it can be simplified, by separating what's needed for default impl support (this issue) from other features (extensions, etc). The derive and extensions functionality doesn't look like it would need to be Soroban specific. Could it be a generic Rust library folks can adopt in any Rust code base? Or are these things bound together?

There's a lot of space to iterate on this, to see how this can evolve as a separate library, before it or something like it is adopted into the SDK. If it can be simplified the future benefit out sizes an immediate benefit now. My understanding is that there isn't urgency to adopt a solution in the SDK immediately because libraries like Axelar's and OpenZeppelin's have solutions that work. While those solutions have limited scope because they are hand crafted for specific libraries, they do work.

I plan to spend more time on using the proposal and experimenting with it and want to dig into it further.

[leighmcculloch]

Cross-posting there is some additional feedback and thoughts about the derive_contract approach here:

• Feat/contracttraits OpenZeppelin/stellar-contracts#334 (comment)

[willemneal]

Thank you @ozgunozerk and @leighmcculloch for the feedback. I have a new proposal which I think should be a good middle ground.

I have updated #[contracttrait] to also handle impl blocks. It is less overhead for new users. Since contractimpl is already a concept and we don't have to introduce contract_derive. Furthermore, we can remove the extra arguments for the macro and just support default.

It is also more similar to the approach taken by #[default_impl], so an easier transition to the OZ codebase, while providing users with customization.

It also makes things simpler. Consider

#[contracttrait]
impl FungibleToken for ExampleContract {}
// or
#[contracttrait(default = OtherImpl)]
impl FungibleToken for ExampleContract {}

Becomes

impl FungibleToken for ExampleContract {
    type Impl =  FungibleToken!(); // returns default implementation
}
// or
impl FungibleToken for ExampleContract {
    type Impl = OtherImpl;
}

#[contractimpl]
impl ExampleContract {
    // all methods call `<ExampleContract as FungibleToken>::..
}

Honestly I don't see how you can get much simpler than this.

Extensions

The extensions feature is indeed not required. It mainly allows you to opt into generating the a type like:

pub struct AmininstrableExt<T: Administratable,N>(PhantomData<T>,PhantomData<N>);

This is what can then allow you to have the blanket impls for different traits.

I have found it very helpful in being able to combine multiple traits. E.g. Pausable, FungibleBlockList.
Consider PausableExt``s implementation of FungibleToken`

impl<T: Pausable, N: FungibleToken> FungibleToken for PausableExt<T, N> {
    type Impl = N;

    fn transfer(e: &Env, from: &Address, to: &Address, amount: i128) {
        T::when_not_paused(e);
        Self::Impl::transfer(e, from, to, amount);
    }

    fn transfer_from(e: &Env, spender: &Address, from: &Address, to: &Address, amount: i128) {
        T::when_not_paused(e);
        Self::Impl::transfer_from(e, spender, from, to, amount);
    }
}

Then using it it with the macro

#[contracttrait(ext = FungibleBlockListExt, ext = PausableExt)]
impl FungibleToken for ExampleContract {}

Becomes

impl FungibleToken for ExampleContract {
    type Impl = FungibleBlockListExt<ExampleContract, PausableExt<ExampleContract, FungibleToken!()>>;
}

As you can see the macro just constructs this type. So this could be rewritten as

#[contracttrait]
impl FungibleToken for ExampleContract {
    type Impl = with_ext!(FungibleBlockListExt,  PausableExt, FungibleToken);
}

generating:

impl FungibleToken for ExampleContract {
    type Impl = FungibleBlockListExt<Self, PausableExt<Self, FungibleToken!()>>;
}

Requiring extensions

The one place where requiring trait extensions is with traits whose base implementation doesn't provide any authentication and you can then require that an extension be used. Which makes it compile time safe compared to just having a note in a comment that devs shouldn't expose the base implementation.

The way this is handled in the macro now is that the dafault type for a contraittrait in wrapped by a generated Never implementation.

struct NeverPausable<T: Pausablle>(Phantom<T>);

impl<N: Pauasable> Pausable for NeverPausable<N> {
            type Impl = N;
            ///
    fn paused(e: &Env) -> bool {
        compile_error("Pausable requires an extension for authentication but none were provided")
}

So then if you do

#[contracttrait]
impl Pausable for ExampleContract {}

You get

impl Pausable for ExampleContract {
    type Impl = NeverPausable<Pausable!()>;
}

For the first iteration i will remove this and to prevent the following from compiling, when defining Pausable contracttrait can require that an implementation is provided rather than using the default.

#[contracttrait]
impl Pausable for ExampleContract {}

rather this will compile:

#[contracttrait]
impl Pausable for ExampleContract {
    type Impl =  with_ext!(AdministratableExt, Pausable);
}

[leighmcculloch]

Focusing on the issue of the trait functions with default implementations not being callable:

I don't see a way to make the proposed example work, unless we hardcode the default implementations

@ozgunozerk I had a play and have opened the following pull request that demonstrates how the idea I described in #1451 (comment) works. It works 99% like regular Rust code when working with traits and functions with default implementations although the declarative macro does unfortunately require manual importing.

• Make trait functions that have default implementations callable #1507

There's also an example of using on the PR and here:

• https://github.com/leighmcculloch/stellar--rs-soroban-sdk--pr1507

@willemneal If we take the issue of trait default functions away, and assume it's resolved through something like #1507, is the extension layer-able on top, and also usable on any generic Rust code and could go into a crate that is not Soroban specific?