|
| 1 | +```text |
| 2 | +ACP: 25 |
| 3 | +Title: Virtual Machine Application Errors |
| 4 | +Author(s): Joshua Kim <https://github.com/joshua-kim> |
| 5 | +Discussions-To: https://github.com/avalanche-foundation/ACPs/discussions/26 |
| 6 | +Status: Proposed |
| 7 | +Track: Standards |
| 8 | +``` |
| 9 | + |
| 10 | +## Abstract |
| 11 | + |
| 12 | +Support a way for a Virtual Machine (VM) to signal application-defined error conditions to another VM. |
| 13 | + |
| 14 | +## Motivation |
| 15 | + |
| 16 | +VMs are able to build their own peer-to-peer application protocols using the `AppRequest`, `AppResponse`, and `AppGossip` primitives. |
| 17 | + |
| 18 | +`AppRequest` is a message type that requires a corresponding `AppResponse` to indicate a succesful response. In the unhappy path where an `AppRequest` is unable to be served, there currently is no native way for a peer to signal an error condition. VMs currently resort to timeouts in failure cases, where a client making a request will fallback to marking its request as failed after some timeout period has expired. |
| 19 | + |
| 20 | +Having a native application error type would offer a more powerful abstraction where Avalanche nodes would be able to score peers based on perceived errors. This is not currently possible because Avalanche networking isn't aware of the specific implementation details of the messages being delivered to VMs. A native application error type would also guarantee that all clients can potentially expect an `AppError` message to unblock an unsuccessful `AppRequest` and only rely on a timeout when absolutely necessary, significantly decreasing the latency for a client to unblock its request in the unhappy path. |
| 21 | + |
| 22 | +## Specification |
| 23 | + |
| 24 | +### Message |
| 25 | + |
| 26 | +This modifies the p2p specification by introducing a new [protobuf](https://protobuf.dev/) message type: |
| 27 | + |
| 28 | +``` |
| 29 | +message AppError { |
| 30 | + bytes chain_id = 1; |
| 31 | + uint32 request_id = 2; |
| 32 | + uint32 error_code = 3; |
| 33 | + string error_message = 4; |
| 34 | +} |
| 35 | +``` |
| 36 | + |
| 37 | +1. `chain_id`: Reserves field 1. Senders **must** use the same chain id of from the original `AppRequest` this `AppError` message is being sent in response to. |
| 38 | +2. `request_id`: Reserves field 2. Senders **must** use the same request id from the original `AppRequest` this `AppError` message is being sent in response to. |
| 39 | +3. `error_code`: Reserves field 3. Application defined error code. Implementations _should_ use the same error codes for the same conditions to allow clients to error match. Negative error codes are reserved for protocol defined errors. VMs may reserve any error code greater than zero. |
| 40 | +4. `error_message`: Reserves field 4. Application defined human-readable error message that _should not_ be used for error matching. For error matching, use `error_code`. |
| 41 | + |
| 42 | +### Reserved Errors |
| 43 | +The following error codes are currently reserved by the Avalanche protocol: |
| 44 | +| Error Code | Description | |
| 45 | +| ---------- | --------------- | |
| 46 | +| 0 | undefined | |
| 47 | +| -1 | network timeout | |
| 48 | + |
| 49 | +### Handling |
| 50 | + |
| 51 | +Clients **must** respond to an inbound `AppRequest` message with either a corresponding `AppResponse` to indicate a successful response, or an `AppError` to indicate an error condition by the requested `deadline` in the original `AppRequest`. |
| 52 | + |
| 53 | +## Backwards Compatibility |
| 54 | + |
| 55 | +This new message type requires a network activation to require either an `AppResponse` or an `AppError` as a required response to an `AppRequest`. |
| 56 | + |
| 57 | +## Reference Implementation |
| 58 | + |
| 59 | +- Message definition: https://github.com/ava-labs/avalanchego/pull/2111 |
| 60 | +- Handling: https://github.com/ava-labs/avalanchego/pull/2248 |
| 61 | + |
| 62 | +## Security Considerations |
| 63 | + |
| 64 | +Optional section that discusses the security implications/considerations relevant to the proposed change. |
| 65 | + |
| 66 | +Clients should be aware that peers can aribtrarily send `AppError` messages to invoke error handling logic in a VM. |
| 67 | + |
| 68 | +## Open Questions |
| 69 | + |
| 70 | +Optional section that lists any concerns that should be resolved prior to implementation. |
| 71 | + |
| 72 | +## Straw Poll |
| 73 | + |
| 74 | +Anyone can open a PR against an ACP and mark themselves as a supporter (you want an ACP to be adopted) or as an objector (you want the ACP to be rejected). This PR must include a message + signature indicating ownership of a given amount of $AVAX. |
| 75 | + |
| 76 | +### Supporters |
| 77 | + * `<message>/<signature>` |
| 78 | + |
| 79 | +### Objectors |
| 80 | + * `<message>/<signature>` |
| 81 | + |
| 82 | +## Copyright |
| 83 | + |
| 84 | +Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/). |
0 commit comments