Add forgeclient: ingot's Forge client as a shared module

.github/workflows/ci.yml

@@ -11,7 +11,7 @@ name: CI
 # Every module runs on every change. The unit tier used to be path-filtered
 # per service, which was sound while no service module imported another and
 # the shared surface lived in an external library. It stopped being sound
-# when the shared modules (protocol/, internal/, attestation/) and the
+# when the shared modules (protocol/, internal/, attestation/, forgeclient/) and the
 # service-to-service dependencies (ingot -> the indexer's query types,
 # hilt -> smelt's stack harness) moved
 # in-repo: a service's behaviour now depends on directories outside its own
@@ -63,6 +63,7 @@ jobs:
           - protocol
           - internal
           - attestation
+          - forgeclient
           - piri
           - hilt
           - sprue

Makefile

@@ -11,7 +11,7 @@
 #   test    unit tests (fast, no Docker)      image  prod container via
 #   clean   remove build outputs                     docker/Dockerfile
 #
-# The shared library modules (protocol, internal, attestation) implement
+# The shared library modules (protocol, internal, attestation, forgeclient) implement
 # build/vet/test only — they ship no binary and no image. protocol and
 # attestation also carry the codegen gate (`make gen-check`).
 #
@@ -22,7 +22,7 @@
 # Services: independent Go modules that ship a container.
 SERVICES := piri hilt sprue ingot delegator piri-signing-service indexing-service
 # Library modules shared by the services (no binary, no image).
-LIBRARIES := protocol internal attestation
+LIBRARIES := protocol internal attestation forgeclient
 # Everything with Go unit tests (smelt's units join test/vet).
 GO_MODULES := $(LIBRARIES) $(SERVICES) smelt
 

README.md

@@ -16,8 +16,9 @@ independent Go modules.
 | `indexing-service/` | `…/forge/indexing-service` | content-routing index (IPNI + UCAN content claims) |
 | `smelt/` | `…/forge/smelt` | the stack harness: boots the whole network in Docker; owns the e2e, S3 and compatibility suites |
 | `protocol/` | `…/forge/protocol` | the wire contract: every UCAN command binding (`commands/**`), `blobindex`, `receipt`, `retrieval`, and the `bytemap`/`digestutil` helpers they need. Depends only on ucantone and third-party modules |
-| `internal/` | `…/forge/internal` | helpers the services share that are not wire contract: `identity`, `jobqueue`, `piece`, `sigv4`, `s3perm`, `zapucan`, the `client/hilt` and `client/delegator` RPC clients, `pdpsigner`, `ipni/advertisement`. Importable only from this repository |
+| `internal/` | `…/forge/internal` | helpers the services share that are not wire contract: `identity`, `jobqueue`, `piece`, `sigv4`, `s3perm`, `zapucan`, `ucanexec`, the `client/hilt` and `client/delegator` RPC clients, `pdpsigner`, `ipni/advertisement`. Importable only from this repository |
 | `attestation/` | `…/forge/attestation` | the did:mailto attestation extension (`attestation`, `didmailto`, the `attest` command). Depends only on ucantone and multiformats |
+| `forgeclient/` | `…/forge/forgeclient` | the Forge protocol client an agent writes through (`/blob/add`, `/ucan/conclude`, `/index/add`, … against the upload service), its `tokenstore`, and the indexer-backed blob `locator`. ingot is its consumer |
 | `docker/` | — | the one `Dockerfile` every service image builds from |
 | `.github/` | — | CI (`ci.yml`), image publishing, releases, and the compatibility workflow |
 

docker/Dockerfile

@@ -8,7 +8,7 @@
 #         --target {prod|dev} .
 #
 # BUILD CONTEXT IS THE REPOSITORY ROOT. Every service reaches the shared
-# modules (protocol/, internal/, attestation/) — and some reach their siblings
+# modules (protocol/, internal/, attestation/, forgeclient/) — and some reach their siblings
 # (hilt uses smelt's stack harness in its integration tests, ingot uses the
 # indexer's query client) — through replace directives in its go.mod,
 # and a replace target outside the build context cannot be seen, so the
@@ -61,6 +61,7 @@ WORKDIR /src
 COPY protocol/go.mod protocol/go.sum ./protocol/
 COPY internal/go.mod internal/go.sum ./internal/
 COPY attestation/go.mod attestation/go.sum ./attestation/
