stellar / laboratory

laboratory

The Stellar Laboratory is a suite of tools to help one learn about exploring the Stellar network. See it in action: https://laboratory.stellar.org/.

Developing

yarn start

Testing hardware wallets requires an HTTPS connection to enable U2F. The recommended way to do this is with ngrok. Once downloaded and authenticated, start ngrok, and tell the laboratory to start with a public URL.

./ngrok http 3000
# in a separate terminal
# the subdomain will appear in ngrok's output
yarn start --public randomsubdomain.ngrok.io

Building for production

yarn build

To build a production docker image using a clean docker build environment:

make docker-build
# or directly with docker
docker build -t lab:localbuild .

To build and run production build locally:

yarn production
# or
yarn prod:build
yarn prod:serve

Production uses Amplitude to emit metrics, so to fully emulate a production build, you'll need to set an AMPLITUDE_API_KEY variable in /public/settings/env-config.js file.

Internal documentation

The docs.md file contains code documentation on the laboratory. The docs.md is only relevant for developing the laboratory.

laboratory's Issues

Fix Orderbook details

It builds the urls incorrectly with just alphanum as the asset type whereas it should be credit_alphanum4 (or 12).

Allow curly brackets in Picker inputs

In the uri template code, we wanted to insert something like '/ledgers/{ledger}/operations' back in. However, the library that we use automatically escapes curly brackets.

To simplify the code dealing with uri templates unescaping, none of the pickers support curly brackets. We won't be spending time on adding curly brackets support in.

