---
name: welshman-app
description: "Use this skill when working with @welshman/app: high-level Svelte stores for nostr apps, session management, WoT (web of trust), making requests, publishing events, user data, or relay selection at the app layer."
---

# welshman/app — Application Layer Stores

`@welshman/app` is the top-level application framework in the welshman stack. It wires together `@welshman/net` (subscriptions/publishing), `@welshman/store` (reactive collections), `@welshman/router` (relay selection), and `@welshman/signer` (key management) into ready-to-use Svelte stores and high-level utilities. It powers production apps like Coracle and Flotilla.

## Installation

```bash
npm install @welshman/app
# or
pnpm add @welshman/app
yarn add @welshman/app
```

## Key Exports

### Core Singletons

| Export | Description |
|---|---|
| `repository` | Singleton `Repository` from `@welshman/net`; non-DVM, non-ephemeral events received from the pool are stored here. WRAP (NIP-59) events are handled separately via `unwrapAndStore` and require `shouldUnwrap` to be set to `true` to process. |
| `tracker` | Singleton `Tracker`; maps event IDs to the relays they were seen on |

### Session Management

| Export | Description |
|---|---|
| `pubkey` | `Writable<string \| undefined>` — active session's pubkey |
| `session` | `Readable<Session \| undefined>` — derived from `pubkey` + `sessions` |
| `sessions` | `Writable<Record<string, Session>>` — all loaded sessions |
| `signer` | `Readable<ISigner \| undefined>` — signer for the active session |
| `signerLog` | `WritableWithGetter<SignerLogEntry[]>` — writable store that the session layer appends signer-operation entries to (useful for UI feedback during remote signing) |
| `SessionMethod` | Enum: `Nip01`, `Nip07`, `Nip46`, `Nip55`, `Pomade`, `Pubkey`, `Anonymous` |

**Login functions** (all call `addSession` internally):

```typescript
loginWithNip01(secret: string): void
loginWithNip07(pubkey: string): void
loginWithNip46(pubkey, clientSecret, signerPubkey, relays): void
loginWithNip55(pubkey: string, signerPackageName: string): void
loginWithPomade(pubkey, email, clientOptions): void
loginWithPubkey(pubkey: string): void   // read-only
```

**Session utilities**:

```typescript
addSession(session: Session): void        // add and activate
dropSession(pubkey: string): void         // remove and clean up signer
getSession(pubkey: string): Session | undefined
updateSession(pubkey, fn): void
clearSessions(): void
nip46Perms: string                        // default NIP-46 permission string
```

**Gift wrap (NIP-59)**:

```typescript
shouldUnwrap: Writable<boolean>           // must be true to process incoming wraps
wrapManager: WrapManager                  // tracks wrap↔rumor mappings
unwrapAndStore(wrap: SignedEvent): Promise<void>
```

### Publishing — Thunks

| Export | Description |
|---|---|
| `publishThunk(options: ThunkOptions): Thunk` | Create, enqueue, and optimistically publish an event |
| `Thunk` | Class representing a single in-flight publish |
| `MergedThunk` | Aggregates multiple `Thunk`s (used by `sendWrapped`) |
| `thunks` | `Writable<Thunk[]>` — all active thunks |
| `abortThunk(thunk)` | Abort all constituent thunks |
| `retryThunk(thunk)` | Re-publish with original options |
| `mergeThunks(thunks[])` | Combine into a `MergedThunk` |

**Thunk status helpers**:

```typescript
thunkIsComplete(thunk): boolean
getThunkError(thunk): string | undefined
getThunkUrlsWithStatus(statuses, thunk): string[]
getCompleteThunkUrls(thunk): string[]
getFailedThunkUrls(thunk): string[]
waitForThunkError(thunk): Promise<string>
waitForThunkCompletion(thunk): Promise<void>
```

`ThunkOptions`:
```typescript
type ThunkOptions = {
  event: EventTemplate   // unsigned — will be signed lazily
  relays: string[]
  recipient?: string     // if set, event is NIP-59 gift-wrapped
  delay?: number         // ms to wait before sending (abort window)
  pow?: number           // proof-of-work difficulty target
  timeout?: number       // ms per relay before marking as timed out
  // PublishOptions callbacks: onSuccess, onFailure, onPending, onTimeout, onAborted, onComplete
}
```

