fallback when all contract selectors fail (#5703)

## Description

This PR closes #5566.

Contracts now can have a special function decorated with `#[fallback]`
which is called when the contract method selection fails.

This function for all intents and purposes works as a standard contract
method, so:

- it cannot call others contracts methods;
- it has the same limitations of inputs and outputs.

This function can return a value like a normal contract would, or it can
use the `__contract_ret` intrinsics to return any value.

## Checklist

- [x] I have linked to any relevant issues.
- [x] I have commented my code, particularly in hard-to-understand
areas.
- [ ] I have updated the documentation where relevant (API docs, the
reference, and the Sway book).
- [x] I have added tests that prove my fix is effective or that my
feature works.
- [x] I have added (or requested a maintainer to add) the necessary
`Breaking*` or `New Feature` labels where relevant.
- [x] I have done my best to ensure that my PR adheres to [the Fuel Labs
Code Review
Standards](https://github.com/FuelLabs/rfcs/blob/master/text/code-standards/external-contributors.md).
- [x] I have requested a review from the relevant team or maintainers.

Author: xunilrj

docs/book/src/blockchain-development/calling_contracts.md

@@ -163,3 +163,31 @@ While the Fuel contract calling paradigm is similar to the EVM's (using an ABI,
 1. [**Native assets**](./native_assets.md): FuelVM calls can forward any native asset not just base asset.
 
 2. **No data serialization**: Contract calls in the FuelVM do not need to serialize data to pass it between contracts; instead they simply pass a pointer to the data. This is because the FuelVM has a shared global memory which all call frames can read from.
+
+## Fallback
+
+When a contract is compiled, a special section called "contract selection" is also generated. This section checks if the contract call method matches any of the available ABI methods. If this fails, one of two possible actions will happen:
+
+1 - if no fallback function was specified, the contract will revert;
+2 - otherwise, the fallback function will be called.
+
+For all intents and purposes the fallback function is considered a contract method, which means that it has all the limitations that other contract methods have. As the fallback function signature, the function cannot have arguments, but they can return anything.
+
+If for some reason the fallback function needs to returns different types, the intrinsic `__contract_ret` can be used.
+
+```sway
+contract;
+
+abi MyContract {
+    fn some_method();
+}
+
+impl ContractB for Contract {
+    fn some_method() {
+    }
+}
+
+#[fallback]
+fn fallback() {
+}
+```

docs/book/src/reference/attributes.md

@@ -59,3 +59,7 @@ More details in [Unit Testing](../testing/unit-testing.md).
 The `#[deprecated]` attribute marks an item as deprecated and makes the compiler emit a warning for every usage of the deprecated item. This warning can be disabled using `#[allow(deprecated)]`.
 
 It is possible to improve the warning message with `#[deprecated(note = "your message")]`
+
+## Fallback
+
+The `#[fallback]` attribute makes the compiler use the marked function as the contract call fallback function, which means that, when a contract is called, and the contract selection fails, the fallback function will be called instead.

sway-core/src/asm_generation/from_ir.rs

@@ -76,10 +76,15 @@ fn compile_module_to_asm(
         BuildTarget::MidenVM => Box::new(MidenVMAsmBuilder::new(kind, context)),
     };
 
+    let mut fallback_fn = None;
+
     // Pre-create labels for all functions before we generate other code, so we can call them
     // before compiling them if needed.
     for func in module.function_iter(context) {
-        builder.func_to_labels(&func);
+        let (start, _) = builder.func_to_labels(&func);
+        if func.is_fallback(context) {
+            fallback_fn = Some(start);
+        }
     }
 
     for function in module.function_iter(context) {
@@ -126,7 +131,7 @@ fn compile_module_to_asm(
             }
 
             let allocated_program = abstract_program
-                .into_allocated_program()
+                .into_allocated_program(fallback_fn)
                 .map_err(|e| handler.emit_err(e))?;
 
             if build_config

sway-core/src/asm_generation/programs/abstract.rs

@@ -39,7 +39,10 @@ impl AbstractProgram {
         }
     }
 
-    pub(crate) fn into_allocated_program(mut self) -> Result<AllocatedProgram, CompileError> {
+    pub(crate) fn into_allocated_program(
+        mut self,
+        fallback_fn: Option<crate::asm_lang::Label>,
+    ) -> Result<AllocatedProgram, CompileError> {
         // Build our bytecode prologue which has a preamble and for contracts is the switch based on
         // function selector.
         let mut prologue = self.build_preamble();
@@ -49,7 +52,7 @@ impl AbstractProgram {
                 self.build_jump_to_entry(&mut prologue);
             }
             (false, ProgramKind::Contract) => {
-                self.build_contract_abi_switch(&mut prologue);
+                self.build_contract_abi_switch(&mut prologue, fallback_fn);
             }
             _ => {}
         }
@@ -172,7 +175,11 @@ impl AbstractProgram {
     /// 'selector'.
     /// See https://fuellabs.github.io/fuel-specs/master/vm#call-frames which
     /// describes the first argument to be at word offset 73.
-    fn build_contract_abi_switch(&mut self, asm_buf: &mut AllocatedAbstractInstructionSet) {
+    fn build_contract_abi_switch(
+        &mut self,
+        asm_buf: &mut AllocatedAbstractInstructionSet,
+        fallback_fn: Option<crate::asm_lang::Label>,
+    ) {
         const SELECTOR_WORD_OFFSET: u64 = 73;
         const INPUT_SELECTOR_REG: AllocatedRegister = AllocatedRegister::Allocated(0);
         const PROG_SELECTOR_REG: AllocatedRegister = AllocatedRegister::Allocated(1);
@@ -241,8 +248,14 @@ impl AbstractProgram {
             });
         }
 
-        // If none of the selectors matched, then revert.  This may change in the future, see
-        // https://github.com/FuelLabs/sway/issues/444
+        if let Some(fallback_fn) = fallback_fn {
+            asm_buf.ops.push(AllocatedAbstractOp {
+                opcode: Either::Right(ControlFlowOp::Call(fallback_fn)),
+                comment: "call fallback function".into(),
+                owning_span: None,
+            });
+        }
+
         asm_buf.ops.push(AllocatedAbstractOp {
             opcode: Either::Left(AllocatedOpcode::MOVI(
                 AllocatedRegister::Constant(ConstantRegister::Scratch),

sway-core/src/control_flow_analysis/dead_code_analysis.rs

@@ -27,7 +27,7 @@ use sway_types::{
     Ident, Named, Spanned,
 };
 
-// Defines if this node starts the dca graph or not
+// Defines if this node is a root in the dca graph or not
 fn is_entry_point(node: &TyAstNode, decl_engine: &DeclEngine, tree_type: &TreeType) -> bool {
     match tree_type {
         TreeType::Predicate | TreeType::Script => {
@@ -59,7 +59,7 @@ fn is_entry_point(node: &TyAstNode, decl_engine: &DeclEngine, tree_type: &TreeTy
                 ..
             } => {
                 let decl = decl_engine.get_function(decl_id);
-                decl.visibility == Visibility::Public || decl.is_test()
+                decl.visibility == Visibility::Public || decl.is_test() || decl.is_fallback()
             }
             TyAstNode {
                 content:

sway-core/src/ir_generation/compile.rs

@@ -1,5 +1,5 @@
 use crate::{
-    decl_engine::{DeclId, DeclRefFunction},
+    decl_engine::{DeclEngineGet, DeclId, DeclRefFunction},
     language::{ty, Visibility},
     metadata::MetadataManager,
     semantic_analysis::namespace,
@@ -140,13 +140,13 @@ pub(super) fn compile_contract(
     )
     .map_err(|err| vec![err])?;
 
-    if let Some(main_function) = entry_function {
+    if let Some(entry_function) = entry_function {
         compile_entry_function(
             engines,
             context,
             &mut md_mgr,
             module,
-            main_function,
+            entry_function,
             logged_types_map,
             messages_types_map,
             None,
@@ -165,6 +165,25 @@ pub(super) fn compile_contract(
         )?;
     }
 
+    // Fallback function needs to be compiled
+    for decl in declarations {
+        if let ty::TyDecl::FunctionDecl(decl) = decl {
+            let decl_id = decl.decl_id;
+            let decl = engines.de().get(&decl_id);
+            if decl.is_fallback() {
+                compile_abi_method(
+                    context,
+                    &mut md_mgr,
+                    module,
+                    &decl_id,
+                    logged_types_map,
+                    messages_types_map,
+                    engines,
+                )?;
+            }
+        }
+    }
+
     compile_tests(
         engines,
         context,
@@ -504,6 +523,7 @@ fn compile_fn(
         selector,
         *visibility == Visibility::Public,
         is_entry,
+        ast_fn_decl.is_fallback(),
         metadata,
     );
 

sway-core/src/language/ty/declaration/function.rs

@@ -10,6 +10,7 @@ use sway_error::handler::{ErrorEmitted, Handler};
 use crate::{
     language::{parsed::FunctionDeclarationKind, CallPath},
     semantic_analysis::type_check_context::MonomorphizeHelper,
+    transform::AttributeKind,
 };
 
 use crate::{
@@ -441,6 +442,10 @@ impl TyFunctionDecl {
         }
     }
 
+    pub fn is_fallback(&self) -> bool {
+        self.attributes.contains_key(&AttributeKind::Fallback)
+    }
+
     /// Whether or not this function is a constructor for the type given by `type_id`.
     ///
     /// Returns `Some(true)` if the function is surely the constructor and `Some(false)` if

sway-core/src/semantic_analysis/ast_node/declaration/auto_impl.rs

@@ -1,4 +1,5 @@
 use crate::{
+    asm_generation::fuel::compiler_constants::MISMATCHED_SELECTOR_REVERT_CODE,
     decl_engine::{DeclEngineGet, DeclId, DeclRef},
     language::{
         parsed::{self, AstNodeContent, Declaration, FunctionDeclarationKind},
@@ -513,6 +514,7 @@ where
         engines: &Engines,
         module_id: Option<ModuleId>,
         contract_fns: &[DeclRef<DeclId<TyFunctionDecl>>],
+        fallback_fn: Option<DeclId<TyFunctionDecl>>,
     ) -> Option<TyAstNode> {
         let mut code = String::new();
 
@@ -581,15 +583,24 @@ where
         }
         .into();
 
+        let fallback = if let Some(fallback_fn) = fallback_fn {
+            let fallback_fn = engines.de().get(&fallback_fn);
+            let return_type = Self::generate_type(engines, fallback_fn.return_type.type_id);
+            let method_name = fallback_fn.name.as_str();
+
+            format!("let result: raw_slice = encode::<{return_type}>({method_name}()); __contract_ret(result.ptr(), result.len::<u8>());")
+        } else {
+            // as the old encoding does
+            format!("__revert({});", MISMATCHED_SELECTOR_REVERT_CODE)
+        };
+
         let code = format!(
-            "{att}
-        pub fn __entry() {{
+            "{att} pub fn __entry() {{
             let method_name = decode_first_param::<str>();
-            __log(method_name);
             {code}
+            {fallback}
         }}"
         );
-
         self.parse_item_fn_to_typed_ast_node(
             engines,
             module_id,

sway-core/src/semantic_analysis/module.rs

@@ -12,7 +12,7 @@ use sway_error::{
 use sway_types::{BaseIdent, Named};
 
 use crate::{
-    decl_engine::DeclEngineGet,
+    decl_engine::{DeclEngineGet, DeclId},
     engine_threading::DebugWithEngines,
     language::{
         parsed::*,
@@ -307,6 +307,17 @@ impl ty::TyModule {
         let mut all_nodes = Self::type_check_nodes(handler, ctx.by_ref(), ordered_nodes)?;
         let submodules = submodules_res?;
 
+        let fallback_fn = collect_fallback_fn(&all_nodes, engines, handler)?;
+        match (&kind, &fallback_fn) {
+            (TreeType::Contract, _) | (_, None) => {}
+            (_, Some(fallback_fn)) => {
+                let fallback_fn = engines.de().get(fallback_fn);
+                return Err(handler.emit_err(CompileError::FallbackFnsAreContractOnly {
+                    span: fallback_fn.span.clone(),
+                }));
+            }
+        }
+
         if ctx.experimental.new_encoding {
             let main_decl = all_nodes.iter_mut().find_map(|x| match &mut x.content {
                 ty::TyAstNodeContent::Declaration(ty::TyDecl::FunctionDecl(decl)) => {
@@ -348,6 +359,7 @@ impl ty::TyModule {
                             engines,
                             parsed.span.source_id().map(|x| x.module_id()),
                             &contract_fns,
+                            fallback_fn,
                         )
                         .unwrap();
                     all_nodes.push(node)
@@ -463,6 +475,53 @@ impl ty::TyModule {
     }
 }
 
+fn collect_fallback_fn(
+    all_nodes: &[ty::TyAstNode],
+    engines: &Engines,
+    handler: &Handler,
+) -> Result<Option<DeclId<ty::TyFunctionDecl>>, ErrorEmitted> {
+    let mut fallback_fns = all_nodes
+        .iter()
+        .filter_map(|x| match &x.content {
+            ty::TyAstNodeContent::Declaration(ty::TyDecl::FunctionDecl(decl)) => {
+                let d = engines.de().get(&decl.decl_id);
+                d.is_fallback().then_some(decl.decl_id)
+            }
+            _ => None,
+        })
+        .collect::<Vec<_>>();
+
+    let mut last_error = None;
+    for f in fallback_fns.iter().skip(1) {
+        let decl = engines.de().get(f);
+        last_error = Some(
+            handler.emit_err(CompileError::MultipleDefinitionsOfFallbackFunction {
+                name: decl.name.clone(),
+                span: decl.span.clone(),
+            }),
+        );
+    }
+
+    if let Some(last_error) = last_error {
+        return Err(last_error);
+    }
+
+    if let Some(fallback_fn) = fallback_fns.pop() {
+        let f = engines.de().get(&fallback_fn);
+        if !f.parameters.is_empty() {
+            Err(
+                handler.emit_err(CompileError::FallbackFnsCannotHaveParameters {
+                    span: f.span.clone(),
+                }),
+            )
+        } else {
+            Ok(Some(fallback_fn))
+        }
+    } else {
+        Ok(None)
+    }
+}
+
 impl ty::TySubmodule {
     pub fn build_dep_graph(
         _handler: &Handler,

sway-core/src/transform/attribute.rs

@@ -68,6 +68,7 @@ pub enum AttributeKind {
     Cfg,
     Deprecated,
     Namespace,
+    Fallback,
 }
 
 impl AttributeKind {
@@ -76,7 +77,9 @@ impl AttributeKind {
     pub fn expected_args_len_min_max(self) -> (usize, Option<usize>) {
         use AttributeKind::*;
         match self {
-            Doc | DocComment | Storage | Inline | Test | Payable | Deprecated => (0, None),
+            Doc | DocComment | Storage | Inline | Test | Payable | Deprecated | Fallback => {
+                (0, None)
+            }
             Allow | Cfg | Namespace => (1, Some(1)),
         }
     }
@@ -85,7 +88,8 @@ impl AttributeKind {
     pub fn expected_args_values(self, _arg_index: usize) -> Option<Vec<String>> {
         use AttributeKind::*;
         match self {
-            Deprecated | Namespace | Doc | DocComment | Storage | Inline | Test | Payable => None,
+            Deprecated | Namespace | Doc | DocComment | Storage | Inline | Test | Payable
+            | Fallback => None,
             Allow => Some(vec![
                 ALLOW_DEAD_CODE_NAME.to_string(),
                 ALLOW_DEPRECATED_NAME.to_string(),

sway-core/src/transform/to_parsed_lang/convert_parse_tree.rs

@@ -32,10 +32,10 @@ use sway_types::{
     constants::{
         ALLOW_ATTRIBUTE_NAME, CFG_ATTRIBUTE_NAME, CFG_EXPERIMENTAL_NEW_ENCODING,
         CFG_PROGRAM_TYPE_ARG_NAME, CFG_TARGET_ARG_NAME, DEPRECATED_ATTRIBUTE_NAME,
-        DOC_ATTRIBUTE_NAME, DOC_COMMENT_ATTRIBUTE_NAME, INLINE_ATTRIBUTE_NAME,
-        NAMESPACE_ATTRIBUTE_NAME, PAYABLE_ATTRIBUTE_NAME, STORAGE_PURITY_ATTRIBUTE_NAME,
-        STORAGE_PURITY_READ_NAME, STORAGE_PURITY_WRITE_NAME, TEST_ATTRIBUTE_NAME,
-        VALID_ATTRIBUTE_NAMES,
+        DOC_ATTRIBUTE_NAME, DOC_COMMENT_ATTRIBUTE_NAME, FALLBACK_ATTRIBUTE_NAME,
+        INLINE_ATTRIBUTE_NAME, NAMESPACE_ATTRIBUTE_NAME, PAYABLE_ATTRIBUTE_NAME,
+        STORAGE_PURITY_ATTRIBUTE_NAME, STORAGE_PURITY_READ_NAME, STORAGE_PURITY_WRITE_NAME,
+        TEST_ATTRIBUTE_NAME, VALID_ATTRIBUTE_NAMES,
     },
     integer_bits::IntegerBits,
 };
@@ -4544,6 +4544,7 @@ fn item_attrs_to_map(
                 CFG_ATTRIBUTE_NAME => Some(AttributeKind::Cfg),
                 DEPRECATED_ATTRIBUTE_NAME => Some(AttributeKind::Deprecated),
                 NAMESPACE_ATTRIBUTE_NAME => Some(AttributeKind::Namespace),
+                FALLBACK_ATTRIBUTE_NAME => Some(AttributeKind::Fallback),
                 _ => None,
             } {
                 match attrs_map.get_mut(&attr_kind) {