NIP-XX --- Validators

[
  "v-language",
  "{LANGUAGE}",
  "{CAPABILITY}",
  ...
]

[
  "v-hint",
  "{HINT}"
]

[
  "v",
  "{VALIDATOR_DEFINITION_EVENT_ID}",
  "{ADDITIONAL_ARGUMENT}",
  ...
]

Validator(event, index)

NostrRead(({FILTER}, ... ))

NostrRead(({FILTER}, ... ), {RELAY_URL})

(
  {EVENT},
  ...
)

NostrValidate(event)

// Requires the "XMLHttpRequest" and "Async" capabilities
 
const expectedHeight = args[0];  // extract expected height from the event
 
const url = `https://blockchain.info/block-height/${expectedHeight}`;  // the block-height query URL
 
const request = new XMLHttpRequest();                      // build a new XMLHttpRequest
request.open("GET", url, false);                           // set up a synchronous GET request to the above URL
request.send();                                            // execute it
return JSON.parse(request.responseText)["blocks"] !== [];  // compare it against the expected error response

[
  "v",
  "{VALIDATOR_ID}",
  "{EXPECTED_BLOCK_HEIGHT}"
]

// Requires the "XMLHttpRequest" and "Async" capabilities
 
const canonicalUrl = args[0];  // extract the canonical content URL from the event
 
if (event.kind !== 1111) {  // verify that we are indeed validating a validator
  return false;             // fail if we're not
}                           //
 
const request = new XMLHttpRequest();                       // build a new XMLHttpRequest
request.open("GET", canonicalUrl, false);                   // set up a synchronous GET request to the above URL
request.send();                                             // execute it
return request.responseText === JSON.parse(event.content);  // compare it against the event's content

[
  "v",
  "{VALIDATOR_ID}",
  "{CANONICAL_URL}"
]

// Requires the "Crypto" and "Async" capabilities
 
/**
 * Calculate the SHA-256 of the given string, and return it as a hex string
 *
 * @param {string} data - The data to hash
 * @return {string}  The resulting hex string
 */
async function sha256toHex(data) {
  return Array.from(
      new Uint8Array(
        await crypto.subtle.digest(
          "SHA-256",
          (new TextEncoder()).encode(data),
        )
      )
    )
    .map((bytes) => bytes.toString(16).padStart(2, "0"))
    .join("")
  ;
}
 
 
// calculate the event ID according to NIP-01
const calculatedId = await sha256toHex(
  JSON.stringify([
    0,
    event.pubkey,
    event.created_at,
    event.kind,
    event.tags,
    event.content
  ])
);
 
if (calculatedId !== event.id) {  // if the calculated ID and the event ID aren't equal,
  return false;                   // then fail
}                                 //
 
const difficulty = event.tags           // although NIP-13 is unclear as to how to manage
  .filter(tag => tag[0] === "nonce")    // multiple "nonce" tags, we take the conservative
  .map(tag => tag[2])                   // approach and consider multiple "nonce" tags as
  .reduce((a, b) => Math.max(a, b), 0)  // describing differing levels of difficulty,
;                                       // keeping only the highest of them
 
let num0s = 0;  // the number of leading 0s
 
// break the ID into 32-bit blocks and fast-forward the count as long as they are 0
for (let i = 0; i < 32; i += 8) {
  const currentInt = parseInt(event.id.substring(i, i + 8), 16);
  num0s += Math.clz32(currentInt);
  if (currentInt) {
    break;
  }
}
 
return difficulty <= num0s;  // validate that the number of leading 0s is at least the difficulty

[
  "v",
  "{VALIDATOR_ID}"
]

{
  ...,
  "kind": 1001,
  ...,
  "pubkey": "{PUBKEY}",
  ...,
  "tags": [
    ...,
    ["y", "{TOKEN_ID}"],     // used input IDs
    ...,
    ["z", "{TOKEN_ID}"],     // used output IDs
    ...
    ["p", "{DESTINATION}"],  // mentioned destination pubkeys --- NOTE: the recommended relay URL, if given, is ignored
    ...
  ],
  ...,
  "content": "{CONTENT}",  // the JSON string serialization of the content object detailed below
  ...
}

