docs: update getting-started and remove examples #477

ntn-x2 · 2022-02-18T09:54:26Z

Getting started update

Provides an overall refresh of the getting started guide, by using the new syntax as in #473, as this PR is based on top of that. It also removes the docs/example.ts file which seemed like a useless repetition of the getting started.

This PR fixes https://github.com/KILTprotocol/ticket/issues/1825.

rflechtner

Very nice! Finally it's a readable and useful document again. Just a few questions.

docs/getting-started.ts

rflechtner · 2022-02-22T15:40:47Z

docs/getting-started.md

-3. Install typescript with `yarn add typescript`
-4. Make a new file, e.g. `touch getting-started.ts`
-5. Execute the file with `npx ts-node getting-started.ts`
+To run the script at any point during this guide, just run `npx ts-node getting-started.ts`.


Would require npx right? We could simply tell people to also add ts-node to their dependencies, in which case you can run yarn ts-node getting-started.ts

rflechtner · 2022-02-22T15:42:26Z

docs/getting-started.md

-   If you don't do this, certain operations like account generation could fail with the notice that "the WASM interface has not been initialized".
-2. Set essential configurations, most importantly the endpoint of the KILT node to which you'll want to connect for actions that read or write to blockchain state.
-   These operations would throw an error if called before an endpoint has been set.
+   If this step is skipped, certain operations like account generation could fail with the error "the WASM interface has not been initialized".


if you want to be precise, sr25519 crypto will not work.

rflechtner · 2022-02-22T15:45:38Z

docs/getting-started.md

-console.log(claimerLightDid.did)
-```
+Before being used in credentials, CTypes must be stored on the KILT blockchain.
+To do so, an on-chain DID is required for the entity willing to write CType on chain.


article missing

rflechtner · 2022-02-22T15:51:17Z

docs/getting-started.md


-The message can be encrypted with the keystore and keys as follows:
+As sender identity and message validity are also checked during decryption, if the decryption process completes successfully, the attester can assume that the sender of the message is also the owner of the claim, as the two identities match.


The last part is something we are about to change, right? So maybe we shouldnt advertise it at this point.

Good point -> cf7198f

rflechtner · 2022-02-22T15:53:27Z

docs/getting-started.md

 }
 ```

-The Attester creates the attestation based on the IRequestForAttestation object she received:
+Then, after verifying the validity of the claims in the request for attestation, the attester builds an attestation.


Unclear it that's a technical process or the attester's job. In any case we should indicate that there is a moment of judgement by the attester.

rflechtner · 2022-02-22T15:57:00Z

docs/getting-started.md

+const selectedCredential = await credential.createPresentation({
+  // Hide the `age` property, and only reveal the `name` one.
  selectedAttributes: ['name'],
  signer: keystore,
  claimerDid: claimerLightDid,
 })


this does allow for a challenge AFAIK

rflechtner · 2022-02-22T16:00:15Z

docs/getting-started.md

