cardano-foundation/cf-adahandle-resolver

This project aims to provide a scoped indexer for retrieving ADA Handle information from the Cardano blockchain and exposing it via REST using Yaci Store

ADA Handle Resolver

This project aims to provide a scoped indexer for retrieving ADA Handle information from the Cardano blockchain and exposing it via REST using Yaci Store.

Why ADA Handle resolver?

One may ask why Ada Handle resolve if there is already: https://github.com/koralabs/handles-public-api

Ada Handler resolver by CF differentiates itself with a number of following traits:

• it demostrates usage of Yaci-Store modular indexer
• is written in Java, thus easier extendable and to easier to reason about by Java Developers
• doesn't have any dependencies to other components, e.g. Ogmios, blockfrost, etc
• handles db has very small on disk footprint
• supports embedded DBs such as H2 for easier deployment

🚀 Getting Started

🐳 Docker

docker run -p 9095:9095 cardanofoundation/adahandle-resolver:latest

🪶 Maven

Prerequisites

Java 17

Build & Run

git clone https://github.com/cardano-foundation/cf-adahandle-resolver.git
cd cf-adahandle-resolver
./mvnw clean package
java -jar target/cf-adahandle-resolver-0.0.1-SNAPSHOT.jar

🧪 Test Reports

To ensure the stability and reliability of this project, unit tests have been implemented. By clicking on the link below, you can access the detailed test report.

📊 Coverage Report

🤖 API Endpoints

Endpoint	Description
http://localhost:9095/swagger-ui.html	Swagger UI for the API endpoints
http://localhost:9095/api/v1/ada-handles/by-stake-address	[GET]s the ADA Handle held by a given stake address
http://localhost:9095/api/v1/ada-handles/by-payment-address	[GET]s the ADA Handle held by a given payment address
http://localhost:9095/api/v1/addresses/by-ada-handle/{adaHandle}	[GET]s the stake and payment addresses behind a provided ADA Handle
http://localhost:9095/api/v1/ada-handles/by-payment-address	[GET]s the payment address behind a provided ADA Handle

👻 Disable Indexer

If you intend to scale this service, running multiple instances of the API is advisable. However, you may not want a crawl job on every instance. To disable the indexer (yaci-store), utilize the disable-indexer profile as an environment variable.

SPRING_ACTIVE_PROFILES=disable-indexer java -jar target/cf-adahandle-resolver-0.0.1-SNAPSHOT.jar

🌱 Environment Variables

Possible profiles: mainnet, preprod, preview, local-node, h2, disable-indexer

Name	Description	Default Value
SPRING_ACTIVE_PROFILES	The active profile of the application	mainnet,h2
PORT	The port on which the server will listen for incoming requests	9095
DB_URL	The URL of the database	jdbc:h2:mem:mydb
DB_USERNAME	The username of the database user	sa
DB_PASSWORD	The password of the database user	password
REMOTE_NODE_URL	The URL of the remote node	relays-new.cardano-mainnet.iohk.io
REMOTE_NODE_PORT	The port of the remote node	3001
LOCAL_NODE_SOCKET_PATH	The path of the local node socket	<No default value>
LOCAL_NODE_HOST	The host of the local node	<No default value>
LOCAL_NODE_PORT	The port of the local node	<No default value>

cf-adahandle-resolver's Issues

[FEATURE] Improve scalability and allow instance to run api only w/o the "crawler"

Is your feature request related to a problem? Please describe.
When launching the resolver, both api and yaci-store cralwer run at the same time. It's not possible to run api only AND two crawlers can't run against the same db w/o risking corrupting it or creating contention.

Describe the solution you'd like
Introducing profile to either:

• disable crawler if desired default behaviour is to have it running
• enable crawler if desired default behaviour is to have it NOT running

Describe alternatives you've considered
N/A

Additional context
N/A

[BUG] Allow or Ignore the '$' Sign in the Handle Name

It is very common to use the $ sign in front of the handle. So both endpoints:

• /api/v1/addresses/by-ada-handle/the.glenlivet
• /api/v1/addresses/by-ada-handle/$the.glenlivet

should return the same address. But currently only the fist one is working while the other results in a 404.

[FEATURE] Support for Spring Boot Starter

It is possible to run this as microservice but it would be nice if a more monolithic approach would be supported where as one could include ada handle related repositories and controllers via including simply a Spring Boot Starter dependency.

I am not sure if it is possible to support both systems, but it could be since then the actual microservice would just use only adahandle spring boot starter as a library...

[BUG] Cip68 handles will not be fetched/stored correctly

To Reproduce
Steps to reproduce the behavior:

1. Go to beta.explorer.cardano.org
2. Try to resolve the handle using /api/v1/addresses/by-ada-handle/walkinwallet
3. It will give a 200 but without content

Expected behavior
It should response with the payment address and stake address

[FEATURE] Enhance response and include info about sync status

Is your feature request related to a problem? Please describe.
Currently, there is no way for ada-handle resolver to know how old is the data we're returning as response.
This is dangerous as adahandle resolution to stale data could lead to funds sent to wrong addresses.

Describe the solution you'd like
We should add extra information to the response that give a sense of how fresh the response is.
A possible solution is to add the current observed tip/slot within the resolver.

Describe alternatives you've considered

• error out is stale data (a bit extreme if you ask)
• instead of showing last slot, maybe just a status=synced|stale|drifted|whatever

Additional context

[FEATURE] Add payment address of handle to the address endpoint

Currently the api only offers a way to get the stake address by providing an ADA handle "/api/v1/addresses/by-ada-handle/{adaHandle}" but we also need a way to resolve the payment address, as the payment address is needed in context of sending assets from one handle user to the other.

"/api/v1/addresses/by-ada-handle/{adaHandle}" should therefore return:

{
    "stake_address": "stake1...",
    "payment_address": "addr1..."
}

The current behavior is that the stake address will be returned in plain text and if the user did not register its stake address, the payment address will be returned, which is confusing anyways.