{
  "inputs": [
    ...,
    {
      "id": "{TOKEN_ID}",  // UUIDv4 --- the ID of an unburned output
      "nonce": "{NONCE}"   // NONCE --- the NONCE of said output, such that SHA-256(NONCE) == Output(ID).commitment
    }
    ...
  ],
  "outputs": [
    ...,
    {
      "id": "{TOKEN_ID}",              // UUIDv4 --- a random ID to associate to this output
      "commitment": "{COMMITMENT}",    // SHA-256 of NONCE --- public commitment to the value of NONCE
      "secret": "{SECRET}",            // Encrypt(DESTINATION, NONCE) --- private revelation of the value of NONCE
      "destination": "{DESTINATION}"   // PubKey --- the PubKey of the output's destination,
    },
    ...
  ]
}

// Requires the "NostrRead", "NostrValidate", "Crypto", and "Async" capabilities
 
/**
 * NOSTR Tokens Validator
 *
 * This generic NOSTR Tokens Validator can be attached to a NOSTR Token Flow Event to validate
 * the actions taken therein.
 * It has been coded so as to allow several different policies, by tweaking the values of:
 *
 * - BURN: a boolean, determining whether it is permitted to burn tokens away
 * - RELAYS: a string Set with the URLs of the preferred relays to use; consensus is required of at
 *     least MORE than half of them
 * - PRE_MINTED: a Set of outputs that are considered pre-minted and pre-assigned
 * - ALLOWED_MINTERS: a Set of pubkeys or prefixes thereof that are allowed to mint tokens
 *
 * Setting values for ALLOWED_MINTERS allows for the emission policy to be controlled tightly, only
 * allowing some, all, or none to add liquidity.
 * For extreme examples, consider:
 *
 * - ALLOWED_MINTERS = new Set(): this allows no-one to mint tokens, all tokens in existence are those
 *     provided in the PRE_MINTED array and none more (consequently, if the PRE_MINTED array is
 *     empty, these tokens basically become impossible to use at all)
 * - ALLOWED_MINTERS = new Set([""]): this allows everyone to mint tokens, since "" is a prefix of any
 *     pubkey, anyone can create liquidity
 *
 * Setting a value for PRE_MINTED makes it so that the given outputs are originally available, thus
 * it allows for emission outside of the dynamic control of ALLOWED_MINTERS.
 * This makes it possible to implement, eg, finite-supply tokens (setting ALLOWED_MINTERS to Set()).
 *
 * Usage merely requires adding a tag of the form:
 *
 *     ["v", "{VALIDATOR_MESSAGE_ID}"]
 *
 * to NOSTR Token Flow events.
 *
 */
 
const BURN = true;                  // whether burning Tokens is allowed
const RELAYS = new Set();           // a set of relay URLs to use
const PRE_MINTED = new Set();       // a set of pre-minted outputs
const ALLOWED_MINTERS = new Set();  // a set of pubkeys or prefixes that are indeed allowed to mint
 
/**
 * Check if two sets contain the same elements
 *
 * @param {Set} a - First set to compare
 * @param {Set} b - Second set to compare
 * @return {boolean}  True if both sets contain the same elements, false otherwise
 */
function equalSets(a, b) {
  return a.size === b.size && new Set([...a, ...b]).size === a.size;
}
 
/**
 * Calculate the SHA-256 of the given string, and return it as a hex string
 *
 * @param {string} data - The data to hash
 * @return {string}  The resulting hex string
 */
async function sha256toHex(data) {
  return Array.from(
      new Uint8Array(
        await crypto.subtle.digest(
          "SHA-256",
          (new TextEncoder()).encode(data),
        )
      )
    )
    .map(bytes => bytes.toString(16).padStart(2, "0"))
    .join("")
  ;
}
 
/**
 * Retrieve the valid NOSTR events selected by the given filter from the given relay
 *
 * @param {object[]} filters - Filter to apply
 * @param {string} relay - Relay to use
 * @return {object[]}  The resulting events
 */
function nostrReadValidated(filters, relay) {
  return NOSTR.read(filter, relay).filter(NOSTR.validate);
}
 
