OE Guides

Runnable developer guides for the Ocean Protocol Enterprise (OE) stack.

Each guide is a short, focused walkthrough backed by a working TypeScript example you can run against a live Ocean Node. The guides target DDO v5, the schema used by the OE stack.

More topics (publishing, editing, compute-to-data) will be added over time. The guides/ + src/ layout is designed so each topic slots in independently.

Start here

New to this repo? Follow these steps in order:

1. Set up the project — Setup below (nvm use, npm install, copy .env).
2. Get an account. You need an Ethereum account to sign transactions.
   • Have an encrypted JSON wallet file from the wallet-creation flow? Start with Use Your Wallet File (Keystore).
   • Already have a raw private key? Put it in .env as PRIVATE_KEY and move on.
3. Fund it with the chain's native token (for gas) and, for priced assets, the payment token.
4. Consume a dataset — the main walkthrough: Consume a Dataset with ocean.js (or the no-code CLI version).

Just need the values to fill in .env? Jump to Environment variables.

Guides

Guide	What you'll do
Use Your Wallet File (Keystore)	Turn the encrypted JSON wallet file into an account the guides can use.
Consume a Dataset with ocean.js	Order and download a v5 dataset from Node.js with ocean.js.
Consume a Dataset with the Ocean CLI	The same outcome, no code, using the Ocean CLI.

Prerequisites

• Node.js 24 — pinned via .nvmrc. Run nvm use in this folder. (package.json sets a minimum of Node 20 via engines.)
• A funded account, an RPC endpoint, and an Ocean Node URL (see below).

Setup

nvm use            # Node 24
npm install
cp .env.example .env   # then fill in the values

Environment variables (see .env.example):

Variable	Required	Purpose
PRIVATE_KEY	one of	Consumer account as a raw hex key (pays for / claims the datatoken).
KEYSTORE_PATH	one of	Encrypted JSON wallet file to use instead of PRIVATE_KEY — see the wallet guide.
KEYSTORE_PASSWORD	no	Password for KEYSTORE_PATH; if unset you are prompted (hidden).
RPC	yes	JSON-RPC endpoint for the asset's chain.
NODE_URL	yes	Ocean Node (metadata cache + provider).
SSI_WALLET_API	no	SSI wallet API for credential-gated v5 assets.
SSI_WALLET_ID	no	SSI wallet id.
SSI_WALLET_DID	no	Preferred wallet DID (defaults to the first).

Run the consume example

npm run consume -- <did> [outputDir] [serviceId]

Extract a private key from a wallet file

If your account came as an encrypted JSON wallet (keystore) file:

npm run extract-key -- ./wallet.json

See the wallet guide for the recommended, no-extraction path (KEYSTORE_PATH).

Type-check

npm run typecheck

Project layout

oe_guides/
├── guides/                     Markdown walkthroughs
│   ├── wallet-keystore.md
│   ├── consume-dataset.md
│   └── consume-with-ocean-cli.md
├── src/                        Runnable TypeScript examples
│   ├── config.ts               env → signer / Ocean config / Aquarius
│   ├── wallet.ts               keystore decrypt + password helpers
│   ├── extract-private-key.ts  CLI: keystore file → private key
│   ├── policyServer.ts         v5 detection + non-blocking policy-server stub
│   └── consume-dataset.ts      the consume example
├── .env.example
├── .nvmrc                      Node 24
├── package.json
└── tsconfig.json

Dependency versions

These are pinned deliberately, not by accident:

• @oceanprotocol/lib (^8.6.2) — resolves to the latest 8.x.
• @oceanprotocol/ddo-js (^0.3.0) — held on 0.3.x on purpose: this is the version @oceanprotocol/lib@8.6.2 itself depends on. Forcing 0.4.0 would install a second, incompatible copy and break the DDO types/instanceof checks when passing objects into ocean.js. Bump both together only when a release of ocean.js depends on ddo-js@^0.4.0.
• ethers (^6) — matches ocean.js's peer requirement.

Note on tsconfig.json: it maps @oceanprotocol/ddo-js via paths to its bundled .d.ts, because that package's exports field omits a types condition. This is a workaround for an upstream packaging gap and can be removed once ddo-js ships a types condition in exports.