Add JS usage examples for building and using contract specifications

[silence48]

Write some examples of using the contractspec in javascript along with an example contract sdk as an alternative to generated bindings.

This is for the bounty #605

[briwylde08]

Woop woop! Thanks again @silence48! We'll review and get back to you by 7/2 🌟

[Shaptic]

👏 👏 👏 this is great work, thank you! Left a first pass of comments below, mostly nits but some bigger things.

[Shaptic]

A line or two here to distinguish the functionality of ContractSpec vs. the functionality that scValToNative and nativeToScVal provides (with cross-references) would help clarify when/where/why each one should be used.

[Shaptic]

Still applicable

[Shaptic]

Call to action and/or cross-references on how to keep going from here would be awesome!

[silence48]

Call to action and/or cross-references on how to keep going from here would be awesome!

I wrote a guide on making a terminal user interface using JavaScript that uses one of these so called 'contractSDK's i describe in this doc. I will add a link to it here.

[Shaptic]

^ still applies!

[briwylde08]

Hey @silence48! Want to double-check, have you implemented the changes and is this one ready again?

[silence48]

Hey @silence48! Want to double-check, have you implemented the changes and is this one ready again?

The changes have been implemented. However... I regret to say I'm not sure how useful this guide is.

In the SDK we can now instantiate a contract client and it automatically loads and parses the spec.

This guide will still be useful for teaching people more of the underlying mechanisms I guess.

[Shaptic]

@silence48 I do still think it's useful for people to gain an understanding of what's going on under the hood! I'll review the new version asap (prob tomorrow morning) 🙏

[ElliotFriend]

Make sure you remove this line, when you're ready to "publish." You can also remove the hide_table_of_contents: true line, if you want. For most of the simpler guides, there's not really much gained by having the TOC, but in these more in-depth ones, it could definitely be useful.

Aside: If you do want the TOC displayed on the side of the page, you may get better results by decreasing your indentations by a level or two. Your Guide: Work with ... heading could actually be an h1 (like # Guide: Work with ...), and then Introduction could start the h2 headings (like ## Introduction). I forget exactly what level it is, but docusaurus will only add up to h3 or h4 (I think?) to the TOC by default.

[Shaptic]

Pretty close to being ready I think!

[Shaptic]

It'd be good to relate this to non-Stellar developers by referencing the Solidity ABI here!

[Shaptic]

Suggestion:

Suggested change

	### Guide: Work with ContractSpecs in JavaScript
	### Guide: Work with Contract Specifications in JavaScript

[Shaptic]

Still applicable

[Shaptic]

You can/should grab xdr from the SDK itself

Suggested change

	import { xdr } from "@stellar/stellar-base";
	import { Spec } from "@stellar/stellar-sdk";
	import { xdr, Spec } from "@stellar/stellar-sdk";

[chadoh]

Spec needs to be imported from the contract entrypoint:

Suggested change

	import { xdr } from "@stellar/stellar-base";
	import { Spec } from "@stellar/stellar-sdk";
	import { xdr } from "@stellar/stellar-sdk";
	import { Spec } from "@stellar/stellar-sdk/contract";

...or used from the contract import:

Suggested change

	import { xdr } from "@stellar/stellar-base";
	import { Spec } from "@stellar/stellar-sdk";
	import { xdr, contract } from "@stellar/stellar-sdk";
	// later, can use `contract.Spec` instead of just `Spec`

[Shaptic]

Suggested change

	There are a few options to get your contract Spec object to work with in javascript. The Spec is constructed from a (xdr.ScSpecEntry)[https://github.com/stellar/js-stellar-base/blob/5efdff0b2a78ed842f7463340b4ff23eb4370635/xdr/curr/Stellar-contract-spec.x#L228]
	There are a few options to get your contract `Spec` object to work with in JavaScript. The `Spec` is constructed from an (xdr.ScSpecEntry)[https://github.com/stellar/js-stellar-base/blob/5efdff0b2a78ed842f7463340b4ff23eb4370635/xdr/curr/Stellar-contract-spec.x#L228]

[Shaptic]

Instead of making it a standalone CLI tool, you could just incorporate it into the next step as a code-only step.

[Shaptic]

easy javascript
?

[Shaptic]

It'd be good to mention here that I'm pretty sure that this is what the Client does (cc @chadoh?) when you use the bindings!

[Shaptic]

Isn't this a repeat of the prior section?

[Shaptic]

^ still applies!

[briwylde08]

Hi @silence48! I'm going to turn these three PRs in the draft form for now. Let me know if you'd like to close them or maybe we can collaborate to get them across the finish line!