IBlueprintServiceManager

Source: https://github.com/tangle-network/tnt-core/blob/main/src/interfaces/IBlueprintServiceManager.sol

IBlueprintServiceManager

Full interface for blueprint-specific service managers

_Blueprint developers implement this to customize all aspects of their blueprint. This is the primary integration point for blueprint developers - implement the hooks you need and leave others as default (via BlueprintServiceManagerBase).

The lifecycle flow:

Blueprint created → onBlueprintCreated
Operators register → onRegister
Service requested → onRequest
Operators approve → onApprove
Service activated → onServiceInitialized
Jobs submitted → onJobCall
Results submitted → onJobResult
Service terminated → onServiceTermination_

Functions

onBlueprintCreated

function onBlueprintCreated(uint64 blueprintId, address owner, address tangleCore) external

Called when blueprint is created

Store the blueprintId and tangleCore address for future reference

Parameters

Name	Type	Description
blueprintId	uint64	The new blueprint ID
owner	address	The blueprint owner
tangleCore	address	The address of the Tangle core contract

onRegister

function onRegister(address operator, bytes registrationInputs) external payable

Called when an operator registers to this blueprint

Validate operator requirements here (stake, reputation, etc.)

Parameters

Name	Type	Description
operator	address	The operator’s address
registrationInputs	bytes	Custom registration data (blueprint-specific encoding)

onUnregister

function onUnregister(address operator) external

Called when an operator unregisters from this blueprint

Parameters

Name	Type	Description
operator	address	The operator’s address

onUpdatePreferences

function onUpdatePreferences(address operator, bytes newPreferences) external payable

Called when an operator updates their preferences (RPC address, etc.)

Parameters

Name	Type	Description
operator	address	The operator’s address
newPreferences	bytes	Updated preferences data

getHeartbeatInterval

function getHeartbeatInterval(uint64 serviceId) external view returns (bool useDefault, uint64 interval)

Get the heartbeat interval for a service

Operators must submit heartbeats within this interval

Parameters

Name	Type	Description
serviceId	uint64	The service ID

Return Values

Name	Type	Description
useDefault	bool	True to use protocol default, false to use custom value
interval	uint64	Heartbeat interval in blocks (0 = disabled)

getHeartbeatThreshold

function getHeartbeatThreshold(uint64 serviceId) external view returns (bool useDefault, uint8 threshold)

Get the heartbeat threshold for a service

Percentage of operators that must respond within interval

Parameters

Name	Type	Description
serviceId	uint64	The service ID

Return Values

Name	Type	Description
useDefault	bool	True to use protocol default
threshold	uint8	Threshold percentage (0-100)

getSlashingWindow

function getSlashingWindow(uint64 serviceId) external view returns (bool useDefault, uint64 window)

Get the slashing window for a service

Time window for disputes before slash is finalized

Parameters

Name	Type	Description
serviceId	uint64	The service ID

Return Values

Name	Type	Description
useDefault	bool	True to use protocol default
window	uint64	Slashing window in blocks

getExitConfig

function getExitConfig(uint64 serviceId) external view returns (bool useDefault, uint64 minCommitmentDuration, uint64 exitQueueDuration, bool forceExitAllowed)

Get the exit configuration for operator departures

Defines minimum commitment and exit queue timing

Parameters

Name	Type	Description
serviceId	uint64	The service ID

Return Values

Name	Type	Description
useDefault	bool	True to use protocol default
minCommitmentDuration	uint64	Minimum time operator must stay after joining (seconds)
exitQueueDuration	uint64	Time between scheduling exit and completing it (seconds)
forceExitAllowed	bool	Whether service owner can force-exit operators

onRequest

function onRequest(uint64 requestId, address requester, address[] operators, bytes requestInputs, uint64 ttl, address paymentAsset, uint256 paymentAmount) external payable

Called when a service is requested

Validate service configuration, operator selection, payment amount

Parameters

Name	Type	Description
requestId	uint64	The request ID
requester	address	Who is requesting the service
operators	address[]	Requested operators
requestInputs	bytes	Service configuration (blueprint-specific encoding)
ttl	uint64	Time-to-live for the service
paymentAsset	address	Payment token address (address(0) for native)
paymentAmount	uint256	Payment amount

onApprove

function onApprove(address operator, uint64 requestId, uint8 stakingPercent) external payable

