Skip to content

Commit 6435f64

Browse files
committed
chore: natspec documentation changes on subgraph service contracts
Signed-off-by: Tomás Migone <[email protected]>
1 parent 28c5bda commit 6435f64

File tree

15 files changed

+556
-299
lines changed

15 files changed

+556
-299
lines changed

packages/subgraph-service/contracts/DisputeManager.sol

Lines changed: 55 additions & 165 deletions
Large diffs are not rendered by default.

packages/subgraph-service/contracts/SubgraphService.sol

Lines changed: 37 additions & 97 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@ import { IGraphPayments } from "@graphprotocol/horizon/contracts/interfaces/IGra
55
import { IGraphToken } from "@graphprotocol/contracts/contracts/token/IGraphToken.sol";
66
import { IGraphTallyCollector } from "@graphprotocol/horizon/contracts/interfaces/IGraphTallyCollector.sol";
77
import { IRewardsIssuer } from "@graphprotocol/contracts/contracts/rewards/IRewardsIssuer.sol";
8+
import { IDataService } from "@graphprotocol/horizon/contracts/data-service/interfaces/IDataService.sol";
89
import { ISubgraphService } from "./interfaces/ISubgraphService.sol";
910

1011
import { OwnableUpgradeable } from "@openzeppelin/contracts-upgradeable/access/OwnableUpgradeable.sol";
@@ -71,15 +72,7 @@ contract SubgraphService is
7172
_disableInitializers();
7273
}
7374

74-
/**
75-
* @notice Initialize the contract
76-
* @dev The thawingPeriod and verifierCut ranges are not set here because they are variables
77-
* on the DisputeManager. We use the {ProvisionManager} overrideable getters to get the ranges.
78-
* @param owner The owner of the contract
79-
* @param minimumProvisionTokens The minimum amount of provisioned tokens required to create an allocation
80-
* @param maximumDelegationRatio The maximum delegation ratio allowed for an allocation
81-
* @param stakeToFeesRatio The ratio of stake to fees to lock when collecting query fees
82-
*/
75+
/// @inheritdoc ISubgraphService
8376
function initialize(
8477
address owner,
8578
uint256 minimumProvisionTokens,
@@ -115,6 +108,7 @@ contract SubgraphService is
115108
* - address `rewardsDestination`: The address where the indexer wants to receive indexing rewards.
116109
* Use zero address for automatic reprovisioning to the subgraph service.
117110
*/
111+
/// @inheritdoc IDataService
118112
function register(
119113
address indexer,
120114
bytes calldata data
@@ -150,6 +144,7 @@ contract SubgraphService is
150144
*
151145
* @param indexer The address of the indexer to accept the provision for
152146
*/
147+
/// @inheritdoc IDataService
153148
function acceptProvisionPendingParameters(
154149
address indexer,
155150
bytes calldata
@@ -183,6 +178,7 @@ contract SubgraphService is
183178
* - address `allocationId`: The id of the allocation
184179
* - bytes `allocationProof`: Signed proof of the allocation id address ownership
185180
*/
181+
/// @inheritdoc IDataService
186182
function startService(
187183
address indexer,
188184
bytes calldata data
@@ -198,7 +194,7 @@ contract SubgraphService is
198194
data,
199195
(bytes32, uint256, address, bytes)
200196
);
201-
_allocate(indexer, allocationId, subgraphDeploymentId, tokens, allocationProof, delegationRatio);
197+
_allocate(indexer, allocationId, subgraphDeploymentId, tokens, allocationProof, _delegationRatio);
202198
emit ServiceStarted(indexer, data);
203199
}
204200

@@ -221,6 +217,7 @@ contract SubgraphService is
221217
* @param data Encoded data:
222218
* - address `allocationId`: The id of the allocation
223219
*/
220+
/// @inheritdoc IDataService
224221
function stopService(
225222
address indexer,
226223
bytes calldata data
@@ -253,8 +250,8 @@ contract SubgraphService is
253250
*
254251
* @param indexer The address of the indexer
255252
* @param paymentType The type of payment to collect as defined in {IGraphPayments}
256-
* @param data Encoded data to fulfill the payment. The structure of the data depends on the payment type. See above.
257253
*/
254+
/// @inheritdoc IDataService
258255
function collect(
259256
address indexer,
260257
IGraphPayments.PaymentTypes paymentType,
@@ -283,7 +280,7 @@ contract SubgraphService is
283280
_allocations.get(allocationId).indexer == indexer,
284281
SubgraphServiceAllocationNotAuthorized(indexer, allocationId)
285282
);
286-
paymentCollected = _collectIndexingRewards(allocationId, poi, delegationRatio);
283+
paymentCollected = _collectIndexingRewards(allocationId, poi, _delegationRatio);
287284
} else {
288285
revert SubgraphServiceInvalidPaymentType(paymentType);
289286
}
@@ -293,38 +290,26 @@ contract SubgraphService is
293290
}
294291

295292
/**
296-
* @notice Slash an indexer
293+
* @notice See {IHorizonStaking-slash} for more details.
297294
* @dev Slashing is delegated to the {DisputeManager} contract which is the only one that can call this
298295
* function.
299-
*
300-
* See {IHorizonStaking-slash} for more details.
301-
*
302-
* Emits a {ServiceProviderSlashed} event.
303-
*
304-
* @param indexer The address of the indexer to be slashed
305-
* @param data Encoded data:
306-
* - uint256 `tokens`: The amount of tokens to slash
307-
* - uint256 `reward`: The amount of tokens to reward the slasher
308296
*/
297+
/// @inheritdoc IDataService
309298
function slash(address indexer, bytes calldata data) external override onlyDisputeManager {
310299
(uint256 tokens, uint256 reward) = abi.decode(data, (uint256, uint256));
311300
_graphStaking().slash(indexer, tokens, reward, address(_disputeManager()));
312301
emit ServiceProviderSlashed(indexer, tokens);
313302
}
314303

315-
/**
316-
* @notice See {ISubgraphService.closeStaleAllocation}
317-
*/
304+
/// @inheritdoc ISubgraphService
318305
function closeStaleAllocation(address allocationId) external override whenNotPaused {
319306
Allocation.State memory allocation = _allocations.get(allocationId);
320307
require(allocation.isStale(maxPOIStaleness), SubgraphServiceCannotForceCloseAllocation(allocationId));
321308
require(!allocation.isAltruistic(), SubgraphServiceAllocationIsAltruistic(allocationId));
322309
_closeAllocation(allocationId);
323310
}
324311

325-
/**
326-
* @notice See {ISubgraphService.resizeAllocation}
327-
*/
312+
/// @inheritdoc ISubgraphService
328313
function resizeAllocation(
329314
address indexer,
330315
address allocationId,
@@ -340,12 +325,10 @@ contract SubgraphService is
340325
_allocations.get(allocationId).indexer == indexer,
341326
SubgraphServiceAllocationNotAuthorized(indexer, allocationId)
342327
);
343-
_resizeAllocation(allocationId, tokens, delegationRatio);
328+
_resizeAllocation(allocationId, tokens, _delegationRatio);
344329
}
345330