+const requestForCredentialMessage = new Kilt.Message(
+  {
+    type: Kilt.Message.BodyType.REQUEST_CREDENTIAL,
+    content: {
+      cTypes: [
+        { cTypeHash: ctype.hash, trustedAttesters: [attesterFullDid.did] },
+      ],
+    },
+  },


For some reason this comment didn't make it... I was asking if we don't allow for a challenge on the request, or have some other challenge procedure for verification at this point?

Dudleyneedham

LGTM, minor changes

Dudleyneedham · 2022-02-23T09:09:00Z

docs/getting-started.md

-   If you don't do this, certain operations like account generation could fail with the notice that "the WASM interface has not been initialized".
-2. Set essential configurations, most importantly the endpoint of the KILT node to which you'll want to connect for actions that read or write to blockchain state.
-   These operations would throw an error if called before an endpoint has been set.
+   If this step is skipped, certain operations like account generation using some algorithms, e.g., Sr25519, could fail with the error "the WASM interface has not been initialized".


Suggested change

If this step is skipped, certain operations like account generation using some algorithms, e.g., Sr25519, could fail with the error "the WASM interface has not been initialized".

If this step is skipped, certain operations such as using some algorithms to generate accounts, e.g., Sr25519, could fail with the error "the WASM interface has not been initialized".

Dudleyneedham · 2022-02-23T09:12:03Z

docs/getting-started.md

-2. Set essential configurations, most importantly the endpoint of the KILT node to which you'll want to connect for actions that read or write to blockchain state.
-   These operations would throw an error if called before an endpoint has been set.
+   If this step is skipped, certain operations like account generation using some algorithms, e.g., Sr25519, could fail with the error "the WASM interface has not been initialized".
+2. Set essential configurations, most importantly the address of the KILT node to connect to for anything that interacts with the KILT blockchain.


Suggested change

2. Set essential configurations, most importantly the address of the KILT node to connect to for anything that interacts with the KILT blockchain.

2. Set essential configurations, most importantly the address of the KILT node to connect to interact with the KILT blockchain.

Dudleyneedham · 2022-02-23T09:14:24Z

docs/getting-started.md

+// Keyring is required to generate KILT accounts.
+const keyring = new Kilt.Utils.Keyring({
+  ss58Format: 38,
+  type: 'ed25519',


We should have a comment here about the sr25519 requiring the cryptoWaitReady.

Dudleyneedham · 2022-02-23T09:15:57Z

docs/getting-started.md

-```
-
-Or by setting a default address in the configuration, connecting implicitly.
+// Keyring is required to generate KILT accounts.


Suggested change

// Keyring is required to generate KILT accounts.

// Keyring is required to generate KILT accounts.

// If you are using `srr25519` to generate KILT accounts, the `cryptoWaitReady` must be called beforehand.

Dudleyneedham · 2022-02-23T09:21:16Z

docs/getting-started.md


 ```typescript
-const tx = await ctype.getStoreTx()
+/* The attester signs the ctype creation transaction resulting from calling `ctype.store()` with its DID. */


We should indicate that if you are not using a local chain, it is best practice to check if the CType is stored on chain

Dudleyneedham

LGTM

ntn-x2 added 📝 documentation chore: documentation ✋on hold status: on hold labels Feb 18, 2022

ntn-x2 self-assigned this Feb 18, 2022

Base automatically changed from aa-did-batches to develop February 22, 2022 14:16

ntn-x2 added 8 commits February 22, 2022 15:38

docs: fix getting-started

45691db

docs: fix example.ts compilation

8967a37

wip: fixing getting-started to properly run

c2fd618

docs: getting-started.ts working from start to end

e3dd244

chore: get rid of examples in GitHub actions

e647cef

docs: getting-started refactored

f873d3d

chore: prettier for getting-started.md

9cd22c4

chore: last fixes

99aa619

ntn-x2 force-pushed the aa-fix-docs branch from dd7cfcc to 99aa619 Compare February 22, 2022 14:52

ntn-x2 marked this pull request as ready for review February 22, 2022 15:06

ntn-x2 requested review from rflechtner and tjwelde February 22, 2022 15:06

ntn-x2 removed the ✋on hold status: on hold label Feb 22, 2022

ntn-x2 requested a review from Dudleyneedham February 22, 2022 15:25

ntn-x2 force-pushed the aa-fix-docs branch from 636fec2 to 99aa619 Compare February 22, 2022 15:35

rflechtner reviewed Feb 22, 2022

View reviewed changes

ntn-x2 added 6 commits February 23, 2022 07:38

chore: replace npx with yarn

5fc34d7

chore: add example of crypto operation failing

ed0eb5b

chore: add missing article

af86a15

chore: remove piece about checks during decryption

cf7198f

chore: clarify checks performed by the attester

ae82e04

chore: add challenge to presentation

8cd592e

Dudleyneedham requested changes Feb 23, 2022

View reviewed changes

ntn-x2 added 2 commits February 23, 2022 13:23

chore: apply feedback as suggested by @Skedley

6a74796

fix: revert dev account to using Ed25519

758f660

Dudleyneedham approved these changes Feb 23, 2022

View reviewed changes

ntn-x2 merged commit 5a4b5c5 into develop Feb 23, 2022

ntn-x2 deleted the aa-fix-docs branch February 23, 2022 13:24

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: update getting-started and remove examples #477

docs: update getting-started and remove examples #477

ntn-x2 commented Feb 18, 2022

rflechtner left a comment

rflechtner Feb 22, 2022

ntn-x2 Feb 23, 2022

rflechtner Feb 22, 2022

ntn-x2 Feb 23, 2022

rflechtner Feb 22, 2022

ntn-x2 Feb 23, 2022

rflechtner Feb 22, 2022

ntn-x2 Feb 23, 2022

rflechtner Feb 22, 2022

ntn-x2 Feb 23, 2022

rflechtner Feb 22, 2022

rflechtner Feb 22, 2022

ntn-x2 Feb 23, 2022

Dudleyneedham left a comment

Dudleyneedham Feb 23, 2022

Dudleyneedham Feb 23, 2022

Dudleyneedham Feb 23, 2022

Dudleyneedham Feb 23, 2022

Dudleyneedham Feb 23, 2022

Dudleyneedham left a comment


		The message can be encrypted with the keystore and keys as follows:
		As sender identity and message validity are also checked during decryption, if the decryption process completes successfully, the attester can assume that the sender of the message is also the owner of the claim, as the two identities match.

	If this step is skipped, certain operations like account generation using some algorithms, e.g., Sr25519, could fail with the error "the WASM interface has not been initialized".
	If this step is skipped, certain operations such as using some algorithms to generate accounts, e.g., Sr25519, could fail with the error "the WASM interface has not been initialized".

	2. Set essential configurations, most importantly the address of the KILT node to connect to for anything that interacts with the KILT blockchain.
	2. Set essential configurations, most importantly the address of the KILT node to connect to interact with the KILT blockchain.

	// Keyring is required to generate KILT accounts.
	// Keyring is required to generate KILT accounts.
	// If you are using `srr25519` to generate KILT accounts, the `cryptoWaitReady` must be called beforehand.

docs: update getting-started and remove examples #477

docs: update getting-started and remove examples #477

Conversation

ntn-x2 commented Feb 18, 2022

Getting started update

rflechtner left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Dudleyneedham left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Dudleyneedham left a comment

Choose a reason for hiding this comment