Skip to content

Commit 47be8cd

Browse files
drewstonedrewstone
authored
docs: tnt-core v0.13.0 — quote requester, slashing reshape, BSM hooks, L2 timelock (#147)
* docs(reference): regen ITangleSlashing, IMBSMRegistry, IBlueprintServiceManager (v0.13.0) - ITangleSlashing: align with the actual SlashingLib events. SlashProposed is 8 fields, SlashExecuted is 4. Add SlashDisputed, SlashCancelled, SlashConfigUpdated event sections. proposeSlash takes uint16 slashBps (was uint256 amount). disputeSlash is external payable. setSlashConfig is the 6-arg form. Add getSlashConfig view. - IMBSMRegistry.pinBlueprint: add a paragraph documenting the deprecation grace-window rejection (revisions in the grace window are refused so pinning cannot defeat the deprecation flow). - IBlueprintServiceManager: document forceRemoveAllowsBelowMin (default false; custom BSMs not inheriting BlueprintServiceManagerBase MUST implement) and getNonPaymentTerminationPolicy (added in v0.11.1, never documented). Mirrored to generated/ copies; tnt-core sync check still passes. * docs(rfq): document EIP-712 quote requester binding (v0.12.0/v0.13.0) QuoteDetails and JobQuoteDetails now carry address requester as the FIRST field of the EIP-712 typed data. The contract enforces requester == msg.sender and rejects wildcard requester == address(0). - pricing-and-payments: reorder field lists (requester first), add a copyable Solidity struct literal and JSON typed-data example, and a Quote-binding key-property bullet covering both QuoteDetails and JobQuoteDetails (with the new typehash strings). - pricing-engine: add Security Notes bullet on requester binding and a Best Practices entry on always populating requester. - operators/pricing/overview: RFQ section gains a requester-binding callout for operator quote-server implementations. - execution-confidentiality: append a customer-request bullet noting that confidential quotes are bound to a specific consumer via requester so they cannot be lifted from the mempool. * docs(slashing,lifecycle): nonReentrant gates, exit-active gate, admin self-dispute (v0.13.0) - slashing: proposeSlash and disputeSlash now nonReentrant. proposeSlash rejects bytes32(0) evidence. executeSlash for a Disputed proposal uses disputeDeadline + TIMESTAMP_BUFFER (15s symmetric with the Pending branch). SLASH_ADMIN_ROLE that is also the proposer of a slash cannot self-dispute their own proposal. - service-lifecycle: new "Exit Gates (v0.13.0)" section covering the Active-status gate on every operator-exit entrypoint, nonReentrant on terminateService, approveService rejecting past-grace requests, and rejection of duplicate operators. force-remove paragraph now mentions the forceRemoveAllowsBelowMin opt-in. - auth-surface: append "(admin cannot self-dispute their own proposal)" to the disputeSlash row. Mark terminateService and forceRemoveOperator as nonReentrant. Note that pinBlueprint reverts inside the deprecation grace window. - network/metrics-and-scoring: list the full slashing event names (Proposed, Disputed, Executed, Cancelled, ConfigUpdated) so indexers know to subscribe to all five. * docs(infra): note 2-day timelock + activate step on bridge messenger/slasher rotation infrastructure/protocol-deployment runbook now reminds operators that bootstrap setMessenger / setSlasher (current = address(0)) takes effect immediately on L2SlashingReceiver, but subsequent rotations are timelocked: queue the new address with setMessenger / setSlasher, then call activateMessenger() / activateSlasher() after SENDER_ACTIVATION_DELAY (2 days) elapses. Document the queue/activate pair as two transactions in the runbook so operators know to schedule the activation tx before the delay window closes. (The L2SlashingReceiver auth-surface table was already updated in the previous commit on this branch.) * docs(release-notes): add tnt-core v0.13.0 release notes New /release-notes/0.13.0 page documenting the v0.12.0/v0.13.0 BREAKING changes (EIP-712 quote requester binding, ITangleSlashing event reshape, Types.ServiceRequest.activated reorder, forceRemoveAllowsBelowMin BSM hook), the round-2 hardening fixes (slashing nonReentrant + admin self-dispute, service lifecycle gates, MBSM grace-window pinning, L2 slashing receiver timelock + CEI revert, beacon SSZ canonical endianness, TNTLockFactory beneficiary gate), and a migration checklist for operator quote servers, indexers, custom BSMs, MBSM operators, L2 receiver operators, beacon proof builders, and SLASH_ADMIN holders. Cites tnt-core PRs #124 and #125 and links the bindings CHANGELOG. Adds top-level "Release Notes" entry to pages/_meta.ts so the section is discoverable from the global navigation.
1 parent e976e83 commit 47be8cd

18 files changed

Lines changed: 723 additions & 42 deletions

‎pages/_meta.ts‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -68,6 +68,10 @@ const meta: Meta = {
6868
title: "Protocol",
6969
type: "page",
7070
},
71+
"release-notes": {
72+
title: "Release Notes",
73+
type: "page",
74+
},
7175
};
7276

