diff --git a/BUILD.bazel b/BUILD.bazel
index 6406df1e85d..87e1fcc1217 100644
--- a/BUILD.bazel
+++ b/BUILD.bazel
@@ -4,55 +4,6 @@ load("@rules_python//python:pip.bzl", "compile_pip_requirements")
 
 package(default_visibility = ["//visibility:public"])
 
-# TODO: pocket-ic = any pocket ic; pocket-ic-VERSIOn: specific and always the same
-genrule(
-    name = "pocket-ic-mainnet",
-    srcs = ["@pocket-ic-mainnet-gz//file"],
-    outs = ["pocket-ic"],
-    cmd = "gunzip -c $< > $@",
-)
-
-string_setting(
-    name = "pocket-ic-variant",
-    build_setting_default = "head",
-    visibility = ["//visibility:public"],
-)
-
-config_setting(
-    name = "pocket-ic-variant-head",
-    flag_values = {
-        ":pocket-ic-variant": "head",
-    },
-)
-
-config_setting(
-    name = "pocket-ic-variant-mainnet",
-    flag_values = {
-        ":pocket-ic-variant": "mainnet",
-    },
-)
-
-alias(
-    name = "pocket-ic-server",
-    actual = select({
-        ":pocket-ic-variant-mainnet": "//:pocket-ic-mainnet",
-        ":pocket-ic-variant-head": "//rs/pocket_ic_server:pocket-ic-server",
-        "//conditions:default": "//rs/pocket_ic_server:pocket-ic-server",
-    }),
-)
-
-#copy_file(
-#    name = "pocket-ic-server",
-#    testonly = True,  # WHY
-#    src = select({
-#        ":pocket-ic-variant-mainnet": "//:pocket-ic-mainnet",
-#        ":pocket-ic-variant-head": "//rs/pocket_ic_server:pocket-ic-server",
-#        "//conditions:default": "//rs/pocket_ic_server:pocket-ic-server",
-#    }),
-#    out = "pocket-ic-server",
-#    is_executable = True,
-#)
-
 # WARNING! .git is the directory, not a regular file! only consume it in your rules if you know how exactly bazel works and understand implications!
 exports_files([
     ".git",
@@ -148,3 +99,54 @@ test_suite(
     tags = ["manual"],
     tests = ["//rs/tests/testing_verification/testnets:single_large_node"],
 )
+
+### Pocket IC
+
+# The pocket-ic server binary. Use this as a test dependency if the test
+# does not require a specific pocket-ic version (see ":pocket-ic-variant"
+# for details). Use this
+# By default returns the pocket-ic server from the source tree to ensure
+# consistency within the source tree. See 'pocket_ic_mainnet_test' for
+# overrides.
+alias(
+    name = "pocket-ic-server",
+    actual = select({
+        ":pocket-ic-variant-mainnet": "//:pocket-ic-mainnet",
+        ":pocket-ic-variant-head": "//rs/pocket_ic_server:pocket-ic-server",
+        "//conditions:default": "//rs/pocket_ic_server:pocket-ic-server",
+    }),
+)
+
+# A setting to switch between different variants of pocket-ic. The
+# default pocket-ic variant/version (head) is the one as in the
+# source tree.
+string_setting(
+    name = "pocket-ic-variant",
+    build_setting_default = "head",
+    visibility = ["//visibility:public"],
+)
+
+config_setting(
+    name = "pocket-ic-variant-head",
+    flag_values = {
+        ":pocket-ic-variant": "head",
+    },
+)
+
+# A "mainnet" variant of the pocket-ic server which represents a
+# released version of pocket-ic.
+config_setting(
+    name = "pocket-ic-variant-mainnet",
+    flag_values = {
+        ":pocket-ic-variant": "mainnet",
+    },
+)
+
+# The pocket-ic as released; use this for tests that ensure consistency
+# with a release pocket-ic/replica.
+genrule(
+    name = "pocket-ic-mainnet",
+    srcs = ["@pocket-ic-mainnet-gz//file"],
+    outs = ["pocket-ic"],
+    cmd = "gunzip -c $< > $@",
+)
diff --git a/bazel/pocket-ic-tests.bzl b/bazel/pocket-ic-tests.bzl
index 8aae368a840..5b59849b707 100644
--- a/bazel/pocket-ic-tests.bzl
+++ b/bazel/pocket-ic-tests.bzl
@@ -1,7 +1,10 @@
-"""Foo bar"""
+"""Build helpers for using the pocket-ic"""
 
 load("@bazel_skylib//lib:paths.bzl", "paths")
 
+# This defines a transition used in the pocket-ic declaration.
+# This allows tests to depend on an arbitrary version of pocket-ic
+# and for dependents to override that version.
 def _pocket_ic_mainnet_transition_impl(_settings, _attr):
     return {
         "//:pocket-ic-variant": "mainnet",
@@ -15,6 +18,30 @@ pocket_ic_mainnet_transition = transition(
     ],
 )
 
+# Rule to override another (test) rule. The resulting rule
+# will use the mainnet pocket-ic varaint.
+pocket_ic_mainnet_test = rule(
+    _pocket_ic_mainnet_test_impl,
+    attrs = {
+        "_allowlist_function_transition": attr.label(
+            default = "@bazel_tools//tools/allowlists/function_transition_allowlist",
+        ),
+        "data": attr.label_list(allow_files = True),
+        "test": attr.label(
+            aspects = [_test_aspect],
+            cfg = "target",
+            executable = True,
+        ),
+    },
+    cfg = pocket_ic_mainnet_transition,
+    executable = True,
+    test = True,
+)
+
+# Provider that allows wrapping/transitioning a test executable. This
+# ensure all the test data & env is forwarded.
+# Adapted from github.com/aherrman/bazel-transitions-demo:
+# https://github.com/aherrmann/bazel-transitions-demo/blob/f22cf40a62131eace14829f262e8d7c00b0a9a19/flag/defs.bzl#L124
 TestAspectInfo = provider("some descr", fields = ["args", "env"])
 
 def _test_aspect_impl(_target, ctx):
@@ -65,21 +92,3 @@ set -euo pipefail
         files = depset(direct = [executable]),
         runfiles = runfiles,
     )]
-
-pocket_ic_mainnet_test = rule(
-    _pocket_ic_mainnet_test_impl,
-    attrs = {
-        "_allowlist_function_transition": attr.label(
-            default = "@bazel_tools//tools/allowlists/function_transition_allowlist",
-        ),
-        "data": attr.label_list(allow_files = True),
-        "test": attr.label(
-            aspects = [_test_aspect],
-            cfg = "target",
-            executable = True,
-        ),
-    },
-    cfg = pocket_ic_mainnet_transition,
-    executable = True,
-    test = True,
-)