### Commands (Higher-level Thunk Factories)

Most return a `Thunk` (or `Promise<Thunk>`). They automatically load the relevant user list before modifying it. Exception: `manageRelay` returns `Promise<Response>` (an HTTP response from the NIP-86 management endpoint), not a Thunk.

| Export | Description |
|---|---|
| `setProfile(profile: Profile)` | Publish NIP-01 profile metadata |
| `follow(tag: string[])` | Add to NIP-02 follow list |
| `unfollow(value: string)` | Remove from follow list |
| `mutePublicly(tag)` | Add to public mute list |
| `mutePrivately(tag)` | Add to private (encrypted) mute list |
| `unmute(value)` | Remove from mute list |
| `setMutes({publicTags?, privateTags?})` | Replace entire mute list |
| `pin(tag)` / `unpin(value)` | Manage pin list |
| `addRelay(url, mode)` / `removeRelay(url, mode)` | NIP-65 relay list management |
| `setRelays(tags)` / `setReadRelays(urls)` / `setWriteRelays(urls)` | Bulk relay list updates |
| `addMessagingRelay(url)` / `removeMessagingRelay(url)` | NIP-17 messaging relay list |
| `addBlockedRelay(url)` / `removeBlockedRelay(url)` | Blocked relay list |
| `addSearchRelay(url)` / `removeSearchRelay(url)` | Search relay list |
| `sendWrapped({event, recipients, ...options})` | NIP-59 gift-wrap to multiple recipients |
| `manageRelay(url, request)` | NIP-86 relay management |
| `createRoom` / `editRoom` / `deleteRoom` / `joinRoom` / `leaveRoom` | NIP-29 group room management |

### Profiles

```typescript
profilesByPubkey: Readable<Map<string, Profile>>
profiles: Readable<Profile[]>
getProfile(pubkey: string): Profile | undefined
loadProfile(pubkey, relayHints?): Promise<void>
forceLoadProfile(pubkey, relayHints?): Promise<void>
deriveProfile(pubkey: string): Readable<Profile | undefined>  // auto-loads
deriveProfileDisplay(pubkey: string): Readable<string>         // display name with fallback
displayProfileByPubkey(pubkey: string): string                 // synchronous
```

### Follow / Mute / Pin Lists

Each list type follows the same pattern (`follow` shown, `mute` and `pin` are identical):

```typescript
followListsByPubkey: Readable<Map<string, List>>
followLists: Readable<List[]>
getFollowList(pubkey): List | undefined
loadFollowList(pubkey, relayHints?): Promise<void>
forceLoadFollowList(pubkey, relayHints?): Promise<void>
deriveFollowList(pubkey): Readable<List | undefined>
```

### Relay Lists

```typescript
// NIP-65 relay lists
relayListsByPubkey / relayLists / getRelayList / loadRelayList / deriveRelayList

// NIP-17 messaging relay lists
messagingRelayListsByPubkey / messagingRelayLists / getMessagingRelayList / loadMessagingRelayList / deriveMessagingRelayList

// Blocked relay lists
blockedRelayListsByPubkey / getBlockedRelayList / loadBlockedRelayList / deriveBlockedRelayList

// Search relay lists (internal only — not exported from @welshman/app)
// Use userSearchRelayList / loadUserSearchRelayList / forceLoadUserSearchRelayList from user.ts instead
```

### Outbox Loading

`makeOutboxLoader` creates a loader function for any event kind. It looks up the target pubkey's relay list (fetching it if needed), then fetches events from their write relays using the outbox model. This is the internal mechanism used by all built-in `loadX` helpers.

```typescript
import {makeOutboxLoader} from '@welshman/app'

// Signature: makeOutboxLoader(kind, filter?, limit?)
// Returns: (pubkey: string, relayHints?: string[]) => Promise<void>
// Results are stored in repository — read via the derived store/getter, not the return value.

// Loader for kind 1 notes (default limit = 1)
const loadNote = makeOutboxLoader(1)
await loadNote('target-pubkey')

// With extra filter constraints
const loadRecentNotes = makeOutboxLoader(1, {since: Math.floor(Date.now() / 1000) - 86400})
await loadRecentNotes('target-pubkey')

// Override the limit via the third positional argument (not inside the filter object)
const loadMany = makeOutboxLoader(1, {}, 20)
await loadMany('target-pubkey')

// With relay hints to seed the lookup
await loadNote('target-pubkey', ['wss://relay.damus.io/'])
```

