OffchainLabs · rauljordan · Jul 28, 2023 · Jul 28, 2023 · prestonvanloon · Jul 28, 2023
diff --git a/api/BUILD.bazel b/api/BUILD.bazel
@@ -37,6 +37,7 @@ go_test(
     deps = [
         "//chain-abstraction:protocol",
         "//challenge-manager/challenge-tree/mock",
+        "@com_github_ethereum_go_ethereum//common",
         "@com_github_gorilla_mux//:mux",
         "@in_gopkg_d4l3k_messagediff_v1//:messagediff_v1",
     ],

diff --git a/api/server.go b/api/server.go
@@ -1,3 +1,6 @@
+// Package api defines an API server for BOLD, allowig retrieval of information
+// from both the assertion chain and the challenge manager contracts in order to
+// understand ongoing challenges.
 package api
 
 import (

diff --git a/chain-abstraction/execution_state.go b/chain-abstraction/execution_state.go
@@ -1,5 +1,5 @@
-// Package protocol
-// From: Nitro validator/execution_state.go
+// Package protocol a series of interfaces for interacting with Arbitrum chains' rollup
+// and challenge contracts via a developer-friendly, high-level API.
 package protocol
 
 import (

diff --git a/chain-abstraction/sol-implementation/BUILD.bazel b/chain-abstraction/sol-implementation/BUILD.bazel
@@ -36,6 +36,7 @@ go_test(
     deps = [
         "//chain-abstraction:protocol",
         "//layer2-state-provider",
+        "//solgen/go/rollupgen",
         "//state-commitments/history",
         "//testing",
         "//testing/setup:setup_lib",

diff --git a/challenge-manager/challenge-tree/mock/edge.go b/challenge-manager/challenge-tree/mock/edge.go
@@ -1,3 +1,4 @@
+// Package mock includes specific mock setups for edge types used in internal tests.
 package mock
 
 import (

diff --git a/challenge-manager/challenge-tree/tree.go b/challenge-manager/challenge-tree/tree.go
@@ -1,6 +1,9 @@
+// Package challengetree includes logic for keeping track of honest edges within a challenge
+// with utilities for computing cumulative path timers for said edges. This is helpful during
+// the confirmation process needed by edge trackers.
+//
 // Copyright 2023, Offchain Labs, Inc.
 // For license information, see https://github.com/offchainlabs/bold/blob/main/LICENSE
-
 package challengetree
 
 import (

diff --git a/challenge-manager/edge-tracker/tracker.go b/challenge-manager/edge-tracker/tracker.go
@@ -1,7 +1,7 @@
 // Copyright 2023, Offchain Labs, Inc.
 // For license information, see https://github.com/offchainlabs/bold/blob/main/LICENSE
 
-// package edgetracker contains the logic for tracking an edge in the challenge manager. It keeps
+// Package edgetracker contains the logic for tracking an edge in the challenge manager. It keeps
 // track of edges created and their own state transitions until an eventual confirmation.
 package edgetracker
 

diff --git a/challenge-manager/manager.go b/challenge-manager/manager.go
@@ -1,6 +1,8 @@
+// Package challengemanager includes the main entrypoint for setting up a BOLD
+// challenge manager instance and challenging assertions onchain.
+//
 // Copyright 2023, Offchain Labs, Inc.
 // For license information, see https://github.com/offchainlabs/bold/blob/main/LICENSE
-
 package challengemanager
 
 import (

diff --git a/challenge-manager/types/interfaces.go b/challenge-manager/types/interfaces.go
@@ -1,3 +1,4 @@
+// Package types includes types and interfaces specific to the challenge manager instance.
 package types
 
 import (

diff --git a/containers/fsm/fsm.go b/containers/fsm/fsm.go
@@ -1,6 +1,9 @@
+// Package fsm defines a generic, finite state machine in Go that is extremely simple
+// and type-safe. It is used by edge tracker goroutines to keep track of the edge states
+// and transition to confirmation.
+//
 // Copyright 2023, Offchain Labs, Inc.
 // For license information, see https://github.com/offchainlabs/bold/blob/main/LICENSE
-
 package fsm
 
 import (

diff --git a/containers/option/option_type.go b/containers/option/option_type.go
@@ -1,6 +1,9 @@
+// Package option defines a generic option type as a way of representing "nothingness"
+// or "something" in a type-safe way. This is useful for representing optional values
+// without the need for nil checks or pointers.
+//
 // Copyright 2023, Offchain Labs, Inc.
 // For license information, see https://github.com/offchainlabs/bold/blob/main/LICENSE
-
 package option
 
 type Option[T any] struct {

diff --git a/containers/slice.go b/containers/slice.go
@@ -1,6 +1,7 @@
+// Package containers defines generic data structures to be used in the BOLD repository.
+//
 // Copyright 2023, Offchain Labs, Inc.
 // For license information, see https://github.com/offchainlabs/bold/blob/main/LICENSE
-
 package containers
 
 import "fmt"

diff --git a/containers/threadsafe/slice.go b/containers/threadsafe/slice.go
@@ -1,6 +1,8 @@
+// Package threadsafe defines generic, threadsafe analogues of common data structures
+// in Go such as maps, slices, and sets for use in BOLD with an intuitive API.
+//
 // Copyright 2023, Offchain Labs, Inc.
 // For license information, see https://github.com/offchainlabs/bold/blob/main/LICENSE
-
 package threadsafe
 
 import "sync"

diff --git a/layer2-state-provider/provider.go b/layer2-state-provider/provider.go
@@ -1,6 +1,9 @@
+// Package l2stateprovider defines a dependency which provides L2 states and proofs
+// needed for the challenge manager to interact with Arbitrum chains' rollup and challenge
+// contracts.
+//
 // Copyright 2023, Offchain Labs, Inc.
 // For license information, see https://github.com/offchainlabs/bold/blob/main/LICENSE
-
 package l2stateprovider
 
 import (

diff --git a/math/math.go b/math/math.go
@@ -1,6 +1,8 @@
+// Package math defines utilities for performing operations critical to the
+// computations performed during a challenge in BOLD.
+//
 // Copyright 2023, Offchain Labs, Inc.
 // For license information, see https://github.com/offchainlabs/bold/blob/main/LICENSE
-
 package math
 
 import (

diff --git a/runtime/retry.go b/runtime/retry.go
@@ -1,6 +1,9 @@
+// Package runtime defines utilities that deal with managing lifecycles of functions
+// and important behaviors at the application runtime, such as retrying failed
+// functions until they succeed.
+//
 // Copyright 2023, Offchain Labs, Inc.
 // For license information, see https://github.com/offchainlabs/bold/blob/main/LICENSE
-
 package retry
 
 import (

diff --git a/state-commitments/history/commitments.go b/state-commitments/history/commitments.go
@@ -1,7 +1,9 @@
+// Package history defines the primitive HistoryCommitment type in the BOLD
+// protocol.
+//
 // Copyright 2023, Offchain Labs, Inc.
 // For license information, see https://github.com/offchainlabs/bold/blob/main/LICENSE
-
-package commitments
+package history
 
 import (
 	"errors"

diff --git a/state-commitments/history/commitments_test.go b/state-commitments/history/commitments_test.go
@@ -1,7 +1,7 @@
 // Copyright 2023, Offchain Labs, Inc.
 // For license information, see https://github.com/offchainlabs/bold/blob/main/LICENSE
 
-package commitments
+package history
 
 import (
 	"fmt"

diff --git a/state-commitments/inclusion-proofs/inclusion_proofs.go b/state-commitments/inclusion-proofs/inclusion_proofs.go
@@ -1,6 +1,8 @@
+// Package inclusionproofs defines a series of utilities for generating and verifying
+// traditional Merkle proofs of data.
+//
 // Copyright 2023, Offchain Labs, Inc.
 // For license information, see https://github.com/offchainlabs/bold/blob/main/LICENSE
-
 package inclusionproofs
 
 import (

diff --git a/state-commitments/prefix-proofs/BUILD.bazel b/state-commitments/prefix-proofs/BUILD.bazel
@@ -25,7 +25,7 @@ go_test(
     embed = [":prefix-proofs"],
     deps = [
         "//solgen/go/mocksgen",
-        "//testing/toys/state-provider",
+        "//testing/mocks/state-provider",
         "@com_github_ethereum_go_ethereum//accounts/abi/bind",
         "@com_github_ethereum_go_ethereum//accounts/abi/bind/backends",
         "@com_github_ethereum_go_ethereum//common",

diff --git a/state-commitments/prefix-proofs/prefix_proofs_test.go b/state-commitments/prefix-proofs/prefix_proofs_test.go
@@ -12,7 +12,7 @@ import (
 
 	"github.com/OffchainLabs/bold/solgen/go/mocksgen"
 	prefixproofs "github.com/OffchainLabs/bold/state-commitments/prefix-proofs"
-	statemanager "github.com/OffchainLabs/bold/testing/toys/state-provider"
+	statemanager "github.com/OffchainLabs/bold/testing/mocks/state-provider"
 	"github.com/ethereum/go-ethereum/accounts/abi/bind"
 	"github.com/ethereum/go-ethereum/accounts/abi/bind/backends"
 	"github.com/ethereum/go-ethereum/common"

diff --git a/testing/endtoend/BUILD.bazel b/testing/endtoend/BUILD.bazel
@@ -27,7 +27,7 @@ go_test(
         "//layer2-state-provider",
         "//testing",
         "//testing/endtoend/internal/backend",
-        "//testing/toys/state-provider",
+        "//testing/mocks/state-provider",
         "@com_github_ethereum_go_ethereum//accounts/abi/bind",
         "@com_github_ethereum_go_ethereum//common",
         "@com_github_stretchr_testify//require",

diff --git a/testing/endtoend/basic_local_test.go b/testing/endtoend/basic_local_test.go
@@ -14,7 +14,7 @@ import (
 	l2stateprovider "github.com/OffchainLabs/bold/layer2-state-provider"
 	challenge_testing "github.com/OffchainLabs/bold/testing"
 	"github.com/OffchainLabs/bold/testing/endtoend/internal/backend"
-	statemanager "github.com/OffchainLabs/bold/testing/toys/state-provider"
+	statemanager "github.com/OffchainLabs/bold/testing/mocks/state-provider"
 	"github.com/ethereum/go-ethereum/accounts/abi/bind"
 	"github.com/ethereum/go-ethereum/common"
 	"github.com/stretchr/testify/require"

diff --git a/testing/endtoend/helpers.go b/testing/endtoend/helpers.go
@@ -1,6 +1,7 @@
+// Package endtoend includes e2e tests for BOLD challenges and assertion posting.
+//
 // Copyright 2023, Offchain Labs, Inc.
 // For license information, see https://github.com/offchainlabs/bold/blob/main/LICENSE
-
 package endtoend
 
 import (

diff --git a/testing/mocks/mocks.go b/testing/mocks/mocks.go
@@ -1,6 +1,7 @@
+// Package mocks includes simple mocks for unit testing BOLD.
+//
 // Copyright 2023, Offchain Labs, Inc.
 // For license information, see https://github.com/offchainlabs/bold/blob/main/LICENSE
-
 package mocks
 
 import (

diff --git a/testing/toys/state-provider/BUILD.bazel → testing/mocks/state-provider/BUILD.bazel b/testing/toys/state-provider/BUILD.bazel → testing/mocks/state-provider/BUILD.bazel
@@ -7,7 +7,7 @@ go_library(
         "execution_engine.go",
         "layer2_state_provider.go",
     ],
-    importpath = "github.com/OffchainLabs/bold/testing/toys/state-provider",
+    importpath = "github.com/OffchainLabs/bold/testing/mocks/state-provider",
     visibility = ["//visibility:public"],
     deps = [
         "//chain-abstraction:protocol",

diff --git a/...g/toys/state-provider/execution_engine.go → .../mocks/state-provider/execution_engine.go b/...g/toys/state-provider/execution_engine.go → .../mocks/state-provider/execution_engine.go
@@ -1,6 +1,6 @@
 // Copyright 2023, Offchain Labs, Inc.
 // For license information, see https://github.com/offchainlabs/bold/blob/main/LICENSE
-package toys
+package stateprovider
 
 import (
 	"encoding/binary"

diff --git a/...s/state-provider/execution_engine_test.go → ...s/state-provider/execution_engine_test.go b/...s/state-provider/execution_engine_test.go → ...s/state-provider/execution_engine_test.go
@@ -1,6 +1,6 @@
 // Copyright 2023, Offchain Labs, Inc.
 // For license information, see https://github.com/offchainlabs/bold/blob/main/LICENSE
-package toys
+package stateprovider
 
 import (
 	"testing"

diff --git a/...s/state-provider/layer2_state_provider.go → ...s/state-provider/layer2_state_provider.go b/...s/state-provider/layer2_state_provider.go → ...s/state-provider/layer2_state_provider.go
@@ -1,6 +1,9 @@
+// Package stateprovider defines smarter mocks for testing purposes that can simulate a layer 2
+// state provider and and layer 2 state execution.
+//
 // Copyright 2023, Offchain Labs, Inc.
 // For license information, see https://github.com/offchainlabs/bold/blob/main/LICENSE
-package toys
+package stateprovider
 
 import (
 	"context"

diff --git a/...te-provider/layer2_state_provider_test.go → ...te-provider/layer2_state_provider_test.go b/...te-provider/layer2_state_provider_test.go → ...te-provider/layer2_state_provider_test.go
@@ -1,6 +1,6 @@
 // Copyright 2023, Offchain Labs, Inc.
 // For license information, see https://github.com/offchainlabs/bold/blob/main/LICENSE
-package toys
+package stateprovider
 
 import (
 	"context"

diff --git a/testing/setup/BUILD.bazel b/testing/setup/BUILD.bazel
@@ -15,7 +15,7 @@ go_library(
         "//solgen/go/mocksgen",
         "//solgen/go/rollupgen",
         "//testing",
-        "//testing/toys/state-provider",
+        "//testing/mocks/state-provider",
         "@com_github_ethereum_go_ethereum//accounts/abi/bind",
         "@com_github_ethereum_go_ethereum//accounts/abi/bind/backends",
         "@com_github_ethereum_go_ethereum//common",

diff --git a/testing/setup/rollup_stack.go b/testing/setup/rollup_stack.go
@@ -1,6 +1,7 @@
+// Package setup prepares a simulated backend for testing.
+//
 // Copyright 2023, Offchain Labs, Inc.
 // For license information, see https://github.com/offchainlabs/bold/blob/main/LICENSE
-
 package setup
 
 import (
@@ -16,7 +17,7 @@ import (
 	"github.com/OffchainLabs/bold/solgen/go/mocksgen"
 	"github.com/OffchainLabs/bold/solgen/go/rollupgen"
 	challenge_testing "github.com/OffchainLabs/bold/testing"
-	statemanager "github.com/OffchainLabs/bold/testing/toys/state-provider"
+	statemanager "github.com/OffchainLabs/bold/testing/mocks/state-provider"
 	"github.com/ethereum/go-ethereum/accounts/abi/bind"
 	"github.com/ethereum/go-ethereum/accounts/abi/bind/backends"
 	"github.com/ethereum/go-ethereum/common"

diff --git a/testing/setup/simulated-backend/simulated_backend_wrapper.go b/testing/setup/simulated-backend/simulated_backend_wrapper.go
@@ -1,3 +1,5 @@
+// Package simulated_backend prepares a wrapper for transaction testing.
+//
 // Copyright 2023, Offchain Labs, Inc.
 // For license information, see https://github.com/offchainlabs/bold/blob/main/LICENSE
 package simulated_backend

diff --git a/testing/tx.go b/testing/tx.go
@@ -1,6 +1,7 @@
+// Package challenge_testing includes all non-production code used in BOLD.
+//
 // Copyright 2023, Offchain Labs, Inc.
 // For license information, see https://github.com/offchainlabs/bold/blob/main/LICENSE
-
 package challenge_testing
 
 import (

diff --git a/time/time_reference.go b/time/time_reference.go
@@ -1,3 +1,5 @@
+// Package time defines abstractions for time-related operations in BOLD.
+//
 // Copyright 2023, Offchain Labs, Inc.
 // For license information, see https://github.com/offchainlabs/bold/blob/main/LICENSE
 package time