Add sentinel errors in go-perun, perun-node and use error codes in User API.

[manoranjith]

Motivation / Context

Among the errors returned by the perun-node,

1. Some errors are related to an external system such as "error in connecting to blockchain node" or "disconnected from blockchain node", that can be rectified by the user. These errors are currently not distinguished by perun node.
2. Some errors from go-perun such as "channel propposal/channel update rejected by peer" are identified by checking for a specific phrase in the error message returned by go-perun.

These errors should be identified and the user of the API should be able to differentiate between different category of errors: Protocol errors, External system errors (that can be fixed by user), Perun-node internal errors etc.,

Description

• [x] Identify a list of errors that should be declared as sentinel errors in go-perun.
• [x] Define an error code scheme, that can differentiate between different categories of errors as described in the motivation section. The following set of 4 steps can be repeated for each of the methods.
  • Make the relevant changes for the errors that can be identified in perun-node.
  • Discuss and make the relevant changes for the errors that need to be identified in in go-perun.
  • Use the sentinel errors to return proper error messages with appropriate error code in the SessionAPI and ChannelAPI.
  • Update the error and error code definition in the API spec.

List of APIs (to track the ones that are completed):

• [x] Node.OpenSesssion
• [x] Session.AddPeerID
• [x] Session.GetPeerID
• [x] Session.OpenPaymentChannel
• [x] Session.GetPaymentChannelsInfo
• [x] Session.SubscribeToPaymentChannelProposals
• [x] Session.UnsubscribeFromPaymentChannelProposals
• [x] Session.RespondToPaymentChannelProposals
• [x] Session.Close
• [x] Channnel.SendUpdate
• [x] Channel.SubscribeToPaymentChannelUpdates
• [x] Channel.UnsubscribeFromPaymentChannelUpdates
• [x] Channel.RespondToPaymentChannelUpdates
• [x] Channel.GetPaymentChannelInfo
• [x] Channel.Close

Relates to

Testing

• All errors relevant to the user are organized in proper error categories and are assigned proper error codes.

Thread Safety

• NA -

[manoranjith]

Collecting info on information that needs to be added to error messages:

1. In Error message returned when the timeout expires when waiting for an on-chain transaction to be confirmed, the transaction ID should be included, so that user can manually check the status of the transaction using other system. Currently (as shown below), only a message is printed.

   could not execute transaction: context deadline exceeded

[anagha-ks]

2. If there is no sufficient balance in user's account when trying to send the amount to the peer, then the returned error should have a message that is insufficient balance in account to pay. (Specify current balance amount along with the error message to inform the user?)

[anagha-ks]

3. Peer went offline or if peer not responding to a user's request.

[anagha-ks]

4. Channel proposal or channel update rejection by the peer.

[anagha-ks]

5. Channels not closed error message - If trying to close the session without closing the channels. Channel IDs that are to be closed should be included so that user can close those particular channels before closing the session.

[anagha-ks]

6. Trying to pay an invalid currency - this can be handled by specifying all the perun-node supported currencies in the error message.

[anagha-ks]

7. No active subscription found for some requests - may be suggest the subscriptions available for that particular request.

[anagha-ks]

8. Already subscribed error message when trying to subscribe the already existing subscription - include subscription ID in the error message.

[anagha-ks]

9. Validate contract returns an error message if there is invalid contracts at given address. Here if we return the address also with the error message, then user can see what is there at the given address and update accordingly.

[manoranjith]

@anagha-ks, among the listed scenarios, I have reacted +1 to the ones that I also think need to be added. I have questions regarding points 7 and 8. As far as I understand the current design of subscriptions, there seems to be no subscription ID as such. The client has to subscribe and that context to receive the notifications. In case of the current reference implementation (gRPC in golang), the messages are received by running a thread in background that calls a function which blocks until a new notification is received. If the client has unsubscribed, it is upto the client to close this thread.

• In case of 7, where there is no active subscription, the user has to just create a new subscription using the relevant API and may not need any additional information to do that.
• In case of 8, there is no subscription ID. If the client side software has no idea of the existing subscription, it can just unsubscribe and subscribe again. This IMO should be fine because the subscription is designed to be consumed only by a single user throughout the lifecycle of the channel and it will be the responsibility of this client side software to manage the routines or functions receiving the subscription messages throughout the lifetime of the channel.

So I am not sure, if we can return the possible subscriptions or subscription ID ?

[manoranjith]

I have tried to categorize the errors into 5 groups based on what impact they could have and how they should be handled. Errors returned by each API will fall into one of these categories.

Category	Explanation	Handling
Participant	Caused by one of the channel participants not acting as per protocol	Agree with peer outside of the system
Client	Caused by the request from client. Could be error in arguments or the configuration provided by the client to access external systems.	Use valid arguments, provide correct configuration to access external systems or fix the external systems; and retry.
Protocol Fatal	Protocol aborted due to unexpected failure in external system. Could result in loss of funds.	Requires manual inspection of the error
Internal	Caused due to an error in the node.	Requires manual inspection of the error

