From 7aab4d10defc06bf96bb0510bee1bb929b1d2245 Mon Sep 17 00:00:00 2001 From: Brandon Millman Date: Fri, 12 Oct 2018 15:07:04 -0700 Subject: [PATCH 1/7] feat(asset-buyer): add hooks for documentation --- package.json | 2 +- packages/asset-buyer/CHANGELOG.json | 8 ++++++++ packages/asset-buyer/package.json | 3 ++- 3 files changed, 11 insertions(+), 2 deletions(-) diff --git a/package.json b/package.json index 031f73ba82..9d5337164b 100644 --- a/package.json +++ b/package.json @@ -40,7 +40,7 @@ }, "config": { "mnemonic": "concert load couple harbor equip island argue ramp clarify fence smart topic", - "packagesWithDocPages": "0x.js connect json-schemas subproviders web3-wrapper contract-wrappers order-utils order-watcher sol-compiler sol-cov ethereum-types" + "packagesWithDocPages": "0x.js connect json-schemas subproviders web3-wrapper contract-wrappers order-utils order-watcher sol-compiler sol-cov ethereum-types asset-buyer" }, "bundlewatch" : { "files": [ diff --git a/packages/asset-buyer/CHANGELOG.json b/packages/asset-buyer/CHANGELOG.json index b50fe2c63f..0d50b7bc33 100644 --- a/packages/asset-buyer/CHANGELOG.json +++ b/packages/asset-buyer/CHANGELOG.json @@ -9,6 +9,14 @@ "note": "Updated to use new modularized artifacts and the latest version of @0xproject/contract-wrappers", "pr": 1105 + }, + { + "note": "Add `gasLimit` and `gasPrice` as optional properties on `BuyQuoteExecutionOpts`", + "pr": 1116 + }, + { + "note": "Add `docs:json` command to package.json", + "pr": 1139 } ] }, diff --git a/packages/asset-buyer/package.json b/packages/asset-buyer/package.json index 8c8f3c92c8..13de96e6b2 100644 --- a/packages/asset-buyer/package.json +++ b/packages/asset-buyer/package.json @@ -17,7 +17,8 @@ "coverage:report:lcov": "nyc report --reporter=text-lcov > coverage/lcov.info", "test:circleci": "yarn test:coverage", "run_mocha": "mocha --require source-map-support/register --require make-promises-safe lib/test/**/*_test.js --exit", - "clean": "shx rm -rf lib test_temp" + "clean": "shx rm -rf lib test_temp", + "docs:json": "typedoc --excludePrivate --excludeExternals --target ES5 --tsconfig typedoc-tsconfig.json --json $JSON_FILE_PATH $PROJECT_FILES" }, "config": { "postpublish": { From 4976b3473893befeb538c57ca6f8010722addd07 Mon Sep 17 00:00:00 2001 From: Brandon Millman Date: Mon, 15 Oct 2018 10:27:57 -0700 Subject: [PATCH 2/7] feat(asset-buyer): add missing types to public interface --- packages/asset-buyer/CHANGELOG.json | 4 ++++ packages/asset-buyer/src/index.ts | 9 ++++++++- 2 files changed, 12 insertions(+), 1 deletion(-) diff --git a/packages/asset-buyer/CHANGELOG.json b/packages/asset-buyer/CHANGELOG.json index 0d50b7bc33..52a8d0d0df 100644 --- a/packages/asset-buyer/CHANGELOG.json +++ b/packages/asset-buyer/CHANGELOG.json @@ -17,6 +17,10 @@ { "note": "Add `docs:json` command to package.json", "pr": 1139 + }, + { + "note": "Add missing types to public interface", + "pr": 1139 } ] }, diff --git a/packages/asset-buyer/src/index.ts b/packages/asset-buyer/src/index.ts index 2da2724d74..9ac3c0b8ae 100644 --- a/packages/asset-buyer/src/index.ts +++ b/packages/asset-buyer/src/index.ts @@ -1,4 +1,10 @@ -export { Provider } from 'ethereum-types'; +export { + JSONRPCRequestPayload, + JSONRPCResponsePayload, + JSONRPCResponseError, + JSONRPCErrorCallback, + Provider, +} from 'ethereum-types'; export { SignedOrder } from '@0xproject/types'; export { BigNumber } from '@0xproject/utils'; @@ -10,6 +16,7 @@ export { AssetBuyerOpts, BuyQuote, BuyQuoteExecutionOpts, + BuyQuoteInfo, BuyQuoteRequestOpts, OrderProvider, OrderProviderRequest, From 2c286ad897d7ae9f2dcc48919033fb0d1c026641 Mon Sep 17 00:00:00 2001 From: Brandon Millman Date: Mon, 15 Oct 2018 10:51:38 -0700 Subject: [PATCH 3/7] feat(monorepo-scripts): add AssetBuyerError to IGNORED_EXCESSIVE_TYPES --- packages/monorepo-scripts/CHANGELOG.json | 8 ++++++++ packages/monorepo-scripts/src/doc_gen_configs.ts | 8 +++++++- .../src/utils/doc_generate_and_upload_utils.ts | 2 +- 3 files changed, 16 insertions(+), 2 deletions(-) diff --git a/packages/monorepo-scripts/CHANGELOG.json b/packages/monorepo-scripts/CHANGELOG.json index 3b8684fab0..4fd87c1d83 100644 --- a/packages/monorepo-scripts/CHANGELOG.json +++ b/packages/monorepo-scripts/CHANGELOG.json @@ -1,4 +1,12 @@ [ + { + "version": "1.0.6", + "changes": [ + { + "note": "Add AssetBuyerError to the IGNORED_EXCESSIVE_TYPES array" + } + ] + }, { "timestamp": 1534210131, "version": "1.0.5", diff --git a/packages/monorepo-scripts/src/doc_gen_configs.ts b/packages/monorepo-scripts/src/doc_gen_configs.ts index e3ddeddc9e..3d5c97dc48 100644 --- a/packages/monorepo-scripts/src/doc_gen_configs.ts +++ b/packages/monorepo-scripts/src/doc_gen_configs.ts @@ -43,7 +43,13 @@ export const docGenConfigs: DocGenConfigs = { // Some types are not explicitly part of the public interface like params, return values, etc... But we still // want them exported. E.g error enum types that can be thrown by methods. These must be manually added to this // config - IGNORED_EXCESSIVE_TYPES: ['NonceSubproviderErrors', 'Web3WrapperErrors', 'ContractWrappersError', 'OrderError'], + IGNORED_EXCESSIVE_TYPES: [ + 'NonceSubproviderErrors', + 'Web3WrapperErrors', + 'ContractWrappersError', + 'OrderError', + 'AssetBuyerError', + ], // Some libraries only export types. In those cases, we cannot check if the exported types are part of the // "exported public interface". Thus we add them here and skip those checks. TYPES_ONLY_LIBRARIES: ['ethereum-types', 'types'], diff --git a/packages/monorepo-scripts/src/utils/doc_generate_and_upload_utils.ts b/packages/monorepo-scripts/src/utils/doc_generate_and_upload_utils.ts index 4fea94414d..547b65eeb7 100644 --- a/packages/monorepo-scripts/src/utils/doc_generate_and_upload_utils.ts +++ b/packages/monorepo-scripts/src/utils/doc_generate_and_upload_utils.ts @@ -331,7 +331,7 @@ export class DocGenerateAndUploadUtils { throw new Error( `${this._packageName} package exports BUT does not need: \n${excessiveReferencesExceptIgnored.join( '\n', - )} \nin it\'s index.ts. Remove them then try again.`, + )} \nin it\'s index.ts. Remove them then try again OR if we still want them exported (e.g error enum types), then add them to the IGNORED_EXCESSIVE_TYPES array.`, ); } } From 55be070dcfd7b9704ba24bc387bca0001f0c47f5 Mon Sep 17 00:00:00 2001 From: Brandon Millman Date: Mon, 15 Oct 2018 22:28:29 -0700 Subject: [PATCH 4/7] feat(monorepo-scripts): add AssetBuyer to CLASSES_WITH_HIDDEN_CONSTRUCTORS --- packages/monorepo-scripts/src/doc_gen_configs.ts | 1 + 1 file changed, 1 insertion(+) diff --git a/packages/monorepo-scripts/src/doc_gen_configs.ts b/packages/monorepo-scripts/src/doc_gen_configs.ts index 3d5c97dc48..b5a36376aa 100644 --- a/packages/monorepo-scripts/src/doc_gen_configs.ts +++ b/packages/monorepo-scripts/src/doc_gen_configs.ts @@ -30,6 +30,7 @@ export const docGenConfigs: DocGenConfigs = { // factory method which instantiates an instance of a class, but we don't want users instantiating it themselves // and getting confused. Any class name in this list will not have it's constructor rendered in our docs. CLASSES_WITH_HIDDEN_CONSTRUCTORS: [ + 'AssetBuyer', 'ERC20ProxyWrapper', 'ERC20TokenWrapper', 'ERC721ProxyWrapper', From aa1085c8f3866da4965c0102be27c0f5e19b3db6 Mon Sep 17 00:00:00 2001 From: Brandon Millman Date: Mon, 15 Oct 2018 23:27:56 -0700 Subject: [PATCH 5/7] feat(website): add asset-buyer documentation --- .../md/docs/asset_buyer/installation.md | 17 +++++ .../md/docs/asset_buyer/introduction.md | 1 + packages/website/md/docs/asset_buyer/usage.md | 39 +++++++++++ packages/website/translations/english.json | 1 + .../website/ts/components/top_bar/top_bar.tsx | 7 ++ .../containers/asset_buyer_documentation.ts | 69 +++++++++++++++++++ packages/website/ts/index.tsx | 8 ++- .../ts/pages/documentation/doc_page.tsx | 1 + packages/website/ts/types.ts | 3 + 9 files changed, 145 insertions(+), 1 deletion(-) create mode 100644 packages/website/md/docs/asset_buyer/installation.md create mode 100644 packages/website/md/docs/asset_buyer/introduction.md create mode 100644 packages/website/md/docs/asset_buyer/usage.md create mode 100644 packages/website/ts/containers/asset_buyer_documentation.ts diff --git a/packages/website/md/docs/asset_buyer/installation.md b/packages/website/md/docs/asset_buyer/installation.md new file mode 100644 index 0000000000..483ee2b652 --- /dev/null +++ b/packages/website/md/docs/asset_buyer/installation.md @@ -0,0 +1,17 @@ +**Install** + +```bash +yarn add @0xproject/asset-buyer +``` + +**Import** + +```javascript +import { AssetBuyer } from '@0xproject/asset-buyer'; +``` + +or + +```javascript +var AssetBuyer = require('@0xproject/asset-buyer').AssetBuyer; +``` diff --git a/packages/website/md/docs/asset_buyer/introduction.md b/packages/website/md/docs/asset_buyer/introduction.md new file mode 100644 index 0000000000..a40d20cc9f --- /dev/null +++ b/packages/website/md/docs/asset_buyer/introduction.md @@ -0,0 +1 @@ +Welcome to the [@0xproject/asset-buyer](https://github.com/0xProject/0x-monorepo/tree/development/packages/asset-buyer) documentation! AssetBuyer is a library that provides an easy way to buy any asset with ETH in one click, leveraging 0x liquidity and the [Forwarder contract](https://0xproject.com/docs/contracts#Forwarder). diff --git a/packages/website/md/docs/asset_buyer/usage.md b/packages/website/md/docs/asset_buyer/usage.md new file mode 100644 index 0000000000..93c681f409 --- /dev/null +++ b/packages/website/md/docs/asset_buyer/usage.md @@ -0,0 +1,39 @@ +**Construction** + +Connecting to a standard relayer API compliant url: + +```typescript +const provider = web3.currentProvider; +const apiUrl = 'https://api.relayer.com/v2'; +const assetBuyer = AssetBuyer.getAssetBuyerForStandardRelayerAPIUrl(provider, apiUrl); +``` + +Providing your own orders: + +```typescript +const provider = web3.currentProvider; +const orders = []; // get these from your own API, a relayer, a friend, from anywhere +const assetBuyer = AssetBuyer.getAssetBuyerForProvidedOrders(provider, orders); +``` + +**Get a quote** + +A [BuyQuote](#types-BuyQuote) object contains enough information to display buy information to an end user + +```typescript +const erc20TokenAddress = '0x5fa3c....'; +const amountToBuy = new BigNumber(50000000000000000000); +const buyQuote = await assetBuyer.getBuyQuoteForERC20TokenAddressAsync(erc20TokenAddress, amountToBuy); +const quoteInfo = buyQuote.worstCaseQuoteInfo; +console.log(quoteInfo.ethAmount); // the total amount the user needs to pay to buy the desired amount (including fees) +console.log(quoteInfo.feeAmount); // a portion of the total ethAmount above that was used to buy fees +console.log(quoteInfo.ethPerAssetPrice); // the rate that this quote provides (e.g. 0.0035ETH / REP) +``` + +**Perform a buy** + +Pass the [BuyQuote](#types-BuyQuote) object from above back to the assetBuyer in order to initiate the buy transaction + +```typescript +const txHash = await assetBuyer.executeBuyQuoteAsync(buyQuote); // the hash of the transaction submitted to the Ethereum network +``` diff --git a/packages/website/translations/english.json b/packages/website/translations/english.json index 9ce458111f..ac8e4900ac 100644 --- a/packages/website/translations/english.json +++ b/packages/website/translations/english.json @@ -73,6 +73,7 @@ "WIKI": "wiki", "WEB3_WRAPPER": "Web3Wrapper", "ORDER_UTILS": "Order Utils", + "ASSET_BUYER": "AssetBuyer", "FAQ": "FAQ", "SMART_CONTRACTS": "0x smart contracts", "STANDARD_RELAYER_API": "standard relayer API", diff --git a/packages/website/ts/components/top_bar/top_bar.tsx b/packages/website/ts/components/top_bar/top_bar.tsx index 7cf3c6ecb6..fe2c1fcf91 100644 --- a/packages/website/ts/components/top_bar/top_bar.tsx +++ b/packages/website/ts/components/top_bar/top_bar.tsx @@ -92,6 +92,7 @@ const DOC_WEBSITE_PATHS_TO_KEY = { [WebsitePaths.ZeroExJs]: Key.ZeroExJs, [WebsitePaths.OrderUtils]: Key.OrderUtils, [WebsitePaths.OrderWatcher]: Key.OrderWatcher, + [WebsitePaths.AssetBuyer]: Key.AssetBuyer, }; const DEFAULT_HEIGHT = 68; @@ -214,6 +215,12 @@ export class TopBar extends React.Component { primaryText={this.props.translate.get(Key.EthereumTypes, Deco.CapWords)} /> , + + + , ({ + docsVersion: state.docsVersion, + availableDocVersions: state.availableDocVersions, + translate: state.translate, + docsInfo, +}); + +const mapDispatchToProps = (dispatch: Dispatch): ConnectedDispatch => ({ + dispatcher: new Dispatcher(dispatch), +}); + +export const Documentation: React.ComponentClass = connect(mapStateToProps, mapDispatchToProps)( + DocPageComponent, +); diff --git a/packages/website/ts/index.tsx b/packages/website/ts/index.tsx index d4a79cc4f3..bb218eac17 100644 --- a/packages/website/ts/index.tsx +++ b/packages/website/ts/index.tsx @@ -68,6 +68,9 @@ const LazyOrderUtilsDocumentation = createLazyComponent('Documentation', async ( const LazyEthereumTypesDocumentation = createLazyComponent('Documentation', async () => import(/* webpackChunkName: "ethereumTypesDocs" */ 'ts/containers/ethereum_types_documentation'), ); +const LazyAssetBuyerDocumentation = createLazyComponent('Documentation', async () => + import(/* webpackChunkName: "assetBuyerDocs" */ 'ts/containers/asset_buyer_documentation'), +); const DOCUMENT_TITLE = '0x: The Protocol for Trading Tokens'; const DOCUMENT_DESCRIPTION = 'An Open Protocol For Decentralized Exchange On The Ethereum Blockchain'; @@ -133,7 +136,10 @@ render( path={`${WebsitePaths.EthereumTypes}/:version?`} component={LazyEthereumTypesDocumentation} /> - + {/* Legacy endpoints */} Date: Wed, 17 Oct 2018 10:33:05 -0700 Subject: [PATCH 6/7] Update asset-buyer usage wording --- packages/website/md/docs/asset_buyer/usage.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/packages/website/md/docs/asset_buyer/usage.md b/packages/website/md/docs/asset_buyer/usage.md index 93c681f409..6462d938e4 100644 --- a/packages/website/md/docs/asset_buyer/usage.md +++ b/packages/website/md/docs/asset_buyer/usage.md @@ -25,8 +25,8 @@ const erc20TokenAddress = '0x5fa3c....'; const amountToBuy = new BigNumber(50000000000000000000); const buyQuote = await assetBuyer.getBuyQuoteForERC20TokenAddressAsync(erc20TokenAddress, amountToBuy); const quoteInfo = buyQuote.worstCaseQuoteInfo; -console.log(quoteInfo.ethAmount); // the total amount the user needs to pay to buy the desired amount (including fees) -console.log(quoteInfo.feeAmount); // a portion of the total ethAmount above that was used to buy fees +console.log(quoteInfo.ethAmount); // the total amount the user needs to pay to buy the desired amount (including ZRX fees) +console.log(quoteInfo.feeAmount); // a portion of the total ethAmount above that was used to buy affiliate fees console.log(quoteInfo.ethPerAssetPrice); // the rate that this quote provides (e.g. 0.0035ETH / REP) ``` From 81505ba56cc8a5b0a2991b07e8320a442ee74f27 Mon Sep 17 00:00:00 2001 From: Brandon Millman Date: Wed, 17 Oct 2018 10:44:25 -0700 Subject: [PATCH 7/7] Fix duplicate BuyQuoteInfo --- packages/asset-buyer/src/index.ts | 1 - 1 file changed, 1 deletion(-) diff --git a/packages/asset-buyer/src/index.ts b/packages/asset-buyer/src/index.ts index 20a36b2501..9ac3c0b8ae 100644 --- a/packages/asset-buyer/src/index.ts +++ b/packages/asset-buyer/src/index.ts @@ -15,7 +15,6 @@ export { AssetBuyerError, AssetBuyerOpts, BuyQuote, - BuyQuoteInfo, BuyQuoteExecutionOpts, BuyQuoteInfo, BuyQuoteRequestOpts,