Skip to content

Commit

Permalink
[Utility] Create trustless_relay_validation.md (#938)
Browse files Browse the repository at this point in the history
## Description

Add diagrams to describe validations done on trustless relays. Part of
work on #918

## Issue

Fixes #918 

## Type of change

Please mark the relevant option(s):

- [ ] New feature, functionality or library
- [ ] Bug fix
- [ ] Code health or cleanup
- [ ] Major breaking change
- [X] Documentation
- [ ] Other <!-- add details here if it a different type of change -->

## List of changes

- Add a new markdown file to show trustless relay validations.

## Testing

- [ ] `make develop_test`; if any code changes were made
- [ ] `make test_e2e` on [k8s
LocalNet](https://github.com/pokt-network/pocket/blob/main/build/localnet/README.md);
if any code changes were made
- [ ] `e2e-devnet-test` passes tests on
[DevNet](https://pocketnetwork.notion.site/How-to-DevNet-ff1598f27efe44c09f34e2aa0051f0dd);
if any code was changed
- [ ] [Docker Compose
LocalNet](https://github.com/pokt-network/pocket/blob/main/docs/development/README.md);
if any major functionality was changed or introduced
- [ ] [k8s
LocalNet](https://github.com/pokt-network/pocket/blob/main/build/localnet/README.md);
if any infrastructure or configuration changes were made

## Required Checklist

- [x] I have performed a self-review of my own code
- [ ] I have commented my code, particularly in hard-to-understand areas
- [ ] I have added, or updated, [`godoc` format
comments](https://go.dev/blog/godoc) on touched members (see:
[tip.golang.org/doc/comment](https://tip.golang.org/doc/comment))
- [ ] I have tested my changes using the available tooling
- [ ] I have updated the corresponding CHANGELOG

### If Applicable Checklist

- [ ] I have updated the corresponding README(s); local and/or global
- [ ] I have added tests that prove my fix is effective or that my
feature works
- [ ] I have added, or updated,
[mermaid.js](https://mermaid-js.github.io) diagrams in the corresponding
README(s)
- [ ] I have added, or updated, documentation and
[mermaid.js](https://mermaid-js.github.io) diagrams in `shared/docs/*`
if I updated `shared/*`README(s)
  • Loading branch information
adshmh authored and red-0ne committed Aug 2, 2023
1 parent d3bf0ad commit c903ca1
Show file tree
Hide file tree
Showing 2 changed files with 75 additions and 0 deletions.
2 changes: 2 additions & 0 deletions utility/doc/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,8 @@ And implement the basic transaction functionality:
- Pause
- Unpause

And implement [the trustless relay validation and execution](TRUSTLESS_RELAY_VALIDATION.md)

Added governance params:

- BlocksPerSessionParamName
Expand Down
73 changes: 73 additions & 0 deletions utility/doc/TRUSTLESS_RELAY_VALIDATION.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,73 @@
# Validation of Trustless Relays

- [A. Client-side Relay Validation](#a-client-side-relay-validation)
- [B. Server-side Relay Validation](#b-server-side-relay-validation)

## A. Client-side Relay Validation

When an application requests to send a trustless relay, the CLI performs several checks on the relay before sending it to the specified servicer.
The following diagram lists all these checks with links to the corresponding code secion (or an issue if the check is not implemented yet).

```mermaid
---
title: Client-side Relay Validation
---
graph TD
app_key{<b><a href='https://github.com/pokt-network/pocket/blob/bfc57eb89907932831b5730c68a09b4656c420c2/app/client/cli/servicer.go#L91'>Validate app key</a></b>}
session{<b><a href='https://github.com/pokt-network/pocket/blob/bfc57eb89907932831b5730c68a09b4656c420c2/app/client/cli/servicer.go#L163'>Validate the Session</a></b>}
servicer{<b><a href='https://github.com/pokt-network/pocket/blob/bfc57eb89907932831b5730c68a09b4656c420c2/app/client/cli/servicer.go#L133'>Validate the Servicer</a></b>}
payload{<b><a href='https://github.com/pokt-network/pocket/blob/f41039b42ce628f73afe27b7f7b6111cca085cf0/app/client/cli/servicer.go#L191'>Deserialize Payload</a></b>}
relay{<b><a href='https://github.com/pokt-network/pocket/issues/943'>Validate relay contents</a></b>}
send[<b><a href='https://github.com/pokt-network/pocket/blob/f41039b42ce628f73afe27b7f7b6111cca085cf0/app/client/cli/servicer.go#L177'>Send Trustless Relay to the provided Servicer</a></b>]
user_err[Return error to user]
app_key-->|Failure| user_err
session-->|Failure| user_err
servicer-->|Failure| user_err
payload-->|Failure| user_err
relay-->|Failure| user_err
app_key-->|Success| session
session-->|Success| servicer
servicer-->|Success| payload
payload-->|Success| relay
relay-->|Success| send
```

## B. Server-side Relay Validation

Once a trustless relay has been received on the server side, i.e. by the servicer, several validations are performed on the relay.
The following diagram outlines all these checks along with links to the corresponding section of the code (or to an issue if the check has not been implemented yet)

```mermaid
---
title: Server-side Relay Validation
---
graph TD
deserialize{<b><a href='https://github.com/pokt-network/pocket/blob/f41039b42ce628f73afe27b7f7b6111cca085cf0/rpc/handlers.go#L85'>Deserialize Relay Payload</a></b>}
meta{<b><a href='https://github.com/pokt-network/pocket/blob/f41039b42ce628f73afe27b7f7b6111cca085cf0/utility/servicer/module.go#L210'>Validate Relay Meta</a></b>}
chain_support{<b><a href='https://github.com/pokt-network/pocket/blob/f41039b42ce628f73afe27b7f7b6111cca085cf0/utility/servicer/module.go#L221'>Validate chain support</a></b>}
session{<b><a href='https://github.com/pokt-network/pocket/blob/f41039b42ce628f73afe27b7f7b6111cca085cf0/utility/servicer/module.go#L378'>Validate the Session</a></b>}
height{<b><a href='https://github.com/pokt-network/pocket/blob/f41039b42ce628f73afe27b7f7b6111cca085cf0/utility/servicer/module.go#L496'>Validate Relay Height</a></b>}
servicer{<b><a href='https://github.com/pokt-network/pocket/blob/f41039b42ce628f73afe27b7f7b6111cca085cf0/utility/servicer/module.go#L332'>Validate Servicer</a></b>}
mine_relay{<b><a href='https://github.com/pokt-network/pocket/blob/f41039b42ce628f73afe27b7f7b6111cca085cf0/utility/servicer/module.go#L254'>Validate the app rate limit</a></b>}
execute[<b><a href='https://github.com/pokt-network/pocket/blob/f41039b42ce628f73afe27b7f7b6111cca085cf0/utility/servicer/module.go#L191'>Execute the Relay</a></b>]
client_err[Return error to client]
deserialize-->|Failure| client_err
meta-->|Failure| client_err
chain_support-->|Failure| client_err
session-->|Failure| client_err
height-->|Failure| client_err
servicer-->|Failure| client_err
mine_relay-->|Failure| client_err
deserialize-->|Success| meta
meta-->|Success| chain_support
chain_support-->|Success| session
session-->|Success| height
height-->|Success| servicer
servicer-->|Success| mine_relay
mine_relay-->|Success| execute
```
<!-- GITHUB_WIKI: utility/trustless_relay -->

0 comments on commit c903ca1

Please sign in to comment.