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

2. `/call` — `resolve_smart_wallet_addr` Method - CIP-113

Open
#769 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

Add the Cardano-specific `/call` method `resolve_smart_wallet_addr`. It converts a supported Cardano address into the Phase 1 CIP-113 smart-wallet address for the Rosetta instance's configured programmable logic base (PLB). The response is deterministic and idempotent for a smart-wallet address that already uses that PLB.

### Phase 1 scope and network model

- The Rosetta instance has exactly one explicitly configured 28-byte PLB script hash (`CIP113_BASE_SCRIPT_HASH`). The value is used directly; it is not padded or hashed again.
- Missing configuration returns existing error `5063`; malformed configuration returns existing error `5064`.
- The method does not discover deployments, query the registry, select protocol versions, determine whether an asset is programmable, or validate CIP-113 transaction semantics.
- The request address must belong to the requested Rosetta network. A network mismatch returns `5068`.
- The examples below use the CIP-0113 Preview PLB `f2182b00a37bd746e20575c9af01ab31312213514cd31e872e0a2a3e` and `network: "preview"`. No Preprod deployment is implied.

### Supported inputs and credential selection

Input | User credential selected | Result
-- | -- | --
Enterprise address with key payment credential | payment key hash | base address with configured PLB script payment credential and selected key stake credential
Base address with key payment and key stake credentials | stake key hash | base address with configured PLB script payment credential and selected key stake credential
Base address with script payment credential equal to configured PLB and key stake credential | stake key hash | the same address (idempotent)
Base address with script payment credential different from configured PLB | — | `5065`
Enterprise address with script payment credential, including PLB | — | `5065`
Base address without a key stake credential | — | `5066`
Pointer, reward/stake, Byron, missing-credential, and unknown address forms | — | `5066`
Malformed Shelley address, unknown era, or requested-network mismatch | — | `5068`

The enterprise payment key and a base address's stake key are normally different HD credentials. The method does not promise that arbitrary enterprise and base addresses belonging to one wallet resolve to the same smart wallet.

### Request and response

`parameters.address` is required and must be a non-empty string. Missing, empty, or non-string values return existing error `5051`.

The response uses the generic Rosetta `CallResponse` shape:

```json
{
"result": {
"account_identifier": {
"address": "addr_test1..."
}
},
"idempotent": true
}
```

### Independently generated Preview vectors

These addresses were assembled from the stated header and credential bytes and Bech32-encoded with a separate checksum implementation. They are not copied from a running Rosetta response.

- Payment key hash: `000102030405060708090a0b0c0d0e0f101112131415161718191a1b`
- Stake key hash: `404142434445464748494a4b4c4d4e4f505152535455565758595a5b`
- Configured PLB: `f2182b00a37bd746e20575c9af01ab31312213514cd31e872e0a2a3e`

Enterprise key input:

```text
addr_test1vqqqzqsrqszsvpcgpy9qkrqdpc83qygjzv2p29shrqv35xcftcpvd
```

Expected resolution:

```text
addr_test1zreps2cq5daaw3hzq46untcp4vcnzgsn29xdx8589c9z50sqqypqxpq9qcrsszg2pvxq6rs0zqg3yyc5z5tpwxqergdszf7mzq
```

Base key/key input:

```text
addr_test1qqqqzqsrqszsvpcgpy9qkrqdpc83qygjzv2p29shrqv35x6qg9pyx3z9ger5sj22fdxy6nj02pg4y56524t9wkzetfdsu7rwxr
```

Expected resolution, and idempotent smart-wallet input/output:

```text
addr_test1zreps2cq5daaw3hzq46untcp4vcnzgsn29xdx8589c9z50jqg9pyx3z9ger5sj22fdxy6nj02pg4y56524t9wkzetfdsk5pff8
```

Checksum-valid unsupported examples:

- Enterprise script: `addr_test1wpsxzcnrv3jkvemgd94xkmrddehhqutjwd682anh0puh57c4ddgvp` → `5065`
- Reward key: `stake_test1upqyzsjrg3z5v36gf99yknzdfe84q52j2d2924jhtpv45kcuwdwec` → `5066`

### Errors

- `5051 CALL_PARAMETER_MISSING` for a missing, empty, or non-string `parameters.address`.
- `5063 CIP113_PLB_SCRIPT_HASH_NOT_CONFIGURED` for missing configuration.
- `5064 CIP113_PLB_SCRIPT_HASH_INVALID` for a configured value that is not exactly 28 bytes of hexadecimal.
- `5065 CIP113_ADDRESS_NOT_SMART_WALLET` for a script payment address outside the supported configured-PLB smart-wallet form.
- `5066 CIP113_ADDRESS_TYPE_NOT_SUPPORTED` for a valid but unsupported address/credential form.
- `5068 CIP113_INVALID_ADDRESS` for malformed, unknown-era, or wrong-network addresses.

All errors are non-retriable and include diagnostic detail where applicable. Code `5067` is intentionally unused.

### Acceptance criteria

- [ ] Dispatch `resolve_smart_wallet_addr` through `/call`.
- [ ] Advertise `resolve_smart_wallet_addr` in `getSupportedMethods()` and `/network/options`.
- [ ] Follow the validation and credential-selection rules above without allowing `NoSuchElementException` or generic runtime failures to escape.
- [ ] Return `result.account_identifier.address` and `idempotent: true`.
- [ ] Preserve the existing derive behavior while sharing PLB configuration validation and smart-wallet address assembly.
- [ ] Document the method, parameters, and generic result in `api.yaml`.
- [ ] Add the three new non-retriable errors to the advertised error set.

### Delivery note

Issue #770 is implemented automatically by adding the third supported call method, but remains open until the separate behavioral testing iteration validates the `/network/options` result and other endpoint behavior. Production-code completion here does not claim production readiness.

Contributor guide

No contributing guide indexed for this repository

Research direction

Start with the existing /call dispatch, getSupportedMethods(), /network/options, and derive behavior, then trace how shared PLB configuration and advertised errors are defined. Add the resolve_smart_wallet_addr request and generic CallResponse behavior, update api.yaml and advertised methods/errors, and verify the listed validation, address-resolution, idempotence, and non-retriable error criteria.

Written by the indexing model from the issue text.

Assessment

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.