Standardize errors

README.md

@@ -112,7 +112,7 @@ want to disable default initialization, then you can prohibit it like this:
 ```rust
 impl Default for StatusMessage {
     fn default() -> Self {
-        near_sdk::env::panic_str("Contract should be initialized before the usage.")
+        near_sdk::env::panic_err(near_sdk::errors::ContractNotInitialized{}.into())
     }
 }
 ```
@@ -154,7 +154,7 @@ pub fn my_method(&mut self) {
 
 pub fn my_method(&mut self ) {
     if near_sdk::env::current_account_id() != near_sdk::env::predecessor_account_id() {
-        near_sdk::env::panic_str("Method my_method is private");
+        near_sdk::env::panic_err(near_sdk::errors::PrivateMethod::new("my_method"));
     }
 ...
 }

examples/callback-results/src/lib.rs

@@ -1,5 +1,6 @@
-use near_sdk::require;
-use near_sdk::{env, near, Promise, PromiseError};
+use near_sdk::require_or_err;
+use near_sdk::{env, near, BaseError, Promise, PromiseError};
+use near_sdk::errors::{InvalidArgument, UnexpectedFailure, InvalidPromiseReturn};
 
 const A_VALUE: u8 = 8;
 
@@ -25,24 +26,28 @@ impl Callback {
 
     /// Returns a static string if fail is false, return
     #[private]
-    pub fn b(fail: bool) -> &'static str {
+    pub fn b(fail: bool) -> Result<&'static str, BaseError> {
         if fail {
-            env::panic_str("failed within function b");
+            return Err(UnexpectedFailure {
+                message: "Failed within function b".to_string(),
+            }
+            .into());
         }
-        "Some string"
+        Ok("Some string")
     }
 
     /// Panics if value is 0, returns the value passed in otherwise.
     #[private]
-    pub fn c(value: u8) -> u8 {
-        require!(value > 0, "Value must be positive");
-        value
+    pub fn c(value: u8) -> Result<u8, InvalidArgument> {
+        require_or_err!(value > 0, InvalidArgument::new("Value must be positive"));
+        Ok(value)
     }
 
     /// Panics if value is 0.
     #[private]
-    pub fn d(value: u8) {
-        require!(value > 0, "Value must be positive");
+    pub fn d(value: u8) -> Result<(), InvalidArgument> {
+        require_or_err!(value > 0, InvalidArgument::new("Value must be positive"));
+        Ok(())
     }
 
     /// Receives the callbacks from the other promises called.
@@ -52,12 +57,12 @@ impl Callback {
         #[callback_result] b: Result<String, PromiseError>,
         #[callback_result] c: Result<u8, PromiseError>,
         #[callback_result] d: Result<(), PromiseError>,
-    ) -> (bool, bool, bool) {
-        require!(a == A_VALUE, "Promise returned incorrect value");
+    ) -> Result<(bool, bool, bool), BaseError> {
+        require_or_err!(a == A_VALUE, InvalidPromiseReturn::new("Promise returned incorrect value"));
         if let Ok(s) = b.as_ref() {
-            require!(s == "Some string");
+            require_or_err!(s == "Some string");
         }
-        (b.is_err(), c.is_err(), d.is_err())
+        Ok((b.is_err(), c.is_err(), d.is_err()))
     }
 }
 

examples/cross-contract-calls/low-level/src/lib.rs

@@ -1,5 +1,6 @@
 use near_sdk::serde_json;
 use near_sdk::{env, near, require, Gas, NearToken, PromiseResult};
+use near_sdk::errors::PromiseFailed;
 
 // Prepaid gas for a single (not inclusive of recursion) `factorial` call.
 const FACTORIAL_CALL_GAS: Gas = Gas::from_tgas(20);
@@ -45,7 +46,7 @@ impl CrossContract {
         require!(env::promise_results_count() == 1);
         let cur = match env::promise_result(0) {
             PromiseResult::Successful(x) => serde_json::from_slice::<u32>(&x).unwrap(),
-            _ => env::panic_str("Promise with index 0 failed"),
+            _ => env::panic_err(PromiseFailed::new(Some(0), None).into()),
         };
         env::value_return(&serde_json::to_vec(&(cur * n)).unwrap());
     }

examples/error-handling/.cargo/config.toml

@@ -0,0 +1,5 @@
+[target.wasm32-unknown-unknown]
+rustflags = ["-C", "link-arg=-s"]
+
+[build]
+target-dir = "../../target"

examples/error-handling/Cargo.toml

@@ -0,0 +1,25 @@
+[package]
+name = "error-handling"
+version = "0.1.0"
+authors = ["Near Inc <[email protected]>"]
+edition = "2021"
+
+[lib]
+crate-type = ["cdylib"]
+
+[dependencies]
+near-sdk = { path = "../../near-sdk" }
+
+[dev-dependencies]
+near-workspaces = { version = "0.9.0", default-features = false, features = ["install"] }
+test-case = "2.0"
+tokio = { version = "1.14", features = ["full"] }
+anyhow = "1.0"
+
+[profile.release]
+codegen-units = 1
+# Tell `rustc` to optimize for small code size.
+opt-level = "z"
+lto = true
+debug = false
+panic = "abort"

examples/error-handling/README.md

@@ -0,0 +1,37 @@
+# error-handling
+
+cargo-near-new-project-description
+
+## How to Build Locally?
+
+Install [`cargo-near`](https://github.com/near/cargo-near) and run:
+
+```bash
+cargo near build
+```
+
+## How to Test Locally?
+
+```bash
+cargo test
+```
+
+## How to Deploy?
+
+Deployment is automated with GitHub Actions CI/CD pipeline.
+To deploy manually, install [`cargo-near`](https://github.com/near/cargo-near) and run:
+
+```bash
+cargo near deploy <account-id>
+```
+
+## Useful Links
+
+- [cargo-near](https://github.com/near/cargo-near) - NEAR smart contract development toolkit for Rust
+- [near CLI](https://near.cli.rs) - Interact with NEAR blockchain from command line
+- [NEAR Rust SDK Documentation](https://docs.near.org/sdk/rust/introduction)
+- [NEAR Documentation](https://docs.near.org)
+- [NEAR StackOverflow](https://stackoverflow.com/questions/tagged/nearprotocol)
+- [NEAR Discord](https://near.chat)
+- [NEAR Telegram Developers Community Group](https://t.me/neardev)
+- NEAR DevHub: [Telegram](https://t.me/neardevhub), [Twitter](https://twitter.com/neardevhub)

examples/error-handling/build.sh

@@ -0,0 +1,7 @@
+#!/bin/bash
+TARGET="${CARGO_TARGET_DIR:-../../target}"
+set -e
+cd "$(dirname $0)"
+
+cargo build --all --target wasm32-unknown-unknown --release
+cp $TARGET/wasm32-unknown-unknown/release/error_handling.wasm ./res/

examples/error-handling/src/lib.rs

@@ -0,0 +1,155 @@
+// Find all our documentation at https://docs.near.org
+use near_sdk::contract_error;
+use near_sdk::near;
+use near_sdk::BaseError;
+
+#[contract_error]
+pub enum MyErrorEnum {
+    X,
+}
+
+#[contract_error(sdk)]
+pub struct MyErrorStruct {
+    x: u32,
+}
+
+#[near(contract_state)]
+#[derive(Default)]
+pub struct Contract {
+    value: u32,
+}
+
+#[near]
+impl Contract {
+    #[init]
+    pub fn new() -> Self {
+        Self { value: 0 }
+    }
+
+    // Examples of RPC response for function call:
+    // is_error = false
+    // --- Result -------------------------
+    // 1
+    // ------------------------------------
+    // (changes value from 0 to 1)
+    //
+    // is_error = true
+    // Failed transaction
+    // Error:
+    // 0: Error: An error occurred during a `FunctionCall` Action, parameter is debug message.
+    // ExecutionError("Smart contract panicked: error in inc_handle_result")
+    // (does not change value)
+    #[handle_result]
+    pub fn inc_handle_result(&mut self, is_error: bool) -> Result<u32, &'static str> {
+        self.value += 1;
+        if is_error {
+            Err("error in inc_handle_result")
+        } else {
+            Ok(self.value)
+        }
+    }
+
+    // Examples of RPC response for function call:
+    // is_error = false
+    // --- Result -------------------------
+    // 2
+    // ------------------------------------
+    // (changes value from 1 to 2)
+    //
+    // is_error = true
+    // Failed transaction
+    // Error:
+    // 0: Error: An error occurred during a `FunctionCall` Action, parameter is debug message.
+    // ExecutionError("Smart contract panicked: {\"error\":{\"error_type\":\"error_handling::MyErrorEnum\",\"value\":\"X\"}}")
+    // (changes value from 2 to 3)
+    #[persist_on_error]
+    pub fn inc_persist_on_err(&mut self, is_error: bool) -> Result<u32, MyErrorEnum> {
+        self.value += 1;
+        if is_error {
+            Err(MyErrorEnum::X)
+        } else {
+            Ok(self.value)
+        }
+    }
+
+    // Examples of RPC response for function call:
+    // is_error = false
+    // --- Result -------------------------
+    // 4
+    // ------------------------------------
+    // (changes value from 3 to 4)
+    //
+    // is_error = true
+    // Failed transaction
+    // Error:
+    // 0: Error: An error occurred during a `FunctionCall` Action, parameter is debug message.
+    //  ExecutionError("Smart contract panicked: {\"error\":{\"error_type\":\"error_handling::MyErrorStruct\",\"value\":{\"x\":5}}}")
+    // (does not change value)
+    pub fn inc_just_result(&mut self, is_error: bool) -> Result<u32, MyErrorStruct> {
+        self.value += 1;
+        if is_error {
+            Err(MyErrorStruct { x: 5 })
+        } else {
+            Ok(self.value)
+        }
+    }
+
+    // Examples of RPC response for function call:
+    // is_error = false
+    // --- Result -------------------------
+    // 5
+    // ------------------------------------
+    // (changes value from 4 to 5)
+    //
+    // is_error = true
+    // Failed transaction
+    // Error:
+    // 0: Error: An error occurred during a `FunctionCall` Action, parameter is debug message.
+    //  ExecutionError("Smart contract panicked: Error")
+    // (does not change value)
+    pub fn inc_just_simple(&mut self, is_error: bool) -> u32 {
+        self.value += 1;
+        if is_error {
+            ::near_sdk::env::panic_str("Error");
+        } else {
+            self.value
+        }
+    }
+
+    // Examples of RPC response for function call:
+    // is_error = false
+    // --- Result -------------------------
+    // 6
+    // ------------------------------------
+    // (changes value from 5 to 6)
+    //
+    // is_error = true
+    // Failed transaction
+    // Error:
+    // 0: Error: An error occurred during a `FunctionCall` Action, parameter is debug message.
+    //  ExecutionError("Smart contract panicked: {\\\"error\\\":{\\\"cause\\\":{\\\"info\\\":{\\\"error\\\":{\\\"x\\\":5}},\\\"name\\\":\\\"near_sdk::utils::contract_error::BaseError\\\"},\\\"name\\\":\\\"CUSTOM_CONTRACT_ERROR\\\"}}")
+    // (does not change value)
+    pub fn inc_base_error(&mut self, is_error: bool) -> Result<u32, BaseError> {
+        self.value += 1;
+        if is_error {
+            Err(MyErrorStruct { x: 5 }.into())
+        } else {
+            Ok(self.value)
+        }
+    }
+
+    // Does not compile as u64 is not marked with contract_error
+    // > the trait `ContractErrorTrait` is not implemented for `u64`
+    // pub fn inc_incorrect_result_type(&mut self, is_error: bool) -> Result<u32, u64> {
+    //     self.value += 1;
+    //     if is_error {
+    //         Err(0)
+    //     } else {
+    //         Ok(self.value)
+    //     }
+    // }
+
+    pub fn get_value(&self) -> u32 {
+        self.value
+    }
+}

examples/error-handling/tests/test_basics.rs

@@ -0,0 +1,59 @@
+use near_sdk::serde_json;
+use near_workspaces::Contract;
+use serde_json::json;
+
+async fn get_value(contract: &Contract) -> anyhow::Result<u64> {
+    let get_value: serde_json::Value =
+        contract.call("get_value").args_json(json!({})).view().await?.json()?;
+
+    println!("get_value: {:?}", get_value);
+
+    get_value.as_u64().ok_or_else(|| anyhow::anyhow!("get_value is not a u64"))
+}
+
+async fn check_call(
+    contract: &Contract,
+    method: &str,
+    is_error: bool,
+    expected_value: u64,
+    expected_error: Option<String>,
+) {
+    let res = contract
+        .call(method)
+        .args_json(json!({ "is_error": is_error }))
+        .max_gas()
+        .transact()
+        .await
+        .unwrap();
+    if is_error {
+        assert!(res.is_failure());
+        if let Some(expected_error) = expected_error {
+            let string_error =
+                format!("{:?}", res.failures()[0].clone().into_result().unwrap_err());
+            assert_eq!(string_error, expected_error);
+        }
+    } else {
+        assert!(res.is_success());
+    }
+    assert_eq!(get_value(&contract).await.unwrap(), expected_value);
+}
+
+#[tokio::test]
+async fn test_error_handling() -> anyhow::Result<()> {
+    let worker = near_workspaces::sandbox().await?;
+    let contract =
+        worker.dev_deploy(&std::fs::read(format!("res/{}.wasm", "error_handling"))?).await?;
+
+    check_call(&contract, "inc_handle_result", false, 1, None).await;
+    check_call(&contract, "inc_persist_on_err", false, 2, None).await;
+    check_call(&contract, "inc_just_result", false, 3, None).await;
+    check_call(&contract, "inc_just_simple", false, 4, None).await;
+    check_call(&contract, "inc_base_error", false, 5, None).await;
+    check_call(&contract, "inc_handle_result", true, 5, None).await;
+    check_call(&contract, "inc_persist_on_err", true, 6, Some("Error { repr: Custom { kind: Execution, error: ActionError(ActionError { index: Some(0), kind: FunctionCallError(ExecutionError(\"Smart contract panicked: {\\\"error\\\":{\\\"cause\\\":{\\\"info\\\":\\\"X\\\",\\\"name\\\":\\\"error_handling::MyErrorEnum\\\"},\\\"name\\\":\\\"CUSTOM_CONTRACT_ERROR\\\"}}\")) }) } }".to_string())).await;
+    check_call(&contract, "inc_just_result", true, 6, Some("Error { repr: Custom { kind: Execution, error: ActionError(ActionError { index: Some(0), kind: FunctionCallError(ExecutionError(\"Smart contract panicked: {\\\"error\\\":{\\\"cause\\\":{\\\"info\\\":{\\\"x\\\":5},\\\"name\\\":\\\"error_handling::MyErrorStruct\\\"},\\\"name\\\":\\\"SDK_CONTRACT_ERROR\\\"}}\")) }) } }".to_string())).await;
+    check_call(&contract, "inc_base_error", true, 6, Some("Error { repr: Custom { kind: Execution, error: ActionError(ActionError { index: Some(0), kind: FunctionCallError(ExecutionError(\"Smart contract panicked: {\\\"error\\\":{\\\"cause\\\":{\\\"info\\\":{\\\"error\\\":{\\\"x\\\":5}},\\\"name\\\":\\\"near_sdk::utils::contract_error::BaseError\\\"},\\\"name\\\":\\\"CUSTOM_CONTRACT_ERROR\\\"}}\")) }) } }".to_string())).await;
+    check_call(&contract, "inc_just_simple", true, 6, None).await;
+
+    Ok(())
+}