Getting Started with ocean.py, Part 4: Walkthrough

Trent McConaghy

·

Follow

Published in

Ocean Protocol

·

4 min read

·

Apr 14, 2023

--

Listen

Share

Introduction

ocean.py is a Python library to privately & securely publish, exchange, and consume data, using Ocean Protocol.

Part 1 of this series introduced ocean.py, and described how to install it. Part 2 described how to set up for local testing, and part 3 for remote.

This post is a fun one! We pick up where part 2 & 3 left off, and walk you through the main flow:

In this post, you’ll publish a data asset, post for free / for sale, dispense it / buy it, and consume it. We’ll closely follow ocean.py’s main-flow.md.

Background: Ocean Basics

This post assumes a basic understanding of Ocean data NFTs and datatokens. If you don’t yet know about these, we recommend learning about those first, by text or video.

• To learn by text: start with the simple description at oceanprotocol.com main site. If you want to dive deeper yet, then check out Ocean docs on architecture and Data NFTs & datatokens.
• Or, check out the video version 👇. [Note: the video was done in early March 2023, therefore it may be a bit out of date]

Main Flow: Video

Here’s a video version this post 👇. Or, jump straight into the text content below. [Note: the video was done in early March 2023, therefore it may be a bit out of date]

Main Flow: Text

Steps in the flow:

1. Alice publishes dataset
2. Bob gets access to the dataset (faucet, priced, etc)
3. Bob consumes the dataset

Let’s go!

(Note: this blog post is up-to-date as of Apr 2023, but if 2+ months have passed, we recommend using the READMEs directly for up-to-date instructions. )

1. Alice publishes dataset

Alice! Alice! Who the f*** is Alice?

Well, for the steps below, you are Alice! 👧

In the same Python console:

#data info
name = "Branin dataset"
url = "https://raw.githubusercontent.com/trentmc/branin/main/branin.arff"

#create data asset
(data_nft, datatoken, ddo) = ocean.assets.create_url_asset(name, url, {"from": alice})

#print
print("Just published asset:")
print(f"  data_nft: symbol={data_nft.symbol}, address={data_nft.address}")
print(f"  datatoken: symbol={datatoken.symbol}, address={datatoken.address}")
print(f"  did={ddo.did}")

You’ve now published an Ocean asset!

• data_nft is the base (base IP)
• datatoken for access by others (licensing)
• ddo holding metadata

(For more info, see Appendix: Publish Details.)

2. Bob gets access to the dataset

If you’ve ever spent time in the world of crypto, or cryptography:

Wherever there’s a Bob, there’s always an Alice

OK, OK. So yes, there’s a Bob. He wants to consume the dataset that Alice just published. The first step is for Bob to get 1.0 datatokens.

Below, we show four possible approaches:

• A & B are when Alice is in contact with Bob. She can mint directly to him, or mint to herself and transfer to him.
• C is when Alice wants to share access for free, to anyone
• D is when Alice wants to sell access

In the same Python console:

from ocean_lib.ocean.util import to_wei

#Approach A: Alice mints datatokens to Bob
datatoken.mint(bob, to_wei(1), {"from": alice})

#Approach B: Alice mints for herself, and transfers to Bob
datatoken.mint(alice, to_wei(1), {"from": alice})
datatoken.transfer(bob, to_wei(1), {"from": alice})

#Approach C: Alice posts for free, via a dispenser / faucet; Bob requests & gets
datatoken.create_dispenser({"from": alice})
datatoken.dispense(to_wei(1), {"from": bob})

#Approach D: Alice posts for sale; Bob buys
# D.1 Alice creates exchange
price = to_wei(100)
exchange = datatoken.create_exchange({"from": alice}, price, ocean.OCEAN_address)

# D.2 Alice makes 100 datatokens available on the exchange
datatoken.mint(alice, to_wei(100), {"from": alice})
datatoken.approve(exchange.address, to_wei(100), {"from": alice})

# D.3 Bob lets exchange pull the OCEAN needed
OCEAN_needed = exchange.BT_needed(to_wei(1), consume_market_fee=0)
ocean.OCEAN_token.approve(exchange.address, OCEAN_needed, {"from":bob})

# D.4 Bob buys datatoken
exchange.buy_DT(to_wei(1), consume_market_fee=0, tx_dict={"from": bob})

You may not realize it, but you just covered a crazy amount of ground!! You just went through four different ways to share data! Minting, transferring, faucets, and selling!

What made this possible is that the access control to the data is tokenized, via datatokens. Then you were basically using the tools of crypto to move those datatokens around.

(For more info, see Appendix: Dispenser / Faucet Details and Exchange Details.)

3. Bob consumes the dataset

Bob now has the datatoken for the dataset! Time to download the dataset and use it.

In the same Python console:

# Bob sends a datatoken to the service to get access
order_tx_id = ocean.assets.pay_for_access_service(ddo, {"from": bob}).hex()

# Bob downloads the file. If the connection breaks, Bob can try again
asset_dir = ocean.assets.download_asset(ddo, bob, './', order_tx_id)

import os
file_name = os.path.join(asset_dir, "file0")

Let’s check that the file is downloaded. In a new console:

cd my_project/datafile.did:op:*
cat file0

The beginning of the file should contain the following contents:

% 1. Title: Branin Function
% 3. Number of instances: 225
% 6. Number of attributes: 2
@relation branin
@attribute 'x0' numeric
@attribute 'x1' numeric
@attribute 'y' numeric
@data
-5.0000,0.0000,308.1291
-3.9286,0.0000,206.1783
...

(For more info, see Appendix: Consume Details.)

Conclusion / Next Step

You’ve now done a walk-through of the main flow, congrats! As Alice, you published a data asset, posted for free / for sale, and had that Bob guy dispense it / buy it and consume it.

Have questions? Here’s the Ocean Protocol #dev-support channel on Discord.

About Ocean Protocol

Ocean was founded to level the playing field for AI and data. Ocean tools enable people to privately & securely publish, exchange, and consume data.

Follow Ocean on Twitter or Telegram to keep up to date. Chat directly with the Ocean community on Discord. Or, track Ocean progress directly on GitHub.