/**
 * Retrieve the NOSTR Token Flow events using the given input or output IDs, up until the given moment
 *
 * @param {"y"|"z"} tagName - the tag to search for
 * @param {number[]} ids - The input IDs to search for
 * @param {number} until - The maximum timestamp to consider
 * @return {object[]}  The resulting events
 */
function fetchFromRelays(tagName, ids, until) {
  const filter = [
    {
      "kinds": [1001],
      `#${tagName}`: ids,
      "until": until,
    }
  ];
 
  let entries = {};
  for (const relay of RELAYS) {
    for (const event of nostrReadValidated(filter, relay)) {
      if (!entries.has(event.id)) {
        entries[event.id] = {"count": 0, "event": event};
      }
      entries[event.id].count++;
    }
  }
 
  const limit = RELAYS.length >> 1;
 
  const deletionFilter = [
    {
      "kinds": [5],
      `#e`: [
        entries
          .values()
          .filter(entry => limit < entry.count)
          .map(entry => entry.event.id)
      ],
      "until": until,
    }
  ];
  for (const relay of RELAYS) {
    for (const event of nostrReadValidated(deletionFilter, relay)) {
      entries[event.id].count--;
    }
  }
 
  return entries
    .values()
    .filter(entry => limit < entry.count)
    .map(entry => entry.event)
  ;
}
 
/**
 * Retrieve the input blocks using the given input IDs, up until the given moment
 *
 * @param {number[]} ids - The input IDs to search for
 * @param {number} until - The maximum timestamp to consider
 * @return {object[]}  The input blocks using the given input IDs
 */
function fetchInputs(ids, until) {
  return fetchFromRelays("y", ids, until)
    .flatMap(event => JSON.parse(event.content).inputs)
    .filter(input => ids.has(input.id))
  ;
}
 
/**
 * Retrieve the output blocks using the given output IDs, up until the given moment
 *
 * @param {number[]} ids - The output IDs to search for
 * @param {number} until - The maximum timestamp to consider
 * @return {object[]}  The output blocks using the given output IDs
 */
function fetchOutputs(ids, until) {
  return fetchFromRelays("z", ids, until)
    .flatMap(event => JSON.parse(event.content).outputs)
    .concat(Array.from(PRE_MINTED))
    .filter(output => ids.has(output.id))
  ;
}
 
/**
 * Retrieve the set of first-values associated to the tag name given in the event given
 *
 * @param {string} tagName - The tag name to look for
 * @param {object} event - The event to extract tag values from
 * @return {Set}  The set of values
 */
function tagValues(tagName, event) {
  let result = new Set(
    events.tags
      .map(tag => tag[0] === tagName ? tag[1] : undefined)
  );
  result.delete(undefined);
  return result;
}
 
 
if (event.kind !== 1001) {  // verify that we're being run on a Token Flow event
  return false;             // fail if we're not
}                           //
 
const taggedInputs = tagValues("y", event);        // retrieve the set of all input tags
const taggedOutputs = tagValues("z", event);       // retrieve the set of all output tags
const taggedDestinations = tagValues("p", event);  // retrieve the set of all destination tags
 
let seenInputs = new Set();        // initialize seen inputs
let seenOutputs = new Set();       // initialize seen outputs
let seenDestinations = new Set();  // initialize seen destinations
 
const content = JSON.parse(event.content);  // parse the event's content
 
let total = 0;  // keep running total of how many funds are moved
 
for (const input of content.inputs) {                          // iterate through each input
  if (seenInputs.has(input.id)) {                              // verify the input ID is not repeated
    return false;                                              // fail if it is
  }                                                            //
  if ([] !== fetchInputs([input.id], event.created_at)) {      // verify that the input is not
    return false;                                              // already burnt, fail otherwise
  }                                                            //
  const outputs = fetchOutputs([input.id], event.created_at);  // retrieve all outputs associated to this input
  if (1 !== outputs.length) {                                  // verify there's only one of them
    return false;                                              // fail otherwise
  }                                                            //
  if (output[0].destination != event.pubkey) {                 // verify it's directed to us,
    return false;                                              // fail otherwise
  }                                                            //
  if (sha256toHex(input.nonce) != output[0].commitment) {      // verify it matches the commitment,
    return false;                                              // fail otherwise
  }                                                            //
  total++;                                                     // accumulate running total
  seenInputs.add(input.id);                                    // add the current input ID to the seen ones
}                                                              //
 
