Skip to content

Commit

Permalink
(chore): Update Functions v1 single line comments to nat spec (#10567)
Browse files Browse the repository at this point in the history
  • Loading branch information
@justinkaseman
justinkaseman committed Sep 8, 2023
1 parent cc85898 commit d3dfc5c
Show file tree
Hide file tree
Showing 17 changed files with 381 additions and 393 deletions.
68 changes: 32 additions & 36 deletions contracts/src/v0.8/functions/dev/1_0_0/FunctionsBilling.sol
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,11 +10,9 @@ import {FunctionsResponse} from "./libraries/FunctionsResponse.sol";

import {SafeCast} from "../../../vendor/openzeppelin-solidity/v4.8.0/contracts/utils/math/SafeCast.sol";

/**
* @title Functions Billing contract
* @notice Contract that calculates payment from users to the nodes of the Decentralized Oracle Network (DON).
* @dev THIS CONTRACT HAS NOT GONE THROUGH ANY SECURITY REVIEW. DO NOT USE IN PROD.
*/
/// @title Functions Billing contract
/// @notice Contract that calculates payment from users to the nodes of the Decentralized Oracle Network (DON).
/// @dev THIS CONTRACT HAS NOT GONE THROUGH ANY SECURITY REVIEW. DO NOT USE IN PROD.
abstract contract FunctionsBilling is Routable, IFunctionsBilling {
using FunctionsResponse for FunctionsResponse.RequestMeta;
using FunctionsResponse for FunctionsResponse.Commitment;
Expand Down Expand Up @@ -82,14 +80,14 @@ abstract contract FunctionsBilling is Routable, IFunctionsBilling {
// | Configuration |
// ================================================================

// @notice Gets the Chainlink Coordinator's billing configuration
// @return config
/// @notice Gets the Chainlink Coordinator's billing configuration
/// @return config
function getConfig() external view returns (Config memory) {
return s_config;
}

// @notice Sets the Chainlink Coordinator's billing configuration
// @param config - See the contents of the Config struct in IFunctionsBilling.Config for more information
/// @notice Sets the Chainlink Coordinator's billing configuration
/// @param config - See the contents of the Config struct in IFunctionsBilling.Config for more information
function updateConfig(Config memory config) public {
_onlyOwner();

Expand All @@ -101,17 +99,17 @@ abstract contract FunctionsBilling is Routable, IFunctionsBilling {
// | Fee Calculation |
// ================================================================

// @inheritdoc IFunctionsBilling
/// @inheritdoc IFunctionsBilling
function getDONFee(bytes memory /* requestData */) public view override returns (uint72) {
return s_config.donFee;
}

// @inheritdoc IFunctionsBilling
/// @inheritdoc IFunctionsBilling
function getAdminFee() public view override returns (uint72) {
return _getRouter().getAdminFee();
}

// @inheritdoc IFunctionsBilling
/// @inheritdoc IFunctionsBilling
function getWeiPerUnitLink() public view returns (uint256) {
Config memory config = s_config;
(, int256 weiPerUnitLink, , uint256 timestamp, ) = s_linkToNativeFeed.latestRoundData();
Expand All @@ -135,7 +133,7 @@ abstract contract FunctionsBilling is Routable, IFunctionsBilling {
// | Cost Estimation |
// ================================================================

// @inheritdoc IFunctionsBilling
/// @inheritdoc IFunctionsBilling
function estimateCost(
uint64 subscriptionId,
bytes calldata data,
Expand All @@ -152,7 +150,7 @@ abstract contract FunctionsBilling is Routable, IFunctionsBilling {
return _calculateCostEstimate(callbackGasLimit, gasPriceWei, donFee, adminFee);
}

// @notice Estimate the cost in Juels of LINK
/// @notice Estimate the cost in Juels of LINK
// that will be charged to a subscription to fulfill a Functions request
// Gas Price can be overestimated to account for flucuations between request and response time
function _calculateCostEstimate(
Expand All @@ -165,7 +163,7 @@ abstract contract FunctionsBilling is Routable, IFunctionsBilling {

uint256 gasPriceWithOverestimation = gasPriceWei +
((gasPriceWei * s_config.fulfillmentGasPriceOverEstimationBP) / 10_000);
// @NOTE: Basis Points are 1/100th of 1%, divide by 10_000 to bring back to original units
/// @NOTE: Basis Points are 1/100th of 1%, divide by 10_000 to bring back to original units

uint96 juelsPerGas = _getJuelsPerGas(gasPriceWithOverestimation);
uint256 estimatedGasReimbursement = juelsPerGas * executionGas;
Expand All @@ -178,12 +176,10 @@ abstract contract FunctionsBilling is Routable, IFunctionsBilling {
// | Billing |
// ================================================================

// @notice Initiate the billing process for an Functions request
// @dev Only callable by the Functions Router
// @param data - Encoded Chainlink Functions request data, use FunctionsClient API to encode a request
// @param requestDataVersion - Version number of the structure of the request data
// @param billing - Billing configuration for the request
// @return commitment - The parameters of the request that must be held consistent at response time
/// @notice Initiate the billing process for an Functions request
/// @dev Only callable by the Functions Router
/// @param request - Chainlink Functions request data, see FunctionsResponse.RequestMeta for the structure
/// @return commitment - The parameters of the request that must be held consistent at response time
function _startBilling(
FunctionsResponse.RequestMeta memory request
) internal returns (FunctionsResponse.Commitment memory commitment) {
Expand Down Expand Up @@ -233,8 +229,8 @@ abstract contract FunctionsBilling is Routable, IFunctionsBilling {
return commitment;
}

// @notice Generate a keccak hash request ID
// @dev uses the number of requests that the consumer of a subscription has sent as a nonce
/// @notice Generate a keccak hash request ID
/// @dev uses the number of requests that the consumer of a subscription has sent as a nonce
function _computeRequestId(
address don,
address client,
Expand All @@ -244,13 +240,13 @@ abstract contract FunctionsBilling is Routable, IFunctionsBilling {
return keccak256(abi.encode(don, client, subscriptionId, nonce));
}

// @notice Finalize billing process for an Functions request by sending a callback to the Client contract and then charging the subscription
// @param requestId identifier for the request that was generated by the Registry in the beginBilling commitment
// @param response response data from DON consensus
// @param err error from DON consensus
// @return result fulfillment result
// @dev Only callable by a node that has been approved on the Coordinator
// @dev simulated offchain to determine if sufficient balance is present to fulfill the request
/// @notice Finalize billing process for an Functions request by sending a callback to the Client contract and then charging the subscription
/// @param requestId identifier for the request that was generated by the Registry in the beginBilling commitment
/// @param response response data from DON consensus
/// @param err error from DON consensus
/// @return result fulfillment result
/// @dev Only callable by a node that has been approved on the Coordinator
/// @dev simulated offchain to determine if sufficient balance is present to fulfill the request
function _fulfillAndBill(
bytes32 requestId,
bytes memory response,
Expand Down Expand Up @@ -305,9 +301,9 @@ abstract contract FunctionsBilling is Routable, IFunctionsBilling {
// | Request Timeout |
// ================================================================

// @inheritdoc IFunctionsBilling
// @dev Only callable by the Router
// @dev Used by FunctionsRouter.sol during timeout of a request
/// @inheritdoc IFunctionsBilling
/// @dev Only callable by the Router
/// @dev Used by FunctionsRouter.sol during timeout of a request
function deleteCommitment(bytes32 requestId) external override onlyRouter {
// Delete commitment
delete s_requestCommitments[requestId];
Expand All @@ -318,7 +314,7 @@ abstract contract FunctionsBilling is Routable, IFunctionsBilling {
// | Fund withdrawal |
// ================================================================

// @inheritdoc IFunctionsBilling
/// @inheritdoc IFunctionsBilling
function oracleWithdraw(address recipient, uint96 amount) external {
_disperseFeePool();

Expand All @@ -331,8 +327,8 @@ abstract contract FunctionsBilling is Routable, IFunctionsBilling {
IFunctionsSubscriptions(address(_getRouter())).oracleWithdraw(recipient, amount);
}

// @inheritdoc IFunctionsBilling
// @dev Only callable by the Coordinator owner
/// @inheritdoc IFunctionsBilling
/// @dev Only callable by the Coordinator owner
function oracleWithdrawAll() external {
_onlyOwner();
_disperseFeePool();
Expand Down
26 changes: 13 additions & 13 deletions contracts/src/v0.8/functions/dev/1_0_0/FunctionsClient.sol
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,8 +6,8 @@ import {IFunctionsClient} from "./interfaces/IFunctionsClient.sol";

import {FunctionsRequest} from "./libraries/FunctionsRequest.sol";

// @title The Chainlink Functions client contract
// @notice Contract developers can inherit this contract in order to make Chainlink Functions requests
/// @title The Chainlink Functions client contract
/// @notice Contract developers can inherit this contract in order to make Chainlink Functions requests
abstract contract FunctionsClient is IFunctionsClient {
using FunctionsRequest for FunctionsRequest.Request;

Expand All @@ -22,11 +22,11 @@ abstract contract FunctionsClient is IFunctionsClient {
i_router = IFunctionsRouter(router);
}

// @notice Sends a Chainlink Functions request
// @param data The CBOR encoded bytes data for a Functions request
// @param subscriptionId The subscription ID that will be charged to service the request
// @param callbackGasLimit the amount of gas that will be available for the fulfillment callback
// @return requestId The generated request ID for this request
/// @notice Sends a Chainlink Functions request
/// @param data The CBOR encoded bytes data for a Functions request
/// @param subscriptionId The subscription ID that will be charged to service the request
/// @param callbackGasLimit the amount of gas that will be available for the fulfillment callback
/// @return requestId The generated request ID for this request
function _sendRequest(
bytes memory data,
uint64 subscriptionId,
Expand All @@ -44,14 +44,14 @@ abstract contract FunctionsClient is IFunctionsClient {
return requestId;
}

// @notice User defined function to handle a response from the DON
// @param requestId The request ID, returned by sendRequest()
// @param response Aggregated response from the execution of the user's source code
// @param err Aggregated error from the execution of the user code or from the execution pipeline
// @dev Either response or error parameter will be set, but never both
/// @notice User defined function to handle a response from the DON
/// @param requestId The request ID, returned by sendRequest()
/// @param response Aggregated response from the execution of the user's source code
/// @param err Aggregated error from the execution of the user code or from the execution pipeline
/// @dev Either response or error parameter will be set, but never both
function fulfillRequest(bytes32 requestId, bytes memory response, bytes memory err) internal virtual;

// @inheritdoc IFunctionsClient
/// @inheritdoc IFunctionsClient
function handleOracleFulfillment(bytes32 requestId, bytes memory response, bytes memory err) external override {
if (msg.sender != address(i_router)) {
revert OnlyRouterCanFulfill();
Expand Down
28 changes: 14 additions & 14 deletions contracts/src/v0.8/functions/dev/1_0_0/FunctionsCoordinator.sol
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,15 +9,15 @@ import {FunctionsBilling} from "./FunctionsBilling.sol";
import {OCR2Base} from "./ocr/OCR2Base.sol";
import {FunctionsResponse} from "./libraries/FunctionsResponse.sol";

// @title Functions Coordinator contract
// @notice Contract that nodes of a Decentralized Oracle Network (DON) interact with
// @dev THIS CONTRACT HAS NOT GONE THROUGH ANY SECURITY REVIEW. DO NOT USE IN PROD.
/// @title Functions Coordinator contract
/// @notice Contract that nodes of a Decentralized Oracle Network (DON) interact with
/// @dev THIS CONTRACT HAS NOT GONE THROUGH ANY SECURITY REVIEW. DO NOT USE IN PROD.
contract FunctionsCoordinator is OCR2Base, IFunctionsCoordinator, FunctionsBilling {
using FunctionsResponse for FunctionsResponse.RequestMeta;
using FunctionsResponse for FunctionsResponse.Commitment;
using FunctionsResponse for FunctionsResponse.FulfillResult;

// @inheritdoc ITypeAndVersion
/// @inheritdoc ITypeAndVersion
string public constant override typeAndVersion = "Functions Coordinator v1.0.0";

event OracleRequest(
Expand Down Expand Up @@ -47,39 +47,39 @@ contract FunctionsCoordinator is OCR2Base, IFunctionsCoordinator, FunctionsBilli
address linkToNativeFeed
) OCR2Base(true) FunctionsBilling(router, config, linkToNativeFeed) {}

// @inheritdoc IFunctionsCoordinator
/// @inheritdoc IFunctionsCoordinator
function getThresholdPublicKey() external view override returns (bytes memory) {
if (s_thresholdPublicKey.length == 0) {
revert EmptyPublicKey();
}
return s_thresholdPublicKey;
}

// @inheritdoc IFunctionsCoordinator
/// @inheritdoc IFunctionsCoordinator
function setThresholdPublicKey(bytes calldata thresholdPublicKey) external override onlyOwner {
if (thresholdPublicKey.length == 0) {
revert EmptyPublicKey();
}
s_thresholdPublicKey = thresholdPublicKey;
}

// @inheritdoc IFunctionsCoordinator
/// @inheritdoc IFunctionsCoordinator
function getDONPublicKey() external view override returns (bytes memory) {
if (s_donPublicKey.length == 0) {
revert EmptyPublicKey();
}
return s_donPublicKey;
}

// @inheritdoc IFunctionsCoordinator
/// @inheritdoc IFunctionsCoordinator
function setDONPublicKey(bytes calldata donPublicKey) external override onlyOwner {
if (donPublicKey.length == 0) {
revert EmptyPublicKey();
}
s_donPublicKey = donPublicKey;
}

// @dev check if node is in current transmitter list
/// @dev check if node is in current transmitter list
function _isTransmitter(address node) internal view returns (bool) {
address[] memory nodes = s_transmitters;
// Bounded by "maxNumOracles" on OCR2Abstract.sol
Expand All @@ -91,7 +91,7 @@ contract FunctionsCoordinator is OCR2Base, IFunctionsCoordinator, FunctionsBilli
return false;
}

// @inheritdoc IFunctionsCoordinator
/// @inheritdoc IFunctionsCoordinator
function startRequest(
FunctionsResponse.RequestMeta calldata request
) external override onlyRouter returns (FunctionsResponse.Commitment memory commitment) {
Expand All @@ -113,19 +113,19 @@ contract FunctionsCoordinator is OCR2Base, IFunctionsCoordinator, FunctionsBilli
return commitment;
}

// DON fees are pooled together. If the OCR configuration is going to change, these need to be distributed.
/// @dev DON fees are pooled together. If the OCR configuration is going to change, these need to be distributed.
function _beforeSetConfig(uint8 /* _f */, bytes memory /* _onchainConfig */) internal override {
if (_getTransmitters().length > 0) {
_disperseFeePool();
}
}

// Used by FunctionsBilling.sol
/// @dev Used by FunctionsBilling.sol
function _getTransmitters() internal view override returns (address[] memory) {
return s_transmitters;
}

// Report hook called within OCR2Base.sol
/// @dev Report hook called within OCR2Base.sol
function _report(
uint256 /*initialGas*/,
address /*transmitter*/,
Expand Down Expand Up @@ -171,7 +171,7 @@ contract FunctionsCoordinator is OCR2Base, IFunctionsCoordinator, FunctionsBilli
}
}

// Used in FunctionsBilling.sol
/// @dev Used in FunctionsBilling.sol
function _onlyOwner() internal view override {
_validateOwnership();
}
Expand Down
Loading

0 comments on commit d3dfc5c

Please sign in to comment.