Composition and trait-based routing model

Inheritance allows you to build upon existing smart contract functionality without duplicating code. In Stylus, the Rust SDK provides tools to implement inheritance patterns similar to Solidity, but with some important differences. This guide walks you through implementing trait-based composition in your Stylus smart contracts.

Overview

The Stylus SDK offers trait-based composition using traits and the #[implements] annotation. This approach follows Rust's composition patterns and provides stronger type safety.

Getting started

Before implementing trait-based composition, ensure you have:

Trait-based composition model

The recommended approach to inheritance in Stylus uses traits and the #[implements] annotation, which follows Rust's standard composition patterns:

Basic example of trait-based composition

How trait-based composition works

The trait-based composition model follows these principles:

1. Define traits that represent interfaces (similar to Solidity interfaces)
2. Implement these traits for your contract
3. Use the #[implements(...)] attribute to tell the Stylus SDK which traits your contract implements
4. The router will connect incoming calls to the appropriate implementation

This approach is aligned with Rust's composition patterns and offers better type safety.

Method overriding

If both parent and child implement the same method, the one in the child will override the one in the parent. This allows for customizing inherited functionality.

ABI export considerations with trait-based composition

When using trait-based composition, you need to be careful about function selectors to ensure correct ABI generation. Due to how Rust handles traits, you may need to explicitly set selectors for methods to match Solidity's expected function signatures.

Methods search order

When using trait-based composition, it's important to understand the order in which methods are searched:

1. The search starts in the type that uses the #[entrypoint] macro
2. If the method is not found, the search continues in the implemented traits, in the order specified in the #[implements] annotation
3. If the method is not found in any implemented trait, the call reverts

In a typical composition chain:

• Calling a method first searches in the contract itself
• If not found there, it looks in the first trait specified in the inheritance list
• If still not found, it searches in the next trait in the list
• This continues until the method is found or all possibilities are exhausted