Skip to content
This repository was archived by the owner on Dec 21, 2021. It is now read-only.

Commit 78449c1

Browse files
teogebteogeb
authored
NET-205: Simplify DataUnion interface (#202)
DataUnion is now an object which we can operate on. To get an instance of DU object, call client.getDataUnion(contractAddress). As the object encapsulates the contract address, we don't need to specify it when we access the DU methods. Some methods that need a member address were previously optional, and the default value for those were the currently authenticated user. Now we need to be more explicit about the parameter and the member address is always required. Also previously there was a dataUnion client option which was a default value for some DU actions. That is no longer supported. There is a new config option factorySidechainAddress. Users don't need to specify this as it has default value in test and will have a default value in production once we know the address. Member join functions: - renamed joinDataUnion() -> join(secret?), if secret is given this will wait until the automatic join request has been processed - added isMember(memberAddress), returns true if the member is an active member - hasJoined() removed Withdraw functions renamed to have word "all" if the amount is not specified: - withdrawAll(options?) - withdrawAllTo(recipient, options?) - signWithdrawAllTo(recipientAddress) - signWithdrawAmountTo(recipientAddress, amountTokenWei) - admin: withdrawFor() -> withdrawAllToMember(memberAddress, options?) - admin: withdrawAllToSigned(memberAddress, recipientAddress, signature, options?) - removed methods that returned the raw withdraw transactions removed: getWithdrawTx(), getWithdrawTxTo(), getWithdrawTxFor() Public query functions: - renamed getDataUnionStats() -> getStats() - getMemberStats(memberAddress) - removed getMembers as it is not supported in DU v2 - renamed getBalance() -> getWithdrawableEarnings(memberAddress) - getAdminFee() - getAdminAddress() - getVersion() Admin functions: - client.deployDataUnion(options), waits until the deployment is ready, supports new options: confirmations and gasPrice - createSecret(name?) - addMembers(memberAddressList, options?) - renamed kick() -> removeMembers(memberAddressList, options?) - setAdminFee(newFeeFraction) Other functions: - not related to DU: client.getTokenBalance() Public accessors for DataUnion objects: - getAddress(), returns string - getSidechainAddress(), returns string Internal functions: - client._getDataUnionFromName({ dataUnionName, deployerAddress }), returns DataUnion - dataUnion._getContract(), returns Promise Future refactoring, should be done after this PR is in 5.x: - Move many DataUnionEndpoints.ts functions to DataUnion class (and inline DataUnion methods that just call an endpoint methods) - Move getTokenBalance to a separate class as it is not DU-related - Remove caching from fetchDataUnionMainnetAddress
1 parent b94bdcd commit 78449c1

19 files changed

+1619
-1717
lines changed

‎.eslintrc.js‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -42,7 +42,9 @@ module.exports = {
4242
'no-shadow': 'off',
4343
'@typescript-eslint/no-shadow': 'error',
4444
'no-unused-vars': 'off',
45-
'@typescript-eslint/no-unused-vars': ['error']
45+
'@typescript-eslint/no-unused-vars': ['error'],
46+
'no-else-return': 'off',
47+
'no-return-await': 'off'
4648
},
4749
settings: {
4850
'import/resolver': {

‎README.md‎

Lines changed: 27 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -324,37 +324,28 @@ All the below functions return a Promise which gets resolved with the result.
324324

325325
## Data Unions
326326

327-
This library provides functions for working with Data Unions.
327+
This library provides functions for working with Data Unions. To get a DataUnion instance, call `client.getDataUnion(address)`. To deploy a new DataUnion, call `deployDataUnion(options)`
328328

329-
TODO: check all this documentation before merging/publishing, probably some of it is out of date (DU1 era)
330-
331-
Data union functions take a third parameter, `options`, which are either overrides to options given in the constructor, or optional arguments to the function.
329+
TODO: All `options`-parameters should be documented (see TypeScript interfaces for the definitions)
332330

331+
These DataUnion-specific options are used from `StreamrClient` options:
333332
| Property | Default | Description |
334333
| :----------------------- | :----------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------- |
335-
| wallet | given in auth | ethers.js Wallet object to use to sign and send withdraw transaction |
336-
| provider | mainnet | ethers.js Provider to use if wallet wasn't provided |
337-
| confirmations | `1` | Number of blocks to wait after the withdraw transaction is mined |
338-
| gasPrice | ethers.js supplied | Probably uses the network estimate |
339-
| dataUnion | - | Address or contract object of the data union that is the target of the operation |
340334
| tokenAddress | 0x0Cf0Ee637<br>88A0849fE52<br>97F3407f701<br>E122cC023 | Token used by the DU |
341-
| minimumWithdrawTokenWei | 1000000 | Threshold value set in AMB configs, smallest token amount that can pass over the bridge |
342-
| sidechainTokenAddress | TODO | sidechain token address |
343335
| factoryMainnetAddress | TODO | Data Union factory that creates a new Data Union |
344-
| sidechainAmbAddress | TODO | Arbitrary Message-passing Bridge (AMB), see [Tokenbridge github page](https://github.com/poanetwork/tokenbridge) |
345-
| payForSignatureTransport | `true` | Someone must pay for transporting the withdraw tx to mainnet, either us or bridge operator |
336+
| minimumWithdrawTokenWei | 1000000 | Threshold value set in AMB configs, smallest token amount that can pass over the bridge |
337+
346338

347339
### Admin Functions
348340

349-
| Name | Returns | Description |
350-
| :-------------------------------------------------------------------- | :------------------ | :------------------------------------------------------------- |
351-
| deployDataUnion(options) | Dataunion contract | Deploy a new Data Union |
352-
| createSecret(dataUnionContractAddress, secret\[, name]) | | Create a secret for a Data Union |
353-
| addMembers(memberAddressList, options) | Transaction receipt | Add members |
354-
| kick(memberAddressList, options) | Transaction receipt | Kick members out from Data Union |
355-
| withdrawMember(memberAddress, options) | | |
356-
| withdrawToSigned(memberAddress, recipientAddress, signature, options) | | |
357-
| setAdminFee(newFeeFraction, options) | Transaction receipt | `newFeeFraction` is a `Number` between 0.0 and 1.0 (inclusive) |
341+
| Name | Returns | Description |
342+
| :-------------------------------------------------------------------------- | :------------------ | :------------------------------------------------------------- |
343+
| createSecret(\[name]) | string | Create a secret for a Data Union |
344+
| addMembers(memberAddressList, \[options]) | Transaction receipt | Add members |
345+
| removeMembers(memberAddressList, \[options]) | Transaction receipt | Remove members from Data Union |
346+
| withdrawAllToMember(memberAddress, \[options]) | | |
347+
| withdrawAllToSigned(memberAddress, recipientAddress, signature, \[options]) | | |
348+
| setAdminFee(newFeeFraction) | Transaction receipt | `newFeeFraction` is a `Number` between 0.0 and 1.0 (inclusive) |
358349

359350
Here's an example how to deploy a data union contract and set the admin fee:
360351

@@ -371,12 +362,12 @@ await client.setAdminFee(0.3, { dataUnion })
371362

372363
| Name | Returns | Description |
373364
| :-------------------------------------------------------------- | :------------------ | :-------------------------------------------------------------------------- |
374-
| joinDataUnion(options) | JoinRequest | Join a Data Union |
375-
| hasJoined(\[memberAddress], options) | - | Wait until member has been accepted |
376-
| withdraw(options) | Transaction receipt | Withdraw funds from Data Union |
377-
| withdrawTo(recipientAddress, dataUnionContractAddress, options) | Transaction receipt | Donate/move your earnings to recipientAddress instead of your memberAddress |
378-
| signWithdrawTo(recipientAddress, options) | Signature (string) | Signature that can be used to withdraw tokens to given recipientAddress |
379-
| signWithdrawAmountTo(recipientAddress, amountTokenWei, options) | Signature (string) | Signature that can be used to withdraw tokens to given recipientAddress |
365+
| join(\[secret]) | JoinRequest | Join the Data Union (if a valid secret is given, the promise waits until the automatic join request has been processed) |
366+
| isMember(memberAddress) | boolean | |
367+
| withdrawAll(\[options]) | Transaction receipt | Withdraw funds from Data Union |
368+
| withdrawAllTo(recipientAddress, \[options]) | Transaction receipt | Donate/move your earnings to recipientAddress instead of your memberAddress |
369+
| signWithdrawAllTo(recipientAddress) | Signature (string) | Signature that can be used to withdraw tokens to given recipientAddress |
370+
| signWithdrawAmountTo(recipientAddress, amountTokenWei) | Signature (string) | Signature that can be used to withdraw tokens to given recipientAddress |
380371

381372
Here's an example how to sign off on a withdraw to (any) recipientAddress:
382373

@@ -386,7 +377,7 @@ const client = new StreamrClient({
386377
dataUnion,
387378
})
388379

389-
const signature = await client.signWithdrawTo(recipientAddress)
380+
const signature = await client.signWithdrawAllTo(recipientAddress)
390381
```
391382

392383
### Query functions
@@ -395,16 +386,12 @@ These are available for everyone and anyone, to query publicly available info fr
395386

396387
| Name | Returns | Description |
397388
| :--------------------------------------------------------- | :--------------------------------------------- | :-------------------------------------- |
398-
| getMemberStats(dataUnionContractAddress\[, memberAddress]) | {earnings, proof, ...} | Get member's stats |
399-
| getDataUnionStats(dataUnionContractAddress) | {activeMemberCount, totalEarnings, ...} | Get Data Union's statistics |
400-
| ~~getMembers(dataUnionContractAddress)~~ | | NOT available in DU2 at the moment |
401-
| getAdminFee(options) | `Number` between 0.0 and 1.0 (inclusive) | Admin's cut from revenues |
402-
| getAdminAddress(options) | Ethereum address | Data union admin's address |
403-
| getDataUnionStats(options) | Stats object | Various metrics from the smart contract |
404-
| getMemberStats(\[memberAddress], options) | Member stats object | Various metrics from the smart contract |
405-
| getMemberBalance(\[memberAddress], options) | `BigNumber` withdrawable DATA tokens in the DU | |
406-
| getTokenBalance(address, options) | `BigNumber` | Mainnet DATA token balance |
407-
| getDataUnionVersion(contractAddress) | `0`, `1` or `2` | `0` if the contract is not a data union |
389+
| getStats() | {activeMemberCount, totalEarnings, ...} | Get Data Union's statistics |
390+
| getMemberStats(memberAddress) | {earnings, proof, ...} | Get member's stats |
391+
| getWithdrawableEarnings(memberAddress) | `BigNumber` withdrawable DATA tokens in the DU | |
392+
| getAdminFee() | `Number` between 0.0 and 1.0 (inclusive) | Admin's cut from revenues |
393+
| getAdminAddress() | Ethereum address | Data union admin's address |
394+
| getVersion() | `0`, `1` or `2` | `0` if the contract is not a data union |
408395

409396
Here's an example how to get a member's withdrawable token balance (in "wei", where 1 DATA = 10^18 wei)
410397

@@ -421,6 +408,7 @@ const withdrawableWei = await client.getMemberBalance(memberAddress)
421408
| Name | Description |
422409
| :-------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
423410
| StreamrClient.generateEthereumAccount() | Generates a random Ethereum private key and returns an object with fields `address` and privateKey. Note that this private key can be used to authenticate to the Streamr API by passing it in the authentication options, as described earlier in this document. |
411+
| getTokenBalance(address) | `BigNumber` | Mainnet DATA token balance |
424412

425413
## Events
426414

0 commit comments

Comments
 (0)