Govern roles, admin, upgrades and wind-downs from the console

app-lib/readContract.test.ts

@@ -1,4 +1,4 @@
-import { nativeToScVal, xdr } from "@stellar/stellar-sdk"
+import { Address, nativeToScVal, xdr } from "@stellar/stellar-sdk"
 import type { Api } from "@stellar/stellar-sdk/rpc"
 import { beforeEach, describe, expect, it, vi } from "vitest"
 import type { DepositRequest, EpochInfo, RedeemRequest } from "./contracts"
@@ -8,6 +8,7 @@ import {
 	readEpochs,
 	readEvents,
 	readLedgerTime,
+	readPendingAdmins,
 } from "./readContract"
 
 const {
@@ -645,3 +646,169 @@ describe("readEvents", () => {
 		expect(read).toEqual({ kind: "unreadable" })
 	})
 })
+
+const ORACLE_ID = "CABQGAYDAMBQGAYDAMBQGAYDAMBQGAYDAMBQGAYDAMBQGAYDAMBQGCK3"
+const PENDING = "GDPO5SQDJY4E2XEE47MAOT2M2F3GR4H2AYYKSMIOT2YPOHAMC36VKWIA"
+
+const pendingAdminKey = (contractId: string): xdr.LedgerKey =>
+	xdr.LedgerKey.contractData(
+		new xdr.LedgerKeyContractData({
+			contract: Address.fromString(contractId).toScAddress(),
+			key: xdr.ScVal.scvVec([xdr.ScVal.scvSymbol("PendingAdmin")]),
+			durability: xdr.ContractDataDurability.temporary(),
+		}),
+	)
+
+const pendingEntry = (
+	contractId: string,
+	liveUntilLedger: number,
+	ttl = liveUntilLedger,
+): Api.LedgerEntryResult =>
+	entryFor(
+		pendingAdminKey(contractId).toXDR("base64"),
+		structScVal({
+			address: Address.fromString(PENDING).toScVal(),
+			live_until_ledger: xdr.ScVal.scvU32(liveUntilLedger),
+		}),
+		ttl,
+	)
+
+const archivalKey = xdr.LedgerKey.configSetting(
+	new xdr.LedgerKeyConfigSetting({
+		configSettingId: xdr.ConfigSettingId.configSettingStateArchival(),
+	}),
+)
+
+const archivalEntry = (maxEntryTtl: number): Api.LedgerEntryResult => ({
+	key: archivalKey,
+	val: xdr.LedgerEntryData.configSetting(
+		xdr.ConfigSettingEntry.configSettingStateArchival(
+			new xdr.StateArchivalSettings({
+				maxEntryTtl,
+				minTemporaryTtl: 16,
+				minPersistentTtl: 4096,
+				persistentRentRateDenominator: xdr.Int64.fromString("1"),
+				tempRentRateDenominator: xdr.Int64.fromString("1"),
+				maxEntriesToArchive: 0,
+				liveSorobanStateSizeWindowSampleSize: 0,
+				liveSorobanStateSizeWindowSamplePeriod: 0,
+				evictionScanSize: 0,
+				startingEvictionScanLevel: 0,
+			}),
+		),
+	),
+})
+
+describe("readPendingAdmins", () => {
+	beforeEach(() => {
+		getLedgerEntriesMock.mockReset()
+		getLatestLedgerMock.mockReset()
+		getLatestLedgerMock.mockResolvedValue({
+			sequence: 1_000,
+			closeTime: "1700000000",
+		})
+	})
+
+	it("asks for each contract's temporary PendingAdmin entry and the archival limits", async () => {
+		getLedgerEntriesMock.mockResolvedValue({ entries: [] })
+
+		await readPendingAdmins([CONTRACT_ID, ORACLE_ID])
+
+		const sent = (getLedgerEntriesMock.mock.calls[0] as xdr.LedgerKey[]).map(
+			(key) => key.toXDR("base64"),
+		)
+		expect(sent).toEqual([
+			pendingAdminKey(CONTRACT_ID).toXDR("base64"),
+			pendingAdminKey(ORACLE_ID).toXDR("base64"),
+			archivalKey.toXDR("base64"),
+		])
+	})
+
+	it("decodes a live transfer with the ledger it was read at and the furthest allowed expiry", async () => {
+		getLedgerEntriesMock.mockResolvedValue({
+			entries: [pendingEntry(CONTRACT_ID, 1_500), archivalEntry(100_000)],
+		})
+
+		const read = await readPendingAdmins([CONTRACT_ID, ORACLE_ID])
+
+		expect(read).toEqual({
+			kind: "value",
+			value: {
+				ledger: {
+					sequence: 1_000,
+					closeTime: 1_700_000_000n,
+					maxLiveUntil: 100_999,
+				},
+				pending: new Map([
+					[
+						CONTRACT_ID,
+						{ address: PENDING, liveUntilLedger: 1_500, expired: false },
+					],
+					[ORACLE_ID, null],
+				]),
+			},
+		})
+	})
+
+	it("reads a transfer past its live_until_ledger as expired while the entry lingers", async () => {
+		getLedgerEntriesMock.mockResolvedValue({
+			entries: [pendingEntry(CONTRACT_ID, 900, 1_200)],
+		})
+
+		const read = await readPendingAdmins([CONTRACT_ID])
+
+		expect(
+			read.kind === "value" && read.value.pending.get(CONTRACT_ID),
+		).toEqual({ address: PENDING, liveUntilLedger: 900, expired: true })
+		expect(read.kind === "value" && read.value.ledger.maxLiveUntil).toBeNull()
+	})
+
+	it("reads an entry whose TTL lapsed as no transfer", async () => {
+		getLedgerEntriesMock.mockResolvedValue({
+			entries: [pendingEntry(CONTRACT_ID, 900)],
+		})
+
+		const read = await readPendingAdmins([CONTRACT_ID])
+
+		expect(read.kind === "value" && read.value.pending.get(CONTRACT_ID)).toBe(
+			null,
+		)
+	})
+
+	it.each([
+		["a value that is not a transfer", xdr.ScVal.scvU32(7)],
+		[
+			"a transfer without an address",
+			structScVal({ live_until_ledger: xdr.ScVal.scvU32(1_500) }),
+		],
+		[
+			"a transfer with a non-numeric expiry",
+			structScVal({
+				address: Address.fromString(PENDING).toScVal(),
+				live_until_ledger: xdr.ScVal.scvString("later"),
+			}),
+		],
+	])("is unreadable when the entry holds %s", async (_, val) => {
+		getLedgerEntriesMock.mockResolvedValue({
+			entries: [
+				entryFor(pendingAdminKey(CONTRACT_ID).toXDR("base64"), val, 1_500),
+			],
+		})
+
+		expect(await readPendingAdmins([CONTRACT_ID])).toEqual({
+			kind: "unreadable",
+		})
+	})
+
+	it.each([
+		["the entries", () => getLedgerEntriesMock.mockRejectedValue(new Error())],
+		["the ledger", () => getLatestLedgerMock.mockRejectedValue(new Error())],
+	])("is unreadable when %s cannot be read", async (_, fail) => {
+		getLedgerEntriesMock.mockResolvedValue({ entries: [] })
+		fail()
+
+		expect(await readPendingAdmins([CONTRACT_ID])).toEqual({
+			kind: "unreadable",
+		})
+	})
+})

