Evidence Documentation for Milestone 3 (TBARewards)

[guillaumedejenlis-da]

Milestone 3: On-Ledger Reward Workflow, Dry-Run, and MainNet Deployment

  | Months after grant approval -- | -- Estimated Delivery | Month 6 Focus | Daml model changes, SV app triggers, wallet integration, dry-run validation, and the live switch on MainNet

Deliverables:

• Daml: CalculateRewardsV2, ProcessRewardsV2, RewardCouponV2 templates with RewardMintingFactory interface and MintingDelegation support.

• Canton: crash-fault tolerant mediator inspection service.

• SV app: CalculateRewardsTrigger, ProcessRewardsTrigger, UnhideRewardCouponV2Trigger, ExpireRewardCouponV2Trigger.

• SV app: ExecuteConfirmedActionTrigger extended for CRARC_StartProcessingRewardsV2.

• SV app: SV onboarding support via BFT reads from Scan instances with complete data.

• SV app: admin API endpoint for archiving stuck dry-run rounds.

• SV app UI: support for new configuration parameters.

• Wallet app: RewardCouponV2 and MintCoupon lookup for reward minting.

• Dry-run mode deployed and validated on MainNet, confirming deterministic reward computation across SV nodes.

• Minimum two-week delay between deploying Dry-run mode on MainNet and enabling actual traffic-based rewards on DevNet. This means that explorers and app builders will be able to see what results would be generated via traffic-based application rewards, and compare them to existing marker-based rewards. Doing this two weeks before enforcing traffic-based app rewards on DevNet means that this computation will be available four weeks before the new rewards logic gets enforced on MainNet.

• Governance vote to switch from featured app markers to traffic-based app rewards.

• Monitoring: metrics and alerting for trigger health and hidden reward coupon counts.

• Resolution of any issues arising during MainNet deployment.

• All code merged into the open-source Canton and Splice repositories with appropriate unit and integration test coverage.

• Updated Splice documentation covering the traffic-based reward configuration, new Scan API endpoints, RewardCouponV2 lifecycle, dry-run mode operation, and SV onboarding interaction with reward accounting.

Acceptance Criteria: Traffic-based app rewards are live on the Global Synchronizer MainNet, with RewardCouponV2 contracts being created for featured app provider parties each round. Dry-run validation has confirmed deterministic reward computation across SV nodes prior to the live switch. Scale testing confirms the system operates within acceptable bounds at 2026 MainNet scale.

Milestone 3: canton-foundation/canton-dev-fund#241

[meiersi-da]

Milestone 3: On-Ledger Reward Workflow, Dry-Run, and MainNet Deployment

  | Months after grant approval -- | -- Estimated Delivery | Month 6 Focus | Daml model changes, SV app triggers, wallet integration, dry-run validation, and the live switch on MainNet
Deliverables:

• Daml: CalculateRewardsV2, ProcessRewardsV2, RewardCouponV2 templates with RewardMintingFactory interface and MintingDelegation support.

See

• CIP-104: Daml for rewards accounting V2 and sv-app UI fixes #4724

• Canton: crash-fault tolerant mediator inspection service.

Done; and verified by chaos monkey tests in DA's CILR test cluster.

• SV app: CalculateRewardsTrigger, ProcessRewardsTrigger, UnhideRewardCouponV2Trigger, ExpireRewardCouponV2Trigger.

• https://github.com/canton-network/splice/blob/main/apps/sv/src/main/scala/org/lfdecentralizedtrust/splice/sv/automation/confirmation/CalculateRewardsTrigger.scala
• https://github.com/canton-network/splice/blob/main/apps/sv/src/main/scala/org/lfdecentralizedtrust/splice/sv/automation/confirmation/CalculateRewardsTrigger.scala
• https://github.com/canton-network/splice/blob/main/apps/sv/src/main/scala/org/lfdecentralizedtrust/splice/sv/automation/delegatebased/UnhideRewardCouponV2Trigger.scala
• https://github.com/canton-network/splice/blob/main/apps/sv/src/main/scala/org/lfdecentralizedtrust/splice/sv/automation/delegatebased/ExpireRewardCouponV2Trigger.scala

• SV app: ExecuteConfirmedActionTrigger extended for CRARC_StartProcessingRewardsV2.

splice/apps/sv/src/main/scala/org/lfdecentralizedtrust/splice/sv/automation/delegatebased/ExecuteConfirmedActionTrigger.scala

