Feedback for Hello World and Vesting examples, willing to PR

[mpizenberg]

Thanks a lot for the examples! This combined with blockfrost free tier makes it very approachable to start programming for Cardano. After doing these two examples, I've some feedback regarding issues and possible improvements.

Hello World

In this first tutorial, a lot of things are covered, I think a bit too much. It touches on:

• aiken
• typescript
• lucid
• cardano scan
• faucet

For someone new to aiken and not fluent in JS/TS there is a lot of info. Considering there is even more TS than aiken, I'd suggest splitting this example in two. A first example would help familiarize with the setup. So that could be doing a transaction between two addresses. It would be very similar, except the core of the TS would just be this chunk:

const tx = await lucid.newTx()
  .payToAddress("addr..", {lovelace: 40000000n})
  .complete();
const signedTx = await tx.sign().complete();
const txHash = await signedTx.submit();

This first example would introduce the faucet, lucid on typescript and cardano scan. Then, building on that, the Hello World! example would introduce the aiken part. It would also have the advantage that we would already have two addresses ready to be used in the Vesting example. As otherwise, during the vesting example, one either have to do a second faucet call, or figure this transfer thing on their own between the original owner and the receiver, for the receiver to have enough funds to trigger the vesting script.

Alright that's just a general feedback. Then there is the specific issue than currently, aiken new creates a validators/hello.ak validator which is positioned first in the list of validators in the built plutus.json, resulting in the locking JS code to pick the wrong validator. It wants the hello_world.ak one, not the hello.ak one. So we either need to change the aiken new command to not produce that file, or the adapt the hello world example.

Vesting example

I've noted the following issues in the vesting example.

1. There is an error "found an unexpected token: 'and'" due to the update in Aiken v1.0.14 changing the and and or syntax to use curly braces instead of being function calls.
2. In the deno ... commands of the page, it is missing the --allow-env part to be able to load the blockfrost key from the evironment.
3. The lower_bound and now names in the contract are confusing. Especially because it's calling lower_bound the thing that is not extracted from the transaction lower_bound time. I'd suggest something like:

   Finite(tx_earliest_time) -> lock_expiration_time <= tx_earliest_time

[mpizenberg]

Let me know what you think. I'm willing to PR the vesting example changes.

[AgustinBadi]

Regarding what you mentioned about the tutorial, I agree that there's a lot of TypeScript to understand all at once, which will be suitable for more experienced users but more challenging to others. Personally, I didn't use Lucid to build the transaction, but rather cardano-cli (bash scripts), which obviously isn't suitable for production but works great for quick tests and is much more accessible for new users. In fact, in the Gimbalabs course, Aiken's lessons have been taught using this approach. Additionally, some may prefer to perform the transaction using Mesh. Considering the above, rather than splitting the tutorial and forcing the reader to use just Lucid, maybe it would be better to include in the section (where the transaction is being built) various collapsible buttons with different options. For example, having a button to build it with Lucid, another button for building with cardano-cli and bash scripting, and so on. This way, regardless of your background, you can build the transaction the way you prefer. I have the bash scripts and would be happy to share them and help if it's decided to go with this approach.

[mpizenberg]

@AgustinBadi multiple options for the transaction building part would be awesome indeed. That's more maintenance work though so that's to be taken into account. I was having a look at PyCardano that seems like it could be another option too.

I think I still believe it's worth splitting into a first example just to get used to the tooling you choose. Whether it is cardano-cli, lucid, mesh, PyCardano, etc.

[AgustinBadi]

Good point, probably having at least a few options would be enough. Anyway, that was just an observation about the splitting suggestion in the post, not the rest. Great to see that you went through the documentation and sent corrections.

[rvcas]

cc @mpizenberg @KtorZ

Although the vesting example tries to build on the hello world example, I don't think we should actually have any of the examples aware of each other. For that kind of thing I would say we can have a new "Learn/Tutorial" section in the side bar which progressively builds knowledge. I think what you're saying makes sense and that we should do something like that. I think we should clean the current examples up to make sure they make zero mention of other examples and then design a new and improved learn/tutorial section. The reason being is because I would like to be able to use the examples to show off all kinds of different/unrelated use cases with various off-chain stacks. So far the examples have used deno but the main tutorial should probably just use something more common like node.

In regards to aiken new we should just say in the example using a callout that is should be deleted

Ex:

Make sure to delete the autogenerated hello.ak file

Addressing Vesting Example Section

There is an error "found an unexpected token: 'and'" due to the update in Aiken v1.0.14 changing the and and or syntax to use curly braces instead of being function calls.

Good catch we should update that. PR is welcome

In the deno ... commands of the page, it is missing the --allow-env part to be able to load the blockfrost key from the evironment.

Also good catch we should update that. PR is welcome

The lower_bound and now names in the contract are confusing. Especially because it's calling lower_bound the thing that is not extracted from the transaction lower_bound time

The interval stuff tends to be confusing in general. We're happy to have that improved in this example.

[KtorZ]

About the Hello, World! tutorial, that's a fair point. I am thinking that perhaps, we could indeed simplify the Hello, World to simply run a test that would show a trace Hello, World!. It would teach people the basics of the command line and some tips for troubleshooting (perhaps we can introduce the ? operator right there and suggest one or two exercises to do on top).

Then, have another tutorial that takes most of the validation code but build the off-chain part using Lucid, and possibly some other library from the ecosystem. We could do PyCardano (Python) and BloxBean (Java) to cover a wider range and show how Aiken can truly interop with multiple off-chain language. That might force us to get moving on the off-chain blueprint code generation which is a good thing.

PS: I am also going to get rid of that hello.ak in the validator. We removed that in the past already and put stuff in the README.md instead. Boilerplate like this is confusing and breaks tutorial, and that's something you ALWAYS get rid of (especially that one since it isn't even compatible with Hello, World tutorial).

[rvcas]

@KtorZ sorry about that I added it back because I noticed most or all programming languages have some minimal code that gets added but I'm fine with not having it. I was just copying what I saw elsewhere.

[KtorZ]

No harm done. But never do it again 😈

And yes, I've been both schools; some puts some boilerplate, some don't. It's often the case that frameworks do it but not languages. Aiken is kind of half way between both I guess. If we came up with something meaningful or, if there was truly something to scaffold (eg a rails app), then why not. But at present, putting code for the sake of putting code is superfluous.

Anyway, main points are: we probably need to ease even more the hello world tutorial to make the entry even smoother. I am all down for that.

[rvcas]

Yea ok I'm in 👍

[mpizenberg]

Noice!