app-lib/readContract.ts

@@ -71,13 +71,10 @@ const userRequestDataKey = (
 const contractDataLedgerKey = (
 	contract: xdr.ScAddress,
 	key: xdr.ScVal,
+	durability = xdr.ContractDataDurability.persistent(),
 ): xdr.LedgerKey =>
 	xdr.LedgerKey.contractData(
-		new xdr.LedgerKeyContractData({
-			contract,
-			key,
-			durability: xdr.ContractDataDurability.persistent(),
-		}),
+		new xdr.LedgerKeyContractData({ contract, key, durability }),
 	)
 
 type EpochKeySet = {
@@ -274,6 +271,115 @@ export async function readLedgerTime(): Promise<bigint | null> {
 	}
 }
 
+export type PendingTransfer = {
+	address: string
+	liveUntilLedger: number
+	expired: boolean
+}
+
+export type LedgerWindow = {
+	sequence: number
+	closeTime: bigint
+	maxLiveUntil: number | null
+}
+
+export type PendingAdmins = {
+	ledger: LedgerWindow
+	pending: Map<string, PendingTransfer | null>
+}
+
+const pendingAdminKey = (contractId: string): xdr.LedgerKey =>
+	contractDataLedgerKey(
+		Address.fromString(contractId).toScAddress(),
+		xdr.ScVal.scvVec([xdr.ScVal.scvSymbol("PendingAdmin")]),
+		xdr.ContractDataDurability.temporary(),
+	)
+
+const archivalSettingsKey = (): xdr.LedgerKey =>
+	xdr.LedgerKey.configSetting(
+		new xdr.LedgerKeyConfigSetting({
+			configSettingId: xdr.ConfigSettingId.configSettingStateArchival(),
+		}),
+	)
+
+const isPendingTransfer = (
+	value: unknown,
+): value is { address: string; live_until_ledger: number } =>
+	typeof value === "object" &&
+	value !== null &&
+	"address" in value &&
+	typeof value.address === "string" &&
+	"live_until_ledger" in value &&
+	typeof value.live_until_ledger === "number"
+
+const decodePendingTransfer =
+	(sequence: number) =>
+	(val: xdr.ScVal): PendingTransfer => {
+		const native: unknown = scValToNative(val)
+		if (!isPendingTransfer(native)) throw new Error("malformed pending admin")
+		return {
+			address: native.address,
+			liveUntilLedger: native.live_until_ledger,
+			expired: sequence > native.live_until_ledger,
+		}
+	}
+
+const maxLiveUntil = (
+	settings: Api.LedgerEntryResult | undefined,
+	sequence: number,
+): number | null =>
+	settings === undefined
+		? null
+		: sequence +
+			settings.val.configSetting().stateArchivalSettings().maxEntryTtl() -
+			1
+
+export async function readPendingAdmins(
+	contractIds: string[],
+): Promise<ContractRead<PendingAdmins>> {
+	const keyed = contractIds.map((contractId) => ({
+		contractId,
+		key: pendingAdminKey(contractId),
+	}))
+	const archival = archivalSettingsKey()
+	try {
+		const [latest, fetched] = await Promise.all([
+			server.getLatestLedger(),
+			fetchChunk([...keyed.map(({ key }) => key), archival]),
+		])
+		if (!fetched.ok) return { kind: "unreadable" }
+		const { sequence } = latest
+		const pending = new Map<string, PendingTransfer | null>()
+		for (const { contractId, key } of keyed) {
+			const read = decodeLedgerEntry(
+				fetched,
+				key,
+				decodePendingTransfer(sequence),
+				sequence,
+			)
+			if (read.kind !== "value" && read.kind !== "archived")
+				return { kind: "unreadable" }
+			pending.set(contractId, read.kind === "value" ? read.value : null)
+		}
+		return {
+			kind: "value",
+			value: {
+				ledger: {
+					sequence,
+					closeTime: BigInt(latest.closeTime),
+					maxLiveUntil: maxLiveUntil(
+						fetched.byKey.get(archival.toXDR("base64")),
+						sequence,
+					),
+				},
+				pending,
+			},
+		}
+	} catch {
+		return { kind: "unreadable" }
+	}
+}
+
 export type EventSelection = { contractId: string; names: string[] }
 
 export type ChainEvent = {

app/src/App.test.tsx

@@ -42,6 +42,21 @@ const disconnectedAuthority: AdminAuthority = {
 	grants: [],
 	signersUnknown: false,
 	addresses: { oracle: null, shareToken: null, identityVerifier: null },
+	holders: {
+		"vault governance": [],
+		"vault manager": [],
+		"vault treasury": [],
+		"vault guardian": [],
+		"oracle attester": [],
+		"oracle guardian": [],
+		"oracle admin": [],
+		"share-token compliance": [],
+		"share-token manager": [],
+		"share-token admin": [],
+		"vault pending admin": [],
+		"oracle pending admin": [],
+		"share-token pending admin": [],
+	},
 }
 
 const renderAt = (path: string) => {