Lines 207 to 215 in 44fdc1f

	case startProcessingAction: CRARC_StartProcessingRewardsV2 =>
	val calculateRewardsCid =
	startProcessingAction.amuletRules_StartProcessingRewardsV2Value.calculateRewardsCid
	store.multiDomainAcsStore
	.lookupContractByIdOnDomain(CalculateRewardsV2.COMPANION)(
	confirmation.domain,
	calculateRewardsCid,
	)
	.map(_.isEmpty)

• SV app: SV onboarding support via BFT reads from Scan instances with complete data.

see

splice/apps/scan/src/main/scala/org/lfdecentralizedtrust/splice/scan/admin/api/client/BftScanConnection.scala

Lines 857 to 983 in 44fdc1f

	/** This is special because in addition to 'Ok' we can receive
	* 'Undetermined' - This might indicate that scan is yet to process activity totals for this round
	* 'CannotProvide' - Indicates that scan does not have required app-activity data to provide a response
	*
	* So simple equality comparison on responses is not possible, and we treat
	* the two non-Ok responses as a "no response" by throwing IgnoreResponse so
	* that this does not cause grouping in executeCall.
	*
	* And if no response could be obtained via bft we respond with 'Undetermined'
	*/
	override def getRewardAccountingActivityTotals(roundNumber: Long)(implicit
	ec: ExecutionContext,
	tc: TraceContext,
	): Future[GetRewardAccountingActivityTotalsResponse] = {
	val undetermined =
	GetRewardAccountingActivityTotalsResponse(
	RewardAccountingActivityTotalsUndetermined(status = "Undetermined")
	)
	val callConfig = BftCallConfig.default(scanList.scanConnections)
	if (!callConfig.enoughAvailableScans) Future.successful(undetermined)
	else
	bftCall[RewardAccountingActivityTotalsOk](
	call = scan =>
	scan.getRewardAccountingActivityTotals(roundNumber).flatMap {
	case GetRewardAccountingActivityTotalsResponse.members
	.RewardAccountingActivityTotalsOk(ok) =>
	Future.successful(ok)
	case _: GetRewardAccountingActivityTotalsResponse.members.RewardAccountingActivityTotalsUndetermined |
	_: GetRewardAccountingActivityTotalsResponse.members.RewardAccountingActivityTotalsCannotProvide =>
	Future.failed(BftScanConnection.IgnoreResponse(scan.url))
	},
	endpoint = "getRewardAccountingActivityTotals",
	callConfig = callConfig,
	consensusLogConfig = BftScanConnection.ConsensusLogConfig(
	disagreementLogLevel = Level.WARN,
	onlyLogDisagreementsInSuccessResponse = true,
	agreementLogLevel = Some(Level.INFO),
	),
	)
	.transform(tryTotals =>
	Success(
	tryTotals.toOption.fold(undetermined)(ok =>
	GetRewardAccountingActivityTotalsResponse(ok)
	)
	)
	)
	}
	/** This is special because in addition to 'Ok' we can receive
	* 'Undetermined' - This might indicate that scan is yet to process root hash for this round
	* 'CannotProvide' - Indicates that scan does not have required app-activity data to provide a response
	*
	* So simple equality comparison on responses is not possible, and we treat
	* the two non-Ok responses as a "no response" by throwing IgnoreResponse so
	* that this does not cause grouping in executeCall.
	*
	* And if no response could be obtained via bft we respond with 'Undetermined'
	*/
	override def getRewardAccountingRootHash(roundNumber: Long)(implicit
	ec: ExecutionContext,
	tc: TraceContext,
	): Future[GetRewardAccountingRootHashResponse] = {
	val undetermined =
	GetRewardAccountingRootHashResponse(
	RewardAccountingRootHashUndetermined(status = "Undetermined")
	)
	val callConfig = BftCallConfig.default(scanList.scanConnections)
	if (!callConfig.enoughAvailableScans) Future.successful(undetermined)
	else
	bftCall[String](
	call = scan =>
	scan.getRewardAccountingRootHash(roundNumber).flatMap {
	case GetRewardAccountingRootHashResponse.members.RewardAccountingRootHashOk(ok) =>
	Future.successful(ok.rootHash)
	case _: GetRewardAccountingRootHashResponse.members.RewardAccountingRootHashUndetermined |
	_: GetRewardAccountingRootHashResponse.members.RewardAccountingRootHashCannotProvide =>
	Future.failed(BftScanConnection.IgnoreResponse(scan.url))
	},
	endpoint = "getRewardAccountingRootHash",
	callConfig = callConfig,
	consensusLogConfig = BftScanConnection.ConsensusLogConfig(
	disagreementLogLevel = Level.WARN,
	onlyLogDisagreementsInSuccessResponse = true,
	agreementLogLevel = Some(Level.INFO),
	),
	)
	.transform(tryRootHash =>
	Success(
	tryRootHash.toOption.fold(undetermined)(rootHash =>
	GetRewardAccountingRootHashResponse(
	RewardAccountingRootHashOk(
	status = "Ok",
	roundNumber = roundNumber,
	rootHash = rootHash,
	)
	)
	)
	)
	)
	}
	/** The batch contents are verifiable via the hash, so BFT agreement across scans is not
	* required: we query a single random scan and return its response.
	* Note: this will not do a retry at all, even if the scan being requested happens to be offline.
	*/
	override def getRewardAccountingBatch(roundNumber: Long, batchHash: String)(implicit
	ec: ExecutionContext,
	tc: TraceContext,
	): Future[Option[GetRewardAccountingBatchResponse]] = {
	val callConfig = BftCallConfig.randomSingleCall(scanList.scanConnections)
	if (!callConfig.enoughAvailableScans) Future.successful(None)
	else
	bftCall[GetRewardAccountingBatchResponse](
	call = scan =>
	scan.getRewardAccountingBatch(roundNumber, batchHash).flatMap {
	case Some(batch) => Future.successful(batch)
	case None => Future.failed(BftScanConnection.IgnoreResponse(scan.url))
	},
	endpoint = "getRewardAccountingBatch",
	callConfig = callConfig,
	)
	.transform(tryBatch => Success(tryBatch.toOption))
	}
	}
	trait HasUrl {
	def url: Uri
	}

