EthAvatar.JS: Get avatar image for an Ethereum address

Recommend this page to a friend!
  Info   View files Example   Screenshots Screenshots   View files View files (38)   DownloadInstall with Composer Download .zip   Reputation   Support forum   Blog    
Ratings Unique User Downloads Download Rankings
Not yet rated by the usersTotal: 15 All time: 537 This week: 3Up
Version License JavaScript version Categories
ethavatar 1.0MIT/X Consortium ...5Node.js, Web services, Graphics
Description Author

This package can get avatar image for an Ethereum address.

It can take a given Ethereum address and sends a request to the FIPS API to retrieve the avatar image associated to that address.

The package can be used either from the command line or from the Web.

Picture of Filip Štamcar
  Performance   Level  
Name: Filip Štamcar <contact>
Classes: 1 package by
Country: Slovenia Slovenia
Age: ???
All time rank: 1831 in Slovenia Slovenia
Week rank: 6 Up1 in Slovenia Slovenia Equal

Details

![EthAvatar Logo][icon-logo]

EthAvatar.JS

[![Stable Version][icon-stable-version]][link-package] [![Unstable Version][icon-unstable-version]][link-package] [![Downloads][icon-downloads]][link-package] [![License][icon-license]][link-license] [![Node.js][icon-nodejs]][link-nodejs] [![Build Status][icon-travis]][link-travis]

EthAvatar.JS is a JavaScript API for EthAvatar.

Description

About EthAvatar

[EthAvatar][link-ethavatar] associates an avatar of your choice with an Ethereum address that you own. It is using [IPFS][link-ipfs] and [Ethereum][link-ethereum] [Smart Sontract][link-contract] to store avatars of addresses.

The avatar image is stored on IPFS and is bound to your address via an Ethereum smart contract.

Features

  • Visual Verification: When sending ether to an exchange for instance, instead of being paranoid if you've pasted the correct address, wallets that support Eth Avatar will be able to fetch the exchange logo as a forms of visual verification. The same also works the other way around when transferring from the exchange to your own wallet.
  • Token Branding: Tokens and contracts will be able to associate branding artwork to their addresses, allowing it to be possibly visible on EtherScan and exchanges once they support Eth Avatar.
  • Personal Use: It's fun to associate avatars with your personal addresses and be able to visually differentiate between them in your wallets.

TODO

  • [x] ~~Command line program~~
  • [x] ~~Watching for contract events~~
  • [x] ~~Deleting avatars~~
  • [x] ~~Uploading avatars from files or URLs~~
  • [x] ~~Better tests~~
  • [ ] Support for JavaScript fronted frameworks

Installation

Using NPM or Yarn

EthAvatar.JS requires [Node.js][link-nodejs] and [NPM][link-npm] or [Yarn][link-yarn]. It works with Node.js 10 or later, but it is recommended to use supported and maintained versions. Note that if you want to use it with Node.js 12 or later, you must use Yarn instead of NPM (because of [Truffle and Web3 bug][link-truffle-bug]).

You could globally install EthAvatar.JS to get command line interface:

npm install -g ethavatar // Using NPM
yarn global add ethavatar // Using Yarn

You could also install EthAvatar.JS locally, so you could use it in your application:

npm install --save ethavatar // Using NPM
yarn add ethavatar // Using Yarn

Using CDN

If you want to use EthAvatar.JS in browser, you could include scripts from one of our CDNs in your HTML website:

<!-- Normal Versions -->
<script src="https://cdn.jsdelivr.net/npm/ethavatar/dist/index.js"></script>
<script src="https://unpkg.com/ethavatar/dist/index.js"></script>

<!-- Minified Versions -->
<script src="https://cdn.jsdelivr.net/npm/ethavatar/dist/index.min.js"></script>
<script src="https://unpkg.com/ethavatar/dist/index.min.js"></script>

Usage

In Command Line

Command line program allows you to get and set avatars using files.

First you should specify Web3 and IPFS connection using ethavatar config:

$ ethavatar config --web3 http://127.0.0.1:8545/
$ ethavatar config --ipfs https://ipfs.infura.io:5001/

Program will save them in ~/.ethavatar file. Web3 connection is required and all providers are supported. IPFS connection is optional and it uses Infura IPFS API by default.

You can get avatar to file using ethavatar get <filename>:

$ ethavatar get avatar.jpg # Save avatar of current address to file avatar.jpg
$ ethavatar get avatar.jpg --address 0x0000000000000000000000000000000000000000 # Save avatar of address 0x0000000000000000000000000000000000000000 to file avatar.jpg

You can set avatar using ethavatar set <filename>:

$ ethavatar set avatar.jpg # Uplaod avatar of current address from fileavatar.jpg

In Applications

Instantiation

The whole class is asynchronous, so you would need to use promises or async/await in your application.

First, include this library and instantiate the class in your file:

const EthAvatar = require('ethavatar')
const ethavatar = new EthAvatar()

Class is using injected Web3 provider (like Mist or MetaMask) and Infura IPFS API. It is using official smart contract for detected network. You could also change them when instantiating the class:

