From fc13b2317cac0746592f850cb27427135502760e Mon Sep 17 00:00:00 2001
From: Peter Harpending <peter@harpending.org>
Date: Thu, 18 Sep 2025 17:52:20 -0700
Subject: [PATCH] massaging API encoding page

---
 API-Encoding.md | 50 +++++++++++++++++++++++++++++++++++++++++++++++++
 Home.md         | 26 ++++++++++++++++++-------
 2 files changed, 69 insertions(+), 7 deletions(-)

diff --git a/API-Encoding.md b/API-Encoding.md
index 74a7c85..677ec7e 100644
--- a/API-Encoding.md
+++ b/API-Encoding.md
@@ -1,5 +1,55 @@
 # API Encoding (`xy_ABCD` strings)
 
+## tl;dr
+
+```erlang
+%% DECODE: pull the binary data out of an xy_ABCD string
+%% deconstructing and pulling useful data out of the resultant bytestring is a
+%% different task (see Protocol page)
+%% https://git.qpq.swiss/QPQ-AG/gmserialization/src/commit/dda5cac7a91ba0ad105815ec3cb1de551a04d719/src/gmser_api_encoder.erl#L69-L82
+{KnownType, Payload} = gmser_api_encoder:decode(ApiStr)
+
+%% ENCODE: from actual data to API garbage
+%% https://git.qpq.swiss/QPQ-AG/gmserialization/src/commit/dda5cac7a91ba0ad105815ec3cb1de551a04d719/src/gmser_api_encoder.erl#L57-L67
+ApiStr = gmser_api_encoder:encode(KnownType, Payload)
+
+%% ApiStr    :: binary()
+%% Payload   :: binary()
+%% KnownType :: known_type()
+
+%% https://git.qpq.swiss/QPQ-AG/gmserialization/src/commit/dda5cac7a91ba0ad105815ec3cb1de551a04d719/src/gmser_api_encoder.erl#L18-L46
+-type known_type() :: key_block_hash
+                    | micro_block_hash
+                    | block_pof_hash
+                    | block_tx_hash
+                    | block_state_hash
+                    | block_witness_hash
+                    | channel
+                    | contract_bytearray
+                    | contract_pubkey
+                    | contract_store_key
+                    | contract_store_value
+                    | contract_source
+                    | transaction
+                    | tx_hash
+                    | account_pubkey
+                    | account_seckey
+                    | associate_chain
+                    | entry
+                    | signature
+                    | name
+                    | native_token
+                    | commitment
+                    | peer_pubkey
+                    | state
+                    | poi
+                    | state_trees
+                    | call_state_tree
+                    | mp_tree_hash
+                    | bytearray.
+```
+
+
 ## Links
 
 - [GMSerialization API Encoder](https://git.qpq.swiss/QPQ-AG/gmserialization/src/commit/ac64e01b0f675c1a34c70a827062f381920742db/src/gmser_api_encoder.erl)
diff --git a/Home.md b/Home.md
index f1a3e7f..e5b3aa9 100644
--- a/Home.md
+++ b/Home.md
@@ -10,16 +10,28 @@
 
 ## Principles
 
-- ~Every article should have a "YouTube Thumbnail" diagram at the top that
-  visually illustrates whatever is explained in the page
-- Things should be illustrated with code examples that work when possible
-- Move links to aeternity things to QPQ repos
-- Every article should have a "I just need to get a thing to work and don't
-  have time to read a whole article" section that links to which things you
-  should just use in practice and maybe a short example of how to use them.
+- **PICTURES:** ~Every article should have a "YouTube Thumbnail" diagram at the
+  top that visually illustrates whatever is explained in the page
+- **QUICKREF:** Every page should have a "I just need to get a thing to work
+  and don't have time to read a whole article" section that links to which
+  things you should just use in practice and maybe a short example of how to
+  use them.
+- **DEMOS DEMOS DEMOS:** Things should be illustrated with code examples that
+  work when possible
+- **CENTRALIZE:** All public technical documentation should be on this wiki,
+  not in a billion separate repos.
+- **LINK:** Provide receipts; i.e. whenever possible, provide a permalink
+  reference to whatever code actually does the thing you're talking about. For
+  instance, the [[API Encoding]] page should link to `gmser_api_encoder` source
+  code whenever it makes sense to do so.
+
+  Part of the goal of this wiki is to acquaint newcomers with the actual
+  gajumaru codebase and to demystify it.
 
 ## TODOs
 
+- Move links to aeternity things to QPQ repos
+
 - API-Encoding:
     - needs practical reference (which functions to call)
     - maybe could use a diagram