for (const output of content.outputs) {      // iterate through each output
  if (seenOutputs.has(output.id)) {          // verify the output ID is not repeated
    return false;                            // fail if it is
  }                                          //
  total--;                                   // decrease running total
  seenOutputs.add(output.id);                // add the current output ID to the seen ones
  seenDestinations.add(output.destination);  // add the destination ID to the seen ones
}                                            //
 
if (fetchOutputs(Array.from(seenOutputs), event.created_at) !== []) {  // make sure the newly-created outputs are new
  return false;                                                        // fail otherwise
}                                                                      //
 
if (!equalSets(taggedInputs, seenInputs)) {  // check that all seen inputs are tagged
  return false;                              // fail if not
}                                            //
 
if (!equalSets(taggedOutputs, seenOutputs)) {  // check that all seen outputs are tagged
  return false;                                // fail if not
}                                              //
 
if (!equalSets(taggedDestinations, seenDestinations)) {  // check that all seen destinations are tagged
  return false;                                          // fail if not
}                                                        //
 
if (total < 0) {                                                    // if we're minting tokens
  return Array.from(ALLOWED_MINTERS)                                // check that at least one allowed minter
    .some(allowedMinter => event.pubkey.startsWith(allowedMinter))  // is a prefix of the current pubkey
  ;                                                                 //
} else if (0 < total) {                                             // if we're burning tokens
  return BURN;                                                      // this is valid only if burning allowed
} else {                                                            // otherwise
  return true;                                                      // everything looks fine, validate
}                                                                   //

// Requires the "NostrRead", "NostrValidate", and "Async" capabilities
 
/**
 * NOSTR Token Ownership
 *
 * This generic NOSTR Token Ownership validator can be attached to a NOSTR Event to validate that the
 * event sender indeed has ownership of the given amount of NOSTR Tokens at the given moment.
 * It has been coded so as to interoperate with the NOSTR Tokens Validator above:
 *
 * - RELAYS: a string Set with the URLs of the preferred relays to use; consensus is required of at
 *     least MORE than half of them
 * - PRE_MINTED: a Set of outputs that are considered pre-minted and pre-assigned
 *
 * Setting a value for PRE_MINTED makes it so that the given outputs are originally available, it is
 * required to be in sync with the one in the corresponding NOSTR Tokens Validator.
 *
 * Usage merely requires adding a tag of the form:
 *
 *     ["v", "{VALIDATOR_MESSAGE_ID}", "{TOKEN_ID_1}", "{TOKEN_ID_2}", ..., "{TOKEN_ID_N}", ...]
 *
 * to NOSTR events.
 *
 */
 
const RELAYS = new Set();      // a set of relay URLs to use
const PRE_MINTED = new Set();  // a set of pre-minted outputs
 
/**
 * Retrieve the valid NOSTR events selected by the given filter from the given relay
 *
 * @param {object[]} filters - Filter to apply
 * @param {string} relay - Relay to use
 * @return {object[]}  The resulting events
 */
function nostrReadValidated(filters, relay) {
  return NOSTR.read(filter, relay).filter(NOSTR.validate);
}
 
/**
 * Retrieve the NOSTR Token Flow events using the given input or output IDs, up until the given moment
 *
 * @param {"y"|"z"} tagName - the tag to search for
 * @param {number[]} ids - The input IDs to search for
 * @param {number} until - The maximum timestamp to consider
 * @return {object[]}  The resulting events
 */
