Add package level godoc for snow #2011

aaronbuchwald · 2025-03-27T21:17:07Z

This PR adds a doc.go with a high level description of the snow package.

aaronbuchwald · 2025-03-28T13:34:14Z

Elvis339 · 2025-03-28T14:33:41Z

I think we can improve reading flow and format if we were to use Markdown supported by godoc.
Additionally this creates anchors which can be shared.

For example

// Package snow simplifies VM development on AvalancheGo by providing adapter 
// between VM logic and AvalancheGo's consensus engine.
//
// # Why Snow Exists
//
// Building directly on the AvalancheGo [block.ChainVM] interface requires deep knowledge of consensus internals. 
// Snow exists to abstract away these complexities, allowing developers to focus on their VMs unique logic rather than
// consensus integration details.

Elvis339 · 2025-03-28T14:42:24Z

snow/doc.go

+// Snow provides an adapter from the AvalancheGo [block.ChainVM] interface to provide a more ergonomic interface for chain developers.
+// The existing interface was largely defined for ease of use by the AvalancheGo consensus engine and as a single all access type for
+// anything required by AvalancheGo (APIs, health check, shutdown, etc.)
+//


GoLand is reporting this:

Potentail improvement:

// Package snow simplifies custom VM development by providing adapter from the AvalancheGo [block.ChainVM] between custom VM logic and AvalancheGo's consensus engine.

Do you know what specific linter or rule that's coming from? I'd prefer to add the linter and start to follow it.

Found this lint rule: https://staticcheck.dev/docs/checks/#ST1020

snow/doc.go

Elvis339 · 2025-03-28T14:45:09Z

snow/doc.go

+// This package defines a simpler to use interface for use within the HyperSDK and to eventually iterate from
+// an initial small, well-defined public API backwards to more layers of customizability including building directly on top of this package.


I think this does not belong to the documentation, it describes internal development strategy rather than information about the package.

IMO documentation should focus on what the package currently does, how to use it, and what problems it solves. Future development plans would be better communicated in a separate roadmap document or project README, not in the package's API documentation.

Changing to:

// This package implements these tough to get right and tedious components and provides // a slimmed down interface for VM developers to implement.

Elvis339 · 2025-03-28T14:50:16Z

snow/doc.go

+// This package simplifies the existing ChainVM interface by implementing the [snowman.Block] interface and allowing VM developers to provide
+// generic type parameters for each possible state of a block within consensus (bytes, input/un-verified, output/verified, accepted).
+// Developers implement a single function to transition between each of these states with all of the information guaranteed to be available
+// at that point in time.
+//
+// For example, when a block is verified, its parent is guaranteed to have been verified successfully. However, it may not be accepted. Therefore,
+// chain developers implement `VerifyBlock` and receive the verified version of the parent (but not accepted type) and the input block to be verified:
+//
+//	VerifyBlock(
+//		ctx context.Context,
+//		parent O,
+//		block I,
+//	) (O, error)
+//


A combination of what you wrote with this should answer the "why snow" question, imo.

// # Snow egonomics (or something similar, this doesn't need to be h1) // Snow simplifies VM development through a type-safe block state system // // Instead of managing block state machine, Snow introduces // **generic** type parameters that represent each distinct block state: // // - B: Raw block bytes // - I: Input/unverified blocks ready for processing // - O: Output/verified blocks that passed validation // - A: Accepted blocks committed to the chain // // This type system ensures you always have access to the appropriate block // representation at each stage of consensus, preventing common errors and // simplifying implementation.

Great call on breaking out the block types this way, incorporated this feedback with a bit more modification

Elvis339 · 2025-03-28T14:53:23Z

snow/doc.go

+// Copyright (C) 2024, Ava Labs, Inc. All rights reserved.
+// See the file LICENSE for licensing terms.
+
+// Snow provides an adapter from the AvalancheGo [block.ChainVM] interface to provide a more ergonomic interface for chain developers.


It might be too much but it'd be good to explain block.ChainVM:

ChainVM is the required interface that any Snowman-compatible blockchain must implement to work with Avalanche's consensus engine.

Going with a bit shorter: (the interface AvalancheGo VM developers must implement)

Maybe I'm too close to it, but a long explanation of what block.ChainVM is seems like overkill or re-summarizing the same information to me. Tried to keep it short, let me know if you have another suggestion!

Elvis339 · 2025-03-28T15:11:11Z

snow/doc.go

+// Further, the package provides two functions [chain.Initialize] and [chain.SetConsensusIndex] as the effective "entrypoint" of the VM.
+// This needs to be split into two parameters, because the consensus index depends on a fully initialized version of the chain.
+// This provides all of the information available to the VM at the time of initialization. See [Chain.Initialize] and
+// [Chain.SetConsensusIndex] for details on the parameters provided to the VM at initialization.