7377
export default meta;

‎pages/developers/api/reference/IBlueprintServiceManager.mdx‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -186,6 +186,63 @@ _Defines minimum commitment and exit queue timing_
186186
| exitQueueDuration | uint64 | Time between scheduling exit and completing it (seconds) |
187187
| forceExitAllowed | bool | Whether service owner can force-exit operators |
188188

189+
#### getNonPaymentTerminationPolicy
190+
191+
```solidity
192+
function getNonPaymentTerminationPolicy(uint64 serviceId) external view returns (bool useDefault, uint64 graceIntervals)
193+
```
194+
195+
Get the non-payment termination policy for subscription services.
196+
197+
Core computes eligibility as
198+
`lastPaymentAt + subscriptionInterval + (subscriptionInterval * graceIntervals)`.
199+
`graceIntervals = 0` means termination is eligible immediately at the first missed
200+
billing tick. Implementations should return `useDefault = true` unless they need
201+
custom grace behavior. Default implementation in `BlueprintServiceManagerBase` returns
202+
`(true, 0)`.
203+
204+
##### Parameters
205+
206+
| Name | Type | Description |
207+
| --------- | ------ | -------------- |
208+
| serviceId | uint64 | The service ID |
209+
210+
##### Return Values
211+
212+
| Name | Type | Description |
213+
| -------------- | ------ | ---------------------------------------------------------------- |
214+
| useDefault | bool | True to use the protocol default policy |
215+
| graceIntervals | uint64 | Additional full intervals to wait after the first missed payment |
216+
217+
#### forceRemoveAllowsBelowMin
218+
219+
```solidity
220+
function forceRemoveAllowsBelowMin(uint64 serviceId) external view returns (bool ok)
221+
```
222+
223+
Whether `forceRemoveOperator` may drop the service below `minOperators`.
224+
225+
By default the protocol enforces `operatorCount > minOperators` even when a blueprint
226+
manager calls `forceRemoveOperator`. A blueprint that genuinely needs
227+
emergency-eviction-below-min must self-document by returning `true`. Reverting or
228+
unimplemented => the protocol enforces the floor (fail-closed). The default
229+
implementation in `BlueprintServiceManagerBase` returns `false`; custom managers that
230+
do **not** inherit `BlueprintServiceManagerBase` MUST implement this hook explicitly
231+
or `forceRemoveOperator` will revert as soon as the eviction would push the operator
232+
count below `minOperators`.
233+
234+
##### Parameters
235+
236+
| Name | Type | Description |
237+
| --------- | ------ | -------------- |
238+
| serviceId | uint64 | The service ID |
239+
240+
##### Return Values
241+
242+
| Name | Type | Description |
243+
| ---- | ---- | ------------------------------------------------------- |
244+
| ok | bool | True to allow eviction below the minimum operator count |
245+
189246
#### onRequest
190247

191248
```solidity

‎pages/developers/api/reference/IMBSMRegistry.mdx‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -89,7 +89,13 @@ Get the latest revision number registered in the registry
8989
function pinBlueprint(uint64 blueprintId, uint32 revision) external
9090
```
9191