Below tables contains the different errors in each category. Additional info is fields in the error response that will contain data required for handling the error as key value pairs. The keys are predefined for each error. In case, the program is allowed to define additional custom keys, it is indicated by adding [additional-allowed].

Category	Code	Error	Additional Info
Participant	101	Peer Response Timedout	Peer alias, response timeout
Participant	102	Rejected by peer	Peer alias, reason
Participant	103	Peer did not fund the channel in time	Peer alias, Funding timeout
Participant	104	User response timeout expired	Expiry Unix Time
Client	201	Resource not found	Resource type, value
Client	202	Resource already exists	Resource type, value
Client	203	Invalid arguments	Argument name, value, reason
Client	204	Failed Pre-condition	Reason, [additional-allowed]
Client	205	Invalid configuration	Configuration name, value, required condition
Client	206	Blockchain node not reachable	Address, Timeout
Client	207	Invalid contracts	Contract Type, Contract Address
Protocol Fatal	301	Protocol aborted due to tx timeout	Tx type, Tx ID, Tx Timeout
Protocol Fatal	302	Protocol aborted as blockchain node disconnected	Tx type, Tx ID, Blockchain Node Addr
Internal	401	Unknown internal error	Nil
Internal	402	Off-chain communication error	Nil

Requesting feedback on this classification.

Update on 5.5.2021:

1. Removed 2 protocol errors (insufficient balance for tx and insufficient funds for funding). Because in both these cases, the transaction will not mined. From the current implementation of the framework, it will interpreted as transaction timed out error.
2. Renamed 206 "Blockchain node not reachable" to "Cannot connect to chain". This error represents connection error when initializing the node or a session.

[manoranjith]

Below, I listed the errors returned by each API by classifying them into one of the above categories. The first column Src contains where the error has to identified and defined as a sentinel error. N -> Node (perun-node) and F -> Framework (go-perun)

Additional info <> indicates it's i value identifying a particular entity or resource and will be filled in by the software when creating the error.

1. Node.GetConfig (No error)

2. Node.OpenSession

   Src	Code	Error message	Additional Info
   N	205	Invalid session configuration	Config name, config value, Required condition
   N	206	Blockchain node not reachable	Address, Timeout
   N	207	Invalid contracts found at given address	Contract type, contract address

3. Node.Time (No error)

4. Node.Help (No error)

5. Session.AddContact

   Src	Code	Error message	Additional Info
   N	201	Unknown Session ID	Type: Session, Value:
   N	202	Peer ID already present under same alias	Type: PeerAlias, Value:
   N	203	Peer Alias used by another peer id	Name: PeerAlias, Value: <>, Reason: Used for another peer id.
   N	203	Invalid off-chain address	Name: Offchain Address, Value: <>, Reason: <>

6. Session.GetContact

   Src	Code	Error message	Additional Info
   N	201	Unknown Session ID	Type: Session, Value:
   N	201	Unknown Peer alias	Type: PeerAlias, Value:

7. Session.OpenPaymentChannel

   Src	Code	Error message	Additional Info
   N	201	Unknown Session ID	Type: Session, Value:
   N	201	Peer alias not found in ID provider	Type: PeerAlias, Value:
   N	203	Invalid Amount	Name: Amount, Value: <>, Reason: <>
   N	204	Invalid Currency	Name: Currency, Value: <>, Reason: Supported currencies are
   F	101	Peer did not respond to channel proposal	Peer alias, response timeout
   F	102	Peer rejected the channel proposal	Peer alias, reason
   F	103	Peer did not fund the channel in time	Peer alias, funding timeout
   F:heavy_check_mark:	301	Funding transaction timedout	Tx Type: Funding, Tx ID: <>, Sender Addr: <>
   F	302	Insufficient funds for funding tx	Tx Type: Funding, Tx ID: <>, Sender Addr: <>
   F	303	Blockchain node disconnected during funding tx	Tx Type: Funding, Tx ID: <>, Blockchain Node Addr <>
   F	304	Insufficient balance for user

8. Session.GetPaymentChannelsInfo

   Src	Code	Error message	Additional Info
   N	201	Unknown Session ID	Type: Session, Value:

9. Session.SubscribeToPaymentChannelProposals

   Src	Code	Error message	Additional Info
   N	201	Unknown Session ID	Type: Session, Value:
   N	202	Subscription already exists	Type: ChProposalSub, Value:

10. Session.UnsubsubscribeFromPayChProposals

    Src	Code	Error message	Additional Info
    N	201	Unknown Session ID	Type: Session, Value:
    N	201	No Active subscription	Type: ChProposalSub, Value:

