clarity-lang / book Goto Github PK

the example at https://github.com/clarity-lang/book/blob/main/projects/sip009-nft/contracts/marvin-token.clar for instance

(define-read-only (get-token-uri (token-id uint))
	(ok none)
)

This will essentially show no image, so by definition is not a valid NTF. I assume that this should be changed to something like

(define-read-only (get-token-uri (token-id uint))

	(ok (some "https://....../{id}.json"))
)

or something similar with an IPFS address if one prefers to use that.

I think that Stacks looks very interesting and has a lot of potential but the only two tutorials available online are the one of this book and the one from hiro.so that is also wrong (doesn't provide with a viable example of a token to be minted only by the owner).

I really think that having a clear and updated NFT contract tutorial is absolutely crucial.

When the build script was originally put together, it was not straightforward to build the latest clarity-repl WASM binary. The script therefore pulls an old version from a CDN. It should instead grab the latest from here: https://github.com/hirosystems/clarinet/tree/develop/components/clarity-repl

As I was reading this book, I was really missing coverage of what seems like a very important core/101 kind of feature: the let function. Unless I missed it, I don't think it's ever covered formally until it just shows up in a code-example under one of the Flow-Control pages (more than halfway thru the book).

In fact, TBH, since I'm not super well-versed in lisps, even referring to let as a function was unnatural to me, as it seems more like a keyword or core language feature. I kept thinking, "surely there's a way for me to create function-local variables, right!?! Right!?" As such, I didn't even think to look for it under "Functions" on the stacks-co language docs.

I think it would make sense for this book to call this kind of thing out. Here's 3 places I think it makes sense:

1. In the "Clarity Basics" section, it could talk a bit more about s-expressions with function names (like let) work, and perhaps even a bit about why some of them require their arguments to be in sub ( ) parens sets... like let ( (..) (..) ) .. ) and all that. Being not super familiar with lisps, knowing when I need ( .. ) is the biggest thing I'm tripping on while learning.

2. In "Storing Data" section, a mention should be made that "function local variables" (with (let .. )) is a fourth place to store data (in addition to the 3 "Constants", "Variables", and "Maps")

3. In "Functions" page, after "Function Body" sub-section, the (let ..) should be covered.

I think it could be covered in all 3 of these places and that would improve the book. If agreed, I'd be happy to send in a PR for such.

Add the ability to build a PDF version of the book.

I tried using the let function and I'm getting a really confusing/buggy error message being reported.

Here's the code:

(define-read-only (get-counter-of (who principal))
	(let ((count (map-get? (counters who))))
		(if
			(is-eq count none) u0 (unwrap-panic count)
		)
	)
)

And here's the error reported:

I think that let syntax is correct, given what I read in the stacks docs. But even if it's an error, the whole [1;4;31mlet thing in the error message sure looks like the parser running incorrectly.

All tests do not work anymore for Clarinet v2. Therefore testing section and projects should be updated. We can link / draw inspiration from the Hiro docs Unit Tests With the Clarinet SDK. (Particularly there are Unit Tests for counter)

Does it make sense to include a chapter how to use native bitcoins in clarity contracts? Or is it out of scope

The chapter should explain

• what state of the bitcoin chain clarity contracts can view
• where clarity-bitcoin library is deployed on mainnet and how to use the contract
• which contracts and applications use clarity-bitcoin (catamaran swaps, magic bridge, zest protocol, bitcoin faces/nfts)

Clarinet test does not work anymore

Add the ability to build an ePub version of the book.

Stacks Discord channel: https://discord.com/channels/621759717756370964/1103835134068805702/1103835136061091920

Summary:
Igor, Marvin, and Trevor discuss publishing a Clarity book with a foreword by Peter Seibel to attract Lisp developers. They consider working with O'Reilly or Addison Wesley for publication. They also discuss potential practice problems and projects for the book, such as creating a DAO, building a DEX, integrating BNS, and highlighting Clarity's security advantages. Marvin suggests launching a custom token with a DAO as a fun learning experience. Igor proposes moving the discussion to a public GitHub artifact.

@MarvinJanssen
Marvin Janssen, [May 3, 2023 at 2:42:28 PM]
Awesome idea

As metioned before you guys joined the group, the book was made with the intent to perhaps publish it one day. It should easily allow for it

