Guppy

https://github.com/storacha/guppy
Admin
Guppy is a Storacha client in Go for enterprise-scale, resumable file uploads with parallel...
Tokens:6,433
Snippets:47
Trust Score:9.2
Update:7 months ago
Show doc for...
Tokens:
Raw
### Clone and Build Guppy on macOS and Linux

Source: https://github.com/storacha/guppy/blob/main/CONTRIBUTING.md

Standard procedure for setting up the Guppy project on Unix-based systems using Makefile commands. This includes cloning the repository, installing dependencies, building the binary, and running tests.

```bash
git clone https://github.com/storacha/guppy.git
cd guppy
go mod download
make build
./guppy --help
make test
```

--------------------------------

### Clone and Build Guppy on Windows

Source: https://github.com/storacha/guppy/blob/main/CONTRIBUTING.md

Instructions for cloning the repository, downloading Go modules, and building the executable on Windows systems. It is recommended to avoid OneDrive-synced folders to prevent build artifact corruption.

```powershell
git clone https://github.com/storacha/guppy.git
cd guppy
go mod download
go build -o guppy.exe .
.\guppy.exe --help
```

--------------------------------

### Initialize Guppy Client

Source: https://github.com/storacha/guppy/blob/main/CLAUDE.md

Example of using the functional options pattern to instantiate a new Storacha client with custom storage and principal configurations.

```go
client.NewClient(client.WithStore(myStore), client.WithPrincipal(myPrincipal))
```

--------------------------------

### Upload Blob to Storacha Space (Go)

Source: https://context7.com/storacha/guppy/llms.txt

Provides a Go code example for uploading binary content (blob) to a Storacha space. It covers the entire upload process, including allocation, PUT requests, and acceptance. It also shows how to implement progress callbacks.

```go
package main

import (
    "context"
    "fmt"
    "os"

    "github.com/storacha/go-ucanto/did"
    "github.com/storacha/guppy/pkg/client"
)

func main() {
    ctx := context.Background()

    // Assume client is already authenticated
    c, _ := client.NewClient( /* ... */ )

    space, _ := did.Parse("did:key:z6MkwDuRThQcyWjqNsK54yKAmzfsiH6BTkASyiucThMtHt1y")

    // Open file to upload
    file, err := os.Open("path/to/file.dat")
    if err != nil {
        panic(err)
    }
    defer file.Close()

    // Upload blob to space
    addedBlob, err := c.SpaceBlobAdd(ctx, file, space)
    if err != nil {
        panic(fmt.Errorf("uploading blob: %w", err))
    }

    fmt.Printf("Uploaded blob:\n")
    fmt.Printf("  Digest: %x\n", addedBlob.Digest)
    fmt.Printf("  Size: %d bytes\n", addedBlob.Size)

    // Upload with progress callback
    stat, _ := file.Stat()
    file.Seek(0, 0)

    addedBlob, err = c.SpaceBlobAdd(ctx, file, space, 
        client.WithPutProgress(func(uploaded int64) {
            pct := float64(uploaded) / float64(stat.Size()) * 100
            fmt.Printf("\rProgress: %.1f%%", pct)
        }),
    )
    if err != nil {
        panic(err)
    }
    fmt.Println("\nUpload complete!")
}
```

--------------------------------

### Manage Database Migrations

Source: https://github.com/storacha/guppy/blob/main/CONTRIBUTING.md

Commands for managing database schema changes using the Goose migration tool. These shortcuts allow developers to create, apply, revert, or check the status of migrations.

```makefile
# Create a new migration
make migration NAME=<new-migration-name>

# Manual migration commands
migrate-up
migrate-down
migrate-reset
migrate-status
```

--------------------------------

### Create Storacha Client with Go

Source: https://context7.com/storacha/guppy/llms.txt

Demonstrates how to create a new client for interacting with the Storacha network using the Go client library. It covers creating clients with default settings, custom identity stores, specific principals, and additional proofs.

```go
package main

import (
    "github.com/storacha/guppy/pkg/client"
    "github.com/storacha/guppy/pkg/agentstore"
)

func main() {
    // Create client with defaults (generates new identity, uses default connection)
    c, err := client.NewClient()
    if err != nil {
        panic(err)
    }

    // Create client with custom store (for persistent identity)
    store, _ := agentstore.NewFileStore("/path/to/data")
    c, err = client.NewClient(
        client.WithStore(store),
    )

    // Create client with specific principal (bring your own identity)
    signer, _ := signer.FromRaw(privateKeyBytes)
    c, err = client.NewClient(
        client.WithPrincipal(signer),
    )

    // Create client with additional proofs (for single operation)
    proof, _ := delegation.ExtractProof(proofBytes)
    c, err = client.NewClient(
        client.WithPrincipal(signer),
        client.WithAdditionalProofs(proof),
    )

    // Get client's DID
    agentDID := c.DID()
    fmt.Println("Agent DID:", agentDID)
}
```