function fetchFromRelays(tagName, ids, until) {
  const filter = [
    {
      "kinds": [1001],
      `#${tagName}`: ids,
      "until": until,
    }
  ];
 
  let entries = {};
  for (const relay of RELAYS) {
    for (const event of nostrReadValidated(filter, relay)) {
      if (!entries.has(event.id)) {
        entries[event.id] = {"count": 0, "event": event};
      }
      entries[event.id].count++;
    }
  }
 
  const limit = RELAYS.length >> 1;
 
  const deletionFilter = [
    {
      "kinds": [5],
      `#e`: [
        entries
          .values()
          .filter(entry => limit < entry.count)
          .map(entry => entry.event.id)
      ],
      "until": until,
    }
  ];
  for (const relay of RELAYS) {
    for (const event of nostrReadValidated(deletionFilter, relay)) {
      entries[event.id].count--;
    }
  }
 
  return entries
    .values()
    .filter(entry => limit < entry.count)
    .map(entry => entry.event)
  ;
}
 
/**
 * Retrieve the input blocks using the given input IDs, up until the given moment
 *
 * @param {number[]} ids - The input IDs to search for
 * @param {number} until - The maximum timestamp to consider
 * @return {object[]}  The input blocks using the given input IDs
 */
function fetchInputs(ids, until) {
  return fetchFromRelays("y", ids, until)
    .flatMap(event => JSON.parse(event.content).inputs)
    .filter(input => ids.has(input.id))
  ;
}
 
/**
 * Retrieve the output blocks using the given output IDs, up until the given moment
 *
 * @param {number[]} ids - The output IDs to search for
 * @param {number} until - The maximum timestamp to consider
 * @return {object[]}  The output blocks using the given output IDs
 */
function fetchOutputs(ids, until) {
  return fetchFromRelays("z", ids, until)
    .flatMap(event => JSON.parse(event.content).outputs)
    .concat(Array.from(PRE_MINTED))
    .filter(output => ids.has(output.id))
  ;
}
 
 
const tokenIdsClean = Set(args);                          // remove duplicates from input token IDs
const outputs = fetchOutputs(                             // retrieve all outputs generating these
    Array.from(tokenIdsClean),                            // token IDs
    event.created_at                                      //
  )                                                       //
  .filter(output => output.destination === event.pubkey)  // keep only those that come our way
;                                                         //
 
if (outputs.length !== tokenIdsClean.length) {  // verify we have them all
  return false;                                 // fail otherwise
}                                               //
 
if (fetchInputs(Array.from(tokenIdsClean), event.created_at) !== []) {  // verify no inputs are used
  return false;                                                         // fail otherwise
}                                                                       //
 
return true;  // if we got here, everything is fine

[
  "v",
  "{OWNERSHIP_ATTESTATION_VALIDATOR_EVENT_ID}",
  "{TOKEN_ID}",
  ...
]

return false;

/**
 * Coalesce the given datum, by using the given replacement when it equals the given sentinel
 *
 * @param {a} datum - Datum to coalesce
 * @param {a} sentinel - The sentinel to trigger replacement
 * @param {a} replacement - The replacement value
 * @return {a}  The result of the coalescing operation
 */
function coalesce(datum, sentinel, replacement) {
  return datum === sentinel ? replacement : datum;
}
 
 
const pRelays = new Set(            // scan all "p" tags and extract the associated relays
  event.tags                        //
    .filter(tag => tag[0] === "p")  //
    .map(tag => tag[2])             //
);                                  //
 
const eRelays = new Set(            // scan all "e" tags and extract the associated relays
  event.tags                        //
    .filter(tag => tag[0] === "e")  //
    .map(tag => tag[2])             //
);                                  //
 
const valueMaximum = event.tags                 // although NIP-69 is unclear as to how to manage
  .filter(tag => tag[0] === "value_maximum")    // multiple "value_maximum" tags, we take the conservative
  .map(tag => tag[1])                           // approach and consider multiple "value_maximum" tags as
  .reduce((a, b) => Math.max(a, b), -Infinity)  // describing differing amounts,
;                                               // keeping only the highest of them
 
const valueMinimum = event.tags                // although NIP-69 is unclear as to how to manage
  .filter(tag => tag[0] === "value_minimum")   // multiple "value_minimum" tags, we take the conservative
  .map(tag => tag[1])                          // approach and consider multiple "value_minimum" tags as
  .reduce((a, b) => Math.min(a, b), Infinity)  // describing differing amounts,
