• Getting Started in Minutes
  • 1. Add Dependencies
  • 2. Stand Up the Relay
• The Event Store
  • Tuning the Indexing Strategy
• Policy System
  • Built-in Policies
  • Composing Policies
  • Writing a Custom Policy
• Testing Your Relay
• Source Map
• Closing Thoughts

Quartz is the core library powering Amethyst, one of the most popular Nostr clients for Android. Beyond client-side features, Quartz ships a fully self-contained, transport-agnostic relay engine — meaning you can wire it to Ktor WebSockets, raw TCP sockets, or any other transport layer.

The design is elegantly simple: you provide a send callback per connection and Quartz hands back a RelaySession that processes raw JSON strings. Plug, play, and relay.

Note: Both NostrServer and EventStore implement AutoCloseable, so they play nicely with Kotlin’s use { } blocks and structured concurrency.

§Getting Started in Minutes

§1. Add Dependencies

Add Ktor and the Quartz module to your Gradle build file:

dependencies {
    implementation("io.ktor:ktor-server-core:3.1.1")
    implementation("io.ktor:ktor-server-netty:3.1.1")
    implementation("io.ktor:ktor-server-websockets:3.1.1")
    implementation(project(":quartz"))
}

§2. Stand Up the Relay

The entire relay — event storage, WebSocket routing, and NIP-01 compliance — fits in a single main() function:

fun main() {
    // Persistent SQLite-backed event store
    val store = EventStore(dbName = "relay-events.db")
    val server = NostrServer(store)

    embeddedServer(Netty, port = 7777) {
        install(WebSockets)

        routing {
            webSocket("/") {
                server.serve(
                    send = { json -> launch { send(Frame.Text(json)) } },
                ) { session ->
                    for (frame in incoming) {
                        if (frame is Frame.Text) {
                            session.receive(frame.readText())
                        }
                    }
                }
            }
        }
    }.start(wait = true)
}

That’s it — you now have a NIP-01 compliant relay listening on ws://localhost:7777. Any Nostr client (Amethyst, Damus, Iris…) can connect immediately.

Tip: Need an ephemeral store for testing? Pass null as the db name: EventStore(null). All events live in memory and vanish when the process stops.

§The Event Store

Quartz ships a SQLite-backed EventStore built on androidx.sqlite with WAL journal mode and a 32 MB memory cache baked in — solid enough for production use on modest hardware.

§Tuning the Indexing Strategy

By default, all single-letter tags with values are indexed. You can fine-tune this trade-off between query speed and database size:

val store = EventStore(
    dbName = "relay-events.db",
    indexStrategy = DefaultIndexingStrategy(
        indexEventsByCreatedAtAlone = false,
        indexTagsByCreatedAtAlone = false,
        indexTagsWithKindAndPubkey = false,
        useAndIndexIdOnOrderBy = false,
    ),
)

Override shouldIndex(kind, tag) on the strategy to apply custom rules per event kind. More indexes means faster queries but a larger database.

§Policy System

Policies are the heart of Quartz’s extensibility. They intercept every client command — EVENT, REQ, COUNT, AUTH — and either pass it through or reject it with a reason string.

§Built-in Policies

§Composing Policies

Combine policies with the + operator (or PolicyStack). All must approve — the first rejection short-circuits the chain:

val server = NostrServer(
    store = store,
    policyBuilder = {
        VerifyPolicy + FullAuthPolicy(
            relay = "wss://myrelay.example.com/".normalizeRelayUrl()!!
        )
    },
)

§Writing a Custom Policy

Implement IRelayPolicy to restrict your relay to specific event kinds — for example, a curated social relay that only accepts profiles, notes, follows, reactions, and long-form articles:

class KindWhitelistPolicy(
    private val allowedKinds: Set<Int>,
) : IRelayPolicy {

    override fun onConnect(send: (Message) -> Unit) { }

    override fun accept(cmd: EventCmd): PolicyResult<EventCmd> =
        if (cmd.event.kind in allowedKinds) {
            PolicyResult.Accepted(cmd)
        } else {
            PolicyResult.Rejected("blocked: kind ${cmd.event.kind} not allowed")
        }

    override fun accept(cmd: ReqCmd) = PolicyResult.Accepted(cmd)
    override fun accept(cmd: CountCmd) = PolicyResult.Accepted(cmd)
    override fun accept(cmd: AuthCmd) = PolicyResult.Accepted(cmd)
}

// Wire it up
val server = NostrServer(
    store = store,
    policyBuilder = {
        VerifyPolicy + KindWhitelistPolicy(
            allowedKinds = setOf(0, 1, 3, 7, 30023)
        )
    },
)

§Testing Your Relay

Because Quartz is transport-agnostic, you can test the relay engine entirely in-process — no HTTP server, no WebSocket handshake, no network. server.connect { … } returns a session you can feed raw JSON directly:

@OptIn(ExperimentalCoroutinesApi::class)
class MyRelayTest {

    @Test
    fun clientCanPublishAndSubscribe() = runTest {
        val dispatcher = UnconfinedTestDispatcher(testScheduler)

        NostrServer(
            store = EventStore(null),        // in-memory
            policyBuilder = { EmptyPolicy }, // accept all
            parentContext = dispatcher,
        ).use { server ->
            val messages = mutableListOf<String>()
            val session = server.connect { messages.add(it) }

            // Publish an event
            session.receive("""["EVENT",{"id":"${"0".repeat(64)}","pubkey":"${"a".repeat(64)}","created_at":1000,"kind":1,"tags":[],"content":"hello","sig":"${"b".repeat(128)}"}]""")
            assertTrue(messages.any { it.contains("OK") })

            // Subscribe and check the event comes back
            session.receive("""["REQ","sub1",{"kinds":[1]}]""")
            assertTrue(messages.any { it.contains("EVENT") })
            assertTrue(messages.any { it.contains("EOSE") })
        }
    }
}

§Source Map

Here’s where everything lives inside the Quartz module:

quartz/src/commonMain/kotlin/com/vitorpamplona/quartz/nip01Core/
├── relay/server/
│   ├── NostrServer.kt          # Main entry point
│   ├── RelaySession.kt         # Per-connection handler
│   ├── LiveEventStore.kt       # Reactive event streaming
│   ├── IRelayPolicy.kt         # Policy interface + PolicyResult
│   └── policies/
│       ├── EmptyPolicy.kt      # Accept everything
│       ├── VerifyPolicy.kt     # Signature verification (default)
│       ├── FullAuthPolicy.kt   # NIP-42 auth required
│       └── PolicyStack.kt      # Chain multiple policies
├── store/
│   ├── IEventStore.kt          # Storage interface
│   └── sqlite/
│       ├── EventStore.kt       # Public SQLite store wrapper
│       ├── SQLiteEventStore.kt # Full implementation
│       └── IndexingStrategy.kt # Index configuration
└── relay/filters/
    ├── Filter.kt               # NIP-01 subscription filters
    └── FilterMatcher.kt        # Event-to-filter matching

§Closing Thoughts

Quartz makes building a Nostr relay genuinely approachable. The policy system is the real gem — it lets you start with a permissive relay and progressively layer in authentication, kind restrictions, rate limiting, or any custom logic your use case demands, all without touching transport code.

Whether you’re running a private relay for a community, experimenting with NIP implementations, or building relay infrastructure for a Nostr app, Quartz gives you a solid, battle-tested foundation that the Amethyst team has been running in production. Give it a spin.

Based on amethyst/quartz/RELAY.md by Vitor Pamplona · MIT License