OOR client 1/4: package primitives + validation baseline

Makefile

@@ -210,7 +210,7 @@ docker-tools:
 
 lint-source: docker-tools
 	@$(call print, "Linting source.")
-	$(DOCKER_TOOLS) custom-gcl run -v $(LINT_WORKERS)
+	$(DOCKER_TOOLS) custom-gcl run -v --timeout=15m $(LINT_WORKERS)
 
 # Globs to exclude generated files from ast-grep.
 AST_GREP_EXCLUDE := --globs '!**/*.pb.go' --globs '!**/*.pb.gw.go' --globs '!**/*.pb.json.go' --globs '!**/db/sqlc/*.go'

db/store.go

@@ -62,8 +62,7 @@ func (s *Store) Close() error {
 type Config struct {
 	// Backend specifies which database backend to use: "sqlite" or
 	// "postgres".
-	//nolint:ll
-	Backend string `long:"backend" description:"Database backend to use (sqlite or postgres)" choice:"sqlite" choice:"postgres"`
+	Backend string `long:"backend" choice:"sqlite" choice:"postgres"`
 
 	// Sqlite contains SQLite-specific configuration
 	Sqlite *SqliteConfig `group:"sqlite" namespace:"sqlite"`

harness/harness.go

@@ -1420,6 +1420,11 @@ func (h *Harness) Faucet(address string, amount btcutil.Amount) string {
 	txID := h.bitcoindSendToAddress(address, amount.ToBTC())
 	h.Logf("Faucet sent %v to %s (txid %s)", amount, address, txID)
 
+	// Ensure the transaction actually lands in mempool before returning.
+	// Some systests intentionally restart client-side actors before mining,
+	// and we want to avoid racing "mine" against "broadcast".
+	h.WaitMempoolTx(txID)
+
 	return txID
 }
 
@@ -1460,6 +1465,26 @@ func (h *Harness) WaitMempoolTxCount(minTxCount int) []string {
 	return txIDs
 }
 
+// WaitMempoolTx waits until the given transaction ID appears in bitcoind's
+// mempool.
+func (h *Harness) WaitMempoolTx(txID string) {
+	h.T.Helper()
+
+	require.Eventually(
+		h.T, func() bool {
+			txIDs := h.MempoolTxIDs()
+			for i := range txIDs {
+				if txIDs[i] == txID {
+					return true
+				}
+			}
+
+			return false
+		}, defaultTimeout, pollInterval,
+		"txid %s not found in mempool", txID,
+	)
+}
+
 // rpcRequest is a JSON-RPC request.
 type rpcRequest struct {
 	JSONRPC string        `json:"jsonrpc"`
@@ -1785,9 +1810,8 @@ func (h *Harness) initAndWaitLNDInstance(
 		)
 		defer cancel()
 
-		conn, err := grpc.DialContext(
-			ctxt, addr, grpc.WithTransportCredentials(tlsCert),
-			grpc.WithBlock(),
+		conn, err := grpc.NewClient(
+			addr, grpc.WithTransportCredentials(tlsCert),
 		)
 		if err != nil {
 			return false
@@ -2049,12 +2073,9 @@ func getLNDClientConn(ctx context.Context, addr, tlsPath,
 	opts := []grpc.DialOption{
 		grpc.WithTransportCredentials(creds),
 		grpc.WithPerRPCCredentials(macaroonCred),
-		grpc.WithBlock(),
 	}
 
-	conn, err := grpc.DialContext(
-		ctx, addr, opts...,
-	)
+	conn, err := grpc.NewClient(addr, opts...)
 	if err != nil {
 		return nil, fmt.Errorf("failed to dial LND: %w", err)
 	}
@@ -2093,10 +2114,9 @@ func getTapdClientConn(ctx context.Context, addr, tlsPath,
 	opts := []grpc.DialOption{
 		grpc.WithTransportCredentials(creds),
 		grpc.WithPerRPCCredentials(macaroonCred),
-		grpc.WithBlock(),
 	}
 
-	conn, err := grpc.DialContext(ctx, addr, opts...)
+	conn, err := grpc.NewClient(addr, opts...)
 	if err != nil {
 		return nil, fmt.Errorf("failed to dial tapd: %w", err)
 	}

harness/tapd_harness.go

@@ -388,9 +388,8 @@ func (th *TapdHarness) initAndWaitLND() {
 		)
 		defer cancel()
 
-		conn, err := grpc.DialContext(
-			ctx, addr, grpc.WithTransportCredentials(tlsCert),
-			grpc.WithBlock(),
+		conn, err := grpc.NewClient(
+			addr, grpc.WithTransportCredentials(tlsCert),
 		)
 		if err != nil {
 			return false

lib/scripts/checkpoint_oor.go

@@ -0,0 +1,103 @@
+package scripts
+
+import (
+	"fmt"
+
+	"github.com/btcsuite/btcd/btcec/v2"
+	"github.com/btcsuite/btcd/txscript"
+	"github.com/btcsuite/btcwallet/waddrmgr"
+	"github.com/lightningnetwork/lnd/input"
+)
+
+// CheckpointPolicy defines the parameters for constructing an OOR checkpoint
+// taproot tree.
+//
+// This is intentionally interface-first and minimal: it provides enough
+// information to deterministically derive a checkpoint output pkScript, while
+// allowing the underlying closure system to evolve later.
+type CheckpointPolicy struct {
+	// OperatorKey is the public key required by the operator-controlled CSV
+	// unroll leaf.
+	OperatorKey *btcec.PublicKey
+
+	// CSVDelay is the relative timelock enforced by the
+	// operator-controlled leaf.
+	//
+	// This is a raw BIP-68 sequence value interpreted by
+	// OP_CHECKSEQUENCEVERIFY.
+	CSVDelay uint32
+}
+
+// CheckpointTapScript constructs the tapscript for an OOR checkpoint output.
+//
+// The checkpoint tree for v0 is a simple two-leaf tree:
+//
+//   - an operator-controlled CSV unroll leaf (operator key + relative
+//     timelock),
+//   - a collaborative leaf between operator and VTXO owner (provided by the
+//     caller as raw script bytes).
+//
+// "Owner" here means the owner of the VTXO being refreshed. The checkpoint
+// output itself is still operator-controlled on the CSV timeout path.
+//
+// For v0, the checkpoint output always uses the ARK NUMS internal key so there
+// is no key-path spend and all spends go through one of the script leaves.
+//
+// This function does not validate that ownerLeafScript is "a correct Ark
+// closure". That validation belongs in higher layers once the canonical closure
+// system is in place (see the closures PRs). For now, this gives OOR primitives
+// a deterministic way to bind checkpoint scripts.
+func CheckpointTapScript(policy CheckpointPolicy,
+	ownerLeafScript []byte) (*waddrmgr.Tapscript, error) {
+
+	switch {
+	case policy.OperatorKey == nil:
+		return nil, fmt.Errorf("operator key must be provided")
+
+	case len(ownerLeafScript) == 0:
+		return nil, fmt.Errorf("owner leaf script must be provided")
+	}
+
+	unrollLeaf, err := UnilateralCSVTimeoutTapLeaf(
+		policy.OperatorKey, policy.CSVDelay,
+	)
+	if err != nil {
+		return nil, fmt.Errorf("unable to construct unroll leaf: %w",
+			err)
+	}
+
+	ownerLeaf := txscript.NewBaseTapLeaf(ownerLeafScript)
+
+	tapscript := input.TapscriptFullTree(&ARKNUMSKey, unrollLeaf, ownerLeaf)
+
+	// Compute and set the root hash since TapscriptFullTree doesn't
+	// populate it.
+	tree := txscript.AssembleTaprootScriptTree(tapscript.Leaves...)
+	rootHash := tree.RootNode.TapHash()
+	tapscript.RootHash = rootHash[:]
+
+	return tapscript, nil
+}
+
+// CheckpointPkScript returns the pkScript for a checkpoint output produced by
+// CheckpointTapScript.
+//
+// The caller should treat this as the canonical way to derive checkpoint output
+// scripts for v0 OOR transfers so both client and server can validate and
+// serialize checkpoint transactions deterministically.
+func CheckpointPkScript(policy CheckpointPolicy,
+	ownerLeafScript []byte) ([]byte, error) {
+
+	tapscript, err := CheckpointTapScript(policy, ownerLeafScript)
+	if err != nil {
+		return nil, err
+	}
+
+	tapKey, err := tapscript.TaprootKey()
+	if err != nil {
+		return nil, fmt.Errorf("unable to compute taproot key: %w",
+			err)
+	}
+
+	return txscript.PayToTaprootScript(tapKey)
+}

lib/scripts/checkpoint_oor_test.go

@@ -0,0 +1,52 @@
+package scripts
+
+import (
+	"testing"
+
+	"github.com/btcsuite/btcd/btcec/v2"
+	"github.com/btcsuite/btcd/txscript"
+	"github.com/stretchr/testify/require"
+)
+
+// TestCheckpointPkScriptIsTaproot asserts that the checkpoint helper returns a
+// valid P2TR script and that it binds the expected internal key and tap tree.
+func TestCheckpointPkScriptIsTaproot(t *testing.T) {
+	t.Parallel()
+
+	operatorKey, err := btcec.NewPrivateKey()
+	require.NoError(t, err)
+
+	policy := CheckpointPolicy{
+		OperatorKey: operatorKey.PubKey(),
+		CSVDelay:    10,
+	}
+
+	ownerLeafScript := []byte{
+		txscript.OP_1,
+		txscript.OP_1,
+		txscript.OP_ADD,
+		txscript.OP_2,
+		txscript.OP_EQUAL,
+	}
+
+	tapscript, err := CheckpointTapScript(policy, ownerLeafScript)
+	require.NoError(t, err)
+	require.NotNil(t, tapscript)
+
+	pkScript, err := CheckpointPkScript(policy, ownerLeafScript)
+	require.NoError(t, err)
+	require.True(t, txscript.IsPayToTaproot(pkScript))
+
+	tree := txscript.AssembleTaprootScriptTree(tapscript.Leaves...)
+	expectedRoot := tree.RootNode.TapHash()
+	require.Equal(t, expectedRoot[:], tapscript.RootHash)
+
+	expectedKey := txscript.ComputeTaprootOutputKey(
+		&ARKNUMSKey, tapscript.RootHash,
+	)
+
+	actualKey, err := tapscript.TaprootKey()
+	require.NoError(t, err)
+	require.Equal(t, expectedKey.SerializeCompressed(),
+		actualKey.SerializeCompressed())
+}