and their use in the triggers above.

• SV app: admin API endpoint for archiving stuck dry-run rounds.

splice/apps/sv/src/main/openapi/sv-internal.yaml

Lines 643 to 661 in 44fdc1f

	/v0/admin/reward-accounting-process/archive-dry-runs:
	post:
	tags: [ sv ]
	x-jvm-package: sv_operator
	operationId: "archiveDryRunRewardAccountingContracts"
	description: |
	Archive active `CalculateRewardsV2` and `ProcessRewardsV2` contracts
	for the specified rounds if they have `dryRun` as `True`.
	requestBody:
	required: true
	content:
	application/json:
	schema:
	$ref: "#/components/schemas/ArchiveDryRunRewardAccountingContractsRequest"
	responses:
	"200":
	description: ok
	"400":
	$ref: "../../../../common/src/main/openapi/common-external.yaml#/components/responses/400"

• SV app UI: support for new configuration parameters.

• 
• descriptions to be improved in Use more descriptive names for reward config #5986

• Wallet app: RewardCouponV2 and MintCoupon lookup for reward minting.

• Traffic-Based App Rewards: add reward sharing config and mint unshared, unassigned RewardCouponV2 #5817
• Traffic-Based App Rewards: Add minting of RewardCouponV2 #5786

• Dry-run mode deployed and validated on MainNet, confirming deterministic reward computation across SV nodes.
• Minimum two-week delay between deploying Dry-run mode on MainNet and enabling actual traffic-based rewards on DevNet. This means that explorers and app builders will be able to see what results would be generated via traffic-based application rewards, and compare them to existing marker-based rewards. Doing this two weeks before enforcing traffic-based app rewards on DevNet means that this computation will be available four weeks before the new rewards logic gets enforced on MainNet.

see SV ops schedule

• dry-run on MainNet planned for July 7th
• switch planned for July 28th

• Governance vote to switch from featured app markers to traffic-based app rewards.
• Monitoring: metrics and alerting for trigger health and hidden reward coupon counts.

see

• Add grafana alert for too many CalculateRewardsV2 contracts #6061
• Add dashboard for traffic-based app rewards #5897

• Resolution of any issues arising during MainNet deployment.
• All code merged into the open-source Canton and Splice repositories with appropriate unit and integration test coverage.

see commits on main

• Updated Splice documentation covering the traffic-based reward configuration, new Scan API endpoints, RewardCouponV2 lifecycle, dry-run mode operation, and SV onboarding interaction with reward accounting.

see

• https://docs.canton.network/global-synchronizer/splice-fundamentals/traffic-based-app-rewards
• https://docs.canton.network/global-synchronizer/splice-fundamentals/reward-sharing

Acceptance Criteria: Traffic-based app rewards are live on the Global Synchronizer MainNet, with RewardCouponV2 contracts being created for featured app provider parties each round.

• TBC

Dry-run validation has confirmed deterministic reward computation across SV nodes prior to the live switch.

• TBC

Scale testing confirms the system operates within acceptable bounds at 2026 MainNet scale.

tested as part of the TBAR Test Plan

Milestone 3: canton-foundation/canton-dev-fund#241