--------------------------------

### Authenticate with Pre-Authorized Identity (Go)

Source: https://context7.com/storacha/guppy/llms.txt

Demonstrates how to use a pre-authorized identity with delegated capabilities for authentication, bypassing interactive login. It requires loading a private key and a UCAN proof file.

```go
package main

import (
    "context"
    "fmt"
    "os"

    uploadcap "github.com/storacha/go-libstoracha/capabilities/upload"
    "github.com/storacha/go-ucanto/did"
    "github.com/storacha/go-ucanto/principal/ed25519/signer"
    "github.com/storacha/guppy/pkg/client"
    "github.com/storacha/guppy/pkg/delegation"
)

func main() {
    ctx := context.Background()

    // Load private key for signing invocations
    keyBytes, err := os.ReadFile("path/to/private.key")
    if err != nil {
        panic(err)
    }
    signer, err := signer.FromRaw(keyBytes)
    if err != nil {
        panic(err)
    }

    // Load UCAN proof (delegation chain granting capabilities)
    proofBytes, err := os.ReadFile("path/to/proof.ucan")
    if err != nil {
        panic(err)
    }
    proof, err := delegation.ExtractProof(proofBytes)
    if err != nil {
        panic(err)
    }

    // Space to interact with
    space, _ := did.Parse("did:key:z6MkwDuRThQcyWjqNsK54yKAmzfsiH6BTkASyiucThMtHt1y")

    // Create client with identity and proofs
    c, err := client.NewClient(
        client.WithPrincipal(signer),
        client.WithAdditionalProofs(proof),
    )
    if err != nil {
        panic(err)
    }

    // List uploads in the space
    listOk, err := c.UploadList(ctx, space, uploadcap.ListCaveats{})
    if err != nil {
        panic(err)
    }

    fmt.Printf("Found %d uploads\n", len(listOk.Results))
    for _, r := range listOk.Results {
        fmt.Printf("  Root: %s, Shards: %d\n", r.Root, len(r.Shards))
    }
}
```

--------------------------------

### Query Storacha Spaces and Proofs (Go)

Source: https://context7.com/storacha/guppy/llms.txt

Illustrates how to query available spaces and capability proofs within the Storacha client. It covers listing all accessible spaces, finding a space by name, and filtering proofs by capability and associated DID.

```go
package main

import (
    "fmt"

    "github.com/storacha/guppy/pkg/client"
    "github.com/storacha/guppy/pkg/agentstore"
)

func main() {
    c, _ := client.NewClient( /* ... */ )

    // List all accessible spaces
    spaces, err := c.Spaces()
    if err != nil {
        panic(err)
    }

    for _, space := range spaces {
        fmt.Printf("Space: %s\n", space.DID())
        fmt.Printf("  Names: %v\n", space.Names())
        fmt.Printf("  Proofs: %d delegations\n", len(space.AccessProofs()))
    }

    // Find space by name
    space, err := c.SpaceNamed("my-project-data")
    if err != nil {
        // Returns SpaceNotFoundError or MultipleSpacesFoundError
        panic(err)
    }
    fmt.Printf("Found space: %s\n", space.DID())

    // Query proofs by capability
    proofs, err := c.Proofs(agentstore.CapabilityQuery{
        Can:  "space/blob/add",
        With: space.DID().String(),
    })
    if err != nil {
        panic(err)
    }
    fmt.Printf("Found %d proofs for space/blob/add\n", len(proofs))

    // Get all proofs (no filter)
    allProofs, _ := c.Proofs()
    fmt.Printf("Total proofs stored: %d\n", len(allProofs))
}
```

--------------------------------

### Build and Manage Guppy CLI

Source: https://github.com/storacha/guppy/blob/main/CLAUDE.md

Standard make commands for building the binary, executing test suites, and managing database migrations within the Guppy project.

```bash
make build          # Build ./guppy binary
make test           # Run tests
make migration NAME=x  # Create migration
```

--------------------------------

### List Stored Uploads and Blobs with Go SDK

Source: https://context7.com/storacha/guppy/llms.txt

Demonstrates how to use the Guppy Go client to retrieve lists of uploads and individual blobs within a specific storage space. It requires a client instance and a valid DID for the space, returning paginated results for both uploads and blobs.