92-
Pin a blueprint to a specific revision (0 disallowed)
92+
Pin a blueprint to a specific revision (0 disallowed).
93+
94+
Reverts if `revision` is currently inside the deprecation grace window. Pinning a blueprint
95+
to a revision that is itself deprecated would defeat the deprecation flow: `getMBSM` would
96+
return `address(0)` the moment `completeDeprecation` ran, breaking every BSM call for the
97+
pinned blueprint. Choose a revision that is not scheduled for deprecation, or wait until
98+
the deprecation has fully completed before pinning to a different revision.
9399

94100
#### unpinBlueprint
95101

‎pages/developers/api/reference/ITangleSlashing.mdx‎

Lines changed: 103 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -11,12 +11,15 @@ Source: https://github.com/tangle-network/tnt-core/blob/main/src/interfaces/ITan
1111

1212
Slashing interface for Tangle protocol
1313

14+
The event declarations on this interface mirror what the protocol actually emits from `SlashingLib`.
15+
Off-chain consumers (Rust bindings, indexers) MUST decode against the shapes documented below.
16+
1417
#### Functions
1518

1619
#### proposeSlash
1720

1821
```solidity
19-
function proposeSlash(uint64 serviceId, address operator, uint256 amount, bytes32 evidence) external returns (uint64 slashId)
22+
function proposeSlash(uint64 serviceId, address operator, uint16 slashBps, bytes32 evidence) external returns (uint64 slashId)
2023
```
2124

2225
Propose a slash against an operator
@@ -27,8 +30,8 @@ Propose a slash against an operator
2730
| --------- | ------- | ------------------------------------ |
2831
| serviceId | uint64 | The service where violation occurred |
2932
| operator | address | The operator to slash |
30-
| amount | uint256 | Amount to slash |
31-
| evidence | bytes32 | Evidence hash |
33+
| slashBps | uint16 | Slash percentage in basis points |
34+
| evidence | bytes32 | Evidence hash (must be non-zero) |
3235

3336
##### Return Values
3437

@@ -39,10 +42,14 @@ Propose a slash against an operator
3942
#### disputeSlash
4043

4144
```solidity
42-
function disputeSlash(uint64 slashId, string reason) external
45+
function disputeSlash(uint64 slashId, string reason) external payable
4346
```
4447

45-
Dispute a slash proposal
48+
Dispute a slash proposal.
49+
50+
`payable` because the implementation requires `msg.value == config.disputeBond` when the bond
51+
is non-zero (and zero otherwise). Typed callers MUST use a payable reference so
52+
`disputeSlash{value: bond}(...)` compiles.
4653

4754
#### executeSlash
4855

@@ -79,11 +86,22 @@ Cancel a slash proposal
7986
#### setSlashConfig
8087

8188
```solidity
82-
function setSlashConfig(uint64 disputeWindow, bool instantSlashEnabled, uint16 maxSlashBps) external
89+
function setSlashConfig(uint64 disputeWindow, bool instantSlashEnabled, uint16 maxSlashBps, uint64 disputeResolutionDeadline, uint256 disputeBond, uint16 maxPendingSlashesPerOperator) external
8390
```
8491

8592
Update slashing configuration
8693

94+
##### Parameters
95+
96+
| Name | Type | Description |
97+
| ---------------------------- | ------- | ---------------------------------------------------------------- |
98+
| disputeWindow | uint64 | Time after `proposeSlash` during which the operator can dispute |
99+
| instantSlashEnabled | bool | Reserved emergency toggle (no effect through the standard API) |
100+
| maxSlashBps | uint16 | Hard cap on any single slash proposal |
101+
| disputeResolutionDeadline | uint64 | Time `SLASH_ADMIN` has to resolve a dispute before it auto-fails |
102+
| disputeBond | uint256 | Native asset bond required to dispute (0 = disabled) |
103+
| maxPendingSlashesPerOperator | uint16 | Cap on concurrent pending slashes per operator (anti-spam) |
104+
87105
#### getSlashProposal
88106

