doc: major rework of trin book, focused on intro/quickstart #1556
Conversation
book/src/concepts/use_cases.md
Outdated
| There are situations where Trin is estimated to not be a good node choice: | ||
| - Very speedy historical state access. It's possible to retrieve old state, but don't expect sub-second contract reads on state as viewed from a historical block. | ||
| - Building blocks locally, as a block producer. Random access to the full state and transaction pool is not supported at the speed needed to build competitive blocks. | ||
| - We remain hopeful that in the future, you could use an externally-generated block (like one provided by MEV-boost) so that you can act as a validater using a standard Consensus client, with Trin as the Execution client. This probably depends on a future where state witnesses are bundled with the block sent to you by the producer. |
There was a problem hiding this comment.
| - We remain hopeful that in the future, you could use an externally-generated block (like one provided by MEV-boost) so that you can act as a validater using a standard Consensus client, with Trin as the Execution client. This probably depends on a future where state witnesses are bundled with the block sent to you by the producer. | |
| - Using [Trin Execution](https://github.com/ethereum/trin/blob/master/trin-execution/README.md), an Execution client, which uses Trin to enable EIP-4444's well-maintaining access to Ethereum's full history for running a validator or a full node. |
I am a bit confused what this is trying to convey. I don't think Trin is going to implement the engine API. This use case seems more like the grounds of Trin Execution. Even then Trin Execution would have the full head state so well someone could use externally-generated block it wouldn't be needed.
I don't understand the current paragraph because if future where state witnesses are bundled with the block, then the CL might as well just use an EVM library so I am not sure I see the value Trin would be providing here. I think the EL usecase is covered by Trin Execution and integrating this functionality into the Trin binary would be substracting from the value Trin provides and also would add unnecessary complexity.
There was a problem hiding this comment.
I don't think
Trinis going to implement the engine API. This use case seems more like the grounds ofTrin Execution
From a user's perspective, I think we want trin to be the entry point that then launches whatever modules need to be launched to accomplish the goal that's being asked of it, including serving the engine API via block execution.
Since this is all future speculation, and framed as such in the book, I don't think we need to have perfect consensus here. We can update the book, as our understanding grows.
I don't understand the current paragraph because if
future where state witnesses are bundled with the block, then the CL might as well just use an EVM library
That seems a plausible direction for some CLs to go, for verifying blocks being sent from other proposers. But if it's your slot to propose, I doubt that all CL clients are going to get rid of the engine calls altogether. I don't think they want to get in the business of requesting the MEV-boost block and verifying it. (open to hearing from them, though!)
Depending on the direction of research, your local client may select some transactions to append onto prebuilt blocks. I don't think the CL wants to get into that either.
So I still think there's room for us to aim at serving the engine API for stakers.
There was a problem hiding this comment.
I don't think
Trinis going to implement the engine API. This use case seems more like the grounds ofTrin ExecutionFrom a user's perspective, I think we want
trinto be the entry point that then launches whatever modules need to be launched to accomplish the goal that's being asked of it, including serving the engine API via block execution.
I want to eventually spin Trin Execution outside of Trin and EF Portal and have it built and maintained by an independent team from Trin. Maybe changing Trin Execution's name would be beneficial to differentiate the projects and prevent confusion. This has been my aspirations from the start of building Trin Execution. If Trin Execution was spun-out I would want to be the lead for the Trin-Execution team.
I think it would be best to focus Trin on being the best Portal client it can be. Well the idea of an everything app could be cool, often having "everything" dilutes the UX of a project. A jack of all trades is a master of none. It is hard to make something very good at something if it tries to do everything. I think Trin's win condition is being integrated into every app under the sun. Trin being written in Rust makes it a prime candidate to do that. Trin being a clean, extendible, performant implementation of Portal. Most people using Trin shouldn't know that they are using it. If Trin is the default Portal implementation developers look to integrate, then Trin will spread faster than our small team can imagine. Trin's main audience should be app developers, not direct users of the Trin binary. As for 99% of the market what they want is a one click app where you don't have to know how to use it.
I think we should discuss what the future of Trin Execution will be during Devcon.
There was a problem hiding this comment.
Cool yeah, let's chat in person. Lot's of interesting future plans to consider.
| @@ -1,6 +1,6 @@ | |||
| # Users | |||
| # Use Cases | |||
There was a problem hiding this comment.
book/src/users/README.md and book/src/concepts/use_cases.md seem to be duplicate pages maybe we could hyperlink to the other one if needed instead of duplicating everything.
There was a problem hiding this comment.
Hah, yeah, just a copy that was supposed to be a move. They are identical (and one of them wasn't linked in the index), so I will delete that one.
book/src/concepts/use_cases.md
Outdated
|
|
||
| Trin is not currently configured to run on mobile, however this is plausibly | ||
| a viable and interesting use case for the future. A trin node could run as a | ||
| background task with configurable limits on disk, CPU and bandwidth use. |
There was a problem hiding this comment.
I am not sure if background task's like mentioned here are possible on mobile without running custom OS's or rooted/jailbroken OS's.
Realistically the usecase would be Trin could only be ran well the the app Trin was embedded in is running. For example Trin being embedded into a mobile app, but Trin wouldn't be able to make requests in the background due to Mobile OS restrictions put in place to save battery life.
There was a problem hiding this comment.
Yeah, this is another one I didn't really take a pass at, besides pointing out that it's for the future. I agree it could use more of a touch-up though 👍🏻
book/src/concepts/use_cases.md
Outdated
| A user has a laptop that frequently is turned off. When | ||
| they want to transact, they can turn on Trin and connect their | ||
| wallet to it. | ||
|
|
||
| *Benefit*: Wallet use without reliance on third party wallet APIs. |
There was a problem hiding this comment.
| A user has a laptop that frequently is turned off. When | |
| they want to transact, they can turn on Trin and connect their | |
| wallet to it. | |
| *Benefit*: Wallet use without reliance on third party wallet APIs. | |
| Traditionally it hasn't be reasonable to run on fullnode and access Ethereum Protocol on laptops due to | |
| - storage | |
| - bandwidth | |
| - battery life | |
| - long sync times | |
| requirements. If a user was to restart there computer and wanted to send a transaction they would need to wait hours. Portal solves this by using minimal storage, battery life, bandwidth, and Portal also has instant sync times. | |
| *Benefit*: Wallet use without reliance on third party wallet APIs. |
I don't think my suggestion is perfect by any means, but I think this use case is missing why running fullnodes doesn't work and how Portal is solving a problem. These examples assume the user knows a lot of information about Ethereum and it's problems, I think Trin is targeting a much wider audience so assuming this knowledge isn't reasnable
There was a problem hiding this comment.
Right, I didn't actually update this particular section at all. I was more focused on the intro/quickstart stuff. Sorry for how the page copy made that unclear.
I do think it's nice to have a page dedicated to punchy user stories that doesn't re-hash the overall benefits. But also it looks like we're missing a page that dives into the overall benefits. I'll throw a new page in, but I'll consider it out of scope for this PR to get it super polished.
carver
changed the title
There was a problem hiding this comment.
overall the PR looks good, it is a big improvement over what we previously! Well I do have an issue with the one section #1556 (comment) I don't think that blocks this PR and can be discussed at Devcon.
| expose `trace_`* or` debug_`* endpoints. | ||
| - Very speedy historical state access. It's possible to retrieve old state, but don't expect sub-second contract reads on state as viewed from a historical block. | ||
| - Building blocks locally, as a block producer. Random access to the full state and transaction pool is not supported at the speed needed to build competitive blocks. | ||
| - We remain hopeful that in the future, you could use an externally-generated block (like one provided by MEV-boost) so that you can act as a validater using a standard Consensus client, with Trin as the Execution client. This probably depends on a future where state witnesses are bundled with the block sent to you by the producer. |
There was a problem hiding this comment.
I think the PR is good to merge, I am just pointing out here that I would like to discuss the future of Trin Execution during Devcon as I outlined here #1556 (comment).
So I do disagree with Trin as the Execution client, but I don't think that disagreement should block this PR from being merged and we can discuss that issue at Devcon.
book/src/users/startup.md
Outdated
| ## All flags | ||
|
|
||
| Below is the current list of command line flags. | ||
|
|
||
| Note that CLI flags may change over time, so run `trin --help` to get the most up-to-date information. | ||
|
|
||
| ```text | ||
| Usage: trin [OPTIONS] [COMMAND] | ||
|
|
||
| Commands: | ||
| create-dashboard | ||
| help Print this message or the help of the given subcommand(s) | ||
|
|
||
| Options: | ||
| --web3-transport <WEB3_TRANSPORT> |
There was a problem hiding this comment.
Oh one last thing I would prefer if this was it's own page so it is more findable named something like Commandline options. As normally I wouldn't expect these to be in the startup page, but that is just my preference we don't need to make that change in this PR. This is definitely better than nothing.
There was a problem hiding this comment.
I feel mixed about it, but I'll try it this way. I liked the idea of having all of the flag-related content on one page. But we clearly have different preferences here, and the book should ideally serve both reading styles.
You want to be thrown into the deep end of reading all possible flags at once. I want an opinionated guide that cuts straight to the couple of flags that are most important to know about. So yeah, separate pages with a top-of-page links to the other is probably the best way to facilitate both wants.
Introduction is more focused on first-time users. It pushes back some of the conceptual stuff, tries to explain several things more clearly, and updates some stale info. Also, it adds an overall Portal benefits page. It's just a rough first stab, to have something in place to update as we move forward.
Introduction is more focused on first-time users. It pushes back some of the conceptual stuff, tries to explain several things more clearly, and updates some stale info.
TODO:
-houtput (with note that it may be out of date)