Called when an operator approves a service request

Parameters

Name	Type	Description
operator	address	The approving operator
requestId	uint64	The request ID
stakingPercent	uint8	Percentage of stake committed to this service (0-100)

onReject

function onReject(address operator, uint64 requestId) external

Called when an operator rejects a service request

Parameters

Name	Type	Description
operator	address	The rejecting operator
requestId	uint64	The request ID

onServiceInitialized

function onServiceInitialized(uint64 blueprintId, uint64 requestId, uint64 serviceId, address owner, address[] permittedCallers, uint64 ttl) external

Called when service becomes active (all operators approved)

Parameters

Name	Type	Description
blueprintId	uint64	The blueprint ID
requestId	uint64	The original request ID
serviceId	uint64	The new service ID
owner	address	The service owner
permittedCallers	address[]	Addresses allowed to submit jobs
ttl	uint64	Service time-to-live

onServiceTermination

function onServiceTermination(uint64 serviceId, address owner) external

Called when service is terminated

Parameters

Name	Type	Description
serviceId	uint64	The service ID
owner	address	The service owner

canJoin

function canJoin(uint64 serviceId, address operator) external view returns (bool allowed)

Check if an operator can join a dynamic service

Called before operator joins - return false to reject

Parameters

Name	Type	Description
serviceId	uint64	The service ID
operator	address	The operator wanting to join

Return Values

Name	Type	Description
allowed	bool	True if operator can join

onOperatorJoined

function onOperatorJoined(uint64 serviceId, address operator, uint16 exposureBps) external

Called after an operator successfully joins a service

Parameters

Name	Type	Description
serviceId	uint64	The service ID
operator	address	The operator that joined
exposureBps	uint16	The operator’s stake exposure in basis points

canLeave

function canLeave(uint64 serviceId, address operator) external view returns (bool allowed)

Check if an operator can leave a dynamic service

Called before operator leaves - return false to reject Note: This is called AFTER the exit queue check. Use getExitConfig to customize timing.

Parameters

Name	Type	Description
serviceId	uint64	The service ID
operator	address	The operator wanting to leave

Return Values

Name	Type	Description
allowed	bool	True if operator can leave

onOperatorLeft

function onOperatorLeft(uint64 serviceId, address operator) external

Called after an operator successfully leaves a service

Parameters

Name	Type	Description
serviceId	uint64	The service ID
operator	address	The operator that left

onExitScheduled

function onExitScheduled(uint64 serviceId, address operator, uint64 executeAfter) external

Called when an operator schedules their exit from a service

Allows manager to track pending exits, notify other parties, etc.

Parameters

Name	Type	Description
serviceId	uint64	The service ID
operator	address	The operator scheduling exit
executeAfter	uint64	Timestamp when exit can be executed

onExitCanceled

function onExitCanceled(uint64 serviceId, address operator) external

Called when an operator cancels their scheduled exit

Parameters

Name	Type	Description
serviceId	uint64	The service ID
operator	address	The operator canceling exit

onJobCall

function onJobCall(uint64 serviceId, uint8 job, uint64 jobCallId, bytes inputs) external payable

Called when a job is submitted

Validate job inputs, check caller permissions, etc.

Parameters

Name	Type	Description
serviceId	uint64	The service ID
job	uint8	The job index in the blueprint
jobCallId	uint64	Unique ID for this job call
inputs	bytes	Job inputs (blueprint-specific encoding)

onJobResult

function onJobResult(uint64 serviceId, uint8 job, uint64 jobCallId, address operator, bytes inputs, bytes outputs) external payable

Called when an operator submits a job result

Validate result format, check operator eligibility, aggregate results

Parameters

Name	Type	Description
serviceId	uint64	The service ID
job	uint8	The job index
jobCallId	uint64	The job call ID
operator	address	The operator submitting
inputs	bytes	Original job inputs
outputs	bytes	Result outputs (blueprint-specific encoding)

onUnappliedSlash

function onUnappliedSlash(uint64 serviceId, bytes offender, uint8 slashPercent) external

Called when a slash is queued but not yet applied

This is the dispute window - gather evidence, notify parties

Parameters

Name	Type	Description
serviceId	uint64	The service ID
offender	bytes	The operator being slashed (encoded as bytes for flexibility)
slashPercent	uint8	Percentage of stake to slash

onSlash