89107
```solidity
@@ -92,16 +110,93 @@ function getSlashProposal(uint64 slashId) external view returns (struct Slashing
92110

93111
Get slash proposal details
94112

113+
#### getSlashConfig
114+
115+
```solidity
116+
function getSlashConfig() external view returns (struct SlashingLib.SlashConfig)
117+
```
118+
119+
Get the current slashing configuration. Returns the live `SlashConfig` tuple containing
120+
`disputeWindow`, `instantSlashEnabled`, `maxSlashBps`, `disputeResolutionDeadline`,
121+
`disputeBond`, and `maxPendingSlashesPerOperator`.
122+
95123
#### Events
96124

97125
#### SlashProposed
98126

99127
```solidity
100-
event SlashProposed(uint64 serviceId, address operator, uint256 amount, bytes32 evidence)
128+
event SlashProposed(uint64 indexed slashId, uint64 indexed serviceId, address indexed operator, address proposer, uint16 slashBps, uint16 effectiveSlashBps, bytes32 evidence, uint64 executeAfter)
101129
```
102130

131+
Emitted when a new slash proposal is created.
132+
133+
##### Parameters
134+
135+
| Name | Type | Description |
136+
| ----------------- | ------- | ----------------------------------------------------------------------- |
137+
| slashId | uint64 | The new slash ID (indexed) |
138+
| serviceId | uint64 | The service where the violation occurred (indexed) |
139+
| operator | address | The slashed operator (indexed) |
140+
| proposer | address | The address that called `proposeSlash` |
141+
| slashBps | uint16 | Requested slash percentage in basis points |
142+
| effectiveSlashBps | uint16 | Slash percentage after exposure scaling (what will actually be applied) |
143+
| evidence | bytes32 | Evidence hash (non-zero, enforced by `proposeSlash`) |
144+
| executeAfter | uint64 | Earliest UNIX timestamp at which the slash can be executed |
145+
146+
#### SlashDisputed
147+
148+
```solidity
149+
event SlashDisputed(uint64 indexed slashId, address indexed disputer, string reason)
150+
```
151+
152+
Emitted when a slash proposal is disputed by the operator or by `SLASH_ADMIN_ROLE`.
153+
154+
##### Parameters
155+
156+
| Name | Type | Description |
157+
| -------- | ------- | ------------------------------------------ |
158+
| slashId | uint64 | The disputed slash ID (indexed) |
159+
| disputer | address | The address that called `disputeSlash` |
160+
| reason | string | Human-readable rationale (free-form input) |
161+
103162
#### SlashExecuted
104163

105164
```solidity
106-
event SlashExecuted(uint64 serviceId, address operator, uint256 amount)
165+
event SlashExecuted(uint64 indexed slashId, uint64 indexed serviceId, address indexed operator, uint256 actualSlashed)
166+
```
167+
168+
Emitted when a slash is executed.
169+
170+
##### Parameters
171+
172+
| Name | Type | Description |
173+
| ------------- | ------- | -------------------------------------------------- |
174+
| slashId | uint64 | The executed slash ID (indexed) |
175+
| serviceId | uint64 | The service the slash was applied to (indexed) |
176+
| operator | address | The slashed operator (indexed) |
177+
| actualSlashed | uint256 | Total stake actually burned in the underlying call |
178+
179+
#### SlashCancelled
180+
181+
```solidity
182+
event SlashCancelled(uint64 indexed slashId, address indexed canceller, string reason)
107183
```
184+
185+
Emitted when a slash proposal is cancelled by `SLASH_ADMIN_ROLE`.
186+
187+
##### Parameters
188+
189+
| Name | Type | Description |
190+
| --------- | ------- | ------------------------------------------- |
191+
| slashId | uint64 | The cancelled slash ID (indexed) |
192+
| canceller | address | Address that called `cancelSlash` (indexed) |
193+
| reason | string | Human-readable rationale (free-form input) |
194+
195+
#### SlashConfigUpdated
196+
197+
```solidity
198+
event SlashConfigUpdated(uint64 disputeWindow, bool instantSlashEnabled, uint16 maxSlashBps, uint64 disputeResolutionDeadline, uint256 disputeBond, uint16 maxPendingSlashesPerOperator)
199+
```
200+
201+
Emitted when `setSlashConfig` updates the slashing configuration. The full new
202+
configuration is included in the event.

‎pages/developers/api/reference/generated/IBlueprintServiceManager.mdx‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -186,6 +186,63 @@ _Defines minimum commitment and exit queue timing_
186186
| exitQueueDuration | uint64 | Time between scheduling exit and completing it (seconds) |
187187
| forceExitAllowed | bool | Whether service owner can force-exit operators |
188188

189+
#### getNonPaymentTerminationPolicy
190+
191+
```solidity
192+
function getNonPaymentTerminationPolicy(uint64 serviceId) external view returns (bool useDefault, uint64 graceIntervals)
193+
```
194+
195+
Get the non-payment termination policy for subscription services.
196+
197+
Core computes eligibility as
198+
`lastPaymentAt + subscriptionInterval + (subscriptionInterval * graceIntervals)`.
199+
`graceIntervals = 0` means termination is eligible immediately at the first missed
200+
billing tick. Implementations should return `useDefault = true` unless they need
201+
custom grace behavior. Default implementation in `BlueprintServiceManagerBase` returns
202+
`(true, 0)`.
203+
204+
##### Parameters
205+
206+
| Name | Type | Description |
207+
| --------- | ------ | -------------- |
208+
| serviceId | uint64 | The service ID |
209+
210+
##### Return Values
211+
212+
| Name | Type | Description |
213+
| -------------- | ------ | ---------------------------------------------------------------- |
214+
| useDefault | bool | True to use the protocol default policy |
215+
| graceIntervals | uint64 | Additional full intervals to wait after the first missed payment |
216+
217+
#### forceRemoveAllowsBelowMin
218+
219+
```solidity
220+
function forceRemoveAllowsBelowMin(uint64 serviceId) external view returns (bool ok)
221+
```
222+
223+
Whether `forceRemoveOperator` may drop the service below `minOperators`.
224+
225+
By default the protocol enforces `operatorCount > minOperators` even when a blueprint
226+
manager calls `forceRemoveOperator`. A blueprint that genuinely needs
227+
emergency-eviction-below-min must self-document by returning `true`. Reverting or
228+
unimplemented => the protocol enforces the floor (fail-closed). The default
229+
implementation in `BlueprintServiceManagerBase` returns `false`; custom managers that
230+
do **not** inherit `BlueprintServiceManagerBase` MUST implement this hook explicitly
231+
or `forceRemoveOperator` will revert as soon as the eviction would push the operator
232+
count below `minOperators`.
233+
234+
##### Parameters
235+
236+
| Name | Type | Description |
237+
| --------- | ------ | -------------- |
238+
| serviceId | uint64 | The service ID |
239+
240+
##### Return Values
241+
242+
| Name | Type | Description |
243+
| ---- | ---- | ------------------------------------------------------- |
244+
| ok | bool | True to allow eviction below the minimum operator count |
245+
189246
#### onRequest
190247

191248
```solidity

‎pages/developers/api/reference/generated/IMBSMRegistry.mdx‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -89,7 +89,13 @@ Get the latest revision number registered in the registry
8989
function pinBlueprint(uint64 blueprintId, uint32 revision) external
9090
```
9191

92-
Pin a blueprint to a specific revision (0 disallowed)
92+
Pin a blueprint to a specific revision (0 disallowed).
93+
94+
Reverts if `revision` is currently inside the deprecation grace window. Pinning a blueprint
95+
to a revision that is itself deprecated would defeat the deprecation flow: `getMBSM` would
96+
return `address(0)` the moment `completeDeprecation` ran, breaking every BSM call for the
97+
pinned blueprint. Choose a revision that is not scheduled for deprecation, or wait until
98+
the deprecation has fully completed before pinning to a different revision.
9399

94100
#### unpinBlueprint
95101

0 commit comments

Comments
 (0)