/// Load Web3 and IPFS
const Web3 = require('web3')
const IpfsAPI = require('ipfs-api')

// Load EthAvatar
const EthAvatar = require('ethavatar')

// Use local Web3 Provider
const web3Provider = new Web3.providers.HttpProvider('http://127.0.0.1:8545/')
const web3Connection = new Web3(web3Provider)

/// Use Infura IPFS API
const ipfsConnection = IpfsAPI('ipfs.infura.io', '5001', {protocol: 'https'})

// Use custom contract address
const contractAddress = '0x96fc5a0b46e9e4b5d114c42d4daeaa1c2517078a'

const ethavatar = new EthAvatar(
  web3Connection,
  ipfsConnection,
  contractAddress
)

Getting Avatars

You should use method get() to get avatar of address. It uses current address as default, but you could specify any other address:

ethavatar.get()
  .then((avatar) => {
    if (typeof avatar === 'undefined') {
      throw new Error('Avatar of address not set')
    } else {
      return avatar
    }

  }).then((avatar) => {
    // Load FileSystem module
    const fs = require('fs')

    // Write avatar to file
    fs.writeFile(
      'avatar.jpg',
      avatar,
      'binary',
      (err) => {
        if (err) {
          throw err
        }
      }
    )

  }).catch((error) => {
    console.error(error.message)
  })

The avatar is returned as buffer, so you could directly write it to file.

Setting Avatars

You should use set() to set avatar of address. It's parameter must be buffer of avatar, so it is possible to upload it from a file:

let avatar = Buffer.from(['00', '01', '03', '04', '05', '06', '07', '08', '09'])

ethavatar.set(avatar)
  .then((avatar) => {
    console.log('Avatar uploaded!')

  }).catch((error) => {
    console.error(error.message)
  })

Deleting Avatars

You should use remove() to remove avatar of address. It doesn't have any parameters and you could only remove avatar of your address:

ethavatar.remove()
  .then(() => {
    console.log('Avatar removed!')

  }).catch((error) => {
    console.error(error.message)
  })

Watching Changes

You can also watch for avatar changes of specific address. It uses current address as default, but you could specify any other address:

ethavatar.watch((result => {
  console.log('User address: ' + result.hashAddress)
  console.log('IPFS hash: ' + result.hash)
}, '0xe12Aa5FB5659bb0DB3f488e29701fE303bcBAf65')

File Operations

File operations are possible with FileHelper class:

const FileHelper = require('ethavatar').fileHelper
const fileHelper = new FileHelper(ethavatar)

You can then save avatar directly to file:

fileHelper.toFile('avatar.png', '0xe12Aa5FB5659bb0DB3f488e29701fE303bcBAf65')
  .then((avatar) => {
    console.log('Avatar saved!')

  }).catch((error) => {
    console.error(error.message)
  })

You can also upload avatar from file:

fileHelper.fromFile('avatar.png')
  .then((avatar) => {
    console.log('Avatar uploaded!')

  }).catch((error) => {
    console.error(error.message)
  })

URL operations

URL operations are possible with UrlHelper class:

const UrlHelper = require('ethavatar').urlHelper
const urlHelper = new UrlHelper(ethavatar)

You can then post avatar as multipart form data:

urlHelper.toUrl('https://example.com/', '0xe12Aa5FB5659bb0DB3f488e29701fE303bcBAf65')
  .then((avatar) => {
    console.log('Avatar downloaded!')

  }).catch((error) => {
    console.error(error.message)
  })

The request will have `multipart/form-datacontent type and includeaddressandavatar` form values.

You can also get avatar from URL:

urlHelper.fromUrl('https://upload.wikimedia.org/wikipedia/en/a/a9/Example.jpg')
  .then((avatar) => {
    console.log('Avatar uploaded!')

  }).catch((error) => {
    console.error(error.message)
  })

Other Examples

You could also look to [example.js][link-example] or [API documentation][link-documentation]. Source code of [console application][link-console] is also great way to learn how this works.

Built With

  • [Ethereum][link-ethereum]
  • [Truffle Framework][link-truffle]
  • [Web3][link-web3]
  • [IPFS][link-ipfs]

Contributing

Please read [CONTRIBUTING.md][link-contributing] for details.

Versioning

This project uses [SemVer][link-semver] for versioning. For the versions available, see the [tags on this repository][link-tags].

License

This project is licensed under the MIT license. See the [LICENSE][link-license-file] file for details.

[icon-logo]: https://screenshotscdn.firefoxusercontent.com/images/ea73525d-a516-4795-b5f3-8ad967d9a324.png

[icon-stable-version]: https://img.shields.io/npm/v/ethavatar/latest.svg?style=flat-square&label=Stable+Version [icon-unstable-version]: https://img.shields.io/npm/v/ethavatar/beta.svg?style=flat-square&label=Unstable+Version [icon-downloads]: https://img.shields.io/npm/dt/ethavatar.svg?style=flat-square&label=Downloads [icon-license]: https://img.shields.io/npm/l/ethavatar.svg?style=flat-square&label=License [icon-nodejs]: https://img.shields.io/node/v/ethavatar.svg?style=flat-square&label=Node.js [icon-travis]: https://img.shields.io/travis/com/filips123/EthAvatar.JS.svg?style=flat-square&label=Build+Status

[link-ethavatar]: https://github.com/gitcoinco/ethavatar/ [link-contract]: https://etherscan.io/address/0x4FbF2f1613Cc86314b22AE10Ae95D19cF2990824/ [link-ethereum]: https://ethereum.org/ [link-truffle]: http://truffleframework.com/ [link-web3]: https://github.com/ethereum/web3.js/ [link-ipfs]: https://ipfs.io/ [link-nodejs]: https://nodejs.org/ [link-npm]: https://www.npmjs.com/ [link-yarn]: https://yarnpkg.com/ [link-semver]: https://semver.org/ [link-license]: https://choosealicense.com/licenses/mit/

[link-package]: https://www.npmjs.com/package/ethavatar/ [link-travis]: https://travis-ci.com/filips123/EthAvatar.JS/

[link-tags]: https://github.com/filips123/ethavatar.js/tags/ [link-license-file]: https://github.com/filips123/ethavatar.js/blob/master/LICENSE/ [link-example]: https://github.com/filips123/ethavatar.js/blob/master/example.js/ [link-documentation]: https://ethavatar.js.org/ [link-console]: https://github.com/filips123/EthAvatar.JS/blob/master/src/console.js/ [link-contributing]: https://github.com/filips123/ethavatar.js/blob/master/CONTRIBUTING.md

[link-truffle-bug]: https://github.com/trufflesuite/truffle/issues/2070

Screenshots  
  • demo.gif
  Files folder image Files  
File Role Description
Files folder image.github (2 files, 2 directories)
Files folder imagesrc (3 files, 3 directories)
Files folder imagetest (1 file, 1 directory)
Plain text file .aegir.js Class Class source
Accessible without login Plain text file .editorconfig Data Auxiliary data
Plain text file .travis.yml Class Class source
Accessible without login Plain text file example.js Example Example script
Accessible without login Plain text file LICENSE Lic. License text
Accessible without login Plain text file package.json Data Auxiliary data
Accessible without login Plain text file README.md Doc. Documentation
Accessible without login Plain text file yarn.lock Data Auxiliary data

  Files folder image Files  /  .github  
File Role Description
Files folder imageISSUE_TEMPLATE (3 files)
Files folder imagePULL_REQUEST_TEMPLATE (2 files)
  Accessible without login Plain text file FUNDING.yml Data Auxiliary data
  Accessible without login Plain text file PULL_REQUEST_TEMPLATE.md Example Example script

  Files folder image Files  /  .github  /  ISSUE_TEMPLATE  
File Role Description
  Accessible without login Plain text file bug-report.md Data Auxiliary data
  Accessible without login Plain text file feature-request.md Data Auxiliary data
  Accessible without login Plain text file support-question.md Data Auxiliary data

  Files folder image Files  /  .github  /  PULL_REQUEST_TEMPLATE  
File Role Description
  Accessible without login Plain text file bugs.md Example Example script
  Accessible without login Plain text file features.md Example Example script

  Files folder image Files  /  src  
File Role Description
Files folder imagedata (1 file)
Files folder imageerrors (14 files)
Files folder imagehelpers (2 files)
  Plain text file client.js Class Class source
  Accessible without login Plain text file console.js Aux. Auxiliary script
  Plain text file index.js Class Class source

  Files folder image Files  /  src  /  data  
File Role Description
  Accessible without login Plain text file EthAvatar.json Data Auxiliary data

  Files folder image Files  /  src  /  errors  
File Role Description
  Plain text file BrowserError.js Class Class source
  Plain text file ContractNotFoundError.js Class Class source
  Plain text file DefaultAddressNotFoundError.js Class Class source
  Plain text file DownloadFileError.js Class Class source
  Plain text file GetAvatarError.js Class Class source
  Plain text file GetUrlError.js Class Class source
  Plain text file InvalidAddressError.js Class Class source
  Plain text file NodeError.js Class Class source
  Plain text file PostUrlError.js Class Class source
  Plain text file RemoveAvatarError.js Class Class source
  Plain text file SetAvatarError.js Class Class source
  Plain text file UploadFileError.js Class Class source
  Plain text file Web3NotAllowedError.js Class Class source
  Plain text file Web3ProviderNotFoundError.js Class Class source

  Files folder image Files  /  src  /  helpers  
File Role Description
  Plain text file file.js Class Class source
  Plain text file url.js Class Class source

  Files folder image Files  /  test  
File Role Description
Files folder imagehelpers (2 files)
  Plain text file client.spec.js Class Class source

  Files folder image Files  /  test  /  helpers  
File Role Description
  Plain text file file.spec.js Class Class source
  Plain text file url.spec.js Class Class source

 Version Control Unique User Downloads Download Rankings  
 97%
Total:15
This week:0
All time:537
This week:3Up