```go
package main

import (
    "context"
    "fmt"

    uploadcap "github.com/storacha/go-libstoracha/capabilities/upload"
    spaceblobcap "github.com/storacha/go-libstoracha/capabilities/space/blob"
    "github.com/storacha/go-ucanto/did"
    "github.com/storacha/guppy/pkg/client"
)

func main() {
    ctx := context.Background()
    c, _ := client.NewClient( /* ... */ )
    space, _ := did.Parse("did:key:z6Mk...")

    // List uploads (roots with their shards)
    uploadList, err := c.UploadList(ctx, space, uploadcap.ListCaveats{})
    if err != nil {
        panic(err)
    }

    fmt.Printf("Uploads (size: %d):\n", uploadList.Size)
    for _, upload := range uploadList.Results {
        fmt.Printf("  Root: %s\n", upload.Root)
        fmt.Printf("    Shards: %d\n", len(upload.Shards))
    }

    // List individual blobs
    blobList, err := c.SpaceBlobList(ctx, space, spaceblobcap.ListCaveats{})
    if err != nil {
        panic(err)
    }

    fmt.Printf("\nBlobs (size: %d):\n", blobList.Size)
    for _, blob := range blobList.Results {
        fmt.Printf("  Digest: %x, Size: %d\n", blob.Blob.Digest, blob.Blob.Size)
    }
}
```

--------------------------------

### Configure Guppy via Environment Variables

Source: https://context7.com/storacha/guppy/llms.txt

Lists essential environment variables for configuring Guppy, including network presets, tracing, profiling, and gateway settings. These variables allow for runtime customization of the client's behavior without modifying configuration files.

```bash
export GUPPY_DATA_DIR="/custom/data/path"
export STORACHA_SERVICE_URL="https://up.forge.storacha.network"
export STORACHA_NETWORK="forge"
export GUPPY_TRACING_ENABLED=1
export GUPPY_GATEWAY_PORT=3000
```

--------------------------------

### Configure Guppy via TOML File

Source: https://context7.com/storacha/guppy/llms.txt

Provides a template for the Guppy configuration file, typically located at ~/.config/guppy/config.toml. This allows for persistent settings regarding repository storage, network endpoints, and gateway behavior.

```toml
[repo]
  data_dir = "~/.storacha/guppy"

[network]
  name = "hot"

[gateway]
  port = 3000
  log_level = "warn"
  trusted = true
```

--------------------------------

### Interactive Login Flow with Go Client

Source: https://context7.com/storacha/guppy/llms.txt

Implements the email-based authentication flow for authorizing an agent with a Storacha account using the Go client library. This involves requesting access, polling for confirmation via email, and adding received proofs to the client for subsequent interactions.

```go
package main

import (
    "context"
    "fmt"

    uploadcap "github.com/storacha/go-libstoracha/capabilities/upload"
    "github.com/storacha/go-ucanto/core/result"
    "github.com/storacha/go-ucanto/did"
    "github.com/storacha/guppy/pkg/client"
)

func main() {
    ctx := context.Background()

    // Space to access after login
    space, _ := did.Parse("did:key:z6MkwDuRThQcyWjqNsK54yKAmzfsiH6BTkASyiucThMtHt1y")

    // Account email to authenticate as
    account, _ := did.Parse("did:mailto:example.com:user")

    // Create client (generates new identity automatically)
    c, _ := client.NewClient()

    // Request access - sends authorization email
    authOk, err := c.RequestAccess(ctx, account.String())
    if err != nil {
        panic(fmt.Errorf("requesting access: %w", err))
    }

    // Poll for authorization confirmation
    fmt.Println("Please click the link in your email to authenticate...")
    resultChan := c.PollClaim(ctx, authOk)

    // Wait for user to click email link
    proofs, err := result.Unwrap(<-resultChan)
    if err != nil {
        panic(fmt.Errorf("claiming access: %w", err))
    }

    // Add received proofs to client
    c.AddProofs(proofs...)

    // Now we can use the client to interact with spaces
    listOk, err := c.UploadList(ctx, space, uploadcap.ListCaveats{})
    if err != nil {
        panic(err)
    }

    for _, r := range listOk.Results {
        fmt.Printf("Upload root: %s\n", r.Root)
    }
}
```

--------------------------------

### Verify DAG Integrity with Guppy CLI

Source: https://context7.com/storacha/guppy/llms.txt

Verifies the integrity and availability of a DAG stored on the network using the Guppy CLI. It takes a root CID as input and outputs verification details including shards, origins, total blocks, and total size.

```bash
# Verify a root CID
guppy verify bafybeibhybbpoqakv7pfj5nlrpmldkgiuksmbi3t2cnhxqxnqvbzkhyzjy

# Output shows:
# - Root CID
# - Shards (with verified block counts)
# - Origins (storage providers serving the content)
# - Total blocks verified
# - Total size
```

--------------------------------

### Display Agent Identity with Guppy CLI

Source: https://context7.com/storacha/guppy/llms.txt

Prints the Decentralized Identifier (DID) of the local agent using the Guppy CLI. This command is useful for identifying the current agent's unique identifier on the network.

```bash
guppy whoami
# Output: did:key:z6MkwDuRThQcyWjqNsK54yKAmzfsiH6BTkASyiucThMtHt1y
```
Tokens:
Raw