aspiers / rolod0x Goto Github PK

Your free private onchain address book

License: MIT License

CSS 0.64% HTML 2.27% TypeScript 88.29% Shell 0.24% JavaScript 6.71% SCSS 1.45% Ruby 0.40%

address-book blockchain foss privacy web3

rolod0x's Introduction

Overview • Features • Video • Installation • Usage • Telegram • FAQ • Donations • Support • Security • Privacy • Development • Star History • Thanks • License

Download for Chrome Download for Firefox

Overview

Would you buy a phone which didn't have an address book feature? Of course not - that would be ridiculous! You'd never know who was calling you, and making phone calls would be painful.

What about a phone which had an address book but required you to publish all the entries so that the whole world could see them? Of course not - that would be a massive privacy violation!

So why accept anything less when using web3 and blockchains?

Well, you don't have to any longer! rolod0x is a free cross-browser extension providing a totally private onchain address book which instantly makes every web3 website more usable and all your addresses more accessible.

For example, take: this randomly-picked transaction on etherscan:

After labelling the From and To addresses in rolod0x, it now looks like this:

Not only that, but whenever these addresses appear on any other website, they will now be labelled in this human-readable way!

Features

Completely free and Open Source!
Completely private local-only web3 address book.
Automatically translates blockchain addresses to human-readable labels.
Add entries directly from within a web page, by right-clicking on an address.
Instantly look up an address via a hotkey.
Works on any website.
Works on any EVM-based blockchain (and could easily support other chains in the future).
Should work on Chrome, Chromium, Brave, or any other browser in the Chrome family.
Should work on Firefox (see #19).
Command-line version for translating addresses output on the terminal.
Light and dark themes.
Named using a triple pun.

Demo video

Installation

Please see the installation guide.

Usage

Please see the user manual.

FAQ

Please see the Frequently Asked Questions page.

Donations

If you find this project helpful and would like to support its development, you can make a donation in a number of ways:

Through Gitcoin Grants Round 20: https://explorer.gitcoin.co/#/round/42161/25/89
Through the Giveth platform: https://giveth.io/project/rolod0x
Send Bitcoin to: bc1quuspvrjepx63k5hpydwqkf6nmtt9eqm86y8w8a

Your contribution will go directly towards enhancing the project, covering development costs, and supporting ongoing maintenance.

We appreciate every donation, no matter the size. It helps to ensure the project's sustainability and motivates us to continue delivering valuable updates and improvements.

Thank you for considering a donation to support our work!

Support

Please see this document.

Security

Please see the SECURITY.md file.

Privacy policy

Please see docs/privacy-policy.md file.

Development and building from source

For information on how to get started with development, please see the developer guide.

Any pull request providing an enhancement or bugfix is extremely welcome!

Star History

Thanks

Thanks to all contributors. Some special mentions:

@fregante for all his great npm modules, several of which are used by rolod0x.
@jonghakseo for https://github.com/Jonghakseo/chrome-extension-boilerplate-react-vite which was a great starting point for a React-based MV3 extension.
Miles Essex for some fantastic design work which freed up my time to focus on technical work. Check out his exciting project Rails which generates dynamic, interactive maps visualising DeFi transactions!
The awesome team at my startup Toucan for being early beta testers and encouraging me to keep working on this project. In particular, thanks to Alex Haase for brainstorming with me and coming up with the perfect name!
Dalton Maag and Canonical for the Ubuntu font whose 0x gave me the inspiration for the logo.
ricmoo for the wonderful ethers Javascript library.

License

Except where otherwise stated, this extension is licensed under the GNU General Public License v3 or later. See LICENSE.txt for details.

This Free Software license was chosen because its copyleft property ensures that rolod0x remains a public good whereby:

the whole community benefits indefinitely from any contributions, and
it's protected against commercial entities who could otherwise profit from the code without requiring any contributions back to the original project.

Why is there also a `LICENSE` file including the Expat ("MIT") license?

This extension is based on https://github.com/Jonghakseo/chrome-extension-boilerplate-react-vite/ released under the permissive Expat (a.k.a. MIT) license, and formerly on https://github.com/fregante/browser-extension-template/ which is released under CC0.

Relicensing to GPL is allowed because the permissive Expat license explicitly allows sublicensing as long as the original copyright notice is preserved.

rolod0x's People

Contributors

Stargazers

Watchers

Forkers

positonic l7cubed beasta

rolod0x's Issues

Write docs

Decide on a good name

etherlabel
ethertag
ethernick
ethlabel
ethtag
0xlabel
0xfrens (but already an NFT collection)
0xbook (as in, address book)
metabook (like MetaMask)

Move example config into CodeMirror as default

Currently, default settings screen on install looks like this:

with the instructions outside the text box. Another option is to move the help text into the text box as comments, so that it can be deleted once the user has got the hang of things. I'm not sure if this is better UX.

Support labelling of DID credentials

Address labelling is just the starting point. We can also label many other things, including DID credentials like the ones used by https://disco.xyz.

Add code editor for options screen

Options:

Switch to manifest v3

Required in order to publish to Chrome Web Store.

Add donation links

Set up a separate hardware wallet for rolod0x.eth
Switch ENS to point to it
~~Set up Liberapay~~ Might do this later
Add .github/FUNDING.yml
Add crypto addresses to README

auto-open Settings tab on extension install

Use https://developer.chrome.com/docs/extensions/reference/api/runtime#event-onInstalled

Bard suggested:

chrome.runtime.onInstalled.addListener((details) => {
    if (details.reason === chrome.runtime.OnInstalledReason.INSTALL) {
        chrome.tabs.create({ url: chrome.extension.getURL("settings.html") });
    }
});

Once working, update Usage section of README too.

Allow easy navigation from address book entry to related websites

Would be great to have a quick way to open any related website from any of the entries in the address book, e.g.

block explorers
Multi-sig web UIs
OZ Defender
Tenderly and similar sites
DeFi apps

This could be supported by pressing a hotkey to open a search field and typing into an incremental substring search to narrow down the list of candidates, then choosing some action to perform on the selected address.

See #134 for the follow-up of creating an action menu where you can press another hotkey to select from a menu of sites to visit. The list of sites should be configurable by the user, with some useful ones out of the box.

Allow splitting addresses into sections each with toggle on/off

Rather than having a single giant <textarea>, we should allow an arbitrary number of sections. This would allow groupings of addresses into natural categories like "work", "personal", "family" etc.

Then each section could be toggled on/off from the extension popup menu like Tampermonkey / Stylus do. This would allow things like safe screensharing of etherscan with work colleagues, by turning off the personal / family sections in advance and only having work addresses labelled during the screenshare.

It would also allow the data of individual sections to be retrieved via URL, opening up many new possibilities as detailed in #24.

Ensure extension works on Firefox

Current status of support

Get settings page working
Get address replacement working
Get settings opening in dedicated tab - should be fixed by #273
Get address search via hotkey working - should be fixed by #273
Get address search via popup menu working - should be fixed by #273
Get right-click to add address label working - should be fixed by #273
Get built-in list of sites enabled by default - tracked in #275 but this may be impossible

Basically anything relating to the background script doesn't work.

Help needed with testing

Do you want rolod0x to support Firefox? You can help make it happen! While a Firefox .zip hasn't been included in a release yet, they're already being built automatically by the CI, so you can download, test, and report back in #274 what isn't working. Just go to this list of successful builds, click on the top one, scroll to the bottom of the build page, and click on the firefox artifact:

Then follow the installation guide for Chrome as it works in more or less the same way.

As soon as you encounter a problem (which may be very early at the time of writing), just come back to this issue and post details. Screenshots are helpful!

Useful resources

Old info, no longer relevant

See fregante/browser-extension-template#78.

Possible approach to solution: transclude-me/extension@78b529e#diff-7ae45ad102eab3b6d7e7896acd08c427a9b25b346470d7bc6507b6481575d519

Display validation of label list

Style parser error container

Show helpful tooltip on mouse hover

Could show any/all of:

original address
copy to clipboard icon
link to blockscan.com, blockscout.com etc.
token balances?

Not sure this is a good idea as it will interfere with tooltips from the page, e.g. etherscan provides these.

allow exceptions per site / page / page elements

The extension mechanism automatically gives users the choice of whether it's active on all sites or just selected ones, but probably it would be helpful to allow more fine-grained exclusions from this, e.g.

Allow on all sites by default, but exclude selected sites / pages matching any regexp in a list.
(This is kind of the opposite of the "enable per site" approach mentioned in #21.)
On selected sites / pages matching any regexp in another list, exclude page elements matching any item in a list of CSS selectors (or perhaps even XPath selectors)

Support labelling of OZ access roles

Address labelling is just the starting point. We can also label many other things, including OZ access roles

Allow switching extension off for the current tab

Should be able to restore the current page to its original state from a toggle switch in the popup menu.

When #16 is implemented, this single toggle switch will turn into one toggle per section.

This is separate from enabling/disabling the extension per site, as implemented in both #55 and Chrome's native site access controls.

Do a basic popup modal

After switching to react-vite in #32, we can now control exactly what the popup modal looks like when clicking on the extension icon. So we need to replace the boilerplate one.

For now this could have just two things:

a basic toggle on/off
a link to the options page

allow automatic importing of Rotki's private and/or global addressbooks

Depends on #16.

This is similar to the idea of importing from URLs detailed in #24, however it would specifically use Rotki's POST /api/(version)/names/addressbook endpoint to import the whole of the private and/or global addressbooks from Rotki's local backend.

The URL for the backend should presumably default to http://localhost:4242 but this should be configurable in case someone is running the Rotki backend on a non-default port.

The addressbooks can be viewed via the following commands when the Rotki backend is running (assuming ijq is installed for convenient inspection):

curl -X POST http://localhost:4242/api/1/names/addressbook/global | ijq
curl -X POST http://localhost:4242/api/1/names/addressbook/private | ijq

Make a logo image

This blocks #94.

Resources

switch to mui

Let's have things looking half decent for the first release, since first impressions count for a lot.

This will pave the way for #12.

add Control-s keyboard shortcut for saving options

Bard suggests:

 useEffect(() => {
    const handleKeyDown = (event) => {
      if (event.ctrlKey && event.key === 's') {
        yourCallbackFunction();
      }
    };

    window.addEventListener('keydown', handleKeyDown);
    return () => window.removeEventListener('keydown', handleKeyDown); // Cleanup on unmount
  }, []);

The cleanup seems overkill though.

fix cursor bug

Cursor gets moved left immediately after insertion of first character in any text input area. Extension shouldn't touch any empty text input area, maybe a bug in replacer? In any case, could check document.activeElement to skip the element where input (cursor) is active. Could also skip elements with contenteditable="true".

Support labelling of function selectors, event topics etc.

Address labelling is just the starting point. We can also label many other things, including EVM event topics.

See https://docs.openchain.xyz/ for an API for looking up function/event signatures.

expand options page

Need tabs or a responsive drawer component

See https://zenoo.github.io/mui-theme-creator/ for some nice ideas. Source code at https://github.com/Zenoo/mui-theme-creator/blob/master/src/components/PreviewWindow/PreviewWindow.tsx

Blocks #46.

Fix running out of storage

https://developer.chrome.com/docs/extensions/reference/storage/#property-sync

8k per item, 100k in total

Options

One item per line
Batches of lines
Use storage.local instead, but no syncing and would have to reimplement bits of https://github.com/fregante/webext-options-sync

disable Save button when addresses aren't changed

In the options page, it shouldn't be possible to click the Save button if nothing has changed.

Deal with duplicate addresses better

~~#217~~
~~Make precedence rules clear~~
Combine labels from duplicates (whilst deduplicating labels!)

Extract full address from HTML attributes, and cross-check with abbreviation

Sometimes there'll be a link like

<a href="https://polygonscan.com/address/0x2F800Db0fdb5223b3C3f354886d907A671414A7F">0x2F800D...414A7F</a>

where the text content is abbreviated but the full address is in the href URL. Currently rolod0x only looks at the text content inside the node, so it can only recognise a partial (abbreviated) match at best, resulting in (by default) the resulting substituted label being surrounded by question marks:

However because the href contains the full address, we can make rolod0x smarter in this case. We should cross-check the two addresses, and if they match, extract the full address from the URL rather than guessing the mapping from the text content.

Conversely, if they don't match, then loudly warn the user of an attempted address poisoning attack as per https://warpcast.com/lefteris.eth/0xd2f0f1ab. This is another reason why we need #81!

switch to React

It's not sustainable to develop long-term without a proper UI framework, so switch to https://github.com/Jonghakseo/chrome-extension-boilerplate-react-vite

look into incorporating fregante/webext-dynamic-content-scripts

Using https://github.com/fregante/webext-dynamic-content-scripts would allow us to ship the extension with a minimal set of hosts enabled (e.g. the block explorers) and then allow the user to enable it on any extra domain; this way we don't need to use a broad <all_urls> permission.

This is one potential solution to #21.

Allow labelling of unlabelled addresses via mouse-over

set badge showing count of addresses replaced

chrome.action.setBadgeText() is a nice easy way to show a count on the extension icon, so it can show how many addresses (or other things) have been replaced.

Support labelling of transactions

Address labelling is just the starting point. We can also label many other things, including transactions.

sort out licensing

Original fregante extension template is GPL v3. Not using this any longer; however I wish to keep GPL v3 anyway. The react-vite one switched to is MIT, which requires the MIT license notice to be kept, but allows sub-licensing. So current plan is to keep MIT license applying to original react-vite code, but release new rolod0x work under GPL v3, so that the extension is effectively under GPL v3.

This complexity might warrant use of https://github.com/fsfe/reuse-tool to clarify which license is applied where.

Operate on limited sites by default, but allowing expansion

Rather than defaulting to <all_urls>, which may cause the extension to get rejected by the Chrome Web Store anyway, if possible we should default to the usual block explorers etc. while ensuring that the user can also apply it to any other site they want.

This is kind of the opposite of the "exceptions per site" approach mentioned in #17.

See #31 for one promising solution to this.

write unit tests

Config parsing would be a good place to start.

Debounce MutationObserver

Since we are observing the whole page (frame, actually), and then recursing the entire DOM for replacement, this is very expensive. It's not yet clear how big of an impact this is on page performance, but we should probably make sure not to do it too regularly. One suggestion is item 10 of this SO answer:

If processing is complex and/or takes a lot of time, it may lead to very long paint frames, unresponsiveness/jank, so in this case you can use debounce or a similar technique e.g. accumulate mutations in an outer array and schedule a run via setTimeout / requestIdleCallback / requestAnimationFrame:
const queue = [];
const mo = new MutationObserver(mutations => {
  if (!queue.length) requestAnimationFrame(process);
  queue.push(mutations);
});
function process() {
  for (const mutations of queue) {
    // ..........
  }
  queue.length = 0;
}
Note that requestAnimationFrame fires only when the page is (or becomes) visible.

Allow deeper inspection of DOM node via right-click menu

For example, going to a block explorer, and doing a contract read which returns a list of addresses within a single HTML text element will not trigger normal rolod0x translation, because it would probably be too expensive to search within every single text element for matching substrings.

In this case, right-clicking on that node could offer an extra context menu item for deeper inspection of that HTML node by rolod0x.

Avoid `use client` warnings

Adding @mui/material/MenuList to Popup.tsx causes a load of warnings to start spewing on the console:

Module level directives cause errors when bundled, 'use client' was ignored.
Module level directives cause errors when bundled, 'use client' was ignored.
Module level directives cause errors when bundled, 'use client' was ignored.
Module level directives cause errors when bundled, 'use client' was ignored.
Module level directives cause errors when bundled, 'use client' was ignored.
Module level directives cause errors when bundled, 'use client' was ignored.
Module level directives cause errors when bundled, 'use client' was ignored.

This appears to be related to rollup/rollup#4699. (See also this explanation of the use client directive).

Even though this is only a warning and presumably harmless since we'll never use SSR, it's annoying and should be eliminated.

Make options screen less ugly

Add option for label format string

Rather than just replacing the address with the label string, it could be replaced by a string generated from a format string specified as a user option. For example, if the format string was %s | 0x%6l...%4r then the address would be replaced by something like my wallet address | 0x123456...1234.

Potential substitution characters

%s -> the whole label string
%Ns -> label string, limited to at most the first N characters
%Nl -> left-most N characters of the address (excluding the initial 0x, to allow the user to omit that if they want)
%Nr -> right-most N characters of the address

Allow URL source for address book sections

Once #16 is implemented to allow multiple sections to the address book, rather than requiring every section to be plain text pasted in, we should allow some sections to be retrieved via a URL.

This could allow retrieval from:

a web server allowing shared access to a single section, which could even be public, e.g. https://raw.githubusercontent.com/...
file:///... if the browser extension security model allows that.
Rotki's private and global addressbooks (tracked separately in #81)

This would open up many use cases and different models for storing and sharing address book data.

label zero-padded addresses

For example, those seen in topic2 and topic3 here:

https://polygonscan.com/address/0xdc1dfa22824af4e423a558bbb6c53a31c3c11dcc#events

Technically, labelling these is arguably incorrect since it's skipping a step of decoding, and pretends that there isn't any other data there when it might actually be an encoding of other values which all happen to be zero. But in practice, it shouldn't do any harm and is still helpful in a few corner cases even though block explorers tend to offer byte decoding for most situations these days anyway.

make options focus on textarea by default

When opening the options page, the textarea should be focused by default.

Publish to Chrome Web Store

https://developer.chrome.com/docs/webstore/publish/

See also #94 and #137 which block this, and #200 which is a nice-to-have.

Publish to Firefox extensions store

https://addons.mozilla.org/en-GB/developers/
https://extensionworkshop.com/documentation/manage/updating-your-extension/

We can do this once Firefox support is fully tested and working (see #19).

Allow choice of whether to sync

Browsers support automatic syncing of extension data between machines. We could use that to make it more convenient for users who use rolod0x on multiple machines.

For privacy reasons, this must be opt-in. We should also ensure that it is encrypted by a password before storage, so that Google etc. never have access to it.

The mechanism for using synced storage is very simple to use: https://github.com/fregante/webext-options-sync#storagetype

As this is implemented, docs/privacy-policy.md must also be updated.

allow different mappings per chain

Due to the way that contract addresses are calculated by the CREATE opcode, it's possible for the same contract address to be used across multiple chains for deployment of entirely different contract code and hence purposes.

Similarly, a user might choose to use an EoA on one chain for an entirely different purpose to how they use it on another chain.

Therefore, there is value in rolod0x optionally supporting different address -> name mappings per chain.

Unfortunately there is no general solution for determining the context of which chain is being referred to when an address is mentioned on a web page. However there are plenty of common use cases where it is easy to determine the chain simply from the URL, e.g. most block explorers have a unique DNS domain per chain like mumbai.polygonscan.com, and Gnosis Safe includes the network as a prefix of the URL's first path segment:

https://app.safe.global/eth:0x.../home
https://app.safe.global/matic:0x.../home

So we should add some intelligence which figures out the web page's chainId where possible, and then supports chain-specific mappings.

This would require a new optional chainId field per entry in the mapping, which in turn requires an extension to the existing text format. If the chainId for an entry is empty, then that address/label mapping applies across all chains. Perhaps a new YAML format is the better way to go here, e.g.

addresses:
- 0x424b294940C93043899D4fE381859085492d34e6
  - label: ToucanCrosschainMessenger proxy
    network: mumbai
  - label: CarbonOffsetBatches v1.3.0-5 impl
    network: alfajores

There could be a special network * or DEFAULT as a fallback, and if that's not present, it could fall back to joining all other labels together into a single string like ToucanCrosschainMessenger proxy (mumbai) / CarbonOffsetBatches v1.3.0-5 impl (alfajores).

UPDATE: recently remembered the existence of chainlists.org, and filed #244 for the task of producing a good JSON schema.

Also, https://chainid.network/chains.json looks very useful.