For those that for some reason REALLY want curly bracket support in the laboratory pickers, then they can submit a PR to allow for this (and also improve the uri template unescaping story.

output area for tx blob

after user hits build button. tx blob should be shown here

Framework that will hold the 4 sections

Endpoint Raw JSON view

dynamically generated JS code

As user is changing the operations above. This view of the js code required to generate the tx should update.

Required fields and messaging around it

We need some way of notifying that fields are optional or required.

To specify this, we want to only label optional fields as optional. This is to try and encourage the user to play with more fields.

However, it may be confusing to a use who can't figure out why they can't submit the form. The solution should be:

• Submit button is always available.
• If the user clicks Submit when there are required fields that aren't filled in, they get a message in each of the require fields that are missing saying "This is a required field".

I prefer to have a simple message "This is a required field" since it is easier to manage one message.

Routing

I started implementing the routing system for the laboratory and realized that I
need more specifics on what exactly we should implement.

These options are not comprehensive but I've tried to consider the different
cases possible and routes we could go.

1. Url naming

Trivial but important. We need to pick what we want the URL to look like.\

Option 1a: We could either go with abbreviated

Endpoint Explorer: https://www.stellar.org/laboratory/#/explorer
Transaction Builder: https://www.stellar.org/laboratory/#/txbuilder
Transaction Signer: https://www.stellar.org/laboratory/#/txsigner

Option 1b: Things fully spelled out

Endpoint Explorer: https://www.stellar.org/laboratory/#/endpoint-explorer
Transaction Builder: https://www.stellar.org/laboratory/#/transaction-builder
Transaction Signer: https://www.stellar.org/laboratory/#/transaction-signer

2. How much information do we want to keep in the url.

For now, I think it might be better to just go with option 2a and spend development
time on other more useful features. In the future, we can move onto 2b if we have
extra dev time.

Option 2a: Minimal

Just have three different possibilities: one for each page:

Example: https://www.stellar.org/laboratory/#/endpoint-explorer

Option 2b: Selective

Store main 2nd level navigation data in the url. For the transaction signer, it
can be the xdr of the transaction. It will only work for the signer though
because the state in the transaction builder may not always be serializable into
a valid xdr blob.

Examples:

https://www.stellar.org/laboratory/#/endpoint-explorer/transactions-for-account
https://www.stellar.org/laboratory/#/transaction-signer/AAAAAGXNhLrhGtltTwCpmqlarh7s1DB2hIkbP//jgzn4Fos/AAAAZAAAAA0AABGHAAAAAAAAAAAAAAABAAAAAAAAAAAAAAAAuocnFfCNi6J2JIoh8FDH1VL8SsVmqAF48W4x9q7kHScAAAAXSHboAAAAAAAAAAAB+BaLPwAAAECWmdSLKo7fSoAwMxnYrQzUiZt8BfCoB/4HoxXnjHo3DkKyZoqJi27phVVbmF98Le6hCzD5t56Y7W6zxj8wvdQL

Option 2c: Full serialization of store of the current page

This option would keep the full serialized state of the specific page in the url.
I think option 2c is not necessary to be displayed on the url at all times as it
would bloat the url and would be overwhelming.

I do see a use case where one can click a share button to build a url with the
serialized state in query params. Then once the link is visited, the query parts
would disappear.

Example:

https://www.stellar.org/laboratory/#/endpoint-explorer/order-book-details?selling_asset_type=native&buying_asset_type=credit_alphanum4&buying_asset_code=KELP&buying_asset_issuer=GBKELPXG2FLP2IBICXY6AZPR64YLBYA3C2OI2W2JPCHS7ZUQ6CLLX5XR

Option 2d: Full serialization of the whole app's store

This will hold EVERYTHING in the url.

3. Landing page

Option 3a: Automatically start at endpoint explorer

Would we have a landing page when none of the pages are selected?

Option 3b: Create a new landing page

The landing page would include a quick intro of the laboratory, and links to
other resources such as the developers site or tutorials that use the laboratory.

Option 3c: Integrate into developers site

This option would eliminate the branding of the laboratory.

Support streaming for the endpoints

Transaction fee isn't optional

Can you replace "(optional)" with "(100 per operation)"

Site url [fragment] routing

Implement the system for updating the url from hash and also changing the page when the hash is there.

Improve setOptions operation bitmask picker

Right now, they're just positive number pickers.

Ideally, they'd be checkboxes that show the result

Fix endpoint horizon error message display

The blue bar should not be showing.

/order_book?

uses alphanumeric on order book example

Documentation uses credit_alphanum4

https://www.stellar.org/developers/horizon/reference/orderbook-details.html

Create keys

Add signature form

Add time bounds to Transaction Builder attributes

Endpoint picker

Set parameters of tx

• source account
• time bounds
• fee
• sequence #
• memo (select type, input based on type)

Add submit transaction endpoint

Form shouldn't clear when you go from tx build to exploration and back

Browsersync watch not working

When I use gulp develop and make changes, it's detecting changes but not telling the browser to reload.

Configure webpack to ignore images in solar css

Right now, if there is a url(), webpack tries to resolve it and unsuccessfully does so causing a crash.

Import tx blob

Parameter forms for all the endpoints

• All Accounts
• Account Details
• All Effects
• Effects for Account
• Effects for Ledger
• Effects for Operation
• Effects for Transaction
• All Ledgers
• Ledger Details
• Offers for Account
• All Operations
• Operations for Account
• Operations for Ledger
• Operations for Transaction
• Operation Details
• Orderbook Details
• All Payments
• Payments for Account
• Payments for Ledger
• Payments for Transaction
• Trades for Orderbook
• All Transactions
• Post Transaction
• Transactions for Account
• Transactions for Ledger
• Transaction Details

Build one functional Endpoint Parameter Selector

Build the first endpoint selector to be later refactored to be able to handle all the endpoints

This issue will be considered done when the endpoint parameter selector can build a url

Figure how we are going to link into a filled out example in the explorer

Types of links we need to support:

• horizon endpoint with parameters
• tx blob for the builder
• tx blob for signing

Add segment tracking so we can see which pages are most visited and where we can improve

Routing is probably a prerequisite. This has to be designed in a way that it does not leak sensitive data.

Refactor ParametersFormComponents

I am currently stuck on building the TransactionBuilder because the ParametersFormComponents are too tightly bound to the EndpointStore.

I propose:

1. Combining asset types into one item (instead of either 2 or 3, depending on how the ExplorerStore does the logic).
2. Limit all communication outside this form component to just simple props and update callbacks. No event handlers (that is the responsibility of the parent component).
3. Consumers of these components can set an error prop to these components. If the component has an error, it will override the error prop.
4. Create a composite component that acts as a proxy to these individual components so that we don't have to repeat a big map like this: https://github.com/stellar/laboratory/blob/txbuilder/src/components/EndpointSetup.js#L64

Overview

There are three main layers and each layer can have their own errors

1. External errors: usually from a store; such as validation requiring interaction between elements
2. Composition level: Errors common to all components such as required ifeld
3. Individual form: Specific errors without needing external info.

composition component (name is TODO)

Example usage (just an example)

let type = 'source_account';
let error = 'This is a required field';
let required = true;

let updateCB = function() { }

<CompositionComponent type={type} error={error} initialValue={} onUpdate={updateCB} required={required} />

Errors

Component starts in a pristine state. Once onUpdate callback has been called at least once, the composition component will go into a dirty state. In the dirty state, it may pass down the This is a required field.

If no errors from this level, inherit errors from above (pane).

Individual form component

• Does not know about store or even app panes. The only thing it talks to is the composition component.

props change

If this.props.initialValue changes, then this will overwrite the state in the inputs

Input change

When input changes, it calls onUpdate with new input

Errors

It handles validation of the values (like valid strKey address). If no errors from this level, inherit errors from above (composition component).

Transaction Builder: Button to fetch next sequence number for account

For this item:

Link from output tx_blob to the signing section

Display errors in the parameter selection form

Import tx blob

Display tree view of txblob in signing section

toggle between testnet and live

Display resulting tx_blob after signature is added

/paths in explorer

Support for now cursor

Fund Address with friend bot

Validation of parameters in parameter selection

Build URL from parameter form

Dynamic Endpoint URL

Needs to change based on the parameters people are selecting

Handle parameters in the URL to bring us to a specific place in the Explorer

add operation button

reorder operations with drag and drop

Allow them to reorder the list of operations.

'?' popup for more info

Implement HTML of parameter selection

Add stuff to solar if and when necessary

Set parameters of each operation

• Create Account
• Payment
• Path Payment
• Manage Offer
• Create Passive Offer
• Set Options
• Change Trust
• Allow Trust
• Account Merge
• Inflation

"Transaction Fee" should tell them it is in stroops

Prompt to doublecheck if user really wants to leave

This should only be for some pages where there is a lot of data being built

https://stackoverflow.com/questions/1119289/how-to-show-the-are-you-sure-you-want-to-navigate-away-from-this-page-when-ch