feat(external-call): Integrate external calls into Canton runtime

[trusch]

Summary

This PR completes the external call feature by integrating all components into the Canton runtime. It wires up the extension service to the Ledger API, command interpreter, and validation pipeline.

Requires #442

Changes

Ledger API Server (LedgerApiServer.scala)

• Initialize ExtensionServiceManager from configuration
• Create shared HttpClient with connection pooling
• Run ExtensionValidator on DAR upload

API Service Owner (ApiServiceOwner.scala)

• Pass ExternalCallHandler to command services

API Services (ApiServices.scala)

• Wire ExternalCallHandler into service creation

Command Interpreter (StoreBackedCommandInterpreter.scala)

Main integration point for command execution:

class StoreBackedCommandInterpreter(
    // ... existing params ...
    externalCallHandler: Option[ExternalCallHandler]
) {

  private def interpretCommands(...): Future[SubmittedTransaction] = {
    engine.submit(...) match {
      case ResultDone(tx) => Future.successful(tx)

      case ResultNeedExternalCall(extId, funcId, config, input, resume) =>
        // Handle external call
        val mode = if (isValidation) ExecutionMode.Validation else ExecutionMode.Submission

        externalCallHandler match {
          case Some(handler) =>
            handler.handleExternalCall(extId, funcId, config, input, mode).flatMap {
              case Right(output) => interpretResult(resume(output))
              case Left(error) => Future.failed(ExternalCallException(error))
            }
          case None =>
            // No handler configured - fail for signatories, use stored for observers
            if (isValidation && hasStoredResult) {
              interpretResult(resume(storedResult))
            } else {
              Future.failed(NoExtensionConfigured(extId))
            }
        }

      case ResultNeedContract(...) => // existing handling
      case ResultNeedKey(...) => // existing handling
      case ResultError(err) => Future.failed(err)
    }
  }
}

DAMLe (DAMLe.scala)

Extended engine wrapper to handle external calls:

• Pass through ResultNeedExternalCall to caller
• Track external call results for validation
• Support replay mode for observers

Model Conformance Checker (ModelConformanceChecker.scala)

Validation integration:

def reInterpret(view: TransactionView, ...): Future[Boolean] = {
  // Extract stored external call results from view
  val storedResults = view.viewParticipantData.actionDescription match {
    case ex: ExerciseActionDescription => ex.externalCallResults
    case _ => Seq.empty
  }

  // Reinterpret with stored results (no HTTP calls)
  engine.reinterpret(
    commands = view.rootAction,
    externalCallResults = storedResults,  // Replay these
    ...
  ).map { reinterpretedTx =>
    // Verify results match
    reinterpretedTx.externalCallResults == storedResults
  }
}

Prepared Transaction Decoder (PreparedTransactionDecoder.scala)

• Decode external call results from prepared transactions

LF Value Translation (LfValueTranslation.scala)

• Handle external call results in value translation

Input Contract Packages (InputContractPackages.scala)

• Track packages referenced by external call results

Canton Config (CantonConfig.scala)

• Added extensions section to participant configuration

IDE Ledger Runner (IdeLedgerRunner.scala)

• Support external calls in Daml Script IDE integration

Repair Service (RepairService.scala)

• Handle external call results in repair operations## Summary

This PR completes the external call feature by integrating all components into the Canton runtime. It wires up the extension service to the Ledger API, command interpreter, and validation pipeline.

Changes

Ledger API Server (LedgerApiServer.scala)

• Initialize ExtensionServiceManager from configuration
• Create shared HttpClient with connection pooling
• Run ExtensionValidator on DAR upload

API Service Owner (ApiServiceOwner.scala)

• Pass ExternalCallHandler to command services

API Services (ApiServices.scala)

• Wire ExternalCallHandler into service creation

Command Interpreter (StoreBackedCommandInterpreter.scala)

Main integration point for command execution:

class StoreBackedCommandInterpreter(
    // ... existing params ...
    externalCallHandler: Option[ExternalCallHandler]
) {

  private def interpretCommands(...): Future[SubmittedTransaction] = {
    engine.submit(...) match {
      case ResultDone(tx) => Future.successful(tx)

      case ResultNeedExternalCall(extId, funcId, config, input, resume) =>
        // Handle external call
        val mode = if (isValidation) ExecutionMode.Validation else ExecutionMode.Submission

        externalCallHandler match {
          case Some(handler) =>
            handler.handleExternalCall(extId, funcId, config, input, mode).flatMap {
              case Right(output) => interpretResult(resume(output))
              case Left(error) => Future.failed(ExternalCallException(error))
            }
          case None =>
            // No handler configured - fail for signatories, use stored for observers
            if (isValidation && hasStoredResult) {
              interpretResult(resume(storedResult))
            } else {
              Future.failed(NoExtensionConfigured(extId))
            }
        }

      case ResultNeedContract(...) => // existing handling
      case ResultNeedKey(...) => // existing handling
      case ResultError(err) => Future.failed(err)
    }
  }
}

DAMLe (DAMLe.scala)

Extended engine wrapper to handle external calls:

• Pass through ResultNeedExternalCall to caller
• Track external call results for validation
• Support replay mode for observers

Model Conformance Checker (ModelConformanceChecker.scala)

Validation integration:

def reInterpret(view: TransactionView, ...): Future[Boolean] = {
  // Extract stored external call results from view
  val storedResults = view.viewParticipantData.actionDescription match {
    case ex: ExerciseActionDescription => ex.externalCallResults
    case _ => Seq.empty
  }

  // Reinterpret with stored results (no HTTP calls)
  engine.reinterpret(
    commands = view.rootAction,
    externalCallResults = storedResults,  // Replay these
    ...
  ).map { reinterpretedTx =>
    // Verify results match
    reinterpretedTx.externalCallResults == storedResults
  }
}

Prepared Transaction Decoder (PreparedTransactionDecoder.scala)

• Decode external call results from prepared transactions

LF Value Translation (LfValueTranslation.scala)

• Handle external call results in value translation

Input Contract Packages (InputContractPackages.scala)

• Track packages referenced by external call results

Canton Config (CantonConfig.scala)

• Added extensions section to participant configuration

IDE Ledger Runner (IdeLedgerRunner.scala)

• Support external calls in Daml Script IDE integration

Repair Service (RepairService.scala)

• Handle external call results in repair operations

Execution Modes

Submission Mode (Signatory)

1. Contract calls externalCall(...)
2. Engine yields ResultNeedExternalCall
3. StoreBackedCommandInterpreter calls HTTP service
4. Result stored in Exercise node
5. Transaction submitted with results

Validation Mode (Observer/Confirmer)

1. Receive transaction with stored results
2. ModelConformanceChecker reinterprets
3. Engine receives stored results (no HTTP)
4. Verify reinterpreted results match stored
5. Accept or reject transaction

Testing

• TestSubmissionService.scala - Test harness for submission
• JdbcLedgerDaoSuite.scala - DAO tests with external calls
• ExampleTransactionConformanceTest.scala - Conformance checking

Execution Modes

Submission Mode (Signatory)

1. Contract calls externalCall(...)
2. Engine yields ResultNeedExternalCall
3. StoreBackedCommandInterpreter calls HTTP service
4. Result stored in Exercise node
5. Transaction submitted with results

Validation Mode (Observer/Confirmer)

1. Receive transaction with stored results
2. ModelConformanceChecker reinterprets
3. Engine receives stored results (no HTTP)
4. Verify reinterpreted results match stored
5. Accept or reject transaction

Testing

• TestSubmissionService.scala - Test harness for submission
• JdbcLedgerDaoSuite.scala - DAO tests with external calls
• ExampleTransactionConformanceTest.scala - Conformance checking

[github-actions]

🎉 Thank you for your contribution! It appears you have not yet signed the Agreement DA Contributor License Agreement (CLA), which is required for your changes to be incorporated into an Open Source Software (OSS) project. Please kindly read the and reply on a new comment with the following text to agree:

---

I have hereby read the Digital Asset CLA and agree to its terms

---

_{You can retrigger this bot by commenting recheck in this Pull Request. Posted by the CLA Assistant Lite bot.}