mppx 0.3.2 → 0.3.4

package/src/Expires.test.ts

@@ -0,0 +1,111 @@
+import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest'
+import * as Expires from './Expires.js'
+
+const FIXED_NOW = new Date('2025-06-15T12:00:00.000Z').getTime()
+
+beforeEach(() => {
+  vi.useFakeTimers()
+  vi.setSystemTime(FIXED_NOW)
+})
+
+afterEach(() => {
+  vi.useRealTimers()
+})
+
+describe('seconds', () => {
+  test('returns ISO string n seconds from now', () => {
+    expect(Expires.seconds(30)).toBe('2025-06-15T12:00:30.000Z')
+  })
+
+  test('0 returns current time', () => {
+    expect(Expires.seconds(0)).toBe('2025-06-15T12:00:00.000Z')
+  })
+
+  test('negative n returns past time', () => {
+    expect(Expires.seconds(-60)).toBe('2025-06-15T11:59:00.000Z')
+  })
+})
+
+describe('minutes', () => {
+  test('returns ISO string n minutes from now', () => {
+    expect(Expires.minutes(5)).toBe('2025-06-15T12:05:00.000Z')
+  })
+
+  test('0 returns current time', () => {
+    expect(Expires.minutes(0)).toBe('2025-06-15T12:00:00.000Z')
+  })
+
+  test('negative n returns past time', () => {
+    expect(Expires.minutes(-10)).toBe('2025-06-15T11:50:00.000Z')
+  })
+})
+
+describe('hours', () => {
+  test('returns ISO string n hours from now', () => {
+    expect(Expires.hours(2)).toBe('2025-06-15T14:00:00.000Z')
+  })
+
+  test('0 returns current time', () => {
+    expect(Expires.hours(0)).toBe('2025-06-15T12:00:00.000Z')
+  })
+
+  test('negative n returns past time', () => {
+    expect(Expires.hours(-3)).toBe('2025-06-15T09:00:00.000Z')
+  })
+})
+
+describe('days', () => {
+  test('returns ISO string n days from now', () => {
+    expect(Expires.days(1)).toBe('2025-06-16T12:00:00.000Z')
+  })
+
+  test('0 returns current time', () => {
+    expect(Expires.days(0)).toBe('2025-06-15T12:00:00.000Z')
+  })
+
+  test('negative n returns past time', () => {
+    expect(Expires.days(-2)).toBe('2025-06-13T12:00:00.000Z')
+  })
+})
+
+describe('weeks', () => {
+  test('returns ISO string n weeks from now', () => {
+    expect(Expires.weeks(1)).toBe('2025-06-22T12:00:00.000Z')
+  })
+
+  test('0 returns current time', () => {
+    expect(Expires.weeks(0)).toBe('2025-06-15T12:00:00.000Z')
+  })
+
+  test('negative n returns past time', () => {
+    expect(Expires.weeks(-1)).toBe('2025-06-08T12:00:00.000Z')
+  })
+})
+
+describe('months', () => {
+  test('returns ISO string n months (30 days) from now', () => {
+    expect(Expires.months(1)).toBe('2025-07-15T12:00:00.000Z')
+  })
+
+  test('0 returns current time', () => {
+    expect(Expires.months(0)).toBe('2025-06-15T12:00:00.000Z')
+  })
+
+  test('negative n returns past time', () => {
+    expect(Expires.months(-1)).toBe('2025-05-16T12:00:00.000Z')
+  })
+})
+
+describe('years', () => {
+  test('returns ISO string n years (365 days) from now', () => {
+    expect(Expires.years(1)).toBe('2026-06-15T12:00:00.000Z')
+  })
+
+  test('0 returns current time', () => {
+    expect(Expires.years(0)).toBe('2025-06-15T12:00:00.000Z')
+  })
+
+  test('negative n returns past time', () => {
+    expect(Expires.years(-1)).toBe('2024-06-15T12:00:00.000Z')
+  })
+})

package/src/cli.test.ts

@@ -6,7 +6,7 @@ import { Addresses } from 'viem/tempo'
 import { afterAll, describe, expect, test } from 'vitest'
 import * as Http from '~test/Http.js'
 import { rpcUrl } from '~test/tempo/prool.js'