This is very useful!
nit: I don't see the links

Struggling to get these links to work within the same package based off these docs https://tip.golang.org/doc/comment#links ... 🤔

RodrigoVillar

Seeing chain.Initialize and chain.SetConsensusIndex w/o hyperlinks hurts me, but everything else looks great!

RodrigoVillar · 2025-03-28T21:05:01Z

snow/doc.go

+// For example, when a block is verified, its parent is guaranteed to have been verified successfully. However, it may not be accepted. Therefore,
+// chain developers implement `VerifyBlock` and receive the verified version of the parent (but not accepted type) and the input block to be verified:
+//
+//	VerifyBlock(


nit: change to Output, Input

RodrigoVillar · 2025-03-28T21:12:34Z

snow/doc.go

+// to provide a more ergonomic interface to VM developers.
+//
+// The existing interface was largely defined for ease of use by the AvalancheGo consensus engine. As a result,
+// all responsibilities are combined into a single, all-access type for anything required by AvalancheGo (APIs, health check, shutdown, etc.).


As a result, all responsibilities are combined into a single, all-access type for anything required by AvalancheGo (APIs, health check, shutdown, etc.).

Is this the problem with using the current block.ChainVM interface? If so, can we make it so that the problem is evident? It seems that this is a statement rather than describing the actual problem.

I think the following:

This package implements these tough to get right and tedious components and provides a slimmed down interface for VM developers to implement.

is actually describing the problem.

RodrigoVillar · 2025-03-28T21:16:03Z

snow/vm.go

+	verifiedSubs         []event.Subscription[Output]
+	rejectedSubs         []event.Subscription[Output]
+	acceptedSubs         []event.Subscription[Accepted]
+	preReadyAcceptedSubs []event.Subscription[Input]
 	// preRejectedSubs handles rejections of I (Input) during/after state sync, before they reach O (Output) state


Can we remove references to the former I generic name?

aaronbuchwald added 3 commits March 27, 2025 15:38

WIP add godoc for snow pkg

bbb7305

Add initial doc.go to snow pkg

4fc88a8

fix list

4e6dd5b

aaronbuchwald marked this pull request as ready for review March 28, 2025 13:34

aaronbuchwald requested review from Elvis339 and RodrigoVillar March 28, 2025 13:34

Elvis339 reviewed Mar 28, 2025

View reviewed changes

aaronbuchwald added 3 commits March 28, 2025 16:28

Update originally declared Input/Output/Accepted types in snow

1500eab

address feedback

3657def

nit

4b5f76a

RodrigoVillar reviewed Mar 28, 2025

View reviewed changes

aaronbuchwald assigned aaronbuchwald and Elvis339 Apr 9, 2025

aaronbuchwald added this to the v0.0.19 milestone Apr 10, 2025

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add package level godoc for snow #2011

Add package level godoc for snow #2011

aaronbuchwald commented Mar 27, 2025

aaronbuchwald commented Mar 28, 2025

Elvis339 commented Mar 28, 2025

Elvis339 Mar 28, 2025

aaronbuchwald Mar 28, 2025

Elvis339 Apr 1, 2025

Elvis339 Mar 28, 2025

aaronbuchwald Mar 28, 2025

Elvis339 Mar 28, 2025

aaronbuchwald Mar 28, 2025

Elvis339 Mar 28, 2025

aaronbuchwald Mar 28, 2025

aaronbuchwald Mar 28, 2025

Elvis339 Mar 28, 2025

aaronbuchwald Mar 28, 2025

RodrigoVillar left a comment •

edited

Loading

RodrigoVillar Mar 28, 2025 •

edited

Loading

RodrigoVillar Mar 28, 2025

RodrigoVillar Mar 28, 2025 •

edited

Loading

RodrigoVillar Mar 28, 2025

		// This package defines a simpler to use interface for use within the HyperSDK and to eventually iterate from
		// an initial small, well-defined public API backwards to more layers of customizability including building directly on top of this package.

Add package level godoc for snow #2011

Are you sure you want to change the base?

Add package level godoc for snow #2011

Conversation

aaronbuchwald commented Mar 27, 2025

aaronbuchwald commented Mar 28, 2025

Elvis339 commented Mar 28, 2025

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

RodrigoVillar left a comment • edited Loading

Choose a reason for hiding this comment

RodrigoVillar Mar 28, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

RodrigoVillar Mar 28, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

RodrigoVillar left a comment •

edited

Loading

RodrigoVillar Mar 28, 2025 •

edited

Loading

RodrigoVillar Mar 28, 2025 •

edited

Loading