+COPY forgeclient/go.mod forgeclient/go.sum ./forgeclient/
 COPY smelt/go.mod smelt/go.sum ./smelt/
 COPY indexing-service/go.mod indexing-service/go.sum ./indexing-service/
 COPY ${SERVICE}/go.mod ${SERVICE}/go.sum* ./${SERVICE}/

ingot/forgeclient/accessdelegate.go → forgeclient/accessdelegate.go

@@ -1,4 +1,3 @@
-// Carried from github.com/fil-forge/guppy/pkg/client/accessdelegate.go.
 package forgeclient
 
 import (

ingot/forgeclient/accounts.go → forgeclient/accounts.go

@@ -1,4 +1,3 @@
-// Carried from github.com/fil-forge/guppy/pkg/client/accounts.go.
 package forgeclient
 
 import (

ingot/forgeclient/accounts_test.go → forgeclient/accounts_test.go

@@ -6,7 +6,7 @@ import (
 	"testing"
 
 	"github.com/fil-forge/forge/attestation/didmailto"
-	"github.com/fil-forge/forge/ingot/tokenstore"
+	"github.com/fil-forge/forge/forgeclient/tokenstore"
 	"github.com/fil-forge/ucantone/absentee"
 	"github.com/fil-forge/ucantone/did"
 	"github.com/fil-forge/ucantone/multikey/ed25519"

ingot/forgeclient/blobadd.go → forgeclient/blobadd.go

@@ -1,6 +1,4 @@
-// Carried/trimmed from github.com/fil-forge/guppy/pkg/client/blobadd.go.
-//
-// Ingot divergences from upstream:
+// Differences from the guppy ancestor (github.com/fil-forge/guppy/pkg/client/blobadd.go):
 //   - Proof chains come from a per-call ProofStore (WithProofStore) so an
 //     invocation can be scoped to a request's per-access-key delegations,
 //     not just the client's token store.
@@ -10,7 +8,7 @@
 //     conclude (park at UploadPart, accept at Complete); BlobConclude
 //     finishes the parked add later.
 //
-// Also dropped from upstream: otel spans, go-log, ctxutil, the progress/stall
+// Also dropped from the ancestor: otel spans, go-log, ctxutil, the progress/stall
 // readers, and the hard requirement that the accept receipt carry a PDP
 // accept invocation.
 package forgeclient

ingot/forgeclient/claimaccess.go → forgeclient/claimaccess.go

@@ -1,4 +1,3 @@
-// Carried from github.com/fil-forge/guppy/pkg/client/claimaccess.go.
 package forgeclient
 
 import (

ingot/forgeclient/client.go → forgeclient/client.go

@@ -1,23 +1,26 @@
-// Package forgeclient is ingot's Forge edge-client: it invokes
-// /blob/add, /ucan/conclude, /index/add, /provider/add, /access/delegate
-// (and the /access login flow) against the upload service (sprue),
-// behaving like a guppy node.
+// Package forgeclient is the Forge protocol client for an agent that writes
+// to the network through the upload service (sprue): it invokes /blob/add
+// (with a deferrable conclude), /ucan/conclude, /blob/abort, /blob/remove,
+// /index/add, /provider/add and /access/delegate, runs the /access login
+// flow, and polls for the receipts those invocations produce. Proof chains
+// come from the client's tokenstore.Store, or per call from any
+// ucanlib.ProofStore (WithProofStore).
 //
-// It is a carried, trimmed copy of github.com/fil-forge/guppy/pkg/client
-// (ingot cannot import guppy: guppy embeds ingot → import cycle). The
-// blob-retrieval path is dropped (ingot reads via blockstore/forge.go),
-// the generic Execute is delegated to internal/ucanexec, and the
-// go-log/otel logging is replaced with an injected *zap.Logger. Keep in
-// sync with upstream; see DESIGN_NOTES.md §B.
+// It descends from github.com/fil-forge/guppy/pkg/client by way of the copy
+// ingot carried while it could not import guppy; ingot is its first
+// consumer. Relative to that ancestor, blob retrieval is not part of this
+// package, the generic Execute is internal/ucanexec's, logging is an
+// injected *zap.Logger (WithLogger), and the accept receipt is not required
+// to carry a PDP accept invocation.
 package forgeclient
 
 import (
 	"context"
 	"fmt"
 	"net/url"
 
-	"github.com/fil-forge/forge/ingot/internal/ucanexec"
-	"github.com/fil-forge/forge/ingot/tokenstore"
+	"github.com/fil-forge/forge/forgeclient/tokenstore"
+	"github.com/fil-forge/forge/internal/ucanexec"
 	"github.com/fil-forge/forge/protocol/receipt"
 	"github.com/fil-forge/ucantone/client"
 	"github.com/fil-forge/ucantone/did"

forgeclient/go.mod

@@ -0,0 +1,63 @@
+module github.com/fil-forge/forge/forgeclient
+
+go 1.27.0
+
+replace github.com/fil-forge/forge/protocol => ../protocol
+
+replace github.com/fil-forge/forge/internal => ../internal
+
+replace github.com/fil-forge/forge/attestation => ../attestation
+
+replace github.com/fil-forge/forge/indexing-service => ../indexing-service
+
+require (
+	github.com/fil-forge/forge/attestation v0.0.0
+	github.com/fil-forge/forge/indexing-service v0.0.0
+	github.com/fil-forge/forge/internal v0.0.0
+	github.com/fil-forge/forge/protocol v0.0.0
+	github.com/fil-forge/ucantone v0.0.0-20260904190501-7fca40e13941
+	github.com/ipfs/go-cid v0.6.2
+	github.com/ipfs/go-log/v2 v2.9.2
+	github.com/multiformats/go-multihash v0.2.3
+	github.com/stretchr/testify v1.12.1
+	github.com/whyrusleeping/cbor-gen v0.3.1
+	go.uber.org/zap v1.28.0
+)
+
+require (
+	github.com/alanshaw/dag-json-gen v0.0.9 // indirect
+	github.com/cespare/xxhash/v2 v2.3.0 // indirect
+	github.com/decred/dcrd/dcrec/secp256k1/v4 v4.4.1 // indirect
+	github.com/fil-forge/automobile v0.0.1 // indirect
+	github.com/go-logr/logr v1.4.4 // indirect
+	github.com/go-logr/stdr v1.2.2 // indirect
+	github.com/gobwas/glob v0.2.3 // indirect
+	github.com/ipni/go-libipni v0.8.2 // indirect
+	github.com/klauspost/cpuid/v2 v2.4.0 // indirect
+	github.com/libp2p/go-buffer-pool v0.1.0 // indirect
+	github.com/libp2p/go-libp2p v0.49.0 // indirect
+	github.com/mattn/go-isatty v0.0.24 // indirect
+	github.com/minio/sha256-simd v1.0.1 // indirect
+	github.com/mr-tron/base58 v1.3.0 // indirect
+	github.com/multiformats/go-base32 v0.1.0 // indirect
+	github.com/multiformats/go-base36 v0.2.0 // indirect
+	github.com/multiformats/go-multiaddr v0.16.1 // indirect
+	github.com/multiformats/go-multibase v0.3.0 // indirect
+	github.com/multiformats/go-multicodec v0.10.0 // indirect
+	github.com/multiformats/go-varint v0.1.0 // indirect
+	github.com/spaolacci/murmur3 v1.1.0 // indirect
+	github.com/stretchr/objx v0.5.3 // indirect
+	go.opentelemetry.io/auto/sdk v1.2.1 // indirect
+	go.opentelemetry.io/otel v1.46.0 // indirect
+	go.opentelemetry.io/otel/metric v1.46.0 // indirect
+	go.opentelemetry.io/otel/trace v1.46.0 // indirect
+	go.uber.org/multierr v1.11.0 // indirect
+	go.yaml.in/yaml/v3 v3.0.5 // indirect
+	golang.org/x/crypto v0.55.0 // indirect
+	golang.org/x/exp v0.0.0-20260824195058-e88cd73687aa // indirect
+	golang.org/x/sys v0.47.0 // indirect
+	golang.org/x/xerrors v0.0.0-20240903120638-7835f813f4da // indirect
+	google.golang.org/protobuf v1.36.11 // indirect
+	lukechampine.com/blake3 v1.4.1 // indirect
+	pitr.ca/jsontokenizer v0.3.2 // indirect
+)