cardano-foundation / cardano-foundation/cardano-rosetta-java

3.`/account/balance` and `/account/coins` - CIP-113 support

Open
#771 0 comments 0 reactions 0 assignees View on GitHub
cip-113
Dominant language
Java
Stars
26
Forks
15
Avg merge
5d 3h
Merged PRs (30d)
2

Description

### Background

CIP-113 smart wallet addresses are valid Cardano base addresses (just with a script hash as
the payment credential). The indexer already tracks UTxOs by address. So for the read
endpoints (`/account/balance`, `/account/coins`), **no new chain query logic is needed** —
the address is passed through to the existing query pipeline unchanged.

The main work is ensuring these endpoints do NOT reject smart wallet addresses as "invalid"
(since they have a script payment credential, some validation paths may reject them) and
that the response format is correct.

### Expected Behavior

**`/account/balance` with smart wallet address:**

```json
// REQUEST
{
"network_identifier": { "blockchain": "cardano", "network": "preprod" },
"account_identifier": {
"address": "addr_test1zreps2cq5daaw3hzq46untcp4vcnzgsn29xdx8589c9z50ntcrahhulmvvsnmwqk2k3nmrz20sw8uj7htlpnlutk0p9sc0k4pa"
}
}

// RESPONSE
{
"block_identifier": { "index": 2847593, "hash": "87a3c2b1..." },
"balances": [
{
"value": "5000000",
"currency": { "symbol": "ADA", "decimals": 6 }
},
{
"value": "1000000",
"currency": {
"symbol": "5553444d",
"decimals": 6,
"metadata": { "policyId": "ce1ed5614e501ca21c08421523e81a2cae9e8aeff93e07cad6df0334" }
}
}
]
}
```

The response format is identical to existing `/account/balance` — no changes needed to
response schema. Smart wallet addresses should just be accepted.

**`/account/coins` with smart wallet address:**

Same address-pass-through behavior. Response format matches existing `/account/coins` with
`tokenBundle` metadata per coin. No schema changes.

**Historical balance** (with `block_identifier`) also works identically — same query, just
point-in-time.

### Acceptance Criteria

- [ ] `POST /account/balance` accepts a CIP-113 smart wallet address and returns ADA + PLT (Programmable token aka cip-113 supported tokens) balances
- [ ] `POST /account/balance` with a historical `block_identifier` works for smart wallet addresses
- [ ] `POST /account/coins` returns all UTxOs (including PLT UTxOs) at the smart wallet address
- [ ] Response format matches existing token bundle format — no new fields added
- [ ] Invalid addresses still rejected (existing behavior preserved)
- [ ] Enterprise/base address queries unaffected (regression check)

### Test Cases

**`/account/balance` tests (`AccountBalanceControllerTest`)**

- A smart wallet address with ADA and no PLT returns just the ADA balance
- A smart wallet address holding a PLT token returns both ADA and PLT balance entries
- A historical query at a specific block height returns balances as of that block
- A smart wallet with no UTxOs returns zero ADA balance with no other entries
- The smart wallet address passes the existing `verifyAddress()` validation (addr_test1z... is accepted)
- An uppercase/wrong-casing smart wallet address returns error 4039 (same casing check as all addresses)
- The PLT currency symbol in the response is the hex-encoded asset name, not a human-readable string
- A currency filter for ADA only does not include PLT in the response
- A currency filter specifying the PLT policy ID returns only PLT balance

**`/account/coins` tests (`AccountCoinsControllerTest`)**

- A smart wallet address returns UTxOs containing ADA
- A smart wallet address returns UTxOs containing PLT tokens
- Each coin identifier follows the `txHash:outputIndex` format
- The `metadata` field of each coin contains `policyId` and `tokens` for native assets
- A collateral return UTxO from a failed transaction appears in the coins response (it is spendable)
- A UTxO containing both ADA and PLT appears once in the list, not once per asset

Contributor guide

No contributing guide indexed for this repository

Research direction

Start with the AccountBalanceControllerTest and AccountCoinsControllerTest cases named in the issue, then trace the existing verifyAddress() validation and read-endpoint query paths. Done means CIP-113 smart wallet addresses pass validation, return the specified ADA and PLT balances or UTxOs—including historical and filtered queries—while invalid, enterprise, and base-address behavior remains unchanged.

Written by the indexing model from the issue text.

Assessment

Tech stack
java
Domain
api, blockchain
Issue type
Feature
Difficulty
3/5
Estimated time
1-2 days
Activity status
Quiet
Clarity
Clearly specified
Newbie friendliness
70/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.