;                                              // keeping only the lowest of them
 
const consensusThreshold = event.tags               // although NIP-69 is unclear as to how to manage
  .filter(tag => tag[0] === "consensus_threshold")  // multiple "consensus_threshold" tags, we take the conservative
  .map(tag => tag[1])                               // approach and consider multiple "consensus_threshold" tags as
  .reduce((a, b) => Math.max(a, b), -Infinity)      // describing differing timestamps,
;                                                   // keeping only the highest of them
 
// clamp to usable values
const usableMaximumValue       = coalesce(valueMaximum      , -Infinity, Infinity);
const usableMinimumValue       = coalesce(valueMinimum      ,  Infinity,        0);
const usableConsensusThreshold = coalesce(consensusThreshold, -Infinity,        0);
 
const closedAt = event.tags                    // although NIP-69 is unclear as to how to manage
  .filter(tag => tag[0] === "closed_at")       // multiple "closed_at" tags, we take the conservative
  .map(tag => tag[1])                          // approach and consider multiple "closed_at" tags as
  .reduce((a, b) => Math.min(a, b), Infinity)  // describing differing timestamps,
;                                              // keeping only the lowest of them
 
const pollOptions = event.tags              // extract all "poll_option" tag values
  .filter(tag => tag[0] === "poll_option")  //
  .map(tag => tag[1])                       //
;                                           //
 
// check that if any "p" or "e" tags exist, they specify a single relay,
// additionally, if they both do, check that they're equal
if (pRelays.size) {
  if (pRelays.size !== 1) {
    return false;
  }
  if (eRelays.size) {
    if (eRelays.size !== 1 || Array.from(pRelays)[0] !== Array.from(eRelays)[0]) {
      return false;
    }
  }
} else if (eRelays.size) {
  if (eRelays.size !== 1) {
    return false;
  }
}
 
return event.content !== ""                              // check that the content is not empty
  && 0 <= usableMinimumValue                             // check that the minimum value is positive
  && usableMinimumValue <= usableMaximumValue            // and at most the maximum value
  && 0 <= usableConsensusThreshold                       // check that the consensus threshold
  && usableConsensusThreshold <= 100                     // is between 0 and 100
  && event.created_at < closedAt                         // check that the poll has life to live
  && pollOptions.length === (new Set(pollOptions)).size  // check that there are no repeated poll options
  && 2 <= pollOptions.length                             // and that there are at least 2 of them
;                                                        //

if (!args.every(                         // check that the given validators are in order and non-repeating
  (x, i) => 0 === i || args[i - 1] < x)  //
) {                                      //
  return false;                          //
}                                        //
 
const attachedValidators = new Set(  // extract all actually attached validators
  event.tags                         //
    .filter(tag => tag[0] === "v")   //
    .map(tag => tag[1])              //
);                                   //
 
for (const arg of args) {              // check that all required validators
  if (!attachedValidators.has(arg)) {  // are indeed attached to this event
    return false;                      // and fail if not
  }                                    //
}                                      //
 
return true;  // everything looks fine

[
  "v",
  "{COMPOSITIONAL_VALIDATOR_EVENT_ID}",
  "{REQUIRED_VALIDATOR_EVENT_ID}",
  ...
]

const NON_DELETABLE_KINDS = new Set([5, 1111, /* ... */]);
 
return NON_DELETABLE_KINDS.has(event.kind) || Nostr.read([
  {
    "kinds": [5],
    "#e": event.id,
    "authors": [event.pubkey],
  }
]).length === 0;

/**
 * Retrieve the valid NOSTR events selected by the given filter
 *
 * @param {object[]} filters - Filter to apply
 * @return {object[]}  The resulting events
 */
function nostrReadValidated(filters) {
  return NOSTR.read(filter).filter(NOSTR.validate);
}
 
 
const NON_DELETABLE_KINDS = new Set([1111, /* ... */]);
 
return NON_DELETABLE_KINDS.has(event.kind) || nostrReadValidated([
  {
    "kinds": [5],
    "#e": event.id,
    "authors": [event.pubkey],
  }
]).length === 0;