Basalt.Generators.Contracts 0.3.0

Basalt.Generators.Contracts

Incremental source generator for smart contract ABI dispatch. Generates method dispatch tables, parameter deserialization, return value serialization, and ABI metadata for classes annotated with [BasaltContract].

Trigger Attributes

All attributes are in the Basalt.Sdk.Contracts namespace.

Usage

[BasaltContract]
public partial class MyToken
{
    [BasaltEntrypoint]
    public void Transfer(Address to, UInt256 amount) { /* ... */ }

    [BasaltView]
    public UInt256 BalanceOf(Address account) { /* ... */ }

    [BasaltEvent]
    public class TransferEvent
    {
        [Indexed] public Address From { get; set; }
        [Indexed] public Address To { get; set; }
        public UInt256 Amount { get; set; }
    }
}

Generated Code

For each [BasaltContract] class, the generator emits {Namespace}.{TypeName}.g.cs containing a partial class extension with:

Dispatch Method

public byte[] Dispatch(byte[] selector, byte[] calldata)

Reads the first 4 bytes of selector as a little-endian uint, then dispatches to the matching contract method via a switch statement. Parameters are deserialized from calldata using BasaltReader. Return values are serialized into a byte[] using BasaltWriter. Void methods return Array.Empty<byte>(). An InvalidOperationException is thrown for unknown selectors or selectors shorter than 4 bytes.

Selector Computation

Method selectors are computed using FNV-1a hash of the method name:

hash = 2166136261
for each char c in methodName:
    hash ^= (byte)c
    hash *= 16777619

The resulting 4-byte value is stored in little-endian order. Selectors appear as 0x{hash:X8} in the ABI.

ABI Metadata

A const string ContractAbi field is generated containing a JSON object with:

• methods -- array of { name, selector, mutability, params: [{ name, type }], returns }.
• events -- array of { name, properties: [{ name, type, indexed }] }.

Supported Parameter / Return Types

Unsupported parameter or return types throw NotSupportedException at runtime.

Event Discovery

Events are collected from three sources:

1. Nested types -- classes/structs nested directly inside the [BasaltContract] class that have [BasaltEvent].
2. Base type hierarchy -- walks the base class chain and collects [BasaltEvent]-annotated nested types from each ancestor.
3. Interfaces and namespaces -- for each interface the contract implements, scans the interface's containing type, containing namespace, and the contract's own containing namespace for [BasaltEvent] types. This discovers events declared alongside interfaces (e.g. a TransferEvent next to an IBST20 interface). A HashSet<string> prevents duplicate entries.

Dependencies

Target framework: netstandard2.0 (required for source generators).