From 62e00683739e95c11d505d5b17a9b34ae0736c03 Mon Sep 17 00:00:00 2001 From: fiatjaf Date: Wed, 5 Jul 2023 13:50:41 -0300 Subject: [PATCH] add readme. --- nson/README.md | 37 +++++++++++++++++++++++++++++++++++++ 1 file changed, 37 insertions(+) create mode 100644 nson/README.md diff --git a/nson/README.md b/nson/README.md new file mode 100644 index 0000000..d220da4 --- /dev/null +++ b/nson/README.md @@ -0,0 +1,37 @@ +# NSON + +A crazy way to encode Nostr events into valid JSON that is also much faster to decode as long as they are actually +encoded using the strict NSON encoding and the decoder is prepared to read it using a NSON decoder. + +See https://github.com/nostr-protocol/nips/pull/515. + +Some benchmarks: + +``` +goos: linux +goarch: amd64 +pkg: github.com/nbd-wtf/go-nostr/nson +cpu: AMD Ryzen 3 3200G with Radeon Vega Graphics +BenchmarkNSONEncoding/json.Marshal-4 6214 230680 ns/op +BenchmarkNSONEncoding/nson.Marshal-4 4520 319058 ns/op +BenchmarkNSONDecoding/json.Unmarshal-4 3741 280641 ns/op +BenchmarkNSONDecoding/nson.Unmarshal-4 46519 23762 ns/op +BenchmarkNSONDecoding/json.Unmarshal_+_sig_verification-4 352 3218583 ns/op +BenchmarkNSONDecoding/nson.Unmarshal_+_sig_verification-4 451 2739238 ns/op +PASS +ok github.com/nbd-wtf/go-nostr/nson 8.291s +``` + +It takes a little while more to encode (although it's probably possible to optimize that), but decodes at 10x the +speed of normal JSON. + +The performance gain is real, but negligible once you add hash validation and signature verification, so it should +be used wisely, mostly for situations in which the reader wouldn't care about the signature, e.g. reading from a +local database. + +## How it works + +It's explained better in the NIP proposal linked above, but the idea is that we encode field offset and sizes into +a special JSON attribute called `"nson"`, and then the reader can just pull the strings directly from the JSON blob +without having to parse the full JSON syntax. Also for fields of static size we don't even need that. This is only +possible because Nostr events have a static and strict format.