Add Canton gRPC Service Clients to provider output (NONEVM-3770) (#737)

This updates the Canton chain providers to:
- Directly return gRPC service clients for all available services
- All these service clients are already authenticated, i.e. they have a
oauth2 token provider setup to automatically add PerRPCCredentials to
all outgoing calls
- Remove the custom `JWTProvider` implementation and replace with an
`authentication.Provider` that re-uses existing oauth2 implementations
- Add UserID & PartyID to output, since those are required by clients in
order to interact with Canton

Follow-up for:
#673

Author: friedemannf

.changeset/polite-loops-beg.md

@@ -0,0 +1,9 @@
+---
+"chainlink-deployments-framework": minor
+---
+
+feat(chain): update Canton support to support clients and authentication
+
+- Add gRPC service clients to Canton chain output
+- Add UserID and PartyID to Canton chain output
+- Remove JWTProvider and replace with oauth2.TokenSource for authentication

chain/canton/canton_chain.go

@@ -1,12 +1,19 @@
 package canton
 
 import (
+	"golang.org/x/oauth2"
+	"google.golang.org/grpc"
+
+	apiv2 "github.com/digital-asset/dazl-client/v8/go/api/com/daml/ledger/api/v2"
+	adminv2 "github.com/digital-asset/dazl-client/v8/go/api/com/daml/ledger/api/v2/admin"
+	participantv30 "github.com/digital-asset/dazl-client/v8/go/api/com/digitalasset/canton/admin/participant/v30"
+
 	chaincommon "github.com/smartcontractkit/chainlink-deployments-framework/chain/internal/common"
 )
 
 type ChainMetadata = chaincommon.ChainMetadata
 
-// Chain represents a Canton network instance used CLDF.
+// Chain represents a Canton network instance initialized by CLDF.
 // It contains chain metadata and augments it with Canton-specific information.
 // In particular, it tracks all known Canton participants and their connection
 // details so that callers can discover and interact with the network's APIs.
@@ -22,15 +29,26 @@ type Chain struct {
 // A participant hosts parties and their local ledger state, and mediates all
 // interactions with the Canton ledger for those parties via its exposed APIs
 // (ledger, admin, validator, etc.). It is identified by a human-readable
-// name, provides a set of API endpoints, and uses a JWT provider to issue
+// name, provides a set of API endpoints, and uses a TokenSource to issue
 // authentication tokens for secure access to those endpoints.
 type Participant struct {
 	// A human-readable name for the participant
 	Name string
 	// The endpoints to interact with the participant's APIs
 	Endpoints ParticipantEndpoints
-	// A JWT provider instance to generate JWTs for authentication with the participant's APIs
-	JWTProvider JWTProvider
+	// The set of service clients to interact with the participant's Ledger API.
+	// All clients are ready-to-use and are already configured with the correct authentication.
+	LedgerServices LedgerServiceClients
+	// (Optional) The set of service clients to interact with the participant's Admin API.
+	// Will only be populated if the participant has been configured with an Admin API URL
+	AdminServices *AdminServiceClients
+	// An OAuth2 token source to obtain access tokens for authentication with the participant's APIs
+	TokenSource oauth2.TokenSource
+	// The UserID that will be used to interact with this participant.
+	// The TokenSource will return access tokens containing this UserID as a subject claim.
+	UserID string
+	// The PartyID that will be used to interact with this participant.
+	PartyID string
 }
 
 // ParticipantEndpoints holds all available API endpoints for a Canton participant
@@ -46,5 +64,87 @@ type ParticipantEndpoints struct {
 	AdminAPIURL string
 	// (HTTP) The URL to access the participant's Validator API
 	// https://docs.sync.global/app_dev/validator_api/index.html
+	// This also serves the Scan Proxy API, which provides access to the Global Scan and Token Standard APIs:
+	// https://docs.sync.global/app_dev/validator_api/index.html#validator-api-scan-proxy
 	ValidatorAPIURL string
 }
+
+// LedgerAdminServiceClients provides all available Ledger API admin gRPC service clients.
+type LedgerAdminServiceClients struct {
+	CommandInspection      adminv2.CommandInspectionServiceClient
+	IdentityProviderConfig adminv2.IdentityProviderConfigServiceClient
+	PackageManagement      adminv2.PackageManagementServiceClient
+	ParticipantPruning     adminv2.ParticipantPruningServiceClient
+	PartyManagement        adminv2.PartyManagementServiceClient
+	UserManagement         adminv2.UserManagementServiceClient
+}
+
+// LedgerServiceClients provides all available Ledger API gRPC service clients.
+type LedgerServiceClients struct {
+	CommandCompletion apiv2.CommandCompletionServiceClient
+	Command           apiv2.CommandServiceClient
+	CommandSubmission apiv2.CommandSubmissionServiceClient
+	EventQuery        apiv2.EventQueryServiceClient
+	PackageService    apiv2.PackageServiceClient
+	State             apiv2.StateServiceClient
+	Update            apiv2.UpdateServiceClient
+	Version           apiv2.VersionServiceClient
+	// Ledger API admin clients
+	// These endpoints can only be accessed if the user the participant has been configured with
+	// has admin rights. Access with caution and only if you're certain that admin rights are available.
+	Admin LedgerAdminServiceClients
+}
+
+// CreateLedgerServiceClients creates all LedgerServiceClients given a gRPC client connection.
+func CreateLedgerServiceClients(conn grpc.ClientConnInterface) LedgerServiceClients {
+	return LedgerServiceClients{
+		Admin: LedgerAdminServiceClients{
+			CommandInspection:      adminv2.NewCommandInspectionServiceClient(conn),
+			IdentityProviderConfig: adminv2.NewIdentityProviderConfigServiceClient(conn),
+			PackageManagement:      adminv2.NewPackageManagementServiceClient(conn),
+			ParticipantPruning:     adminv2.NewParticipantPruningServiceClient(conn),
+			PartyManagement:        adminv2.NewPartyManagementServiceClient(conn),
+			UserManagement:         adminv2.NewUserManagementServiceClient(conn),
+		},
+		CommandCompletion: apiv2.NewCommandCompletionServiceClient(conn),
+		Command:           apiv2.NewCommandServiceClient(conn),
+		CommandSubmission: apiv2.NewCommandSubmissionServiceClient(conn),
+		EventQuery:        apiv2.NewEventQueryServiceClient(conn),
+		PackageService:    apiv2.NewPackageServiceClient(conn),
+		State:             apiv2.NewStateServiceClient(conn),
+		Update:            apiv2.NewUpdateServiceClient(conn),
+		Version:           apiv2.NewVersionServiceClient(conn),
+	}
+}
+
+// AdminServiceClients provides all available Admin API service clients.
+// These services can only be accessed if the user the participant has been configured with has
+// admin rights.
+type AdminServiceClients struct {
+	Package                  participantv30.PackageServiceClient
+	ParticipantInspection    participantv30.ParticipantInspectionServiceClient
+	ParticipantRepair        participantv30.ParticipantRepairServiceClient
+	ParticipantStatus        participantv30.ParticipantStatusServiceClient
+	PartyManagement          participantv30.PartyManagementServiceClient
+	Ping                     participantv30.PingServiceClient
+	Pruning                  participantv30.PruningServiceClient
+	ResourceManagement       participantv30.ResourceManagementServiceClient
+	SynchronizerConnectivity participantv30.SynchronizerConnectivityServiceClient
+	TrafficControl           participantv30.TrafficControlServiceClient
+}
+
+// CreateAdminServiceClients creates all AdminServiceClients given a gRPC client connection.
+func CreateAdminServiceClients(conn grpc.ClientConnInterface) AdminServiceClients {
+	return AdminServiceClients{
+		Package:                  participantv30.NewPackageServiceClient(conn),
+		ParticipantInspection:    participantv30.NewParticipantInspectionServiceClient(conn),
+		ParticipantRepair:        participantv30.NewParticipantRepairServiceClient(conn),
+		ParticipantStatus:        participantv30.NewParticipantStatusServiceClient(conn),
+		PartyManagement:          participantv30.NewPartyManagementServiceClient(conn),
+		Ping:                     participantv30.NewPingServiceClient(conn),
+		Pruning:                  participantv30.NewPruningServiceClient(conn),
+		ResourceManagement:       participantv30.NewResourceManagementServiceClient(conn),
+		SynchronizerConnectivity: participantv30.NewSynchronizerConnectivityServiceClient(conn),
+		TrafficControl:           participantv30.NewTrafficControlServiceClient(conn),
+	}
+}

chain/canton/canton_chain_test.go

@@ -1,10 +1,13 @@
 package canton
 
 import (
+	"reflect"
+	"strings"
 	"testing"
 
 	chainsel "github.com/smartcontractkit/chain-selectors"
 	"github.com/stretchr/testify/assert"
+	"google.golang.org/grpc"
 )
 
 func TestChain_ChainInfo(t *testing.T) {
@@ -41,3 +44,39 @@ func TestChain_ChainInfo(t *testing.T) {
 		})
 	}
 }