function onSlash(uint64 serviceId, bytes offender, uint8 slashPercent) external

Called when a slash is finalized and applied

Parameters

Name	Type	Description
serviceId	uint64	The service ID
offender	bytes	The slashed operator
slashPercent	uint8	Percentage slashed

querySlashingOrigin

function querySlashingOrigin(uint64 serviceId) external view returns (address slashingOrigin)

Query the account authorized to propose slashes for a service

Override to allow custom slashing authorities (dispute contracts, etc.)

Parameters

Name	Type	Description
serviceId	uint64	The service ID

Return Values

Name	Type	Description
slashingOrigin	address	Address that can slash (default: this contract)

queryDisputeOrigin

function queryDisputeOrigin(uint64 serviceId) external view returns (address disputeOrigin)

Query the account authorized to dispute slashes

Override to allow custom dispute resolution

Parameters

Name	Type	Description
serviceId	uint64	The service ID

Return Values

Name	Type	Description
disputeOrigin	address	Address that can dispute (default: this contract)

queryDeveloperPaymentAddress

function queryDeveloperPaymentAddress(uint64 serviceId) external view returns (address payable developerPaymentAddress)

Get the developer payment address for a service

Override to route payments to different addresses per service

Parameters

Name	Type	Description
serviceId	uint64	The service ID

Return Values

Name	Type	Description
developerPaymentAddress	address payable	Address to receive developer share

queryIsPaymentAssetAllowed

function queryIsPaymentAssetAllowed(uint64 serviceId, address asset) external view returns (bool isAllowed)

Check if a payment asset is allowed for this blueprint

Parameters

Name	Type	Description
serviceId	uint64	The service ID
asset	address	The payment asset address (address(0) for native)

Return Values

Name	Type	Description
isAllowed	bool	True if the asset can be used for payment

getRequiredResultCount

function getRequiredResultCount(uint64 serviceId, uint8 jobIndex) external view returns (uint32 required)

Get the number of results required to complete a job

Override for consensus requirements (e.g., 2/3 majority)

Parameters

Name	Type	Description
serviceId	uint64	The service ID
jobIndex	uint8	The job index

Return Values

Name	Type	Description
required	uint32	Number of results needed (0 = service operator count)

requiresAggregation

function requiresAggregation(uint64 serviceId, uint8 jobIndex) external view returns (bool required)

Check if a job requires BLS aggregated results

When true, operators must submit individual signatures that are aggregated off-chain, then submitted via submitAggregatedResult instead of submitResult

Parameters

Name	Type	Description
serviceId	uint64	The service ID
jobIndex	uint8	The job index

Return Values

Name	Type	Description
required	bool	True if BLS aggregation is required for this job

getAggregationThreshold

function getAggregationThreshold(uint64 serviceId, uint8 jobIndex) external view returns (uint16 thresholdBps, uint8 thresholdType)

Get the aggregation threshold configuration for a job

Only relevant if requiresAggregation returns true

Parameters

Name	Type	Description
serviceId	uint64	The service ID
jobIndex	uint8	The job index

Return Values

Name	Type	Description
thresholdBps	uint16	Threshold in basis points (6700 = 67%)
thresholdType	uint8	0 = CountBased (% of operators), 1 = StakeWeighted (% of total stake)

onAggregatedResult

function onAggregatedResult(uint64 serviceId, uint8 job, uint64 jobCallId, bytes output, uint256 signerBitmap, uint256[2] aggregatedSignature, uint256[4] aggregatedPubkey) external

Called when an aggregated job result is submitted

Validate the aggregated result, verify BLS signature, check threshold

Parameters

Name	Type	Description
serviceId	uint64	The service ID
job	uint8	The job index
jobCallId	uint64	The job call ID
output	bytes	The aggregated output
signerBitmap	uint256	Bitmap of which operators signed
aggregatedSignature	uint256[2]	The aggregated BLS signature (G1 point x, y)
aggregatedPubkey	uint256[4]	The aggregated public key of signers (G2 point)

getMinOperatorStake

function getMinOperatorStake() external view returns (bool useDefault, uint256 minStake)

Get the minimum stake required for operators to register for this blueprint

Called during operator registration to validate stake requirements

Return Values

Name	Type	Description
useDefault	bool	True to use protocol default from staking module
minStake	uint256	Custom minimum stake amount (only used if useDefault=false)

IBlueprintHook IERC7540