What we would need it is a bunch more practice projects and perhaps a separate website for the book where we publish all interactive examples and people can hack away on it

We already have a few different online IDEs so should be easy and quick enough

I like the tie-in with LISP. Do we know if any other popular chains use a LISP-like language for their smart contracts?

The kind of flow I had in mind when I wrote the book was the one from “Node.js the Right Way”. I read it ages ago when starting out with Node and what I loved about it is that it:

1. Covered the basics
2. Covered the latest developments
3. Covered everything you needed to know about the toolchain to start working (node runtime, npm)
4. And especially: introduced a lot of practical practice projects that you can build completely by just following the book.

When the Clarity book was put together, it was just one of many projects so I didn’t have a ton of time at the Foundation to write up some really nice practice projects back to back. I think adding such projects would bring it to the next level

(Also a common complaint to the book, for example the tiny market place project only covers the Clarity side, not any frontend so some people starting out didn’t really know where to go from there.)

@kenrogers

Some thoughts on projects that could make this the #1 resource for learning Clarity and take it over the finish line:

• +1 to adding a frontend, at least for one or two projects
• Creating an NFT collection
• Creating a DAO with ExecutorDAO
• Build a DEX
• Integrate BNS into a Clarity contract
• Some sort of Bitcoin-first app where we are using Friedger's Clarity<>Bitcoin library to read and verify transactions
• Security section - Clarity's security advantages over Solidity are not discussed enough, should add a whole section on security properties and advantages along with some "hack this contract" style projects and exercises with things like as-contract vulnerabilities

Happy to help with these where I can. Currently working on a large Bitcoin→Stacks course that teaches both Bitcoin programming fundamentals and then adds Stacks in, will focus heavily on sBTC when Mini comes out. It's designed to be a go-to all-in-one introductory resource for learning Bitcoin development.

Expanded Clarity book would be an excellent next step for mastering Clarity after learning the fundamentals of Bitcoin and Stacks. Should also source project ideas from other experienced Clarity devs like setzeus.

Hello, I've found a small error in the highlighted sentence. "using" should be replaced with "user".

Also, I think this particular sentence could be rewritten for more clarity.

Example: "Additionally, there is the possibility that a user may try to list an NFT for sale without actually owning it. However, this issue will be addressed by the NFT contract's built-in safeguards."

I was playing around with different approaches to the "quiz" on the "Read Only Functions" page. And I had this code entered:

(define-map counters principal uint)

(map-set counters 'ST1J4G6RR643BCG8G8SR6M2D9Z9KXT2NJDRK3FBTK u5)
(map-set counters 'ST20ATRN26N9P05V2F1RHFRV24X8C8M3W54E427B2 u10)

(define-read-only (get-counter-of (who principal))
	(begin
		(asserts! (not (is-eq (map-get? counters who) none)) u0)
		(unwrap-panic (map-get? counters who))
	)
	
;;	(if (is-eq (map-get? counters who) none)
;;		u0
;;		(unwrap-panic (map-get? counters who))
;;	)

)

;; These exist:
(print (get-counter-of 'ST1J4G6RR643BCG8G8SR6M2D9Z9KXT2NJDRK3FBTK))
(print (get-counter-of 'ST20ATRN26N9P05V2F1RHFRV24X8C8M3W54E427B2))

;; This one does not:
(print (get-counter-of 'ST21HMSJATHZ888PD0S0SSTWP4J61TCRJYEVQ0STB))

As far as I can tell, that code is valid and well-formed. I have the four lines of the first approach I tried commented out, each with a ;; at the beginning of the line.

But when I run that code, I get this error:

I don't understand that error, it sure seems fine. If I simply remove the 4 lines of commented code, everything runs fine. But why would having those 4 lines of comments there cause the parser to choke?

But even more strangely, if the four commented lines are changed to this:

;;   (if (is-eq (map-get? counters who) none)
;;		u0
;;		(unwrap-panic (map-get? counters who))
;;	)

You'll notice the contents of those comments are almost identical, except different whitespace (three spaces on the first line, but tabs indenting the other 3 lines).

Weirdly, the parser chokes differently now. Here's the error in that case:

Unless I'm missing something, it sure seems like indentation whitespace shouldn't matter, and definitely shouldn't matter inside of lines of comments.

Not sure if it would matter, but I'm using Chrome 105 on Windows 10.