11. Session.RespondToPayChProposal

    Src	Code	Error message	Additional Info
    N	201	Unknown Session ID	Type: Session, Value:
    N	201	Unknown Proposal ID	Type: Proposal, Value:
    N	104	User response timeout expired	ExpiryUnixTimeStamp: <>
    F	402	Response not acknowledged by peer
    F	103	Peer did not fund the channel in time	Peer alias, funding timeout
    F :heavy_check_mark:	301	Funding transaction timedout	Tx Type: Funding, Tx ID: <>, Sender Addr: <>
    F	302	Insufficient funds for funding tx	Tx Type: Funding, Tx ID: <>, Sender Addr: <>
    F	303	Blockchain node disconnected during funding tx	Tx Type: Funding, Tx ID: <>, Blockchain Node Addr <>
    F	304	Insufficient balance for user

12. Session.Close

    Src	Code	Error message	Additional Info
    N	201	Unknown Session ID	Type: Session, Value:
    N	204	Failed Pre-condition	Reason: Session has open channels, OpenChannels:

13. Channel.SendUpdate

    Src	Code	Error message	Additional Info
    N	201	Unknown Session ID	Type: Session, Value:
    N	201	Unknown Channel ID	Type: Channel, Value:
    N	201	Peer Alias not a participant in this channel	Type: PeerAlias, Value:
    N	203	Invalid Amount	Name: Amount, Value: <>, Reason: <>
    N	204	Invalid Currency	Name: Currency, Value: <>, Reason: Supported currencies are
    F	101	Peer did not respond to channel update	Peer alias, response timeout
    F	102	Peer rejected the channel update	Peer alias, reason

14. Channel.SubscribeToPaymentChannelUpdates

    Src	Code	Error message	Additional Info
    N	201	Unknown Session ID	Type: Session, Value:
    N	201	Unknown Channel ID	Type: Channel, Value:
    N	202	Subscription already exists	Type: ChUpdateSub, Value:

15. Channel.UnsubsubscribeFromPayChUpdates

    Src	Code	Error message	Additional Info
    N	201	Unknown Session ID	Type: Session, Value:
    N	201	Unknown Channel ID	Type: Channel, Value:
    N	201	No Active subscription	Type: ChUpdateSub, Value:

    16. Channel.RespondToPayChUpdates

    Src	Code	Error message	Additional Info
    N	201	Unknown Session ID	Type: Session, Value:
    N	201	Unknown Channel ID	Type: Channel, Value:
    N	201	Unknown Update ID	Type: Update, Value:
    N	104	User response timeout expired	ExpiryUnixTimeStamp: <>
    F	402	Response not acknowledged by peer

16. Channel.GetPayChInfo

    Src	Code	Error message	Additional Info
    N	201	Unknown Session ID	Type: Session, Value:
    N	201	Unknown Channel ID	Type: Channel, Value:

17. Channel.Close

    Src	Code	Error message	Additional Info
    N	201	Unknown Session ID	Type: Session, Value:
    N	201	Unknown Channel ID	Type: Channel, Value:
    F	301	Finalizing transaction timedout	Tx Type: Register, Tx ID: <>, Sender Addr: <>
    F	302	Insufficient funds for finalizing tx	Tx Type: Register, Tx ID: <>, Sender Addr: <>
    F	303	Blockchain node disconnected during finalizing tx	Tx Type: Register, Tx ID: <>, Blockchain Node Addr <>
    F	301	Withdrawing transaction timedout	Tx Type: Withdraw, Tx ID: <>, Sender Addr: <>
    F	302	Insufficient funds for withdrawing tx	Tx Type: Withdraw, Tx ID: <>, Sender Addr: <>
    F	303	Blockchain node disconnected during withdrawing tx	Tx Type: Withdraw, Tx ID: <>, Blockchain Node Addr <>

[manoranjith]

@choeppler @danielksan81 @anagha-ks As discussed in the weekly call, I have updated the error classification to reflect the following changes, (For previous version, see the older revisions of the comment by clicking on edited button in the comment header)

1. Merge the external safe error category into client error category . Because in both these cases, the source of error is the client request. The error could be in the requests itself (invalid arguments) or in the configuration provided by the client to access the external system. To fix this error which the user has to fix and retry the request.
2. Rename external unsafe to protocol fatal error, because the term is more descriptive.
3. Since we have one category lesser than previous, I have updated the error codes as well.

[manoranjith]

Also, to provide a context on the basis for the above classification.

1. The classification into categories is done based on how the error should handled by the client.
2. The classification further into specific errors is done based on what data fields will be required in the additional info field. Very rarely (only one case so far: 204 Failed Pre-condition), are additional fields optional allowed. In all other cases, they keys are fixed and it makes parsing on data easier on the client side independent of the programming language.

[manoranjith]

Looking into the code of go-perun framework, I noticed that some of the sentinel errors have already been defined. I am marking those with a :heavy_check_mark: after the F.

[manoranjith]

Re-opening the issue as the specification in the proposals repo needs to be updated and documentation needs to added for the API.