+
+func TestCreateLedgerServiceClients(t *testing.T) {
+	t.Parallel()
+
+	var conn grpc.ClientConnInterface
+	ledgerServiceClients := CreateLedgerServiceClients(conn)
+	assertNoFieldIsZero(t, ledgerServiceClients)
+	assertNoFieldIsZero(t, ledgerServiceClients.Admin)
+}
+
+func TestCreateAdminServiceClients(t *testing.T) {
+	t.Parallel()
+
+	var conn grpc.ClientConnInterface
+	adminServiceClients := CreateAdminServiceClients(conn)
+	assertNoFieldIsZero(t, adminServiceClients)
+}
+
+// assertNoFieldIsZero checks that all fields of a struct are non-zero. If any field is zero, it fails the test and reports which fields were zero.
+func assertNoFieldIsZero(t *testing.T, structValue any, msgAndArgs ...any) {
+	t.Helper()
+
+	var emptyFields []string
+	structT := reflect.TypeOf(structValue)
+	structV := reflect.ValueOf(structValue)
+	for i := range structT.NumField() {
+		field := structT.Field(i)
+		if structV.Field(i).IsZero() {
+			emptyFields = append(emptyFields, field.Name)
+		}
+	}
+
+	if len(emptyFields) > 0 {
+		assert.Fail(t, "Expected all fields to be set, but the following fields were zero: "+strings.Join(emptyFields, ", "), msgAndArgs...)
+	}
+}

