dckc commented 7 months ago

There is a gap in our documentation on docs.agoric.com in that we don't sufficiently explain/walk-through how a developer is supposed to a) build a client UI and b) connect it to a smart contract they've build on the Agoric chain.

https://docs.agoric.com/guides/getting-started/contract-rpc.html exists but it's more conceptual and background context - which while important to the reader/developer isn't a step-by-step guide on how to actually build the client UI.

Dapp-offer-up is a functional example contract and client UI that our docs reference in 'Getting Started' section (https://docs.agoric.com/guides/getting-started/) of our docs and in the 'Smart Contract Basics' section (https://docs.agoric.com/guides/zoe/contract-walkthru.html). It stands to reason that it the 'how to build a client UI' guide uses same smart contract for continuity and consistency. It will be easier for the developer/reader to follow along.

This ticket tracks the effort to document the step-by-step process through which a developer builds client UI (using dapp offer up as an example) and connect it to the offer up smart contract for full end-to-end functionality.

Requirements:

Must reference dapp-offer-up contract and tie in with 'Getting Started' and 'Smart Contract Basics' such that it reads in a cohesive and easy-to-follow manner
Must include instructions around how to query an RPC node to get data from contract
Must reference utilization of UI components to simplify the UI building experience for developers
Must use UI Kit (if UI kit explainer is needed, this needs to be incorporated)
Must be written in step-by-step sequential format that is easy to follow

Acceptance Criteria:

To ensure the how-to guide achieves our goal of being easy-to-follow and digest for developers - we will request review of @kbennett2000 (and maybe others) to follow along to elicit feedback. Iterations may be needed in order for us learn and improve on this.
This will need to succeed before pushing to production docs.agoric.com

User Story: As a Developer I should be able to read the docs and get 2 things:

Understanding of how to build a Client UI and make it interact with my deployed smart contract
Get a repo/bundle of a sample Client UI that I could use to create my own Client

ui-kit and the basics of writing a dapp must be fully documented.

earlier idea:

reorg "Smart Wallet Dapp Architecture"?

### Tasks
- [ ] Sam to propose how-to page structure

dckc commented 6 months ago

the smart wallet architecture page has a bunch of details that are kinda abstracted by ui-kit

dckc commented 4 months ago

1035 is not merged.

otoole-brendan commented 4 months ago

Updated the ticket body with more context, approach and high level requirements. @samsiegart to provide how-to page structure based on his experience building client UIs.

dckc commented 4 months ago

The short "how to make an offer" video developed in https://github.com/Agoric/documentation/pull/976 seems worth keeping.

I'd like to see

one that goes from a blank create-react-app skeleton to making queries.
explainer-how-to-make-an-offer.md and its video... maybe update it a bit to flow from the 1st one?

samsiegart commented 3 months ago

@dckc I hadn't seen that make-an-offer page before, that's good stuff. We're planning a full tutorial-style thing with multiple pages, starting from:

Scaffold and harden the app (I'm going to use vite instead of CRA but similar deal)
Set up wallet connection and read purses
Use chainStorageWatcher to read the contract/vstorage
Use the wallet connection to make an offer and handle the updates (will look pretty much like that make-an-offer page, maybe will replace it).

Each section would walk through with code snippets and shell commands so the user can build along, link to relevant docs that explain the concepts/components as they come up, and we'd have different branches in dapp-offer-up to serve as checkpoints for each section, with the last checkpoint being pretty much identical to dapp-offer-up@main. WDYT?

dckc commented 3 months ago

@dckc ... We're planning ...

Scaffold and harden ...

Set up wallet connection and read purses

Use chainStorageWatcher to read the contract/vstorage

Use the wallet connection to make an offer ...

... WDYT?

yes, that's very close to what I had in mind.

meanwhile, note https://docs.agoric.com/guides/getting-started/explainer-how-to-make-an-offer.html landed.

dckc commented 3 months ago

oh... re wallet connection before chainStorageWatcher... that seems a little awkward: won't most dapps want to show some stuff from the chain before users connect their wallet?

samsiegart commented 3 months ago

oh... re wallet connection before chainStorageWatcher... that seems a little awkward: won't most dapps want to show some stuff from the chain before users connect their wallet?

That's true, we might want to switch the order of things. After the AgoricProvider is added, you can get the chainStorageWatcher without connecting to the wallet. It's easy enough to show that the dapp can load some stuff before the user clicks "connect" though.

dckc commented 3 months ago

Scaffold and harden the app (I'm going to use vite instead of CRA but similar deal)

ah... right.. dapp-offer-up started with vite

https://github.com/Agoric/dapp-offer-up/commit/716e95cff1aff11f90bfcdff53220d63130f64ce

Agoric / documentation

How to build a Client UI - document ui-kit #922

1035 is not merged.