mirror of
https://github.com/oceanprotocol/ocean.js.git
synced 2024-11-26 20:39:05 +01:00
Adding introduction to code examples guide + updating the main readme
This commit is contained in:
Jamie Hewitt
parent
331da90db5
commit
64c464239c
60
README.md
60
README.md
@ -24,7 +24,7 @@ This is in alpha state. If you run into problems, please open up a [new issue](h
|
||||
|
||||
- [📚 Prerequisites](#-prerequisites)
|
||||
- [🏗 Installation](#-installation)
|
||||
- [🏄 Quickstart](#-quickstart): simple flow, marketplace, compute-to-data, more
|
||||
- [📖 Learn More](#-learn-more)
|
||||
- [🦑 Development](#-development)
|
||||
- [✨ Code Style](#-code-style)
|
||||
- [👩🔬 Testing](#-testing)
|
||||
@ -42,66 +42,18 @@ This is in alpha state. If you run into problems, please open up a [new issue](h
|
||||
- Docker ([Managed as a non-root user](https://docs.docker.com/engine/install/linux-postinstall/))
|
||||
- A Unix based operating system (Mac or Linux)
|
||||
|
||||
### Note
|
||||
|
||||
Any function that uses `getPastEvents()` will only work on Eth (see: <https://github.com/oceanprotocol/ocean.js/issues/741>). This includes:
|
||||
|
||||
- searchPoolforDT()
|
||||
- getPoolsbyCreator()
|
||||
- getPoolSharesByAddress()
|
||||
- getAllPoolLogs()
|
||||
- getPreviousValidOrders()
|
||||
- searchforDT()
|
||||
- getExchangesbyCreator()
|
||||
- getExchangeSwaps()
|
||||
- getAllExchangesSwaps()
|
||||
|
||||
## 🏗 Installation
|
||||
|
||||
```bash
|
||||
npm install @oceanprotocol/lib
|
||||
```
|
||||
|
||||
## 🏄 Quickstart
|
||||
|
||||
```ts
|
||||
import { Ocean, Config, ConfigHelper, Logger } from '@oceanprotocol/lib'
|
||||
|
||||
const defaultConfig: Config = new ConfigHelper().getConfig(
|
||||
'rinkeby',
|
||||
'YOUR_INFURA_PROJECT_ID'
|
||||
)
|
||||
|
||||
const config = {
|
||||
...defaultConfig,
|
||||
metadataCacheUri: 'https://your-metadata-cache.com',
|
||||
providerUri: 'https://your-provider.com'
|
||||
}
|
||||
|
||||
async function init() {
|
||||
const ocean = await Ocean.getInstance(config)
|
||||
return ocean
|
||||
}
|
||||
```
|
||||
|
||||
Here are flows to try out, from beginners to advanced.
|
||||
|
||||
- **[Beginners guide](docs/beginners_guide.md)** - for developers who are completely new to blockchain, no coding experience is required.
|
||||
- **[Simple flow](docs/quickstart_simple.md)** - the essence of Ocean - creating a data NFT & datatoken.
|
||||
- **[Marketplace flow](docs/quickstart_marketplace.md)** - a data asset is posted for sale in a datatoken pool, then purchased. Includes metadata and Compute-to-Data.
|
||||
|
||||
|
||||
### 📖 Learn more
|
||||
|
||||
- [Get test OCEAN](docs/get-test-OCEAN.md) - from rinkeby
|
||||
- [Understand config parameters](docs/parameters.md) - envvars vs files
|
||||
- [Learn about off-chain services](docs/services.md) - Ocean Provider for data services, Aquarius metadata store
|
||||
- [Learn about wallets](docs/wallets.md) - on generating, storing, and accessing private keys
|
||||
- [Get an overview of ocean.js](docs/overview.md) - key modules and functions
|
||||
|
||||
If you have any difficulties with the quickstarts, or if you have further questions about how to use ocean.js please reach out to us on [Discord](https://discord.gg/TnXjkR5).
|
||||
|
||||
If you notice any bugs or issues with ocean.js please [open an issue on github](https://github.com/oceanprotocol/ocean.js/issues/new?assignees=&labels=bug&template=bug_report.md&title=).
|
||||
- Checkout our [code examples](CodeExamples.md) to see how you can use ocean.js.
|
||||
- Refer to the [Ocean Protocol documentation](https://docs.oceanprotocol.com/) for more guides and tutorials.
|
||||
- Visit the [Ocean Protocol website](https://docs.oceanprotocol.com/) for general information about Ocean Protocol.
|
||||
- If you have any difficulties or if you have further questions about how to use ocean.js please reach out to us on [Discord](https://discord.gg/TnXjkR5).
|
||||
- If you notice any bugs or issues with ocean.js please [open an issue on github](https://github.com/oceanprotocol/ocean.js/issues/new?assignees=&labels=bug&template=bug_report.md&title=).
|
||||
|
||||
## 🦑 Development
|
||||
|
||||
|
||||
394
docs/overview.md
394
docs/overview.md
@ -1,394 +0,0 @@
|
||||
# Overview
|
||||
|
||||
Here is an overview of all ot the main functions and submodules:
|
||||
|
||||
### Ocean instance
|
||||
|
||||
Create/get datatoken, get dtfactory, user orders (history)
|
||||
|
||||
```
|
||||
import { Ocean } from '@oceanprotocol/lib'
|
||||
const ocean = await Ocean.getInstance(config)
|
||||
```
|
||||
|
||||
Then use the following submodules...
|
||||
|
||||
# Assets
|
||||
|
||||
Publish, get, list, search, order, consume/download
|
||||
|
||||
```Typescript
|
||||
ocean.asset.getInstance(config: InstantiableConfig): Promise<Assets>;
|
||||
```
|
||||
|
||||
```Typescript
|
||||
ocean.asset.create(metadata: Metadata, publisher: Account, services?: Service[], dtAddress?: string, cap?: string, name?: string, symbol?: string, providerUri?: string): SubscribablePromise<CreateProgressStep, DDO>;
|
||||
```
|
||||
|
||||
```Typescript
|
||||
ocean.asset.ownerAssets(owner: string): Promise<QueryResult>;
|
||||
```
|
||||
|
||||
```Typescript
|
||||
ocean.asset.resolve(did: string): Promise<DDO>;
|
||||
```
|
||||
|
||||
```Typescript
|
||||
ocean.asset.resolveByDTAddress(dtAddress: string, offset?: number, page?: number, sort?: number): Promise<DDO[]>;
|
||||
```
|
||||
|
||||
```Typescript
|
||||
ocean.asset.editMetadata(ddo: DDO, newMetadata: EditableMetadata): Promise<DDO>;
|
||||
```
|
||||
|
||||
```Typescript
|
||||
ocean.asset.updateMetadata(ddo: DDO, consumerAccount: string): Promise<TransactionReceipt>;
|
||||
```
|
||||
|
||||
```Typescript
|
||||
ocean.asset.editServiceTimeout(ddo: DDO, serviceIndex: number, timeout: number): Promise<DDO>;
|
||||
```
|
||||
|
||||
```Typescript
|
||||
ocean.asset.creator(did: string): Promise<string>;
|
||||
```
|
||||
|
||||
```Typescript
|
||||
ocean.asset.query(query: SearchQuery): Promise<QueryResult>;
|
||||
```
|
||||
|
||||
```Typescript
|
||||
ocean.asset.search(text: string): Promise<QueryResult>;
|
||||
```
|
||||
|
||||
```Typescript
|
||||
ocean.asset.getServiceByType(did: string, serviceType: string): Promise<Service>;
|
||||
```
|
||||
|
||||
```Typescript
|
||||
ocean.asset.getServiceByIndex(did: string, serviceIndex: number): Promise<Service>;
|
||||
```
|
||||
|
||||
```Typescript
|
||||
ocean.asset.createAccessServiceAttributes(creator: Account, cost: string, datePublished: string, timeout?: number, providerUri?: string): Promise<ServiceAccess>;
|
||||
```
|
||||
|
||||
```Typescript
|
||||
ocean.asset.initialize(did: string, serviceType: string, consumerAddress: string, serviceIndex: number, serviceEndpoint: string): Promise<any>;
|
||||
```
|
||||
|
||||
```Typescript
|
||||
ocean.asset.order(did: string, serviceType: string, payerAddress: string, serviceIndex?: number, mpAddress?: string, consumerAddress?: string, searchPreviousOrders?: boolean): Promise<string>;
|
||||
```
|
||||
|
||||
```Typescript
|
||||
ocean.asset.download(did: string, txId: string, tokenAddress: string, consumerAccount: Account, destination: string): Promise<string | true>;
|
||||
```
|
||||
|
||||
```Typescript
|
||||
ocean.asset.simpleDownload(dtAddress: string, serviceEndpoint: string, txId: string, account: string): Promise<string>;
|
||||
```
|
||||
|
||||
```Typescript
|
||||
ocean.asset.getOrderHistory(account: Account, serviceType?: string, fromBlock?: number): Promise<Order[]>;
|
||||
```
|
||||
|
||||
# Datatoken Pool
|
||||
|
||||
Create, add/remove liquidity, check liquidity, price, buy datatokens
|
||||
|
||||
```Typescript
|
||||
ocean.pool.
|
||||
```
|
||||
|
||||
```Typescript
|
||||
ocean.pool.createDTPool(account: string, token: string, amount: string, weight: string, fee: string): Promise<string>;
|
||||
```
|
||||
|
||||
```Typescript
|
||||
ocean.pool.getDTAddress(poolAddress: string): Promise<string>;
|
||||
```
|
||||
|
||||
```Typescript
|
||||
ocean.pool.getOceanReserve(poolAddress: string): Promise<string>;
|
||||
```
|
||||
|
||||
```Typescript
|
||||
ocean.pool.getDTReserve(poolAddress: string): Promise<string>;
|
||||
```
|
||||
|
||||
```Typescript
|
||||
ocean.pool.getMaxBuyQuantity(poolAddress: string, tokenAddress: string): Promise<string>;
|
||||
```
|
||||
|
||||
```Typescript
|
||||
ocean.pool.getOceanMaxBuyQuantity(poolAddress: string): Promise<string>;
|
||||
```
|
||||
|
||||
```Typescript
|
||||
ocean.pool.getDTMaxBuyQuantity(poolAddress: string): Promise<string>;
|
||||
```
|
||||
|
||||
```Typescript
|
||||
ocean.pool.calcInGivenOut(poolAddress: string, tokenInAddress: string, tokenOutAddress: string, tokenOutAmount: string): Promise<string>;
|
||||
```
|
||||
|
||||
```Typescript
|
||||
ocean.pool.calcOutGivenIn(poolAddress: string, tokenInAddress: string, tokenOutAddress: string, tokenInAmount: string): Promise<string>;
|
||||
```
|
||||
|
||||
```Typescript
|
||||
ocean.pool.calcPoolOutGivenSingleIn(poolAddress: string, tokenInAddress: string, tokenInAmount: string): Promise<string>;
|
||||
```
|
||||
|
||||
```Typescript
|
||||
ocean.pool.calcSingleInGivenPoolOut(poolAddress: string, tokenInAddress: string, poolShares: string): Promise<string>;
|
||||
```
|
||||
|
||||
```Typescript
|
||||
ocean.pool.calcSingleOutGivenPoolIn(poolAddress: string, tokenOutAddress: string, poolShares: string): Promise<string>;
|
||||
```
|
||||
|
||||
```Typescript
|
||||
ocean.pool.calcPoolInGivenSingleOut(poolAddress: string, tokenOutAddress: string, tokenOutAmount: string): Promise<string>;
|
||||
```
|
||||
|
||||
```Typescript
|
||||
ocean.pool.getPoolSharesRequiredToRemoveDT(poolAddress: string, dtAmount: string): Promise<string>;
|
||||
```
|
||||
|
||||
```Typescript
|
||||
ocean.pool.getDTRemovedforPoolShares(poolAddress: string, poolShares: string): Promise<string>;
|
||||
```
|
||||
|
||||
```Typescript
|
||||
ocean.pool.getPoolSharesRequiredToRemoveOcean(poolAddress: string, oceanAmount: string): Promise<string>;
|
||||
```
|
||||
|
||||
```Typescript
|
||||
ocean.pool.getOceanRemovedforPoolShares(poolAddress: string, poolShares: string): Promise<string>;
|
||||
```
|
||||
|
||||
```Typescript
|
||||
ocean.pool.getTokensRemovedforPoolShares(poolAddress: string, poolShares: string): Promise<TokensReceived>;
|
||||
```
|
||||
|
||||
```Typescript
|
||||
ocean.pool.getDTMaxAddLiquidity(poolAddress: string): Promise<string>;
|
||||
```
|
||||
|
||||
```Typescript
|
||||
ocean.pool.getOceanMaxAddLiquidity(poolAddress: string): Promise<string>;
|
||||
```
|
||||
|
||||
```Typescript
|
||||
ocean.pool.getMaxAddLiquidity(poolAddress: string, tokenAddress: string): Promise<string>;
|
||||
```
|
||||
|
||||
```Typescript
|
||||
ocean.pool.getMaxRemoveLiquidity(poolAddress: string, tokenAddress: string): Promise<string>;
|
||||
```
|
||||
|
||||
```Typescript
|
||||
ocean.pool.getDTMaxRemoveLiquidity(poolAddress: string): Promise<string>;
|
||||
```
|
||||
|
||||
```Typescript
|
||||
ocean.pool.getOceanMaxRemoveLiquidity(poolAddress: string): Promise<string>;
|
||||
```
|
||||
|
||||
```Typescript
|
||||
ocean.pool.buyDT(account: string, poolAddress: string, dtAmountWanted: string, maxOceanAmount: string, maxPrice?: string): Promise<TransactionReceipt>;
|
||||
```
|
||||
|
||||
```Typescript
|
||||
ocean.pool.sellDT(account: string, poolAddress: string, dtAmount: string, oceanAmountWanted: string, maxPrice?: string): Promise<TransactionReceipt>;
|
||||
```
|
||||
|
||||
```Typescript
|
||||
ocean.pool.addDTLiquidity(account: string, poolAddress: string, amount: string): Promise<TransactionReceipt>;
|
||||
```
|
||||
|
||||
```Typescript
|
||||
ocean.pool.removeDTLiquidity(account: string, poolAddress: string, amount: string, maximumPoolShares: string): Promise<TransactionReceipt>;
|
||||
```
|
||||
|
||||
```Typescript
|
||||
ocean.pool.addOceanLiquidity(account: string, poolAddress: string, amount: string): Promise<TransactionReceipt>;
|
||||
```
|
||||
|
||||
```Typescript
|
||||
ocean.pool.removeOceanLiquidity(account: string, poolAddress: string, amount: string, maximumPoolShares: string): Promise<TransactionReceipt>;
|
||||
```
|
||||
|
||||
```Typescript
|
||||
ocean.pool.removePoolLiquidity(account: string, poolAddress: string, poolShares: string, minDT?: string, minOcean?: string): Promise<TransactionReceipt>;
|
||||
```
|
||||
|
||||
```Typescript
|
||||
ocean.pool.getDTPrice(poolAddress: string): Promise<string>;
|
||||
```
|
||||
|
||||
```Typescript
|
||||
ocean.pool.searchPoolforDT(dtAddress: string): Promise<string[]>;
|
||||
```
|
||||
|
||||
```Typescript
|
||||
ocean.pool.getOceanNeeded(poolAddress: string, dtRequired: string): Promise<string>;
|
||||
```
|
||||
|
||||
```Typescript
|
||||
ocean.pool.getOceanReceived(poolAddress: string, dtSold: string): Promise<string>;
|
||||
```
|
||||
|
||||
```Typescript
|
||||
ocean.pool.getDTNeeded(poolAddress: string, OceanRequired: string): Promise<string>;
|
||||
```
|
||||
|
||||
```Typescript
|
||||
ocean.pool.getPoolsbyCreator(account?: string): Promise<PoolDetails[]>;
|
||||
```
|
||||
|
||||
```Typescript
|
||||
ocean.pool.getPoolDetails(poolAddress: string): Promise<PoolDetails>;
|
||||
```
|
||||
|
||||
```Typescript
|
||||
ocean.pool.getPoolLogs(poolAddress: string, account?: string): Promise<PoolTransaction[]>;
|
||||
```
|
||||
|
||||
```Typescript
|
||||
ocean.pool.getAllPoolLogs(account: string): Promise<PoolTransaction[]>;
|
||||
```
|
||||
|
||||
# Fixed rate exchange
|
||||
|
||||
Create, price, buy datatokens
|
||||
|
||||
```Typescript
|
||||
ocean.exchange.create(datatoken: string, rate: string, address: string): Promise<string>;
|
||||
```
|
||||
|
||||
```Typescript
|
||||
ocean.exchange.generateExchangeId(datatoken: string, owner: string): Promise<string>;
|
||||
```
|
||||
|
||||
```Typescript
|
||||
ocean.exchange.buyDT(exchangeId: string, datatokenAmount: string, address: string): Promise<TransactionReceipt>;
|
||||
```
|
||||
|
||||
```Typescript
|
||||
ocean.exchange.getNumberOfExchanges(): Promise<number>;
|
||||
```
|
||||
|
||||
```Typescript
|
||||
ocean.exchange.setRate(exchangeId: string, newRate: number, address: string): Promise<TransactionReceipt>;
|
||||
```
|
||||
|
||||
```Typescript
|
||||
ocean.exchange.activate(exchangeId: string, address: string): Promise<TransactionReceipt>;
|
||||
```
|
||||
|
||||
```Typescript
|
||||
ocean.exchange.deactivate(exchangeId: string, address: string): Promise<TransactionReceipt>;
|
||||
```
|
||||
|
||||
```Typescript
|
||||
ocean.exchange.getRate(exchangeId: string): Promise<string>;
|
||||
```
|
||||
|
||||
```Typescript
|
||||
ocean.exchange.getSupply(exchangeId: string): Promise<string>;
|
||||
```
|
||||
|
||||
```Typescript
|
||||
ocean.exchange.getOceanNeeded(exchangeId: string, datatokenAmount: string): Promise<string>;
|
||||
```
|
||||
|
||||
```Typescript
|
||||
ocean.exchange.getExchange(exchangeId: string): Promise<FixedPriceExchange>;
|
||||
```
|
||||
|
||||
```Typescript
|
||||
ocean.exchange.getExchanges(): Promise<string[]>;
|
||||
```
|
||||
|
||||
```Typescript
|
||||
ocean.exchange.isActive(exchangeId: string): Promise<boolean>;
|
||||
```
|
||||
|
||||
```Typescript
|
||||
ocean.exchange.CalcInGivenOut(exchangeId: string, datatokenAmount: string): Promise<string>;
|
||||
```
|
||||
|
||||
```Typescript
|
||||
ocean.exchange.searchforDT(datatokenAddress: string, minSupply: string): Promise<FixedPriceExchange[]>;
|
||||
```
|
||||
|
||||
```Typescript
|
||||
ocean.exchange.getExchangesbyCreator(account?: string): Promise<FixedPriceExchange[]>;
|
||||
```
|
||||
|
||||
```Typescript
|
||||
ocean.exchange.getExchangeSwaps(exchangeId: string, account?: string): Promise<FixedPriceSwap[]>;
|
||||
```
|
||||
|
||||
```Typescript
|
||||
ocean.exchange.getAllExchangesSwaps(account: string): Promise<FixedPriceSwap[]>;
|
||||
```
|
||||
|
||||
# Compute-to-data
|
||||
|
||||
consume/start, stop, results, status, define-service
|
||||
|
||||
```Typescript
|
||||
ocean.compute.start(did: string, txId: string, tokenAddress: string, consumerAccount: Account, algorithmDid?: string, algorithmMeta?: MetadataAlgorithm, output?: Output, serviceIndex?: string, serviceType?: string, algorithmTransferTxId?: string, algorithmDatatoken?: string): Promise<ComputeJob>;
|
||||
```
|
||||
|
||||
```Typescript
|
||||
ocean.compute.stop(consumerAccount: Account, did: string, jobId: string): Promise<ComputeJob>;
|
||||
```
|
||||
|
||||
```Typescript
|
||||
ocean.compute.delete(consumerAccount: Account, did: string, jobId: string): Promise<ComputeJob>;
|
||||
```
|
||||
|
||||
```Typescript
|
||||
ocean.compute.status(consumerAccount: Account, did?: string, jobId?: string): Promise<ComputeJob[]>;
|
||||
```
|
||||
|
||||
```Typescript
|
||||
ocean.compute.result(consumerAccount: Account, did: string, jobId: string): Promise<ComputeJob>;
|
||||
```
|
||||
|
||||
```Typescript
|
||||
ocean.compute.createServerAttributes(serverId: string, serverType: string, cost: string, cpu: string, gpu: string, memory: string, disk: string, maxExecutionTime: number): Server;
|
||||
```
|
||||
|
||||
```Typescript
|
||||
ocean.compute.createContainerAttributes(image: string, tag: string, checksum: string): Container;
|
||||
```
|
||||
|
||||
```Typescript
|
||||
ocean.compute.createClusterAttributes(type: string, url: string): Cluster;
|
||||
```
|
||||
|
||||
```Typescript
|
||||
ocean.compute.createProviderAttributes(type: string, description: string, cluster: Cluster, containers: Container[], servers: Server[]): {
|
||||
type: string;
|
||||
description: string;
|
||||
environment: {
|
||||
cluster: Cluster;
|
||||
supportedServers: Server[];
|
||||
supportedContainers: Container[];
|
||||
};
|
||||
};
|
||||
```
|
||||
|
||||
```Typescript
|
||||
ocean.compute.createComputeService(consumerAccount: Account, cost: string, datePublished: string, providerAttributes: any, computePrivacy?: ServiceComputePrivacy, timeout?: number, providerUri?: string): ServiceCompute;
|
||||
```
|
||||
|
||||
```Typescript
|
||||
ocean.compute.order(consumerAccount: string, datasetDid: string, serviceIndex: number, algorithmDid?: string, algorithmMeta?: MetadataAlgorithm, mpAddress?: string): SubscribablePromise<OrderProgressStep, string>;
|
||||
```
|
||||
@ -1,7 +1,29 @@
|
||||
/// # Ocean.js Code Examples
|
||||
|
||||
/// The following guide runs you through the process of using ocean.js to publish and then consume a dataset. The code examples below are all working and you can learn how to publish by following along.
|
||||
/// ## Introduction
|
||||
|
||||
/// The following guide runs you through the process of using ocean.js to publish and then consume a dataset. The code examples below are all working and you can learn how to publish by following along.
|
||||
/// The process involves creating a Data NFT (which represents the base-IP on-chain) and a datatoken (which will be used to purchase the dataset). This guide provides all the code you need and no prior knowledge is required. It is helpful if you have some experience with javascript but it is not necessary.
|
||||
|
||||
/// Selling your data over the blockchain puts you in charge of how it is used and can be a great source of passive income. There are many AI startups that have deep expertise in machine learning but need more data to improve their models. Selling your data via the blockchain gives you a level of security that you would be unable to achieve if you were selling via a centralised marketplace.
|
||||
|
||||
/// In this guide we'll be making use of the Ocean.js library. Ocean Protocol provides you with everything you need to quickly get setup and start selling data over the blockchain.
|
||||
|
||||
/// If you have any questions or issues at any point while following along to this article please reach out to us on [discord](https://discord.gg/TnXjkR5).
|
||||
|
||||
/// Here are the steps we will be following throughout the article:
|
||||
|
||||
/// 1. Prerequisites
|
||||
/// 2. Initialize services
|
||||
/// 3. Create a new node.js project
|
||||
/// 4. Install dependencies
|
||||
/// 5. Create a config file and update contract addresses
|
||||
/// 6. Publish a new datatoken
|
||||
/// 7. Mint 200 tokens
|
||||
/// 8. Publish a dataset
|
||||
/// 9. Allow the marketplace to sell your datatokens
|
||||
|
||||
/// Let's go through each step:
|
||||
/// Start by importing all of the necessary dependencies
|
||||
|
||||
/// ```Typescript
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user