Skip to content

Latest commit

 

History

History
165 lines (123 loc) · 3.89 KB

README.md

File metadata and controls

165 lines (123 loc) · 3.89 KB
Raw

ethpm.js

API Documentation Build Status

Work in progress library for interacting with EthPM packages in Javascript and TypeScript.

Check out a short guided tutorial here.

Usage Example

const ethpm: Session = await EthPM.configure<HasManifests>({
  manifests: "ethpm/manifests/v3",
}).connect();

const pkg = await ethpm.manifests.read(examples["wallet-with-send"]);

Available APIs

There are multiple APIs that you can enable on your ethpm instance. Each api can be enabled by passing it's corresponding string into your ethpm object's configuration.

ethpm/manifests/v3

Description: Enables reading & writing of V3 manifests to/from JSON and Package instances.

Configuration:

const ethpm = await EthPM.configure({
  manifests: "ethpm/manifests/v3",
}).connect();

Usage:

// to generate a `Package` instance from a manifest JSON string
const package = await v3.read(manifestJson);

// to generate a manifest JSON string from a `Package` instance
const manifestJson = await v3.write(package)

ethpm/installer/truffle

Description: Writes ethpm package assets to disk, according to the written specification.

Configuration:

const ethpm = await EthPM.configure({
  installer: "ethpm/installer/truffle",
  storage: "ethpm/storage/ipfs",
}).connect({
  workingDirectory: '/path/to/working/directory',
  ipfs: {
    host: 'ipfs.infura.io',
	port: '5001',
	protocol: 'https'
  }
});

Usage:

  • Currently only IPFS uris are supported.
// to install the target package in the working directory
var manifestUri = "ipfs://Qm..."
var registryAddress = "0x123abc..."
await ethpm.install(manifestUri, registryAddress)

// to install the target package under an alias in the working directory
var alias = "alternate-name"
await ethpm.install(manifestUri, registryAddress, alias)

ethpm/storage/ipfs

Description: Reads & writes files from IPFS.

Configuration:

const ethpm = await EthPM.configure({
  storage: "ethpm/storage/ipfs",
}).connect({
  ipfs: {
    host: 'ipfs.infura.io',
	port: '5001',
	protocol: 'https'
  }
});

Usage:

const content = "wordswordswordswordspunchline"

const uri = await ethpm.storage.write(content)

const readContent = await ethpm.storage.read(uri)

const predictedUri = await ethpm.storage.predictUri(content)

const hash = await ethpm.storage.hash(content)

ethpm/registries/web3

Description: Publishes packages to on-chain package registries, and fetches release data from these registries.

Configuration:

const ethpm = await EthPM.configure({
  registries: "ethpm/registries/web3",
}).connect({
  provider: web3,
  registryAddress: '0x123abc...'
});

Usage:

// list all packages
const packages = await ethpm.registries.packages()

// list all release data for a particular package's releases
const ownedReleases = await ethpm.registries.package('owned').releases()

// get manifest uri for a specific release
const manifestUri = await ethpm.registries.package('owned').release('1.0.0')

// cut a release to the connected registry
await ethpm.registries.publish('owned', '1.0.0', 'ipfs://Qm...')

ethpm URI util

import { EthpmURI } from 'ethpm/utils/uri';

const rawUri = 'ethpm://snakecharmers.eth/owned@1.0.0'
const ethpmUri = new EthpmURI(rawUri)

ethpmUri.raw
> 'ethpm://snakecharmers.eth/owned@1.0.0'

ethpmUri.scheme
> 'ethpm'

ethpmUri.address
> 'snakecharmers.eth'

// defaults to 1 if no chain id included in rawUri
ethpmUri.chainId
> 1

ethpmUri.packageName
> 'owned'

ethpmUri.version
> '1.0.0'

ethpmUri.namespacedAsset
> ''