Skip to content

Commit

Permalink
Scrub Soroban "Status" terminology, it has been "Error" for a while.
Browse files Browse the repository at this point in the history
  • Loading branch information
graydon committed Dec 20, 2024
1 parent 82508de commit 382b313
Show file tree
Hide file tree
Showing 5 changed files with 17 additions and 17 deletions.
4 changes: 2 additions & 2 deletions docs/build/guides/conventions/error-enum.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -34,8 +34,8 @@ impl Contract {
}
```

When converted to XDR, the value becomes an `ScVal`, containing a `ScStatus`, containing the integer value of the error as contract error.
When converted to XDR, the value becomes an `ScVal`, containing a `ScError`, containing the integer value of the error as contract error.

```json
{ "status": { "contractError": 1 } }
{ "error": { "contractError": 1 } }
```
18 changes: 9 additions & 9 deletions docs/build/smart-contracts/example-contracts/errors.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -59,15 +59,15 @@ count: U32(2)
count: U32(3)
count: U32(4)
count: U32(5)
Status(ContractError(1))
contract call invocation resulted in error Status(ContractError(1))
Error(ContractError(1))
contract call invocation resulted in error Error(ContractError(1))
test test::test ... ok
thread 'test::test_panic' panicked at 'called `Result::unwrap()` on an `Err` value: HostError
Value: Status(ContractError(1))
Value: Error(ContractError(1))
Debug events (newest first):
0: "Status(ContractError(1))"
0: "Error(ContractError(1))"
1: "count: U32(5)"
2: "count: U32(4)"
3: "count: U32(3)"
Expand Down Expand Up @@ -219,7 +219,7 @@ fn test() {
}

#[test]
#[should_panic(expected = "Status(ContractError(1))")]
#[should_panic(expected = "Error(ContractError(1))")]
#E3256B
fn test_panic() {
let env = Env::default();
Expand Down Expand Up @@ -257,7 +257,7 @@ Two functions are generated for every contract function, one that returns a `Res

### `try_increment`

In the first test the `try_increment` function is called and returns `Result<Result<u32, _>, Result<Error, Status>>`.
In the first test the `try_increment` function is called and returns `Result<Result<u32, _>, Result<Error, InvokeError>>`.

```rust
assert_eq!(client.try_increment(), Ok(Ok(5)));
Expand All @@ -268,13 +268,13 @@ assert_eq!(client.try_increment(), Err(Ok(Error::LimitReached)));

- If the function call is successful but returns a value that is not a `u32`, `Ok(Err(_))` is returned.

- If the function call is unsuccessful, `Err(Ok(Error))` is returned.
- If the function call is unsuccessful and fails with an error in the `Error` enum, `Err(Ok(Error))` is returned.

- If the function call is unsuccessful but returns an error code not in the `Error` enum, or returns a system error code, `Err(Err(Status))` is returned and the `Status` can be inspected.
- If the function call is unsuccessful but returns an error code not in the `Error` enum, or returns a system error code, `Err(Err(InvokeError))` is returned and the `InvokeError` can be inspected.

### `increment`

In the second test the `increment` function is called and returns `u32`. When the last call is made the function panicks.
In the second test the `increment` function is called and returns `u32`. When the last call is made the function panics.

```rust
assert_eq!(client.increment(), 5);
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -16,8 +16,8 @@ sidebar_position: 5

Contracts are invoked through a pair of host functions `call` and `try_call`:

- `try_call(contract, function, args)` calls `function` exported from `contract`, passing `args` and returning a `Status` on any error.
- `call(contract, function, args)` just calls `try_call` with its arguments and traps on `Status`, essentially propagating the error.
- `try_call(contract, function, args)` calls `function` exported from `contract`, passing `args` and returning a `Error` on any error.
- `call(contract, function, args)` just calls `try_call` with its arguments and traps on `Error`, essentially propagating the error.

In both cases `contract` is a `Binary` host object containing the contract ID, `function` is a `Symbol` holding the name of an exported function to call, and `args` is a `Vector` of values to pass as arguments.

Expand Down
2 changes: 1 addition & 1 deletion docs/learn/encyclopedia/errors-and-debugging/debugging.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -53,4 +53,4 @@ While we encourage most testing to happen in local-testing mode, some problems w

- A "sandbox" host with a mock-ledger that can read and write `CONTRACT_DATA` ledger entries to the local filesystem.
- A general logging system that allows contracts to log values of the [shared host/guest "value" type](../contract-development/environment-concepts.mdx), even in production.
- User-extensible `Status` codes that can be returned from any contract call to indicate problems.
- User-extensible `Error` codes that can be returned from any contract call to indicate problems.
6 changes: 3 additions & 3 deletions docs/learn/encyclopedia/errors-and-debugging/errors.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ The [errors example] demonstrates how to define your own error types.

## Error Enums

Errors are a special type of enum integer type that are stored on ledger as `Status` values containing a `u32` code.
Errors are a special type of enum integer type that are stored on ledger as `Error` values containing a `u32` code.

```rust
#[contracterror]
Expand All @@ -39,8 +39,8 @@ pub enum Error {
}
```

When converted to XDR, the value becomes an `ScVal`, containing a `ScStatus`, containing the integer value of the error as contract error.
When converted to XDR, the value becomes an `ScVal`, containing a `ScError`, containing the integer value of the error as contract error.

```json
{ "status": { "contractError": 1 } }
{ "error": { "contractError": 1 } }
```

0 comments on commit 382b313

Please sign in to comment.