feat: claim back expired offers (#339)

* feat(transfer): claim back pending/expired offers (withdraw)

Adds sender-side claim-back for offer-based (registry/AllocationFactory)
transfers — e.g. an unaccepted or expired USDCx offer — so the sender can
reclaim the locked holding by exercising TransferInstruction_Withdraw.

API (3 endpoints):
- POST /api/v2/transfer/outgoing/{contractID}/withdraw/prepare   (non-custodial)
- POST /api/v2/transfer/outgoing/{contractID}/withdraw/execute   (non-custodial; reuses Execute)
- POST /api/v2/transfer/outgoing/{contractID}/withdraw/custodial (custodial, server-signed)

The request is validated against the indexer first (direct lookup by contract
id, new GET /indexer/v1/admin/transfers/{contractID}): the offer must exist, be
owned by the caller (sender), be offer-kind, and still be withdrawable
(pending/expired). Registry "already accepted/archived" conflicts map to 409.

SDK: registry GetWithdrawChoiceContext + client WithdrawTransferInstruction /
PrepareWithdrawTransfer, factored to share the choice-context command builder
and submission tails with the existing accept flow.

Implements #292.

* fix(transfer): nil-guard the indexer lookup in claimableTransfer

Address review: GetTransfer's interface permits (nil, nil); treat a nil
result as not-found rather than dereferencing it.

* test(e2e): claim back an expired USDCx offer to an external party

A custodial sender offers USDCx to an external (unregistered) party with a short
validity; the offer expires unaccepted, the sender claims it back via the
custodial withdraw endpoint, the offer leaves the expired set (archived
on-ledger), and the sender's USDCx balance is whole again.

Adds the WithdrawCustodial e2e shim + APIServer interface method and a
WaitForOutgoingTransferGone DSL helper.

* fix(devstack): serve withdraw choice-context in usdcx-registry

The claim-back (TransferInstruction_Withdraw) flow fetches a withdraw
choice-context from the registrar, but the devstack usdcx-registry mock only
routed .../choice-contexts/accept — so custodial/non-custodial withdraw 500'd
in e2e. Withdraw needs the same instrument-level context (TransferRule +
InstrumentConfiguration) as accept, so route both to the same handler.

Author: sadiq1971

pkg/cantonsdk/token/client.go

@@ -47,6 +47,7 @@ const (
 	spliceTransferFactory = "TransferFactory"
 	transferInstrEntity   = "TransferInstruction"
 	acceptChoice          = "TransferInstruction_Accept"
+	withdrawChoice        = "TransferInstruction_Withdraw"
 
 	spliceHoldingModule = "Splice.Api.Token.HoldingV1"
 	spliceHoldingEntity = "Holding"
@@ -141,6 +142,17 @@ type Token interface {
 	PrepareAcceptTransfer(
 		ctx context.Context, partyID, instructionCID, instrumentAdmin string,
 	) (*PreparedTransfer, error)
+
+	// WithdrawTransferInstruction reclaims a pending/expired offer-based transfer for a
+	// custodial sender by exercising TransferInstruction_Withdraw server-side.
+	WithdrawTransferInstruction(ctx context.Context, partyID, instructionCID, instrumentAdmin string) error
+
+	// PrepareWithdrawTransfer builds a Canton transaction for a non-custodial sender to
+	// reclaim a pending/expired offer and returns the hash to sign externally. Use
+	// ExecuteTransfer to complete it.
+	PrepareWithdrawTransfer(
+		ctx context.Context, partyID, instructionCID, instrumentAdmin string,
+	) (*PreparedTransfer, error)
 }
 
 // Client implements CIP-56 token operations.
@@ -1285,22 +1297,66 @@ func (c *Client) AcceptTransferInstruction(ctx context.Context, partyID, instruc
 	if partyID == "" || instructionCID == "" || instrumentAdmin == "" {
 		return fmt.Errorf("partyID, instructionCID, and instrumentAdmin are required")
 	}
+	cmd, disclosed, err := c.buildInstructionChoiceCommand(ctx, instructionCID, instrumentAdmin, "accept", acceptChoice)
+	if err != nil {
+		return err
+	}
+	if err := c.exerciseInstructionAsCustodial(ctx, partyID, cmd, disclosed); err != nil {
+		return fmt.Errorf("accept transfer instruction: %w", err)
+	}
+	return nil
+}
+
+// WithdrawTransferInstruction reclaims a pending or expired offer-based transfer for a
+// custodial sender: the middleware holds the user's key and exercises
+// TransferInstruction_Withdraw server-side, returning the locked holding to the sender.
+// Mirrors AcceptTransferInstruction but for the sender side.
+func (c *Client) WithdrawTransferInstruction(ctx context.Context, partyID, instructionCID, instrumentAdmin string) error {
+	if partyID == "" || instructionCID == "" || instrumentAdmin == "" {
+		return fmt.Errorf("partyID, instructionCID, and instrumentAdmin are required")
+	}
+	cmd, disclosed, err := c.buildInstructionChoiceCommand(ctx, instructionCID, instrumentAdmin, "withdraw", withdrawChoice)
+	if err != nil {
+		return err
+	}
+	if err := c.exerciseInstructionAsCustodial(ctx, partyID, cmd, disclosed); err != nil {
+		return fmt.Errorf("withdraw transfer instruction: %w", err)
+	}
+	return nil
+}
+
+// buildInstructionChoiceCommand fetches the registrar's choice-context for the given
+// action ("accept"/"withdraw") on a TransferInstruction and builds the exercise command
+// plus its disclosed contracts. Shared by the accept and withdraw (claim-back) flows,
+// which differ only in the registry endpoint and the on-ledger choice name.
+func (c *Client) buildInstructionChoiceCommand(
+	ctx context.Context, instructionCID, instrumentAdmin, action, choice string,
+) (*lapiv2.Command, []*lapiv2.DisclosedContract, error) {
 	if c.registryClient == nil {
-		return fmt.Errorf("no registry client configured for accept")
+		return nil, nil, fmt.Errorf("no registry client configured for %s", action)
 	}
 	extCfg, ok := c.cfg.ExternalTokens[instrumentAdmin]
 	if !ok {
-		return fmt.Errorf("unsupported external token issuer: %s", instrumentAdmin)
+		return nil, nil, fmt.Errorf("unsupported external token issuer: %s", instrumentAdmin)
 	}
 
-	acceptResp, err := c.registryClient.GetAcceptChoiceContext(ctx, extCfg.RegistryURL, instrumentAdmin, instructionCID)
+	var ctxResp *AcceptContextResponse
+	var err error
+	switch action {
+	case "accept":
+		ctxResp, err = c.registryClient.GetAcceptChoiceContext(ctx, extCfg.RegistryURL, instrumentAdmin, instructionCID)
+	case "withdraw":
+		ctxResp, err = c.registryClient.GetWithdrawChoiceContext(ctx, extCfg.RegistryURL, instrumentAdmin, instructionCID)
+	default:
+		return nil, nil, fmt.Errorf("unsupported instruction action: %s", action)
+	}
 	if err != nil {
-		return fmt.Errorf("get accept choice context: %w", err)
+		return nil, nil, fmt.Errorf("get %s choice context: %w", action, err)
 	}
 
-	ctxValue, err := encodeChoiceContextRecord(acceptResp.ChoiceContextData)
+	ctxValue, err := encodeChoiceContextRecord(ctxResp.ChoiceContextData)
 	if err != nil {
-		return fmt.Errorf("encode choice context: %w", err)
+		return nil, nil, fmt.Errorf("encode choice context: %w", err)
 	}
 
 	extraArgs := &lapiv2.Value{
@@ -1314,9 +1370,9 @@ func (c *Client) AcceptTransferInstruction(ctx context.Context, partyID, instruc
 		},
 	}
 
-	disclosed, err := convertDisclosedContractSlice(acceptResp.DisclosedContracts, c.cfg.DomainID)
+	disclosed, err := convertDisclosedContractSlice(ctxResp.DisclosedContracts, c.cfg.DomainID)
 	if err != nil {
-		return fmt.Errorf("convert disclosed contracts: %w", err)
+		return nil, nil, fmt.Errorf("convert disclosed contracts: %w", err)
 	}
 
 	cmd := &lapiv2.Command{
@@ -1328,7 +1384,7 @@ func (c *Client) AcceptTransferInstruction(ctx context.Context, partyID, instruc
 					EntityName: transferInstrEntity,
 				},
 				ContractId: instructionCID,
-				Choice:     acceptChoice,
+				Choice:     choice,
 				ChoiceArgument: &lapiv2.Value{
 					Sum: &lapiv2.Value_Record{
 						Record: &lapiv2.Record{
@@ -1341,19 +1397,23 @@ func (c *Client) AcceptTransferInstruction(ctx context.Context, partyID, instruc
 			},
 		},
 	}
+	return cmd, disclosed, nil
+}
 
-	// External parties (the only kind this api-server creates for custodial users)
-	// can't be submitted as via plain SubmitAndWait — the participant doesn't hold
-	// the signing key. Use Interactive Submission with the user's stored key.
+// exerciseInstructionAsCustodial submits a TransferInstruction choice on behalf of a
+// custodial party via Interactive Submission with the user's middleware-held key.
+// External parties can't use plain SubmitAndWait (the participant doesn't hold the key).
+func (c *Client) exerciseInstructionAsCustodial(
+	ctx context.Context, partyID string, cmd *lapiv2.Command, disclosed []*lapiv2.DisclosedContract,
+) error {
 	if c.keyResolver == nil {
-		return fmt.Errorf("accept transfer instruction: no key resolver configured " +
-			"(custodial accept requires the api-server to hold the user's signing key)")
+		return fmt.Errorf("no key resolver configured " +
+			"(custodial instruction exercise requires the api-server to hold the user's signing key)")
 	}
 	signerKey, err := c.keyResolver(partyID)
 	if err != nil {
-		return fmt.Errorf("accept transfer instruction: resolve signing key for %s: %w", partyID, err)
+		return fmt.Errorf("resolve signing key for %s: %w", partyID, err)
 	}
-
 	commands := &lapiv2.Commands{
 		SynchronizerId:     c.cfg.DomainID,
 		CommandId:          uuid.NewString(),
@@ -1362,10 +1422,7 @@ func (c *Client) AcceptTransferInstruction(ctx context.Context, partyID, instruc
 		Commands:           []*lapiv2.Command{cmd},
 		DisclosedContracts: disclosed,
 	}
-	if err := c.prepareAndExecuteAsUser(ctx, commands, signerKey, partyID); err != nil {
-		return fmt.Errorf("accept transfer instruction: %w", err)
-	}
-	return nil
+	return c.prepareAndExecuteAsUser(ctx, commands, signerKey, partyID)
 }
 
 func (c *Client) PrepareAcceptTransfer(
@@ -1374,63 +1431,35 @@ func (c *Client) PrepareAcceptTransfer(
 	if partyID == "" || instructionCID == "" || instrumentAdmin == "" {
 		return nil, fmt.Errorf("partyID, instructionCID, and instrumentAdmin are required")
 	}
-	if c.registryClient == nil {
-		return nil, fmt.Errorf("no registry client configured for accept")
-	}
-	extCfg, ok := c.cfg.ExternalTokens[instrumentAdmin]
-	if !ok {
-		return nil, fmt.Errorf("unsupported external token issuer: %s", instrumentAdmin)
-	}
-
-	acceptResp, err := c.registryClient.GetAcceptChoiceContext(ctx, extCfg.RegistryURL, instrumentAdmin, instructionCID)
-	if err != nil {
-		return nil, fmt.Errorf("get accept choice context: %w", err)
-	}
-
-	ctxValue, err := encodeChoiceContextRecord(acceptResp.ChoiceContextData)
+	cmd, disclosed, err := c.buildInstructionChoiceCommand(ctx, instructionCID, instrumentAdmin, "accept", acceptChoice)
 	if err != nil {
-		return nil, fmt.Errorf("encode choice context: %w", err)
+		return nil, err
 	}
+	return c.prepareInstructionTx(ctx, partyID, instructionCID, cmd, disclosed)
+}
 
-	extraArgs := &lapiv2.Value{
-		Sum: &lapiv2.Value_Record{
-			Record: &lapiv2.Record{
-				Fields: []*lapiv2.RecordField{
-					{Label: "context", Value: ctxValue},
-					{Label: "meta", Value: values.EmptyMetadata()},
-				},
-			},
-		},
+// PrepareWithdrawTransfer builds a Canton transaction for a non-custodial sender to
+// reclaim a pending or expired offer-based transfer (TransferInstruction_Withdraw) and
+// returns the hash the sender signs externally. Use ExecuteTransfer to complete it.
+func (c *Client) PrepareWithdrawTransfer(
+	ctx context.Context, partyID, instructionCID, instrumentAdmin string,
+) (*PreparedTransfer, error) {
+	if partyID == "" || instructionCID == "" || instrumentAdmin == "" {
+		return nil, fmt.Errorf("partyID, instructionCID, and instrumentAdmin are required")
 	}
-
-	disclosed, err := convertDisclosedContractSlice(acceptResp.DisclosedContracts, c.cfg.DomainID)
+	cmd, disclosed, err := c.buildInstructionChoiceCommand(ctx, instructionCID, instrumentAdmin, "withdraw", withdrawChoice)
 	if err != nil {
-		return nil, fmt.Errorf("convert disclosed contracts: %w", err)
-	}
-
-	cmd := &lapiv2.Command{
-		Command: &lapiv2.Command_Exercise{
-			Exercise: &lapiv2.ExerciseCommand{
-				TemplateId: &lapiv2.Identifier{
-					PackageId:  c.cfg.SpliceTransferPackageID,
-					ModuleName: spliceTransferModule,
-					EntityName: transferInstrEntity,
-				},
-				ContractId: instructionCID,
-				Choice:     acceptChoice,
-				ChoiceArgument: &lapiv2.Value{
-					Sum: &lapiv2.Value_Record{
-						Record: &lapiv2.Record{
-							Fields: []*lapiv2.RecordField{
-								{Label: "extraArgs", Value: extraArgs},
-							},
-						},
-					},
-				},
-			},
-		},
+		return nil, err
 	}
+	return c.prepareInstructionTx(ctx, partyID, instructionCID, cmd, disclosed)
+}
 
+// prepareInstructionTx prepares a TransferInstruction-choice exercise for external
+// (non-custodial) signing and returns the hash to sign. Shared by the accept and
+// withdraw prepare flows.
+func (c *Client) prepareInstructionTx(
+	ctx context.Context, partyID, instructionCID string, cmd *lapiv2.Command, disclosed []*lapiv2.DisclosedContract,
+) (*PreparedTransfer, error) {
 	authCtx := c.ledger.AuthContext(ctx)
 	prepResp, err := c.ledger.Interactive().PrepareSubmission(authCtx, &interactivev2.PrepareSubmissionRequest{
 		UserId:             c.cfg.UserID,
@@ -1441,7 +1470,7 @@ func (c *Client) PrepareAcceptTransfer(
 		DisclosedContracts: disclosed,
 	})
 	if err != nil {
-		return nil, fmt.Errorf("prepare accept submission: %w", err)
+		return nil, fmt.Errorf("prepare submission: %w", err)
 	}
 
 	pt := &PreparedTransfer{
@@ -1453,7 +1482,7 @@ func (c *Client) PrepareAcceptTransfer(
 		ExpiresAt:            time.Now().UTC().Add(preparedTxCacheTTL),
 	}
 
-	c.logger.Info("prepared non-custodial accept",
+	c.logger.Info("prepared non-custodial instruction tx",
 		zap.String("transfer_id", pt.TransferID),
 		zap.String("party_id", partyID),
 		zap.String("contract_id", instructionCID),

pkg/cantonsdk/token/registry_client.go

@@ -17,8 +17,10 @@ import (
 )
 
 const (
-	registryPathFmt      = "/api/token-standard/v0/registrars/%s/registry/transfer-instruction/v1/transfer-factory"
-	acceptContextPathFmt = "/api/token-standard/v0/registrars/%s/registry/transfer-instruction/v1/%s/choice-contexts/accept"
+	registryPathFmt = "/api/token-standard/v0/registrars/%s/registry/transfer-instruction/v1/transfer-factory"
+	// choiceContextPathFmt is the registrar's per-instruction choice-context
+	// endpoint. The final %s is the action ("accept" or "withdraw").
+	choiceContextPathFmt = "/api/token-standard/v0/registrars/%s/registry/transfer-instruction/v1/%s/choice-contexts/%s"
 )
 
 // RegistryClient calls the Splice Transfer Factory Registry API to discover
@@ -294,35 +296,54 @@ func ConvertAnyValueChoiceContext(raw json.RawMessage) (AcceptChoiceContext, err
 func (rc *RegistryClient) GetAcceptChoiceContext(
 	ctx context.Context, registryBaseURL, registrarParty, instructionCID string,
 ) (*AcceptContextResponse, error) {
-	path := fmt.Sprintf(acceptContextPathFmt, registrarParty, instructionCID)
+	return rc.getChoiceContext(ctx, registryBaseURL, registrarParty, instructionCID, "accept")
+}
+
+// GetWithdrawChoiceContext calls the registrar's withdraw choice-context endpoint for a
+// TransferInstruction. Returns the choiceContextData and disclosed contracts needed to
+// exercise TransferInstruction_Withdraw (sender reclaims a pending/expired offer).
+func (rc *RegistryClient) GetWithdrawChoiceContext(
+	ctx context.Context, registryBaseURL, registrarParty, instructionCID string,
+) (*AcceptContextResponse, error) {
+	return rc.getChoiceContext(ctx, registryBaseURL, registrarParty, instructionCID, "withdraw")
+}
+
+// getChoiceContext fetches a per-instruction choice-context for the given action
+// ("accept" or "withdraw"). The response shape is identical across actions, so both
+// the accept and withdraw flows share this. action is interpolated into the registrar
+// endpoint path and the error messages.
+func (rc *RegistryClient) getChoiceContext(
+	ctx context.Context, registryBaseURL, registrarParty, instructionCID, action string,
+) (*AcceptContextResponse, error) {
+	path := fmt.Sprintf(choiceContextPathFmt, registrarParty, instructionCID, action)
 	url := strings.TrimRight(registryBaseURL, "/") + path
 	body := []byte(`{"meta":{},"excludeDebugFields":false}`)
 
 	httpReq, err := http.NewRequestWithContext(ctx, http.MethodPost, url, bytes.NewReader(body))
 	if err != nil {
-		return nil, fmt.Errorf("create accept context request: %w", err)
+		return nil, fmt.Errorf("create %s context request: %w", action, err)
 	}
 	httpReq.Header.Set("Content-Type", "application/json")
 
 	resp, err := rc.httpClient.Do(httpReq)
 	if err != nil {
-		return nil, fmt.Errorf("accept context request failed: %w", err)
+		return nil, fmt.Errorf("%s context request failed: %w", action, err)
 	}
 	defer resp.Body.Close()
 
 	const maxResponseBytes = 1 << 20
 	respBody, err := io.ReadAll(io.LimitReader(resp.Body, maxResponseBytes))
 	if err != nil {
-		return nil, fmt.Errorf("read accept context response: %w", err)
+		return nil, fmt.Errorf("read %s context response: %w", action, err)
 	}
 
 	if resp.StatusCode != http.StatusOK {
-		return nil, fmt.Errorf("accept context returned %d: %s", resp.StatusCode, string(respBody))
+		return nil, fmt.Errorf("%s context returned %d: %s", action, resp.StatusCode, string(respBody))
 	}
 
 	var result AcceptContextResponse
 	if err := json.Unmarshal(respBody, &result); err != nil {
-		return nil, fmt.Errorf("parse accept context response: %w", err)
+		return nil, fmt.Errorf("parse %s context response: %w", action, err)
 	}
 	return &result, nil
 }