fix(token): default role to app-provider so --instance alone resolves the endpoint (#307)

* fix(token): default role to app-provider so --instance alone resolves the endpoint

Endpoint auto-resolution already worked, but every layer defaulted the
role to app-user, so instance-only token commands resolved the app-user
participant instead of the provider. Make app-provider the single
canonical default across the token CLI flags, the shared resolvers
(token.ResolveLedgerEndpoint, localnet.ResolveLedgerEndpoint), the
roleOrDefault/opts.Role fallbacks, and the Web UI roleFromQuery so CLI
and UI stay at parity.

Add endpoint-optional tests: a token verb resolves its ledger endpoint
from --instance alone (default role) and from --instance + --role picks
that role's captured participant port, with --endpoint always optional.

* fix(token): address PR #307 review — UI default, Explorer isolation, endpoint visibility

- Align Tokens frontend DEFAULT_ROLE / tokenQuery omission with app-provider
- Restore shared localnet.ResolveLedgerEndpoint empty-role default to app-user (Explorer)
- Surface resolved host:port + role via resolveEndpoint stderr and activity JSON/UI
- Return ErrUnresolvedLedgerEndpoint from RunMint/RunBurn before instrument checks
- Document --role default change; expand mint/burn/accept/UI regression coverage

* fix(explorer): align empty-role default with shared app-provider resolver

Instead of isolating the token default, keep ResolveLedgerEndpoint at
app-provider and update Explorer CLI flags, Web handlers, and the
Explorer screen so omitting --role / ?role= cannot drift from the
shared resolver. DAR remains app-user.

* fix(dar): default role to app-provider across CLI, UI, and Wallet

Bring DAR list/inspect/upload empty-role fallback and the DAR/Wallet
screen pickers in line with the canonical app-provider default already
used by Tokens and Explorer. Update docs and mocks accordingly.

* fix(token): echo resolved endpoint/role in JSON+UI and pin every role default

Addresses the two open review findings on the endpoint-optional PR.

Finding "endpoint contract not universal": add a shared
api/types.ResolvedEndpoint (endpoint + role) and embed it in the
TokenListResponse, TokenHoldingsResponse, AllocationsResponse, and
PendingTransfersResponse bodies, then populate it at every surface:

  - CLI: token ls / balance / allocations / transfers now set the
    resolved host:port + role on the JSON envelope (activity already
    carried them).
  - Web UI: handleTokensList / handleTokenHoldings /
    handleAllocationsList / handlePendingTransfersList echo the same
    endpoint + role.

Mirror the new fields in frontend/src/api.ts and regenerate the
schema-shape golden (add-only; no SchemaVersion bump).

Finding "partial default coverage": expand
TestCLIRoleFlags_DefaultAppProvider from six builders to every token CLI
builder that carries a --role flag (allocate, allocations,
allocations withdraw/cancel, balance, balances, create, demo, faucet,
party new/ls, summary, transfers), so any verb regressing to app-user
fails loudly.

Add regression tests asserting the endpoint/role fields appear on the
Web UI list/holdings JSON (offline fallback + live endpoint) and the
CLI balance JSON, and update docs/changes-from-proposal.md to describe
the fields precisely.

Author: zheli

docs/changes-from-proposal.md

@@ -44,6 +44,11 @@ Every deviation listed here is **intentional**, not an oversight or implementati
   - [`burn` requires explicit confirmation](#burn-requires-explicit-confirmation)
   - [`--instance` required flag](#--instance-required-flag)
   - [`--name` collision in `token create`](#--name-collision-in-token-create)
+  - [`token ls` — list instruments (new)](#token-ls--list-instruments-new)
+  - [Ledger endpoint auto-resolves on every token verb](#ledger-endpoint-auto-resolves-on-every-token-verb)
+  - [`--role` defaults to `app-provider`](#--role-defaults-to-app-provider)
+  - [`token create` issuer defaults to the acting role's party](#token-create-issuer-defaults-to-the-acting-roles-party)
+  - [phantom `token settle` reference removed](#phantom-token-settle-reference-removed)
 - [`telemetry` (root-level, new)](#telemetry-root-level-new)
 
 ---
@@ -289,7 +294,7 @@ The embedded skill docs are the same artifacts that back the Web UI's Agent Skil
 
 **Proposal said:** DAR commands connect to participants via the named instance implicitly.
 
-**Shipped:** Each `dar` subcommand carries its own connection flags: `--admin-host`, `--token`, `--insecure` (defaults to `true`), `--ca-cert`, `--instance` (alias `--name`), `--role` (default `app-user`). There is no standalone `dar connect` command.
+**Shipped:** Each `dar` subcommand carries its own connection flags: `--admin-host`, `--token`, `--insecure` (defaults to `true`), `--ca-cert`, `--instance` (alias `--name`), `--role` (default `app-provider`). There is no standalone `dar connect` command.
 
 **Why:** Per-command connection flags make the DAR subcommands usable against any Ledger API endpoint, not just DevKit-managed instances. This gives operators more flexibility in CI and multi-environment workflows without requiring a running LocalNet registry.
 
@@ -406,12 +411,22 @@ The embedded skill docs are the same artifacts that back the Web UI's Agent Skil
 
 **Proposal said:** the token commands' connection details were unspecified beyond selecting an instance.
 
-**Shipped:** every `token` verb resolves the participant gRPC endpoint from the instance's captured ports when `--endpoint` is omitted — matching the Web UI, which never asks for an endpoint. `--endpoint` stays an explicit override; when no port is captured the command prints a remediation and exits non-zero rather than failing opaquely. `party ls` and `token ls` resolve best-effort (falling back to the registry-only list when offline).
+**Shipped:** every `token` verb resolves the participant gRPC endpoint from the instance's captured ports when `--endpoint` is omitted — matching the Web UI, which never asks for an endpoint. `--endpoint` stays an explicit override; when no port is captured the command prints a remediation and exits non-zero rather than failing opaquely. `party ls` and `token ls` resolve best-effort (falling back to the registry-only list when offline). Successful resolution announces the host:port and role — on CLI stderr for every verb, and as `endpoint`/`role` fields on the shared JSON/UI response bodies (`token ls`, `token balance`, `token allocations`, `token transfers`, `token activity` and their Web UI counterparts, via `api/types.ResolvedEndpoint`) — so operators can see which participant a verb dialed regardless of surface.
 
 **Why:** Requiring a hand-typed `--endpoint` on a command the Web UI runs endpoint-free breaks CLI ↔ Web UI parity and makes the common case (`token <verb> --instance foo`) unusable on a running LocalNet.
 
 ---
 
+### `--role` defaults to `app-provider`
+
+**Proposal said:** role selection was unspecified; early implementation defaulted `--role` / `?role=` to `app-user`.
+
+**Shipped:** every participant-scoped surface falls back to **`app-provider`** when role is omitted: token CLI/UI (`token.DefaultRole`, `roleFromQuery`, `tokenQuery`), Explorer (`internal/localnet.ResolveLedgerEndpoint`, `contracts` / `tx`, Web ACS/transactions handlers, Explorer screen), DAR (`dar --role`, Web DAR list/inspect/upload fallback, DAR screen), and the Wallet screen's role picker. Explicit `--role` / `?role=` / upload `roles` still win.
+
+**Why:** The provider participant is the mint/create operator on LocalNet. Defaulting to `app-user` made `--instance` alone resolve the wrong (often uncaptured) participant ledger port, so endpoint auto-resolution looked broken. Aligning every surface on `app-provider` restores instance-only usability and keeps CLI ↔ Web UI on the same participant.
+
+---
+
 ### `token create` issuer defaults to the acting role's party
 
 **Proposal said:** `token create` names an issuer but did not specify how a bare alias or role name resolves.

docs/explorer.md

@@ -38,10 +38,11 @@ The top-bar **Projecting through** widget controls two things:
    sticks to the URL's `?instance=` query parameter, so it
    survives navigating between tabs and reloading the page.
 2. **Role** — which Splice JWT to authenticate with. The choices
-   are `app-user`, `app-provider`, and `sv`. Each role is a
+   are `app-provider` (default), `app-user`, and `sv`. Each role is a
    different user in the participant's user management; the
    contracts you see are the ones that role's user has rights to
-   read.
+   read. The default matches the CLI (`contracts` / `tx --role`) and
+   the shared ledger-endpoint resolver.
 
 Switching either control re-runs the ACS snapshot. There is no
 client-side filtering across roles — you get a fresh view from the

docs/tokens.md

@@ -33,12 +33,14 @@ canton-devkit localnet up --name v2 --version 0.6.12
 canton-devkit localnet status --name v2
 ```
 
-All token subcommands take `--instance <name>` and, for on-ledger
-actions, `--endpoint <participant host:port>` (the participant ledger
-gRPC port — `localnet status --name v2` prints it). Where a `--token`
-flag exists it can stay empty — a per-role dev JWT is auto-issued
+All token subcommands take `--instance <name>`. For on-ledger actions,
+`--endpoint <participant host:port>` is optional: when omitted the
+command resolves the acting role's captured participant ledger gRPC
+port from the instance (the same port `localnet status --name v2`
+prints). An explicit `--endpoint` always wins. Where a `--token` flag
+exists it can stay empty — a per-role dev JWT is auto-issued
 (`mint`/`create`/`demo` always auto-issue); `--role` defaults to
-`app-user`.
+`app-provider` (the provider participant that mints/creates).
 
 ---
 

frontend/mock/router.ts

@@ -555,8 +555,8 @@ function handleTokensRoute(
       current_role?: string;
     };
     identity.instance = instance;
-    identity.available_roles = identity.available_roles ?? ["app-user", "app-provider", "sv"];
-    identity.current_role = url.searchParams.get("role") ?? identity.current_role ?? "app-user";
+    identity.available_roles = identity.available_roles ?? ["app-provider", "app-user", "sv"];
+    identity.current_role = url.searchParams.get("role") ?? identity.current_role ?? "app-provider";
     jsonResponse(res, 200, identity);
     return true;
   }

frontend/mock/seed-utils.ts

@@ -183,7 +183,7 @@ export function validateSchema(body: unknown): boolean {
 export function parseSeedArgs(argv: string[]): SeedOptions | { error: string } {
   let baseUrl = "http://127.0.0.1:7777";
   let instance = "";
-  let role = "app-user";
+  let role = "app-provider";
   let asName: string | undefined;
   let dryRun = false;
 
@@ -199,7 +199,7 @@ export function parseSeedArgs(argv: string[]): SeedOptions | { error: string } {
         error: [
           "Usage: npm run mock:seed -- --instance <name> [options]",
           "  --base-url URL   Backend base URL (default http://127.0.0.1:7777)",
-          "  --role ROLE      Role for scoped endpoints (default app-user)",
+          "  --role ROLE      Role for scoped endpoints (default app-provider)",
           "  --as NAME        Rewrite instance name in output (e.g. demo)",
           "  --dry-run        Print targets without writing files",
         ].join("\n"),

frontend/src/api.ts

@@ -711,9 +711,9 @@ export interface MetricsSummary {
 // ── DAR Manager ─────────────────────────────────────────
 //
 // The Web UI lists DARs uploaded to a participant. Role defaults
-// to app-user (the common dev target). The backend reads the
-// per-role admin port from state.json so the browser
-// doesn't need to know about gRPC.
+// to app-provider (same canonical default as Tokens / Explorer).
+// The backend reads the per-role admin port from state.json so the
+// browser doesn't need to know about gRPC.
 export type Role = "app-user" | "app-provider" | "sv";
 
 export interface DARRow {
@@ -734,7 +734,7 @@ export interface DARListResponse {
   dars: DARRow[];
 }
 
-export const fetchDARList = (name: string, role: Role = "app-user") =>
+export const fetchDARList = (name: string, role: Role = "app-provider") =>
   apiFetch<DARListResponse>(
     `/api/instances/${encodeURIComponent(name)}/dar?role=${role}`,
   );
@@ -859,7 +859,7 @@ export interface DARInspectResponse {
 export const fetchDARInspect = (
   instance: string,
   mainID: string,
-  role: Role = "app-user",
+  role: Role = "app-provider",
 ) =>
   apiFetch<DARInspectResponse>(
     `/api/instances/${encodeURIComponent(instance)}/dar/${encodeURIComponent(mainID)}/inspect?role=${role}`,
@@ -916,7 +916,7 @@ export const fetchDARDiff = (
   instance: string,
   a: string,
   b: string,
-  role: Role = "app-user",
+  role: Role = "app-provider",
 ) =>
   apiFetch<DARDiffResponse>(
     `/api/instances/${encodeURIComponent(instance)}/dar/diff?a=${encodeURIComponent(a)}&b=${encodeURIComponent(b)}&role=${role}`,
@@ -1021,7 +1021,7 @@ export interface ContractsListResponse {
 
 export const fetchContracts = (
   name: string,
-  role: Role = "app-user",
+  role: Role = "app-provider",
   limit = 100,
 ) =>
   apiFetch<ContractsListResponse>(
@@ -1057,7 +1057,7 @@ export interface ContractDetailResponse {
 export const fetchContractDetail = (
   name: string,
   contractId: string,
-  role: Role = "app-user",
+  role: Role = "app-provider",
 ) =>
   apiFetch<ContractDetailResponse>(
     `/api/instances/${encodeURIComponent(name)}/contracts/${encodeURIComponent(contractId)}?role=${role}`,
@@ -1094,7 +1094,7 @@ export interface ContractStreamEvent {
 // (strict-tail semantics — direct curl, smoke tests).
 export function openContractsStream(
   name: string,
-  role: Role = "app-user",
+  role: Role = "app-provider",
   since?: number,
 ): EventSource {
   const sinceParam =
@@ -1161,7 +1161,7 @@ export interface TransactionFilters {
 
 export const fetchTransactions = (
   name: string,
-  role: Role = "app-user",
+  role: Role = "app-provider",
   limit = 100,
   filters: TransactionFilters = {},
 ) => {
@@ -1216,7 +1216,7 @@ export interface TxReplayResponse {
 export const fetchTxReplay = (
   name: string,
   updateId: string,
-  role: Role = "app-user",
+  role: Role = "app-provider",
   parties?: string[],
 ) => {
   const params = new URLSearchParams({ role });
@@ -1601,11 +1601,21 @@ export interface TokenHolding {
 
 export interface TokensListResponse {
   schema_version: number;
+  // Endpoint contract: the participant host:port + role this list was
+  // resolved against ("" endpoint = recorded/offline fallback). Mirrors
+  // internal/api/types.ResolvedEndpoint.
+  endpoint: string;
+  role: string;
   tokens: TokenRef[];
 }
 
 export interface TokenHoldingsResponse {
   schema_version: number;
+  // Endpoint contract: the participant host:port + role this balance was
+  // read from ("" endpoint = registry pseudo-balance). Mirrors
+  // internal/api/types.ResolvedEndpoint.
+  endpoint: string;
+  role: string;
   // Response-level provenance (matches every row's source); the UI
   // renders one disclaimer banner when "registry".
   source: HoldingSource;
@@ -1700,11 +1710,13 @@ export interface BatchResult {
   ok: boolean;
 }
 
-// Matches the backend default in roleFromQuery — keep in sync.
-const DEFAULT_ROLE = "app-user";
+// Matches the backend token.DefaultRole / roleFromQuery — keep in sync.
+// Explorer and DAR callers below keep their own app-user defaults.
+const DEFAULT_ROLE = "app-provider";
 
 // tokenQuery builds `?instance=...&role=...` (role omitted when it just
 // repeats the default), so every token endpoint forwards role uniformly.
+// Selecting app-user must send role=app-user (no longer the omitted default).
 function tokenQuery(instance: string, role?: string): string {
   const params = new URLSearchParams({ instance });
   if (role && role !== DEFAULT_ROLE) params.set("role", role);
@@ -1807,13 +1819,13 @@ interface PartiesResponse {
 }
 
 // Lists the instance's registered party aliases.
-export const fetchParties = (instance: string, role = "app-user") =>
+export const fetchParties = (instance: string, role = "app-provider") =>
   apiFetch<PartiesResponse>(
     `/api/parties?instance=${encodeURIComponent(instance)}&role=${encodeURIComponent(role)}`,
   ).then((r) => r.parties);
 
 // Allocates a party under an alias and grants the role's user act/read-as.
-export const createParty = (instance: string, alias: string, role = "app-user") =>
+export const createParty = (instance: string, alias: string, role = "app-provider") =>
   apiFetch<PartyRef>(`/api/parties?instance=${encodeURIComponent(instance)}`, {
     method: "POST",
     headers: { "Content-Type": "application/json" },
@@ -1845,7 +1857,7 @@ interface HoldingContractsResponse {
 // TokenRef list (mapped to InstrumentRef) when the ledger is unreachable.
 export async function fetchInstruments(
   instance: string,
-  role = "app-user",
+  role = "app-provider",
 ): Promise<InstrumentRef[]> {
   const r = await apiFetch<InstrumentsResponse>(
     `/api/tokens?instance=${encodeURIComponent(instance)}&role=${encodeURIComponent(role)}`,
@@ -1864,7 +1876,7 @@ export async function fetchInstruments(
   }));
 }
 
-export const fetchMatrix = (instance: string, role = "app-user") =>
+export const fetchMatrix = (instance: string, role = "app-provider") =>
   apiFetch<MatrixResponse>(
     `/api/tokens/matrix?instance=${encodeURIComponent(instance)}&role=${encodeURIComponent(role)}`,
   ).then((r) => r.matrix);
@@ -1899,7 +1911,7 @@ interface InstrumentSummaryResponse {
 export const fetchInstrumentSummary = (
   instance: string,
   symbol: string,
-  role = "app-user",
+  role = "app-provider",
 ) =>
   apiFetch<InstrumentSummaryResponse>(
     `/api/tokens/${encodeURIComponent(symbol)}/summary?instance=${encodeURIComponent(
@@ -1948,7 +1960,7 @@ export interface ActivityPage {
 export const fetchActivity = (
   instance: string,
   symbol: string,
-  role = "app-user",
+  role = "app-provider",
   limit = 50,
 ): Promise<ActivityPage> =>
   apiFetch<ActivityResponse>(
@@ -1961,7 +1973,7 @@ export const fetchHoldingContracts = (
   instance: string,
   symbol: string,
   party: string,
-  role = "app-user",
+  role = "app-provider",
 ) => {
   const params = new URLSearchParams({
     instance,
@@ -2126,7 +2138,7 @@ export async function planTransfer(
   symbol: string,
   from: string,
   amount: string,
-  role = "app-user",
+  role = "app-provider",
 ): Promise<TransferPlan> {
   const params = new URLSearchParams({ instance, role, plan: "1" });
   const resp = await fetch(
@@ -2177,6 +2189,10 @@ export const acceptTransfer = (
 
 interface AllocationsListResponse {
   schema_version: number;
+  // Endpoint contract: participant host:port + role this scan resolved
+  // against. Mirrors internal/api/types.ResolvedEndpoint.
+  endpoint: string;
+  role: string;
   allocations: AllocationSummary[];
   aliases: AliasMap;
 }
@@ -2199,6 +2215,10 @@ export async function fetchAllocations(
 
 interface PendingTransfersListResponse {
   schema_version: number;
+  // Endpoint contract: participant host:port + role this scan resolved
+  // against. Mirrors internal/api/types.ResolvedEndpoint.
+  endpoint: string;
+  role: string;
   pending_transfers: TransferSummary[];
   truncated?: boolean;
   aliases: AliasMap;

frontend/src/screens/DARScreen.test.tsx

@@ -132,7 +132,7 @@ function withProviders(ui: React.ReactElement) {
 const fakeDAR = {
   schema_version: 1,
   instance: "demo",
-  role: "app-user",
+  role: "app-provider",
   dars: [
     { main: "a".repeat(64), name: "demo-pkg", version: "1.0.0" },
     { main: "b".repeat(64), name: "other-pkg", version: "0.1.0" },

frontend/src/screens/DARScreen.tsx

@@ -36,7 +36,9 @@ import { DARDiff } from "./DARDiff";
 // right detail rail that only exists once a package is selected.
 // Vetting is live per-participant end-to-end.
 
-const ROLES: Role[] = ["app-user", "app-provider", "sv"];
+// Default (app-provider) first — matches CLI dar --role and handler
+// empty-role fallback.
+const ROLES: Role[] = ["app-provider", "app-user", "sv"];
 
 // Package table column template — shared by the header band and rows.
 const COLS = "1.6fr 0.55fr 1.1fr 1.15fr";
@@ -60,7 +62,7 @@ type UploadState =
 export function DARScreen() {
   const sel = useInstanceSelection();
   const name = sel.selected;
-  const [role, setRole] = useState<Role>("app-user");
+  const [role, setRole] = useState<Role>("app-provider");
   // Participants an upload fans out to (parallel, backend-side).
   // Orthogonal to `role`, which drives only the package LIST.
   const [vetTargets, setVetTargets] = useState<Record<Role, boolean>>({

frontend/src/screens/ExplorerScreen.test.tsx

@@ -78,7 +78,7 @@ function stubFetch(contracts: unknown[] = []) {
         return json({
           schema_version: 1,
           instance: "demo",
-          role: "app-user",
+          role: "app-provider",
           ledger_end: 30,
           count: TX_ROWS.length,
           scanned_from: 0,
@@ -90,7 +90,7 @@ function stubFetch(contracts: unknown[] = []) {
         return json({
           schema_version: 1,
           instance: "demo",
-          role: "app-user",
+          role: "app-provider",
           ledger_end: 30,
           contracts,
         });
@@ -122,6 +122,27 @@ describe("ExplorerScreen — transactions filters + replay", () => {
     vi.restoreAllMocks();
   });
 
+  it("defaults the Explorer role to app-provider", async () => {
+    stubFetch();
+    render(
+      <Providers>
+        <ExplorerScreen />
+      </Providers>,
+    );
+    const fetchMock = global.fetch as unknown as ReturnType<typeof vi.fn>;
+    await waitFor(() => {
+      const contractsCall = fetchMock.mock.calls
+        .map(([u]) => String(u))
+        .find((u) => u.includes("/contracts?") || u.includes("/contracts&"));
+      // Snapshot fetch uses /contracts?role=...&limit=...
+      const snap = fetchMock.mock.calls
+        .map(([u]) => String(u))
+        .find((u) => u.includes("/contracts") && u.includes("role="));
+      expect(snap ?? contractsCall).toBeTruthy();
+      expect(snap ?? contractsCall).toContain("role=app-provider");
+    });
+  });
+
   it("forwards party / template / offset filters to the transactions endpoint (#24)", async () => {
     stubFetch();
     await gotoTransactions();