-import { deployEscrow } from '~test/tempo/stream.js'
+import { deployEscrow } from '~test/tempo/session.js'
 import { accounts, asset, client, fundAccount } from '~test/tempo/viem.js'
 import * as Store from './Store.js'
 import * as Mppx_server from './server/Mppx.js'
@@ -517,9 +517,9 @@ test('mppx --help', () => {
       -H, --header <header>  Add header (repeatable) 
       -L, --location         Follow redirects 
       -X, --method <method>  HTTP method 
-      --channel <id>         Reuse existing stream channel ID 
+      --channel <id>         Reuse existing session channel ID 
       --confirm              Show confirmation prompts 
-      --deposit <amount>     Deposit amount for stream payments (human-readable units) 
+      --deposit <amount>     Deposit amount for session payments (human-readable units) 
       --json <json>          Send JSON body (sets Content-Type and Accept, implies POST) 
       -V, --version          Display version number 
       -h, --help             Display this message 

package/src/cli.ts

@@ -16,8 +16,8 @@ import * as Challenge from './Challenge.js'
 import * as Credential from './Credential.js'
 import * as Mppx from './client/Mppx.js'
 import { tempo } from './tempo/client/index.js'
-import type { StreamCredentialPayload } from './tempo/stream/Types.js'
-import { signVoucher } from './tempo/stream/Voucher.js'
+import type { SessionCredentialPayload } from './tempo/session/Types.js'
+import { signVoucher } from './tempo/session/Voucher.js'
 
 const require = createRequire(import.meta.url)
 const { name, version } = require('../package.json') as { name: string; version: string }
@@ -41,9 +41,9 @@ cli
   .option('-H, --header <header>', 'Add header (repeatable)')
   .option('-L, --location', 'Follow redirects')
   .option('-X, --method <method>', 'HTTP method')
-  .option('--channel <id>', 'Reuse existing stream channel ID')
+  .option('--channel <id>', 'Reuse existing session channel ID')
   .option('--confirm', 'Show confirmation prompts')
-  .option('--deposit <amount>', 'Deposit amount for stream payments (human-readable units)')
+  .option('--deposit <amount>', 'Deposit amount for session payments (human-readable units)')
   .option('--json <json>', 'Send JSON body (sets Content-Type and Accept, implies POST)')
   .example(`${name} example.com/content`)
   .example(`${name} example.com/api --json '{"key":"value"}'`)
@@ -79,7 +79,7 @@ cli
     if (silent) options.confirm = false
 
     const accountName = resolveAccountName(options.account)
-    const privateKey = process.env.MPPX_PRIVATE_KEY ?? (await createKeychain(accountName).get())
+    const privateKey = process.env.MPPX_PRIVATE_KEY || (await createKeychain(accountName).get())
     if (!privateKey) {
       if (options.account) console.log(`Account "${accountName}" not found.`)
       else console.log(`No account found.`)
@@ -158,7 +158,7 @@ cli
       }
 
       const account = privateKeyToAccount(privateKey as `0x${string}`)
-      const rpcUrl = options.rpcUrl ?? process.env.MPPX_RPC_URL
+      const rpcUrl = options.rpcUrl ?? (process.env.MPPX_RPC_URL || undefined)
       const client = createClient({
         chain: await resolveChain({ ...options, rpcUrl }),
         transport: http(rpcUrl),
@@ -289,7 +289,7 @@ cli
               suggestedDeposit ?? cliDeposit ?? (isTestnet(client.chain!) ? '10' : undefined)
             if (!resolved) {
               console.error(
-                'Stream payment requires a deposit. Use --deposit <amount> or connect to testnet.',
+                'Session payment requires a deposit. Use --deposit <amount> or connect to testnet.',
               )
               process.exit(1)
             }
@@ -313,21 +313,21 @@ cli
         })(),
       )
 
-      const streamMd = challenge.request.methodDetails as
+      const sessionMd = challenge.request.methodDetails as
         | { escrowContract?: string; chainId?: number }
         | undefined
-      let streamChannelId: `0x${string}` | undefined
-      let streamEscrowContract: Address | undefined
-      let streamChainId = 0
-      let streamCumulativeAmount = 0n
+      let sessionChannelId: `0x${string}` | undefined
+      let sessionEscrowContract: Address | undefined
+      let sessionChainId = 0
+      let sessionCumulativeAmount = 0n
 
       if (challenge.intent === 'session') {
-        const parsed = Credential.deserialize<StreamCredentialPayload>(credential)
-        streamChannelId = parsed.payload.channelId
-        streamChainId = streamMd?.chainId ?? client.chain?.id ?? 0
-        streamEscrowContract = streamMd?.escrowContract as Address | undefined
+        const parsed = Credential.deserialize<SessionCredentialPayload>(credential)
+        sessionChannelId = parsed.payload.channelId
+        sessionChainId = sessionMd?.chainId ?? client.chain?.id ?? 0
+        sessionEscrowContract = sessionMd?.escrowContract as Address | undefined
         if ('cumulativeAmount' in parsed.payload && parsed.payload.cumulativeAmount)
-          streamCumulativeAmount = BigInt(parsed.payload.cumulativeAmount)
+          sessionCumulativeAmount = BigInt(parsed.payload.cumulativeAmount)
 
         if (parsed.payload.action === 'open') {
           const depositRaw =
@@ -379,8 +379,9 @@ cli
               typeof receiptJson.acceptedCumulative === 'string' &&
               receiptJson.acceptedCumulative
             ) {
-              streamCumulativeAmount = BigInt(receiptJson.acceptedCumulative)
-              if (streamChannelId) writeChannelCumulative(streamChannelId, streamCumulativeAmount)
+              sessionCumulativeAmount = BigInt(receiptJson.acceptedCumulative)
+              if (sessionChannelId)
+                writeChannelCumulative(sessionChannelId, sessionCumulativeAmount)
             }
             info(`\n${pc.bold(pc.green('Payment Receipt'))}\n`)
             const rows: [string, string][] = []
@@ -421,21 +422,21 @@ cli
           let buffer = ''
           let currentEvent = ''
 
-          const streamCred =
+          const sessionCred =
             challenge.intent === 'session'
-              ? Credential.deserialize<StreamCredentialPayload>(credential)
+              ? Credential.deserialize<SessionCredentialPayload>(credential)
               : undefined
-          const channelId = streamCred?.payload.channelId
+          const channelId = sessionCred?.payload.channelId
           const md = challenge.request.methodDetails as
             | { escrowContract?: string; chainId?: number }
             | undefined
-          const streamChainId = md?.chainId ?? client.chain?.id ?? 0
+          const sessionChainId = md?.chainId ?? client.chain?.id ?? 0
           const escrowContract = md?.escrowContract as Address | undefined
           let cumulativeAmount =
-            streamCred?.payload &&
-            'cumulativeAmount' in streamCred.payload &&
-            streamCred.payload.cumulativeAmount
-              ? BigInt(streamCred.payload.cumulativeAmount)
+            sessionCred?.payload &&
+            'cumulativeAmount' in sessionCred.payload &&
+            sessionCred.payload.cumulativeAmount
+              ? BigInt(sessionCred.payload.cumulativeAmount)
               : 0n
           let _voucherSeq = 0
 
@@ -481,7 +482,7 @@ cli
                 currentEvent === 'payment-need-voucher' &&
                 channelId &&
                 escrowContract &&
-                streamChainId
+                sessionChainId
               ) {
                 try {
                   const event = JSON.parse(data) as {
@@ -496,7 +497,7 @@ cli
                     account,
                     { channelId, cumulativeAmount },
                     escrowContract,
-                    streamChainId,
+                    sessionChainId,
                   )
                   const voucherCred = Credential.serialize({
                     challenge,
@@ -506,7 +507,7 @@ cli
                       cumulativeAmount: cumulativeAmount.toString(),
                       signature,
                     },
-                    source: `did:pkh:eip155:${streamChainId}:${account.address}`,
+                    source: `did:pkh:eip155:${sessionChainId}:${account.address}`,
                   })
                   await globalThis.fetch(url, {
                     method: 'POST',
@@ -583,15 +584,15 @@ cli
           }
           if (buffer.trim()) await processLines([buffer])
 
-          if (channelId && escrowContract && streamChainId) {
+          if (channelId && escrowContract && sessionChainId) {
             const signature = await signVoucher(
               client,
               account,
               { channelId, cumulativeAmount },
               escrowContract,
-              streamChainId,
+              sessionChainId,
             )
-            const closePayload: StreamCredentialPayload = {
+            const closePayload: SessionCredentialPayload = {
               action: 'close',
               channelId,
               cumulativeAmount: cumulativeAmount.toString(),
@@ -600,7 +601,7 @@ cli
             const closeCred = Credential.serialize({
               challenge,
               payload: closePayload,
-              source: `did:pkh:eip155:${streamChainId}:${account.address}`,
+              source: `did:pkh:eip155:${sessionChainId}:${account.address}`,
             })
             const closeRes = await globalThis.fetch(url, {
               method: 'POST',
@@ -638,9 +639,9 @@ cli
           const shouldClose =
             challenge.intent === 'session' &&
             credentialResponse.ok &&
-            streamChannelId &&
-            streamEscrowContract &&
-            streamChainId
+            sessionChannelId &&
+            sessionEscrowContract &&
+            sessionChainId
           if (shouldClose && options.confirm) {
             info('\n')
           }
@@ -650,20 +651,20 @@ cli
             const signature = await signVoucher(
               client,
               account,
-              { channelId: streamChannelId!, cumulativeAmount: streamCumulativeAmount },
-              streamEscrowContract!,
-              streamChainId,
+              { channelId: sessionChannelId!, cumulativeAmount: sessionCumulativeAmount },
+              sessionEscrowContract!,
+              sessionChainId,
             )
-            const closePayload: StreamCredentialPayload = {
+            const closePayload: SessionCredentialPayload = {
               action: 'close',
-              channelId: streamChannelId!,
-              cumulativeAmount: streamCumulativeAmount.toString(),
+              channelId: sessionChannelId!,
+              cumulativeAmount: sessionCumulativeAmount.toString(),
               signature,
             }
             const closeCred = Credential.serialize({
               challenge,
               payload: closePayload,
-              source: `did:pkh:eip155:${streamChainId}:${account.address}`,
+              source: `did:pkh:eip155:${sessionChainId}:${account.address}`,
             })
             const closeRes = await globalThis.fetch(url, {
               ...fetchInit,
@@ -673,7 +674,7 @@ cli
               },
             })
             if (closeRes.ok) {
-              deleteChannelState(streamChannelId!)
+              deleteChannelState(sessionChannelId!)
               const closeReceiptHeader = closeRes.headers.get('Payment-Receipt')
               let closeTxHash: string | undefined
               if (closeReceiptHeader) {
@@ -690,7 +691,7 @@ cli
                   ? ` ${pc.dim(pc.link(`${explorerUrl}/tx/${closeTxHash}`, closeTxHash))}`
                   : ''
               info(
-                `\n${pc.dim('Channel closed.')} ${pc.dim(`Spent ${fmtBalance(streamCumulativeAmount, tokenSymbol, tokenDecimals)}.`)}${txInfo}\n`,
+                `\n${pc.dim('Channel closed.')} ${pc.dim(`Spent ${fmtBalance(sessionCumulativeAmount, tokenSymbol, tokenDecimals)}.`)}${txInfo}\n`,
               )
             } else {
               const closeBody = await closeRes.text().catch(() => '')
@@ -698,10 +699,10 @@ cli
                 `${pc.dim(pc.yellow('Channel close failed'))} ${pc.dim(`(${closeRes.status})`)}\n`,
               )
               info(
-                `${pc.dim(`  channelId:          ${streamChannelId}`)}\n` +
-                  `${pc.dim(`  cumulativeAmount:   ${streamCumulativeAmount}`)}\n` +
-                  `${pc.dim(`  escrowContract:     ${streamEscrowContract}`)}\n` +
-                  `${pc.dim(`  chainId:            ${streamChainId}`)}\n` +
+                `${pc.dim(`  channelId:          ${sessionChannelId}`)}\n` +
+                  `${pc.dim(`  cumulativeAmount:   ${sessionCumulativeAmount}`)}\n` +
+                  `${pc.dim(`  escrowContract:     ${sessionEscrowContract}`)}\n` +
+                  `${pc.dim(`  chainId:            ${sessionChainId}`)}\n` +
                   `${pc.dim(`  account:            ${account.address}`)}\n` +
                   `${pc.dim(`  response:           ${closeBody || '(empty)'}`)}\n`,
               )
@@ -784,7 +785,11 @@ cli
         const accounts = await createKeychain().list()
         if (accounts.length === 1) createDefaultStore().set(resolvedName)
         console.log(`Account "${resolvedName}" saved to keychain.`)
-        console.log(pc.dim(`Address ${account.address}`))
+        const explorerUrl = tempoMainnet.blockExplorers?.default?.url
+        const addrDisplay = explorerUrl
+          ? pc.link(`${explorerUrl}/address/${account.address}`, account.address)
+          : account.address
+        console.log(pc.dim(`Address ${addrDisplay}`))
         resolveChain(options)
           .then((chain) => createClient({ chain, transport: http(options.rpcUrl) }))
           .then((client) =>
@@ -823,8 +828,12 @@ cli
         const account = privateKeyToAccount(key as `0x${string}`)
         const balanceLines = await fetchBalanceLines(account.address, { includeTestnet: false })
         if (!options.yes) {
+          const explorerUrl = tempoMainnet.blockExplorers?.default?.url
+          const addrDisplay = explorerUrl
+            ? pc.link(`${explorerUrl}/address/${account.address}`, account.address)
+            : account.address
           process.stderr.write(pc.dim(`Delete account "${options.account}"\n`))
-          process.stderr.write(pc.dim(`  Address  ${account.address}\n`))
+          process.stderr.write(pc.dim(`  Address  ${addrDisplay}\n`))
           for (let i = 0; i < balanceLines.length; i++)
             process.stderr.write(
               pc.dim(`  ${i === 0 ? 'Balance' : '       '}  ${balanceLines[i]}\n`),
@@ -897,6 +906,7 @@ cli
           }),
         )
         const resolved = entries.filter((e) => e !== undefined)
+        const explorerUrl = tempoMainnet.blockExplorers?.default?.url
         const maxWidth = Math.max(
           ...resolved.map((e) => e.name.length + (e.name === currentDefault ? 1 : 0)),
         )
@@ -904,7 +914,10 @@ cli
           const isDefault = entry.name === currentDefault
           const label = isDefault ? `${entry.name}${pc.dim('*')}` : entry.name
           const width = entry.name.length + (isDefault ? 1 : 0)
-          console.log(`${label}${' '.repeat(maxWidth - width + 2)}${pc.dim(entry.address)}`)
+          const addrDisplay = explorerUrl
+            ? pc.link(`${explorerUrl}/address/${entry.address}`, entry.address)
+            : entry.address
+          console.log(`${label}${' '.repeat(maxWidth - width + 2)}${pc.dim(addrDisplay)}`)
         }
         return
       }
@@ -918,10 +931,14 @@ cli
           process.exit(1)
         }
         const account = privateKeyToAccount(key as `0x${string}`)
-        console.log(`${pc.dim('Address')}  ${account.address}`)
+        const rpcUrl = options.rpcUrl ?? (process.env.MPPX_RPC_URL || undefined)
+        const chain = rpcUrl ? await resolveChain({ rpcUrl }) : tempoMainnet
+        const explorerUrl = chain.blockExplorers?.default?.url
+        const addrDisplay = explorerUrl
+          ? pc.link(`${explorerUrl}/address/${account.address}`, account.address)
+          : account.address
+        console.log(`${pc.dim('Address')}  ${addrDisplay}`)
 
-        const rpcUrl = options.rpcUrl ?? process.env.MPPX_RPC_URL
-        const chain = rpcUrl ? await resolveChain({ rpcUrl }) : undefined
         const balanceLines = await fetchBalanceLines(
           account.address,
           chain && rpcUrl ? { chain, rpcUrl } : undefined,
@@ -1054,7 +1071,7 @@ function createDefaultStore() {
 
 function resolveAccountName(explicit?: string): string {
   if (explicit) return explicit
-  if (process.env.MPPX_ACCOUNT) return process.env.MPPX_ACCOUNT
+  if (process.env.MPPX_ACCOUNT?.trim()) return process.env.MPPX_ACCOUNT
   return createDefaultStore().get()
 }
 
@@ -1238,9 +1255,9 @@ const pc = (() => {
     bgMagentaBright: f('\x1b[105m', '\x1b[49m'),
     bgCyanBright: f('\x1b[106m', '\x1b[49m'),
     bgWhiteBright: f('\x1b[107m', '\x1b[49m'),
-    link(url: string, text: string) {
+    link(url: string, text: string, noUnderline?: boolean) {
       if (!isColorSupported) return text
-      return `\x1b]8;;${url}\x07${pc.underline(text)}\x1b]8;;\x07`
+      return `\x1b]8;;${url}\x07${noUnderline ? text : pc.underline(text)}\x1b]8;;\x07`
     },
   }
 })()
@@ -1268,6 +1285,8 @@ function chainName(chain: { id: number; name: string }) {
 }
 
 const pathUsd = '0x20c0000000000000000000000000000000000000' as Address
+const usdcE = '0x20C000000000000000000000b9537d11c60E8b50' as Address
+const mainnetTokens = [pathUsd, usdcE] as const
 const testnetTokens = [
   '0x20c0000000000000000000000000000000000000',
   '0x20c0000000000000000000000000000000000001',
@@ -1275,11 +1294,20 @@ const testnetTokens = [
   '0x20c0000000000000000000000000000000000003',
 ] as const
 
-function fmtBalance(b: bigint, symbol: string, decimals = 6) {
+function fmtBalance(
+  b: bigint,
+  symbol: string,
+  decimals = 6,
+  opts?: { explorerUrl?: string | undefined; token?: string | undefined },
+) {
   const value = Number(b) / 10 ** decimals
   const [int, dec] = value.toString().split('.')
   const formatted = int!.replace(/\B(?=(\d{3})+(?!\d))/g, '_')
-  return `${dec ? `${formatted}.${dec}` : formatted} ${pc.dim(symbol)}`
+  const sym =
+    opts?.explorerUrl && opts.token
+      ? pc.dim(pc.link(`${opts.explorerUrl}/token/${opts.token}`, symbol, true))
+      : pc.dim(symbol)
+  return `${dec ? `${formatted}.${dec}` : formatted} ${sym}`
 }
 
 function isTestnet(chain: Chain) {
@@ -1296,9 +1324,13 @@ async function fetchTokenInfo(
     Actions.token.getBalance(client, { account, token }).catch(() => 0n),
     Actions.token.getMetadata(client, { token }).catch(() => ({ symbol: token as string })),
   ])
-  const symbol = token === pathUsd ? 'PathUSD' : metadata.symbol
+  const knownSymbols: Record<string, string> = {
+    [pathUsd]: 'PathUSD',
+    [usdcE]: 'USDC.e',
+  }
+  const symbol = knownSymbols[token] ?? metadata.symbol
   const decimals = 'decimals' in metadata ? metadata.decimals : 6
-  return { balance, symbol, decimals }
+  return { balance, symbol, decimals, token }
 }
 
 function detectTerminalBg(
@@ -1340,6 +1372,7 @@ async function fetchBalanceLines(
 ): Promise<string[]> {
   if (opts?.chain) {
     const client = createClient({ chain: opts.chain, transport: http(opts.rpcUrl) })
+    const explorerUrl = opts.chain.blockExplorers?.default?.url
     const label = pc.dim(`(${chainName(opts.chain)})`)
     if (isTestnet(opts.chain)) {
       const results = await Promise.all(
@@ -1347,24 +1380,46 @@ async function fetchBalanceLines(
       )
       return results
         .filter((t) => t.balance > 0n)
-        .map((t) => `${fmtBalance(t.balance, t.symbol, t.decimals)} ${label}`)
+        .map(
+          (t) =>
+            `${fmtBalance(t.balance, t.symbol, t.decimals, { explorerUrl, token: t.token })} ${label}`,
+        )
     }
-    const { balance, symbol, decimals } = await fetchTokenInfo(client, pathUsd, address)
-    return [`${fmtBalance(balance, symbol, decimals)} ${label}`]
+    const results = await Promise.all(
+      mainnetTokens.map((token) => fetchTokenInfo(client, token, address)),
+    )
+    return results.map(
+      (t) =>
+        `${fmtBalance(t.balance, t.symbol, t.decimals, { explorerUrl, token: t.token })} ${label}`,
+    )
   }
 
-  const mainnetClient = createClient({ chain: tempoMainnet, transport: http() })
-  const mainnetInfo = await fetchTokenInfo(mainnetClient, pathUsd, address)
-  const lines = [fmtBalance(mainnetInfo.balance, mainnetInfo.symbol, mainnetInfo.decimals)]
+  const mainnetClient = createClient({
+    chain: tempoMainnet,
+    transport: http(process.env.MPPX_RPC_URL || undefined),
+  })
+  const mainnetExplorerUrl = tempoMainnet.blockExplorers?.default?.url
+  const mainnetResults = await Promise.all(
+    mainnetTokens.map((token) => fetchTokenInfo(mainnetClient, token, address)),
+  )
+  const lines = mainnetResults.map((t) =>
+    fmtBalance(t.balance, t.symbol, t.decimals, {
+      explorerUrl: mainnetExplorerUrl,
+      token: t.token,
+    }),
+  )
 
   if (opts?.includeTestnet !== false) {
     const testnetClient = createClient({ chain: tempoModerato, transport: http() })
+    const testnetExplorerUrl = tempoModerato.blockExplorers?.default?.url
     const testnetResults = await Promise.all(
       testnetTokens.map((token) => fetchTokenInfo(testnetClient, token, address)),
     )
     for (const t of testnetResults) {
       if (t.balance > 0n)
-        lines.push(`${fmtBalance(t.balance, t.symbol, t.decimals)} ${pc.dim('(testnet)')}`)
+        lines.push(
+          `${fmtBalance(t.balance, t.symbol, t.decimals, { explorerUrl: testnetExplorerUrl, token: t.token })} ${pc.dim('(testnet)')}`,
+        )
     }
   }
 

package/src/internal/env.ts

@@ -0,0 +1,54 @@
+/** Map of configuration keys to environment variable names, checked in order. */
+const variables = {
+  realm: [
+    'FLY_APP_NAME',
+    'HEROKU_APP_NAME',
+    'HOST',
+    'HOSTNAME',
+    'MPP_REALM',
+    'RAILWAY_PUBLIC_DOMAIN',
+    'RENDER_EXTERNAL_HOSTNAME',
+    'VERCEL_URL',
+    'WEBSITE_HOSTNAME',
+  ],
+  secretKey: ['MPP_SECRET_KEY'],
+} as const satisfies Record<string, readonly string[]>
+
+/** Fallback values when no environment variable is set. */
+const defaults = {
+  realm: 'MPP Payment',
+  secretKey: 'tmp',
+} as const satisfies Record<keyof typeof variables, string>
+
+/**
+ * Resolves a configuration value from environment variables.
+ *
+ * Checks platform-specific env vars in order, falling back to a default.
+ *
+ * @example
+ * ```ts
+ * Env.get('realm')     // e.g. "my-app.vercel.app"
+ * Env.get('secretKey') // e.g. value of MPP_SECRET_KEY
+ * ```
+ */
+export function get(key: keyof typeof variables): string {
+  for (const name of variables[key]) {
+    const value = read(name)
+    if (value) return value
+  }
+  return defaults[key]
+}
+
+/** Reads a single environment variable, probing available runtime APIs. */
+function read(name: string): string | undefined {
+  try {
+    if (typeof process !== 'undefined' && process?.env) return process.env[name] || undefined
+  } catch {}
+
+  try {
+    const deno = (globalThis as any).Deno
+    if (deno?.env?.get) return deno.env.get(name) || undefined
+  } catch {}
+
+  return undefined
+}