README

Author: probably-not

README.md

@@ -12,6 +12,17 @@ Wrap your untrusted NIFs so that they can never crash your node.
 
 <!-- HEX PACKAGE DESCRIPTION END -->
 
+## Motivation
+
+NIFs are great - sometimes... when they're written in a safe way, have been in use for a very long time, and are trusted by the community, then they have likely been through the process of finding most bugs that are in their underlying source. However, sometimes new libraries come out, and have not been as battle tested as you'd like. Some may have bugs, and when a NIF has a bug, it can crash your entire BEAM node! Code running inside of a NIF does not provide the same safety guarantees that the BEAM gives.
+
+But... what if it could?
+
+I recently ran into this issue, using a library based on a NIF, and the NIF's underlying source was having sporadic crashes. I don't own the library, nor do I own the underlying C source, so while I can submit PRs to them to get it fixed, I still need some way to guarantee safety in the meantime. And thus, SafeNIF was born!
+
+SafeNIF allows you to wrap your NIFs to run on an isolated peer node raised on the same machine. If the NIF crashes, only this peer node dies.
+The guarantees of the BEAM continue, and you get fault tolerance and crash isolation, even for NIFs, all in native Elixir (with a touch of Erlang's standard library).
+
 ## Benchmarks
 
 Benchmarks can be found in the `bench` directory.
@@ -28,12 +39,6 @@ SafeNIF's main concern is allowing any consumers to simply wrap any NIF by calli
 
 **The following information was generated by Claude and Reviewed by @probably-not. If issues in this README are found, feel free to open up a PR to fix them!**
 
-## The Problem
-
-NIFs (Native Implemented Functions) are powerful but dangerous. A buggy or malicious NIF can crash your entire BEAM node, taking down all processes and connections with it. There's no way to catch or recover from a NIF crash - your node simply dies.
-
-SafeNIF solves this by running untrusted code on isolated peer nodes. If the NIF crashes, only the peer dies. Your main node continues running, and you get a clean error tuple back.
-
 ## Usage
 
 ### Basic Usage