Skip to content

AGENTS.md

Latest commit

 

History

History
57 lines (44 loc) · 4.28 KB

AGENTS.md

File metadata and controls

57 lines (44 loc) · 4.28 KB

AGENTS.md

This file provides guidance to AI coding agents (Claude Code, Codex, Cursor, Copilot, and others) working in this repository. It is loaded into agent context automatically — keep it concise.

Overview

github.com/onflow/flow-go-sdk is the reference Go SDK for the Flow blockchain. It provides client packages for the Flow Access API over gRPC and HTTP, Cadence-aware transaction and script helpers, ECDSA/BLS crypto primitives, and account-creation templates. The module is compatible with the Flow Emulator for local development.

Build and Test Commands

Targets from the root Makefile:

  • make test — full test suite with coverage (writes coverage.txt). Sets CGO_CFLAGS via crypto_adx_flag.mk.
  • make coverage — runs test, then go tool cover -html=coverage.txt.
  • make generate — installs mockery v2.53.5 and runs go generate ./... to regenerate mocks.
  • make check-tidy — runs generate, then go mod tidy, then fails if the working tree is dirty.
  • make check-headers — runs ./check-headers.sh; fails if any .go file is missing the Apache-2.0 header.
  • make ci — full CI pipeline: check-tidy + test + coverage. Matches .github/workflows/ci.yml.
  • make generate-openapi — regenerates access/http/models/ from the upstream Flow OpenAPI spec (requires swagger-codegen).

Examples live in a separate Go module under examples/ with its own Makefile. Run via make -C examples <target> (e.g. make -C examples send-transactions). Examples require a running Flow Emulator — see examples/README.md.

Architecture

  • Root package flow — core domain types: Account, Transaction, Block, Event, Collection, Address.
  • access/ — Client interface (the primary SDK surface). Two implementations:
    • access/grpc/ — gRPC client (grpc.NewClient, grpc.MainnetHost, grpc.TestnetHost, grpc.EmulatorHost). Recommended transport per README.
    • access/http/ — REST client. access/http/models/ is generated from OpenAPI.
  • crypto/ — key generation, signing, hashing. crypto/awskms/ and crypto/cloudkms/ provide AWS KMS and Google Cloud KMS signers.
  • templates/ — prebuilt Cadence transactions for account creation and key management.
  • test/ — test fixtures (entities.go, greetings.go, signer.go).
  • client/ — deprecated; re-exports access/grpc. New code should import access/grpc directly (see client/client.go doc comment).
  • examples/ — runnable end-to-end examples against the Flow Emulator. Separate Go module with a replace directive back to the SDK root (examples/go.mod).

Conventions and Gotchas

  • Go 1.25.0 required (go.mod). CI pins go-version: '1.25' in .github/workflows/ci.yml.
  • CGO is required by default for BLS support (via github.com/onflow/crypto). Build with CGO_ENABLED=1. You can build with CGO_ENABLED=0 but must also pass the no-cgo build tag; any BLS call will then panic at runtime (README: Installing).
  • ADX instructions: crypto_adx_flag.mk detects CPU support and sets CRYPTO_FLAG for BLST. Always invoke via the Makefile (not raw go test) to pick up the flag on older machines.
  • Regenerate mocks after interface changes: run make generate whenever you touch access.Client, access/grpc.RPCClient, access/grpc.ExecutionDataRPCClient, or access/http.handler — go:generate directives in those files drive mockery. make check-tidy fails CI if generated output is not committed.
  • Apache-2.0 license header required on every .go file — enforced by check-headers.sh in CI.
  • Do not edit client/ — deprecated shim retained for backward compatibility.
  • CONTRIBUTING.md mentions make lint — no such target exists in the Makefile. Use gofmt and go vet directly.
  • When writing portable code, depend on the access.Client interface so callers can swap gRPC/HTTP; reach for grpc.BaseClient / http.BaseClient only when transport-specific options are needed (access/README.md).

Files Not to Modify

  • access/http/models/*.go — generated by swagger-codegen via make generate-openapi.
  • access/grpc/mocks/*.go, access/mocks/Client.go, access/http/mock_handler.go — generated by mockery via make generate.
  • client/client.go — deprecated shim.
  • go.sum — managed by go mod.