chain/canton/jwt_provider.go

@@ -0,0 +1,82 @@
+package authentication
+
+import (
+	"context"
+
+	"golang.org/x/oauth2"
+	"google.golang.org/grpc/credentials"
+	"google.golang.org/grpc/credentials/insecure"
+)
+
+// Provider provides authentication credentials for connecting to a Canton participant's API endpoints.
+// The Provider acts as both a raw token-source for HTTP API authentication, and a gRPC credentials provider for gRPC endpoint authentication.
+//
+// Implementations of this interface can implement different means of fetching and refreshing authentication tokens,
+// as well as enforcing different levels of transport security. The specific implementation of the Provider
+// should be chosen based on the environment being connected to (e.g. LocalNet vs. production, i.e. CI/OIDC).
+type Provider interface {
+	// TokenSource returns an oauth2.TokenSource that can be used to retrieve access tokens for authenticating with the participant's API endpoints.
+	TokenSource() oauth2.TokenSource
+	// TransportCredentials returns gRPC transport credentials to be used when connecting to the participant's RPC endpoints.
+	TransportCredentials() credentials.TransportCredentials
+	// PerRPCCredentials returns gRPC per-RPC credentials to be used when connecting to the participant's gRPC endpoints.
+	PerRPCCredentials() credentials.PerRPCCredentials
+}
+
+// InsecureStaticProvider is an insecure implementation of Provider that always
+// returns the same static access token and does not provide/enforce transport security.
+// This provider is only suitable for testing against LocalNet or other non-production environments.
+type InsecureStaticProvider struct {
+	AccessToken string
+}
+
+var _ Provider = InsecureStaticProvider{}
+
+func NewInsecureStaticProvider(accessToken string) InsecureStaticProvider {
+	return InsecureStaticProvider{
+		AccessToken: accessToken,
+	}
+}
+
+func (i InsecureStaticProvider) TokenSource() oauth2.TokenSource {
+	return oauth2.StaticTokenSource(&oauth2.Token{
+		AccessToken: i.AccessToken,
+	})
+}
+
+func (i InsecureStaticProvider) TransportCredentials() credentials.TransportCredentials {
+	return insecure.NewCredentials()
+}
+
+func (i InsecureStaticProvider) PerRPCCredentials() credentials.PerRPCCredentials {
+	return insecureTokenSource{
+		TokenSource: i.TokenSource(),
+	}
+}
+
+// insecureTokenSource is an insecure OAuth2 PerRPCCredentials implementation that retrieves tokens from an underlying oauth2.TokenSource.
+// It does not enforce transport security, making it only suitable for testing against LocalNet.
+type insecureTokenSource struct {
+	oauth2.TokenSource
+}
+
+var _ credentials.PerRPCCredentials = insecureTokenSource{}
+
+func (ts insecureTokenSource) GetRequestMetadata(ctx context.Context, uri ...string) (map[string]string, error) {
+	token, err := ts.Token()
+	if err != nil {
+		return nil, err
+	}
+	if token == nil {
+		//nolint:nilnil // nothing to do here, just returning no metadata and no error
+		return nil, nil
+	}
+
+	return map[string]string{
+		"authorization": "Bearer " + token.AccessToken,
+	}, nil
+}
+
+func (ts insecureTokenSource) RequireTransportSecurity() bool {
+	return false
+}

chain/canton/jwt_provider_test.go

@@ -0,0 +1,40 @@
+package authentication
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"google.golang.org/grpc/credentials/insecure"
+)
+
+func TestInsecureStaticProvider(t *testing.T) {
+	t.Parallel()
+
+	testToken := "test-token-123"
+	provider := NewInsecureStaticProvider(testToken)
+
+	// Test that TokenSource returns the correct token
+	token, err := provider.TokenSource().Token()
+	require.NoError(t, err)
+	assert.Equal(t, testToken, token.AccessToken)
+
+	// Test that the provider returns the correct transport credentials
+	transportCredentials := provider.TransportCredentials()
+	assert.Equal(t, insecure.NewCredentials(), transportCredentials)
+
+	// Test that the provider returns the correct per RPC credentials
+	perRPCCredentials := provider.PerRPCCredentials()
+	require.NotNil(t, perRPCCredentials)
+
+	// Test that the RPC credentials return the correct metadata
+	metadata, err := perRPCCredentials.GetRequestMetadata(t.Context())
+	require.NoError(t, err)
+	header, ok := metadata["authorization"]
+	require.True(t, ok, "PerRPCCredentials didn't return authorization header")
+	assert.Equal(t, "Bearer "+testToken, header)
+
+	// Test that the RPC credentials do not require transport security
+	requireTransportSecurity := perRPCCredentials.RequireTransportSecurity()
+	assert.False(t, requireTransportSecurity, "PerRPCCredentials must not require transport security")
+}