**Relay URL helpers** (exported from index):

```typescript
getPubkeyRelays(pubkey: string, mode?: RelayMode): string[]
derivePubkeyRelays(pubkey: string, mode?: RelayMode): Readable<string[]>
```

### User Data Stores (current session)

These automatically derive from the active `pubkey` and trigger a load on first access:

```typescript
userProfile: Readable<Profile | undefined>
userFollowList: Readable<List | undefined>
userMuteList: Readable<List | undefined>
userPinList: Readable<List | undefined>
userRelayList: Readable<List | undefined>
userMessagingRelayList: Readable<List | undefined>
userSearchRelayList: Readable<List | undefined>
userBlockedRelayList: Readable<List | undefined>
userBlossomServerList: Readable<List | undefined>
```

Corresponding loaders (operate on the current session's pubkey):

```typescript
loadUserProfile(relays?)
forceLoadUserProfile(relays?)
loadUserFollowList / forceLoadUserFollowList
loadUserMuteList / forceLoadUserMuteList
loadUserPinList / forceLoadUserPinList
loadUserRelayList / forceLoadUserRelayList
loadUserMessagingRelayList / forceLoadUserMessagingRelayList
// ...etc for each list type
```

### Router

```typescript
import {Router, routerContext, addMaximalFallbacks, addMinimalFallbacks} from '@welshman/router'

// The index.ts wires up routerContext automatically:
// routerContext.getUserPubkey, getPubkeyRelays, getRelayQuality, getDefaultRelays, etc.

Router.get()                        // singleton with app-wired context
Router.get().FromUser()             // relays to publish from the current user
Router.get().ForPubkey(pubkey)      // relays to read a pubkey's events
Router.get().Event(event)           // best relay for a specific event
Router.get().Index()                // indexer/bootstrap relays
Router.get().FromRelays(urls)       // relay set from explicit URLs
  .policy(addMaximalFallbacks)      // add fallback relays
  .limit(8)
  .getUrls()                        // string[]
  .getUrl()                         // string | undefined (first)
```

`routerContext` settings (configure before using router):

```typescript
import {routerContext} from '@welshman/router'  // from @welshman/router, not @welshman/app

routerContext.getDefaultRelays = () => ["wss://relay.damus.io/", "wss://nos.lol/"]
```

### Tag Utilities

```typescript
tagPubkey(pubkey: string): string[]          // ["p", pubkey, relayHint, displayName]
tagEvent(event, url?, mark?): string[][]     // e-tag (+ a-tag if replaceable)
tagEventPubkeys(event): string[][]           // p-tags for all mentioned pubkeys (excl. self)
tagEventForQuote(event, relay?): string[]    // q-tag
tagEventForReply(event, relay?): string[][]  // full reply thread tags
tagEventForComment(event, relay?): string[][]// NIP-22 comment tags
tagEventForReaction(event, relay?): string[][]// reaction tags
tagZapSplit(pubkey, split?): string[]        // zap tag
```

### Web of Trust (WoT)

```typescript
// Reactive stores
followersByPubkey: Readable<Map<string, Set<string>>>
mutersByPubkey: Readable<Map<string, Set<string>>>
wotGraph: Writable<Map<string, number>>  // pubkey → score; rebuilt on follow/mute changes
maxWot: Readable<number>

// Synchronous getters
getFollows(pubkey): string[]
getMutes(pubkey): string[]
getFollowers(pubkey): string[]
getMuters(pubkey): string[]
getNetwork(pubkey): string[]             // follows-of-follows (excludes direct follows)
getFollowsWhoFollow(pubkey, target): string[]
getFollowsWhoMute(pubkey, target): string[]
getWotScore(pubkey, target): number      // follows-who-follow minus follows-who-mute

// Per-user reactive score
getUserWotScore(tpk: string): number
deriveUserWotScore(tpk: string): Readable<number>
```

### Handles & Zappers

```typescript
handlesByNip05: Writable<Map<string, Handle>>
deriveHandle(nip05: string): Readable<Handle | undefined>   // auto-loads
loadHandle(nip05): Promise<void>

zappersByLnurl: Writable<Map<string, Zapper>>
deriveZapper(lnurl: string): Readable<Zapper | undefined>   // auto-loads
loadZapper(lnurl): Promise<void>
```

### Feeds

```typescript
import {makeFeedController} from '@welshman/app'
import {makeKindFeed} from '@welshman/feeds'

// makeFeedController wraps FeedController with app-level scope/WoT helpers
const ctrl = makeFeedController({
  feed: makeKindFeed(NOTE),
  useWindowing: true,
  signal: abortController.signal,
  onEvent: (e) => { /* handle event */ },
  onExhausted: () => { /* no more events */ },
})

ctrl.load(100)
abortController.abort()
```

WoT-scoped feed helpers (passed automatically to `FeedController`):

```typescript
getPubkeysForScope(scope: string): string[]   // Scope.Self|Follows|Network|Followers
getPubkeysForWOTRange(min: number, max: number): string[]  // fractional of maxWot
```

### Sync (Negentropy)

```typescript
import {pull, push, hasNegentropy} from '@welshman/app'

// pull/push use negentropy if the relay supports it, falling back to plain requests
await pull({relays, filters})
await push({relays, filters})
hasNegentropy(url: string): boolean
```

### Application Context

```typescript
import {appContext} from '@welshman/app'

appContext.dufflepudUrl = 'https://my-dufflepud.example.com'
```

[Dufflepud](https://github.com/coracle-social/dufflepud) is an optional proxy server for NIP-05 lookups, zapper resolution, relay metadata, and link previews. Not required but helps bypass CORS.

---

## Common Patterns

### Login and publish a note

```typescript
import {makeSecret} from '@welshman/util'
import {loginWithNip07, publishThunk, signer} from '@welshman/app'
import {Router} from '@welshman/router'
import {NOTE, makeEvent} from '@welshman/util'
import {Nip07Signer} from '@welshman/signer'

// NIP-07 login
const nip07 = new Nip07Signer()
const pubkey = await nip07.getPubkey()
loginWithNip07(pubkey)

// Publish with optimistic local update and 3s undo window
const thunk = publishThunk({
  event: makeEvent(NOTE, {content: 'Hello Nostr!'}),
  relays: Router.get().FromUser().getUrls(),
  delay: 3000,
})

// Subscribe to per-relay status
thunk.subscribe($thunk => {
  for (const [url, result] of Object.entries($thunk.results)) {
    console.log(url, result.status, result.detail)
  }
})

// Soft-undo within delay window
setTimeout(() => thunk.controller.abort(), 1000)

// Wait for all relays to finish (thunk.complete is a Deferred<void>)
await thunk.complete
```

### Derive a reactive profile

```typescript
import {deriveProfile, deriveProfileDisplay} from '@welshman/app'

const targetPubkey = '97c70a44366a6535c145b333f973ea86dfdc2d7a99da618c40c64705ad98e322'

// Reactive store — loads the profile in the background on first subscribe
const profile = deriveProfile(targetPubkey)

// Reactive display name with npub fallback
const name = deriveProfileDisplay(targetPubkey)

// In Svelte
// $: displayName = $name
```

### Reply to an event

```typescript
import {publishThunk, tagEventForReply, tagPubkey, signer} from '@welshman/app'
import {Router} from '@welshman/router'
import {NOTE, makeEvent} from '@welshman/util'
import type {TrustedEvent} from '@welshman/util'

async function replyTo(parent: TrustedEvent, content: string) {
  const tags = tagEventForReply(parent)

  return publishThunk({
    event: makeEvent(NOTE, {content, tags}),
    relays: Router.get().PublishEvent(parent).getUrls(),
  })
}
```

### Send a NIP-59 gift-wrapped DM

```typescript
import {sendWrapped} from '@welshman/app'
import {DIRECT_MESSAGE, makeEvent} from '@welshman/util'

const mergedThunk = await sendWrapped({
  event: makeEvent(DIRECT_MESSAGE, {content: 'secret message'}),
  recipients: [recipientPubkey],
})

// Monitor combined status
mergedThunk.subscribe($t => {
  for (const [url, result] of Object.entries($t.results)) {
    console.log(url, result.status)
  }
})
```

### Follow/unfollow

```typescript
import {follow, unfollow} from '@welshman/app'

// tag format: ["p", pubkey] or ["p", pubkey, relayHint, petname]
await follow(["p", "97c70a44366a6535c145b333f973ea86dfdc2d7a99da618c40c64705ad98e322"])
await unfollow("97c70a44366a6535c145b333f973ea86dfdc2d7a99da618c40c64705ad98e322")
```

### Web of Trust filtering

```typescript
import {deriveUserWotScore, getWotScore, wotGraph, maxWot} from '@welshman/app'
import {get} from 'svelte/store'

// Filter a list of pubkeys to those with positive WoT score
const $graph = get(wotGraph)
const trusted = pubkeys.filter(pk => ($graph.get(pk) ?? 0) > 0)

// Reactive score for a single user
const score = deriveUserWotScore(somePubkey)

// Normalize by max score (0–1 range)
const $max = get(maxWot)
const normalized = ($graph.get(somePubkey) ?? 0) / ($max || 1)
```

### Load a feed of notes

```typescript
import {makeFeedController, getPubkeysForScope} from '@welshman/app'
import {makeKindFeed} from '@welshman/feeds'
import {NOTE} from '@welshman/util'

const abort = new AbortController()

const ctrl = makeFeedController({
  feed: makeKindFeed(NOTE),
  useWindowing: true,
  signal: abort.signal,
  onEvent: event => console.log(event),
  onExhausted: () => console.log('no more events'),
})

ctrl.load(50)

// cleanup
abort.abort()
```

---

## Integration Notes

- `@welshman/app` **re-exports nothing** from `@welshman/net`, `@welshman/router`, etc. Import those directly when you need low-level primitives (`load`, `request`, `publish`, `Router` scenarios beyond `FromUser`).
- The `index.ts` bootstrap code runs on import and automatically wires `routerContext` (pubkey relays, relay quality, default/indexer/search relays) and hooks `Pool` to store incoming events in `repository`. **Import `@welshman/app` early in your app entry point** so this runs before any requests. The canonical side-effect import pattern is:

  ```typescript
  // app entry point — must be first, before any @welshman/net or @welshman/router imports
  import "@welshman/app"

  // Then optionally override defaults
  import {routerContext} from "@welshman/router"
  routerContext.getDefaultRelays = () => ["wss://relay.damus.io/", "wss://nos.lol/"]
  ```
- `repository` and `tracker` are singletons shared across the whole app. All subscriptions made through `@welshman/net` that pass through the pool will populate `repository` automatically.
- `Router` is imported from `@welshman/router` but `routerContext` is configured by `@welshman/app/index.ts`. Use `Router.get()` (not `new Router(...)`) to get the app-configured singleton.
- `deriveProfile`, `deriveFollowList`, etc. use `makeLoadItem` under the hood: they fire a network request on first subscribe if data is not already in the repository, then resolve immediately on subsequent subscribes.
- `userFollowList`, `userMuteList`, etc. are derived from `pubkey`. They automatically re-derive when the active session changes (multi-account support).

---

## Using Welshman Stores Outside Svelte

All welshman stores implement the Svelte store contract: a `subscribe(callback) → unsubscribe` method where the callback fires **synchronously** with the current value on first call, then again on every change. This makes them trivially adaptable to any reactive framework — no Svelte runtime required, only the type imports.

### React

```typescript
import {useState, useEffect} from 'react'
import type {Readable, Writable} from 'svelte/store'

// Returns the current store value; re-renders when it changes.
function useReadable<T>(store: Readable<T>): T {
  const [value, setValue] = useState<T>(() => {
    // subscribe fires synchronously — capture the initial value then unsub immediately
    let initial!: T
    store.subscribe(v => { initial = v })()
    return initial
  })
  useEffect(() => store.subscribe(setValue), [store])
  return value
}

// Returns [currentValue, setter] — setter calls store.set directly.
function useWritable<T>(store: Writable<T>): [T, (value: T) => void] {
  return [useReadable(store), store.set]
}
```

Usage:

```tsx
import {userProfile, pubkey} from '@welshman/app'

function ProfileHeader() {
  const profile = useReadable(userProfile)
  const [currentPubkey, setPubkey] = useWritable(pubkey)

  return <div>{profile?.name ?? currentPubkey}</div>
}
```

### SolidJS

```typescript
import {createSignal, onCleanup} from 'solid-js'
import type {Readable, Writable} from 'svelte/store'

// Returns a SolidJS accessor (getter function); updates reactively.
function useReadable<T>(store: Readable<T>): () => T {
  let initial!: T
  store.subscribe(v => { initial = v })()   // sync capture then unsubscribe

  const [value, setValue] = createSignal<T>(initial)
  onCleanup(store.subscribe(v => setValue(() => v)))
  return value
}

// Returns [accessor, setter].
function useWritable<T>(store: Writable<T>): [() => T, (value: T) => void] {
  return [useReadable(store), store.set]
}
```

Usage:

```tsx
import {userProfile} from '@welshman/app'

function ProfileHeader() {
  const profile = useReadable(userProfile)
  return <div>{profile()?.name}</div>
}
```

### Vue

```typescript
import {ref, onUnmounted} from 'vue'
import type {Readable, Writable} from 'svelte/store'

function useReadable<T>(store: Readable<T>) {
  let initial!: T
  store.subscribe(v => { initial = v })()

  const value = ref<T>(initial)
  const unsub = store.subscribe(v => { value.value = v as any })
  onUnmounted(unsub)
  return value  // use as a readonly ref
}
```

### Notes

- **No Svelte runtime needed.** Only `svelte/store` types are imported. The store objects themselves ship with `@welshman/app`.
- **Welshman stores with `.get()`** (created via `withGetter`) can be read synchronously without subscribing — useful in event handlers and callbacks outside any reactive context. Most writable stores in `@welshman/app` expose `.get()`.
- **`subscribe` always fires immediately.** Unlike many observable libraries, the initial emission is synchronous, so the `useState` / `createSignal` initial value is always populated on first render.

---

## Gotchas & Tips

- **Thunks sign lazily.** `publishThunk` returns synchronously and immediately writes an unsigned/hashed event to `repository` for optimistic UI. Actual signing happens in a background queue. Do not assume the event has an `id` suitable for embedding in other events until signing completes.
- **`delay` is an undo window, not a debounce.** The thunk starts the delay timer immediately; if not aborted before `delay` ms, it signs and publishes. Calling `thunk.controller.abort()` after the delay has elapsed does nothing.
- **`sendWrapped` uses `recipients`, not `pubkeys`.** The docs example uses `pubkeys` but the actual type is `recipients: string[]`.
- **Gift wrap processing requires opt-in.** Set `shouldUnwrap.set(true)` to enable automatic NIP-59 unwrapping of incoming `kind:1059` events. Without this, wrapped events are silently discarded.
- **`commands` force-load lists before modifying them.** `follow()`, `unfollow()`, etc. call `forceLoadUserFollowList` to ensure they have the latest list before adding/removing, preventing accidental list truncation. Do not call these in rapid succession without awaiting each one.
- **WoT graph is rebuilt at most once per second** (throttled). Do not expect `wotGraph` to reflect a `follow()` call immediately; subscribe to the store instead.
- **`routerContext.getDefaultRelays` is throttled** with a 200 ms window by default in `index.ts`. It returns up to the 5 highest-quality known relays. Override it before any relay connections if you want a fixed bootstrap list.
- **Multiple sessions are supported.** Call `loginWith*` multiple times to add sessions. Switch the active session with `pubkey.set(otherPubkey)`. Remove a session with `dropSession(pubkey)` — this also cleans up the cached signer.
- **Stores have `.get()` via `withGetter`.** `pubkey.get()`, `signer.get()`, `session.get()`, `signerLog.get()`, `shouldUnwrap.get()` all work without `get()` from `svelte/store`. Use this for synchronous reads outside of reactive contexts.
- **`appContext.dufflepudUrl` must be set before first handle/zapper load.** There is no lazy re-fetch; set it at app startup.