346-
/**
347-
* @notice See {ISubgraphService.migrateLegacyAllocation}
348-
*/
331+
/// @inheritdoc ISubgraphService
349332
function migrateLegacyAllocation(
350333
address indexer,
351334
address allocationId,
@@ -354,79 +337,49 @@ contract SubgraphService is
354337
_migrateLegacyAllocation(indexer, allocationId, subgraphDeploymentID);
355338
}
356339

357-
/**
358-
* @notice See {ISubgraphService.setPauseGuardian}
359-
*/
340+
/// @inheritdoc ISubgraphService
360341
function setPauseGuardian(address pauseGuardian, bool allowed) external override onlyOwner {
361342
_setPauseGuardian(pauseGuardian, allowed);
362343
}
363344

364-
/**
365-
* @notice See {ISubgraphService.setRewardsDestination}
366-
*/
345+
/// @inheritdoc ISubgraphService
367346
function setRewardsDestination(address rewardsDestination) external override {
368347
_setRewardsDestination(msg.sender, rewardsDestination);
369348
}
370349

371-
/**
372-
* @notice See {ISubgraphService.setMinimumProvisionTokens}
373-
*/
350+
/// @inheritdoc ISubgraphService
374351
function setMinimumProvisionTokens(uint256 minimumProvisionTokens) external override onlyOwner {
375352
_setProvisionTokensRange(minimumProvisionTokens, DEFAULT_MAX_PROVISION_TOKENS);
376353
}
377354

378-
/**
379-
* @notice See {ISubgraphService.setDelegationRatio}
380-
*/
355+
/// @inheritdoc ISubgraphService
381356
function setDelegationRatio(uint32 delegationRatio) external override onlyOwner {
382357
_setDelegationRatio(delegationRatio);
383358
}
384359

385-
/**
386-
* @notice See {ISubgraphService.setStakeToFeesRatio}
387-
*/
360+
/// @inheritdoc ISubgraphService
388361
function setStakeToFeesRatio(uint256 stakeToFeesRatio_) external override onlyOwner {
389362
_setStakeToFeesRatio(stakeToFeesRatio_);
390363
}
391364

392-
/**
393-
* @notice See {ISubgraphService.setMaxPOIStaleness}
394-
*/
365+
/// @inheritdoc ISubgraphService
395366
function setMaxPOIStaleness(uint256 maxPOIStaleness) external override onlyOwner {
396367
_setMaxPOIStaleness(maxPOIStaleness);
397368
}
398369

399-
/**
400-
* @notice See {ISubgraphService.setCurationCut}
401-
*/
370+
/// @inheritdoc ISubgraphService
402371
function setCurationCut(uint256 curationCut) external override onlyOwner {
403372
require(PPMMath.isValidPPM(curationCut), SubgraphServiceInvalidCurationCut(curationCut));
404373
curationFeesCut = curationCut;
405374
emit CurationCutSet(curationCut);
406375
}
407376

