Skip to content

Commit f07d661

Browse files
zguesmizguesmi
authored
docs: Update doc and diagrams (#279)
1 parent 72a3854 commit f07d661

File tree

8 files changed

+3121
-3028
lines changed

8 files changed

+3121
-3028
lines changed

‎docs/solidity/index.md‎

Lines changed: 134 additions & 148 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,21 @@
11
# Solidity API
22

3+
## IexecInterfaceNative
4+
5+
A global interface that aggregates all the interfaces needed to interact with
6+
the PoCo contracts in native mode.
7+
8+
_Referenced in the SDK with the current path `contracts/IexecInterfaceNative.sol`.
9+
Changing the name or the path would cause a breaking change in the SDK._
10+
11+
## IexecInterfaceToken
12+
13+
A global interface that aggregates all the interfaces needed to interact with
14+
the PoCo contracts in token mode.
15+
16+
_Referenced in the SDK with the current path `contracts/IexecInterfaceToken.sol`.
17+
Changing the name or the path would cause a breaking change in the SDK._
18+
319
## FacetBase
420

521
_Every facet must inherit from this contract._
@@ -74,28 +90,26 @@ function verifyPresignatureOrSignature(address _identity, bytes32 _hash, bytes _
7490
### assertDatasetDealCompatibility
7591

7692
```solidity
77-
function assertDatasetDealCompatibility(struct IexecLibOrders_v5.DatasetOrder datasetOrder, bytes32 dealid) external view returns (bool result, string reason)
93+
function assertDatasetDealCompatibility(struct IexecLibOrders_v5.DatasetOrder datasetOrder, bytes32 dealId) external view
7894
```
7995

8096
Public view function to check if a dataset order is compatible with a deal.
8197
This function performs all the necessary checks to verify dataset order compatibility with a deal.
98+
Reverts with `IncompatibleDatasetOrder(reason)` if the dataset order is not compatible with the deal, does
99+
nothing otherwise.
82100

83-
_This function is mainly consumed by offchain clients. It should be carefully inspected if used inside on-chain code.
84-
This function should not be used in matchOrders as it does not check the same requirements._
101+
_This function is mainly consumed by offchain clients. It should be carefully inspected if
102+
used in on-chain code.
103+
This function should not be used in `matchOrders` since it does not check the same requirements.
104+
The choice of reverting instead of returning true/false is motivated by the Java middleware
105+
requirements._
85106

86107
#### Parameters
87108

88109
| Name | Type | Description |
89110
| ---- | ---- | ----------- |
90111
| datasetOrder | struct IexecLibOrders_v5.DatasetOrder | The dataset order to verify |
91-
| dealid | bytes32 | The deal ID to check against |
92-
93-
#### Return Values
94-
95-
| Name | Type | Description |
96-
| ---- | ---- | ----------- |
97-
| result | bool | true if the dataset order is compatible with the deal, false otherwise |
98-
| reason | string | the specific reason why the compatibility check failed, empty string if successful |
112+
| dealId | bytes32 | The deal ID to check against |
99113

100114
### matchOrders
101115

@@ -457,115 +471,6 @@ function groupmember_purpose() external pure returns (uint256)
457471
function eip712domain_separator() external view returns (bytes32)
458472
```
459473

460-
## IexecPocoBoostAccessorsFacet
461-
462-
Access to PoCo Boost tasks must be done with PoCo Classic `IexecAccessors`.
463-
464-
### viewDealBoost
465-
466-
```solidity
467-
function viewDealBoost(bytes32 id) external view returns (struct IexecLibCore_v5.DealBoost deal)
468-
```
469-
470-
Get a deal created by PoCo Boost facet.
471-
472-
#### Parameters
473-
474-
| Name | Type | Description |
475-
| ---- | ---- | ----------- |
476-
| id | bytes32 | The ID of the deal. |
477-
478-
## IexecPocoBoostFacet
479-
480-
Works for deals with requested trust = 0.
481-
482-
### matchOrdersBoost
483-
484-
```solidity
485-
function matchOrdersBoost(struct IexecLibOrders_v5.AppOrder appOrder, struct IexecLibOrders_v5.DatasetOrder datasetOrder, struct IexecLibOrders_v5.WorkerpoolOrder workerpoolOrder, struct IexecLibOrders_v5.RequestOrder requestOrder) external returns (bytes32)
486-
```
487-
488-
This boost match orders is only compatible with trust <= 1.
489-
The requester gets debited.
490-
491-
#### Parameters
492-
493-
| Name | Type | Description |
494-
| ---- | ---- | ----------- |
495-
| appOrder | struct IexecLibOrders_v5.AppOrder | The order signed by the application developer. |
496-
| datasetOrder | struct IexecLibOrders_v5.DatasetOrder | The order signed by the dataset provider. |
497-
| workerpoolOrder | struct IexecLibOrders_v5.WorkerpoolOrder | The order signed by the workerpool manager. |
498-
| requestOrder | struct IexecLibOrders_v5.RequestOrder | The order signed by the requester. |
499-
500-
#### Return Values
501-
502-
| Name | Type | Description |
503-
| ---- | ---- | ----------- |
504-
| [0] | bytes32 | The ID of the deal. |
505-
506-
### sponsorMatchOrdersBoost
507-
508-
```solidity
509-
function sponsorMatchOrdersBoost(struct IexecLibOrders_v5.AppOrder appOrder, struct IexecLibOrders_v5.DatasetOrder datasetOrder, struct IexecLibOrders_v5.WorkerpoolOrder workerpoolOrder, struct IexecLibOrders_v5.RequestOrder requestOrder) external returns (bytes32)
510-
```
511-
512-
Sponsor match orders boost for a requester.
513-
Unlike the standard `matchOrdersBoost(..)` hook where the requester pays for
514-
the deal, this current hook makes it possible for any `msg.sender` to pay for
515-
a third party requester.
516-
517-
Be aware that anyone seeing a valid request order on the network
518-
(via an off-chain public marketplace, via a `sponsorMatchOrdersBoost(..)`
519-
pending transaction in the mempool or by any other means) might decide
520-
to call the standard `matchOrdersBoost(..)` hook which will result in the
521-
requester being debited instead. Therefore, such a front run would result
522-
in a loss of some of the requester funds deposited in the iExec account
523-
(a loss value equivalent to the price of the deal).
524-
525-
#### Parameters
526-
527-
| Name | Type | Description |
528-
| ---- | ---- | ----------- |
529-
| appOrder | struct IexecLibOrders_v5.AppOrder | The app order. |
530-
| datasetOrder | struct IexecLibOrders_v5.DatasetOrder | The dataset order. |
531-
| workerpoolOrder | struct IexecLibOrders_v5.WorkerpoolOrder | The workerpool order. |
532-
| requestOrder | struct IexecLibOrders_v5.RequestOrder | The requester order. |
533-
534-
### pushResultBoost
535-
536-
```solidity
537-
function pushResultBoost(bytes32 dealId, uint256 index, bytes results, bytes resultsCallback, bytes authorizationSign, address enclaveChallenge, bytes enclaveSign) external
538-
```
539-
540-
Accept results of a task computed by a worker during Boost workflow.
541-
542-
#### Parameters
543-
544-
| Name | Type | Description |
545-
| ---- | ---- | ----------- |
546-
| dealId | bytes32 | The id of the target deal. |
547-
| index | uint256 | The index of the target task of the deal. |
548-
| results | bytes | The results of the task computed by the worker. |
549-
| resultsCallback | bytes | The results of the task computed by the worker that will be forwarded as call data to the callback address set by the requester. |
550-
| authorizationSign | bytes | The authorization signed by the scheduler. authorizing the worker to push a result. |
551-
| enclaveChallenge | address | The enclave address which can produce enclave signature. |
552-
| enclaveSign | bytes | The signature generated from the enclave. |
553-
554-
### claimBoost
555-
556-
```solidity
557-
function claimBoost(bytes32 dealId, uint256 index) external
558-
```
559-
560-
Claim task to get a refund if task is not completed after deadline.
561-
562-
#### Parameters
563-
564-
| Name | Type | Description |
565-
| ---- | ---- | ----------- |
566-
| dealId | bytes32 | The ID of the deal. |
567-
| index | uint256 | The index of the task. |
568-
569474
## IexecLibCore_v5
570475

571476
### Account
@@ -1129,34 +1034,6 @@ function m_schedulerRewardRatioPolicy() external view returns (uint256)
11291034
function m_workerStakeRatioPolicy() external view returns (uint256)
11301035
```
11311036

1132-
## IexecInterfaceNative
1133-
1134-
A global interface that aggregates all the interfaces needed to interact with
1135-
the PoCo contracts in native mode.
1136-
1137-
_Referenced in the SDK with the current path `contracts/IexecInterfaceNative.sol`.
1138-
Changing the name or the path would cause a breaking change in the SDK._
1139-
1140-
## IexecInterfaceToken
1141-
1142-
A global interface that aggregates all the interfaces needed to interact with
1143-
the PoCo contracts in token mode.
1144-
1145-
_Referenced in the SDK with the current path `contracts/IexecInterfaceToken.sol`.
1146-
Changing the name or the path would cause a breaking change in the SDK._
1147-
1148-
### receive
1149-
1150-
```solidity
1151-
receive() external payable
1152-
```
1153-
1154-
### fallback
1155-
1156-
```solidity
1157-
fallback() external payable
1158-
```
1159-
11601037
## IexecCategoryManagerFacet
11611038

11621039
### createCategory
@@ -1761,3 +1638,112 @@ function manageWorkerpoolOrder(struct IexecLibOrders_v5.WorkerpoolOrderOperation
17611638
function manageRequestOrder(struct IexecLibOrders_v5.RequestOrderOperation _requestorderoperation) external
17621639
```
17631640

1641+
## IexecPocoBoostAccessorsFacet
1642+
1643+
Access to PoCo Boost tasks must be done with PoCo Classic `IexecPocoAccessors`.
1644+
1645+
### viewDealBoost
1646+
1647+
```solidity
1648+
function viewDealBoost(bytes32 id) external view returns (struct IexecLibCore_v5.DealBoost deal)
1649+
```
1650+
1651+
Get a deal created by PoCo Boost facet.
1652+
1653+
#### Parameters
1654+
1655+
| Name | Type | Description |
1656+
| ---- | ---- | ----------- |
1657+
| id | bytes32 | The ID of the deal. |
1658+
1659+
## IexecPocoBoostFacet
1660+
1661+
Works for deals with requested trust = 0.
1662+
1663+
### matchOrdersBoost
1664+
1665+
```solidity
1666+
function matchOrdersBoost(struct IexecLibOrders_v5.AppOrder appOrder, struct IexecLibOrders_v5.DatasetOrder datasetOrder, struct IexecLibOrders_v5.WorkerpoolOrder workerpoolOrder, struct IexecLibOrders_v5.RequestOrder requestOrder) external returns (bytes32)
1667+
```
1668+
1669+
This boost match orders is only compatible with trust <= 1.
1670+
The requester gets debited.
1671+
1672+
#### Parameters
1673+
1674+
| Name | Type | Description |
1675+
| ---- | ---- | ----------- |
1676+
| appOrder | struct IexecLibOrders_v5.AppOrder | The order signed by the application developer. |
1677+
| datasetOrder | struct IexecLibOrders_v5.DatasetOrder | The order signed by the dataset provider. |
1678+
| workerpoolOrder | struct IexecLibOrders_v5.WorkerpoolOrder | The order signed by the workerpool manager. |
1679+
| requestOrder | struct IexecLibOrders_v5.RequestOrder | The order signed by the requester. |
1680+
1681+
#### Return Values
1682+
1683+
| Name | Type | Description |
1684+
| ---- | ---- | ----------- |
1685+
| [0] | bytes32 | The ID of the deal. |
1686+
1687+
### sponsorMatchOrdersBoost
1688+
1689+
```solidity
1690+
function sponsorMatchOrdersBoost(struct IexecLibOrders_v5.AppOrder appOrder, struct IexecLibOrders_v5.DatasetOrder datasetOrder, struct IexecLibOrders_v5.WorkerpoolOrder workerpoolOrder, struct IexecLibOrders_v5.RequestOrder requestOrder) external returns (bytes32)
1691+
```
1692+
1693+
Sponsor match orders boost for a requester.
1694+
Unlike the standard `matchOrdersBoost(..)` hook where the requester pays for
1695+
the deal, this current hook makes it possible for any `msg.sender` to pay for
1696+
a third party requester.
1697+
1698+
Be aware that anyone seeing a valid request order on the network
1699+
(via an off-chain public marketplace, via a `sponsorMatchOrdersBoost(..)`
1700+
pending transaction in the mempool or by any other means) might decide
1701+
to call the standard `matchOrdersBoost(..)` hook which will result in the
1702+
requester being debited instead. Therefore, such a front run would result
1703+
in a loss of some of the requester funds deposited in the iExec account
1704+
(a loss value equivalent to the price of the deal).
1705+
1706+
#### Parameters
1707+
1708+
| Name | Type | Description |
1709+
| ---- | ---- | ----------- |
1710+
| appOrder | struct IexecLibOrders_v5.AppOrder | The app order. |
1711+
| datasetOrder | struct IexecLibOrders_v5.DatasetOrder | The dataset order. |
1712+
| workerpoolOrder | struct IexecLibOrders_v5.WorkerpoolOrder | The workerpool order. |
1713+
| requestOrder | struct IexecLibOrders_v5.RequestOrder | The requester order. |
1714+
1715+
### pushResultBoost
1716+
1717+
```solidity
1718+
function pushResultBoost(bytes32 dealId, uint256 index, bytes results, bytes resultsCallback, bytes authorizationSign, address enclaveChallenge, bytes enclaveSign) external
1719+
```
1720+
1721+
Accept results of a task computed by a worker during Boost workflow.
1722+
1723+
#### Parameters
1724+
1725+
| Name | Type | Description |
1726+
| ---- | ---- | ----------- |
1727+
| dealId | bytes32 | The id of the target deal. |
1728+
| index | uint256 | The index of the target task of the deal. |
1729+
| results | bytes | The results of the task computed by the worker. |
1730+
| resultsCallback | bytes | The results of the task computed by the worker that will be forwarded as call data to the callback address set by the requester. |
1731+
| authorizationSign | bytes | The authorization signed by the scheduler. authorizing the worker to push a result. |
1732+
| enclaveChallenge | address | The enclave address which can produce enclave signature. |
1733+
| enclaveSign | bytes | The signature generated from the enclave. |
1734+
1735+
### claimBoost
1736+
1737+
```solidity
1738+
function claimBoost(bytes32 dealId, uint256 index) external
1739+
```
1740+
1741+
Claim task to get a refund if task is not completed after deadline.
1742+
1743+
#### Parameters
1744+
1745+
| Name | Type | Description |
1746+
| ---- | ---- | ----------- |
1747+
| dealId | bytes32 | The ID of the deal. |
1748+
| index | uint256 | The index of the task. |
1749+

0 commit comments

Comments
 (0)