feat: add non-custodial signing flow (key_mode, prepare/execute API, external registration)

pkg/app/api/server.go

@@ -24,6 +24,7 @@ import (
 	"github.com/chainsafe/canton-middleware/pkg/registry"
 	"github.com/chainsafe/canton-middleware/pkg/token"
 	tokenprovider "github.com/chainsafe/canton-middleware/pkg/token/provider"
+	"github.com/chainsafe/canton-middleware/pkg/transfer"
 	userservice "github.com/chainsafe/canton-middleware/pkg/user/service"
 	"github.com/chainsafe/canton-middleware/pkg/userstore"
 
@@ -32,7 +33,12 @@ import (
 	"go.uber.org/zap"
 )
 
-const defaultRequestTimeout = 60
+const (
+	defaultRequestTimeout = 60
+	topologyCacheTTL      = 5 * time.Minute
+	transferCacheTTL      = 2 * time.Minute
+	transferCacheMaxSize  = 10000
+)
 
 // Server holds cfg to init the api server.
 type Server struct {
@@ -99,19 +105,28 @@ func (s *Server) Run() error {
 	// Keep this defer as a safety net.
 	defer stopReconcile()
 
+	topologyCache := userservice.NewTopologyCache(topologyCacheTTL)
+	go topologyCache.Start(ctx)
+
 	registrationService := userservice.NewService(
 		userStore,
 		cantonClient.Identity,
 		cipher,
 		logger,
 		cfg.SkipCantonSigVerify,
+		topologyCache,
 	)
 
 	tokenDataProvider := tokenprovider.NewCanton(cantonClient.Token)
 	tokenService := token.NewTokenService(cfg.Token, tokenDataProvider, userStore, cantonClient.Token)
 	evmStore := ethrpcstore.NewStore(dbBun)
 
-	router := s.setupRouter(evmStore, cantonClient, tokenService, userservice.NewLog(registrationService, logger), logger)
+	transferCache := transfer.NewPreparedTransferCache(transferCacheTTL, transferCacheMaxSize)
+	go transferCache.Start(ctx)
+	transferSvc := transfer.NewTransferService(cantonClient.Token, userStore, transferCache, tokenSymbols(cfg.Token))
+	regSvcLog := userservice.NewLog(registrationService, logger)
+	transferSvcLog := transfer.NewLog(transferSvc, logger)
+	router := s.setupRouter(evmStore, cantonClient, tokenService, regSvcLog, transferSvcLog, logger)
 
 	err = apphttp.ServeAndWait(ctx, router, logger, cfg.Server)
 
@@ -210,6 +225,7 @@ func (s *Server) setupRouter(
 	cantonClient *canton.Client,
 	tokenService *token.Service,
 	registrationService userservice.Service,
+	transferSvc transfer.Service,
 	logger *zap.Logger,
 ) chi.Router {
 	r := chi.NewRouter()
@@ -229,6 +245,9 @@ func (s *Server) setupRouter(
 	// Registration endpoints
 	userservice.RegisterRoutes(r, registrationService, logger)
 
+	// Non-custodial transfer endpoints (prepare/execute)
+	transfer.RegisterRoutes(r, transferSvc, logger)
+
 	registryHandler := registry.NewHandler(cantonClient.Token, logger)
 	r.Handle("/registry/transfer-instruction/v1/transfer-factory", registryHandler)
 	logger.Info("Splice Registry API enabled",
@@ -242,3 +261,16 @@ func (s *Server) setupRouter(
 
 	return r
 }
+
+// tokenSymbols extracts the unique symbol strings from the token config.
+func tokenSymbols(cfg *token.Config) []string {
+	seen := make(map[string]bool, len(cfg.SupportedTokens))
+	var symbols []string
+	for _, tkn := range cfg.SupportedTokens {
+		if !seen[tkn.Symbol] {
+			seen[tkn.Symbol] = true
+			symbols = append(symbols, tkn.Symbol)
+		}
+	}
+	return symbols
+}

pkg/app/errors/errors.go

@@ -28,6 +28,8 @@ const (
 	CategoryDataConflict
 	// CategoryLocked The client is not able to access the requested resource due to its locked state
 	CategoryLocked
+	// CategoryGone The resource existed but is no longer available (e.g. expired)
+	CategoryGone
 	// CategoryDependencyFailure A dependent service is throwing errors
 	CategoryDependencyFailure
 	// CategoryGeneralError The service failed in an unexpected way
@@ -54,6 +56,8 @@ func (c Category) String() string {
 		return "CategoryDataConflict"
 	case CategoryLocked:
 		return "CategoryLocked"
+	case CategoryGone:
+		return "CategoryGone"
 	case CategoryDependencyFailure:
 		return "CategoryDependencyFailure"
 	case CategoryRecovering:
@@ -208,6 +212,19 @@ func DependencyError(err error, message string) error {
 	}
 }
 
+// GoneError returns an error with category CategoryGone (HTTP 410).
+// Use when a resource existed but is no longer available (e.g. expired transfers).
+func GoneError(err error, message string) error {
+	if err == nil {
+		err = errors.New("gone: " + message)
+	}
+	return &ServiceError{
+		Category: CategoryGone,
+		Message:  message,
+		Err:      err,
+	}
+}
+
 // ConflictError returns an error with category CategoryDataConflict
 // the error message provided is returned to the user
 // the error object provided is logged in logger
@@ -253,6 +270,8 @@ func (err ServiceError) StatusCode() int {
 		return http.StatusConflict
 	case CategoryLocked:
 		return http.StatusLocked
+	case CategoryGone:
+		return http.StatusGone
 	case CategoryDependencyFailure:
 		return http.StatusBadGateway
 	case CategoryGeneralError:

pkg/auth/evm.go

@@ -3,7 +3,9 @@ package auth
 import (
 	"encoding/hex"
 	"fmt"
+	"strconv"
 	"strings"
+	"time"
 
 	"github.com/ethereum/go-ethereum/common"
 	"github.com/ethereum/go-ethereum/crypto"
@@ -69,3 +71,30 @@ func ValidateEVMAddress(address string) bool {
 func NormalizeAddress(address string) string {
 	return common.HexToAddress(address).Hex()
 }
+
+// ValidateTimedMessage checks that a message contains a Unix timestamp suffix
+// (format: "{prefix}:{unix_seconds}") and that it is within maxAge of now.
+// This provides replay protection: captured signatures expire after maxAge.
+func ValidateTimedMessage(msg string, maxAge time.Duration) error {
+	idx := strings.LastIndex(msg, ":")
+	if idx < 0 || idx == len(msg)-1 {
+		return fmt.Errorf("message must contain a colon-separated Unix timestamp (e.g. transfer:1710000000)")
+	}
+
+	tsStr := msg[idx+1:]
+	ts, err := strconv.ParseInt(tsStr, 10, 64)
+	if err != nil {
+		return fmt.Errorf("invalid timestamp in message: %w", err)
+	}
+
+	msgTime := time.Unix(ts, 0)
+	age := time.Since(msgTime)
+	if age < 0 {
+		age = -age
+	}
+	if age > maxAge {
+		return fmt.Errorf("message expired: timestamp is %s old (max %s)", age.Truncate(time.Second), maxAge)
+	}
+
+	return nil
+}

pkg/cantonsdk/identity/client.go

@@ -38,6 +38,15 @@ type Identity interface {
 	GetFingerprintMapping(ctx context.Context, fingerprint string) (*FingerprintMapping, error)
 
 	GrantActAsParty(ctx context.Context, partyID string) error
+
+	// GenerateExternalPartyTopology generates the topology transactions and multi-hash
+	// needed for external party allocation. The multi-hash must be signed by the party's
+	// private key and submitted via AllocateExternalPartyWithSignature.
+	GenerateExternalPartyTopology(ctx context.Context, hint string, spkiPublicKey []byte) (*ExternalPartyTopology, error)
+
+	// AllocateExternalPartyWithSignature completes external party allocation using
+	// a client-provided DER signature of the topology multi-hash.
+	AllocateExternalPartyWithSignature(ctx context.Context, topology *ExternalPartyTopology, derSignature []byte) (*Party, error)
 }
 
 // Client implements the Identity interface.
@@ -142,6 +151,69 @@ func (c *Client) AllocateExternalParty(ctx context.Context, hint string, spkiPub
 	}, nil
 }
 
+func (c *Client) GenerateExternalPartyTopology(ctx context.Context, hint string, spkiPublicKey []byte) (*ExternalPartyTopology, error) {
+	authCtx := c.ledger.AuthContext(ctx)
+
+	pubKey := &lapiv2.SigningPublicKey{
+		Format:  lapiv2.CryptoKeyFormat_CRYPTO_KEY_FORMAT_DER_X509_SUBJECT_PUBLIC_KEY_INFO,
+		KeyData: spkiPublicKey,
+		KeySpec: lapiv2.SigningKeySpec_SIGNING_KEY_SPEC_EC_SECP256K1,
+	}
+
+	topoResp, err := c.ledger.PartyAdmin().GenerateExternalPartyTopology(authCtx, &adminv2.GenerateExternalPartyTopologyRequest{
+		Synchronizer: c.cfg.DomainID,
+		PartyHint:    hint,
+		PublicKey:    pubKey,
+	})
+	if err != nil {
+		return nil, fmt.Errorf("generate external party topology: %w", err)
+	}
+
+	return &ExternalPartyTopology{
+		TopologyTransactions: topoResp.TopologyTransactions,
+		MultiHash:            topoResp.MultiHash,
+		Fingerprint:          topoResp.PublicKeyFingerprint,
+	}, nil
+}
+
+func (c *Client) AllocateExternalPartyWithSignature(
+	ctx context.Context, topology *ExternalPartyTopology, derSignature []byte,
+) (*Party, error) {
+	authCtx := c.ledger.AuthContext(ctx)
+
+	multiHashSig := &lapiv2.Signature{
+		Format:               lapiv2.SignatureFormat_SIGNATURE_FORMAT_DER,
+		Signature:            derSignature,
+		SignedBy:             topology.Fingerprint,
+		SigningAlgorithmSpec: lapiv2.SigningAlgorithmSpec_SIGNING_ALGORITHM_SPEC_EC_DSA_SHA_256,
+	}
+
+	signedTxs := make([]*adminv2.AllocateExternalPartyRequest_SignedTransaction, len(topology.TopologyTransactions))
+	for i, tx := range topology.TopologyTransactions {
+		signedTxs[i] = &adminv2.AllocateExternalPartyRequest_SignedTransaction{
+			Transaction: tx,
+		}
+	}
+
+	allocResp, err := c.ledger.PartyAdmin().AllocateExternalParty(authCtx, &adminv2.AllocateExternalPartyRequest{
+		Synchronizer:           c.cfg.DomainID,
+		OnboardingTransactions: signedTxs,
+		MultiHashSignatures:    []*lapiv2.Signature{multiHashSig},
+	})
+	if err != nil {
+		return nil, fmt.Errorf("allocate external party: %w", err)
+	}
+
+	c.logger.Info("Allocated external party with client signature",
+		zap.String("party_id", allocResp.PartyId),
+		zap.String("key_fingerprint", topology.Fingerprint))
+
+	return &Party{
+		PartyID: allocResp.PartyId,
+		IsLocal: false,
+	}, nil
+}
+
 func (c *Client) ListParties(ctx context.Context) ([]*Party, error) {
 	authCtx := c.ledger.AuthContext(ctx)
 

pkg/cantonsdk/identity/types.go

@@ -1,6 +1,8 @@
 package identity
 
-import "errors"
+import (
+	"errors"
+)
 
 // Party contains the result of allocating a new Canton party.
 type Party struct {
@@ -17,6 +19,14 @@ type FingerprintMapping struct {
 	EvmAddress  string
 }
 
+// ExternalPartyTopology holds the intermediate state from GenerateExternalPartyTopology
+// needed to complete external party allocation with a client-provided signature.
+type ExternalPartyTopology struct {
+	TopologyTransactions [][]byte // Serialized topology transactions
+	MultiHash            []byte   // Hash to be signed by the party's key
+	Fingerprint          string   // Canton key fingerprint (multihash of SPKI public key)
+}
+
 // CreateFingerprintMappingRequest contains inputs for creating a FingerprintMapping.
 type CreateFingerprintMappingRequest struct {
 	UserParty   string