408-
/**
409-
* @notice See {ISubgraphService.getAllocation}
410-
*/
377+
/// @inheritdoc ISubgraphService
411378
function getAllocation(address allocationId) external view override returns (Allocation.State memory) {
412379
return _allocations[allocationId];
413380
}
414381

415-
/**
416-
* @notice Get allocation data to calculate rewards issuance
417-
* @dev Implements {IRewardsIssuer.getAllocationData}
418-
* @dev Note that this is slightly different than {getAllocation}. It returns an
419-
* unstructured subset of the allocation data, which is the minimum required to mint rewards.
420-
*
421-
* Should only be used by the {RewardsManager}.
422-
*
423-
* @param allocationId The allocation Id
424-
* @return indexer The indexer address
425-
* @return subgraphDeploymentId Subgraph deployment id for the allocation
426-
* @return tokens Amount of allocated tokens
427-
* @return accRewardsPerAllocatedToken Rewards snapshot
428-
* @return accRewardsPending Rewards pending to be minted due to allocation resize
429-
*/
382+
/// @inheritdoc IRewardsIssuer
430383
function getAllocationData(
431384
address allocationId
432385
) external view override returns (address, bytes32, uint256, uint256, uint256) {
@@ -440,57 +393,39 @@ contract SubgraphService is
440393
);
441394
}
442395

443-
/**
444-
* @notice Return the total amount of tokens allocated to subgraph.
445-
* @dev Implements {IRewardsIssuer.getSubgraphAllocatedTokens}
446-
* @dev To be used by the {RewardsManager}.
447-
* @param subgraphDeploymentId Deployment Id for the subgraph
448-
* @return Total tokens allocated to subgraph
449-
*/
396+
/// @inheritdoc IRewardsIssuer
450397
function getSubgraphAllocatedTokens(bytes32 subgraphDeploymentId) external view override returns (uint256) {
451398
return _subgraphAllocatedTokens[subgraphDeploymentId];
452399
}
453400

454-
/**
455-
* @notice See {ISubgraphService.getLegacyAllocation}
456-
*/
401+
/// @inheritdoc ISubgraphService
457402
function getLegacyAllocation(address allocationId) external view override returns (LegacyAllocation.State memory) {
458403
return _legacyAllocations[allocationId];
459404
}
460405

461-
/**
462-
* @notice See {ISubgraphService.getDisputeManager}
463-
*/
406+
/// @inheritdoc ISubgraphService
464407
function getDisputeManager() external view override returns (address) {
465408
return address(_disputeManager());
466409
}
467410

468-
/**
469-
* @notice See {ISubgraphService.getGraphTallyCollector}
470-
*/
411+
/// @inheritdoc ISubgraphService
471412
function getGraphTallyCollector() external view override returns (address) {
472413
return address(_graphTallyCollector());
473414
}
474415

475-
/**
476-
* @notice See {ISubgraphService.getCuration}
477-
*/
416+
/// @inheritdoc ISubgraphService
478417
function getCuration() external view override returns (address) {
479418
return address(_curation());
480419
}
481420

482-
/**
483-
* @notice See {ISubgraphService.encodeAllocationProof}
484-
*/
421+
/// @inheritdoc ISubgraphService
485422
function encodeAllocationProof(address indexer, address allocationId) external view override returns (bytes32) {
486423
return _encodeAllocationProof(indexer, allocationId);
487424
}
488425

489-
/**
490-
* @notice See {ISubgraphService.isOverAllocated}
491-
*/
426+
/// @inheritdoc ISubgraphService
492427
function isOverAllocated(address indexer) external view override returns (bool) {
493-
return _isOverAllocated(indexer, delegationRatio);
428+
return _isOverAllocated(indexer, _delegationRatio);
494429
}
495430

496431
// -- Data service parameter getters --
@@ -537,6 +472,7 @@ contract SubgraphService is
537472
* Emits a {QueryFeesCollected} event.
538473
*
539474
* @param _signedRav Signed RAV
475+
* @return feesCollected The amount of fees collected
540476
*/
541477
function _collectQueryFees(
542478
IGraphTallyCollector.SignedRAV memory _signedRav
@@ -591,6 +527,10 @@ contract SubgraphService is
591527
return tokensCollected;
592528
}
593529

530+
/**
531+
* @notice Set the stake to fees ratio.
532+
* @param _stakeToFeesRatio The stake to fees ratio
533+
*/
594534
function _setStakeToFeesRatio(uint256 _stakeToFeesRatio) private {
595535
require(_stakeToFeesRatio != 0, SubgraphServiceInvalidZeroStakeToFeesRatio());
596536
stakeToFeesRatio = _stakeToFeesRatio;

0 commit comments

Comments
 (0)