From 2afb1287a2b90a6a678f09f8bf20fe82a1157444 Mon Sep 17 00:00:00 2001
From: Eric McCarthy <7607035+bendyarm@users.noreply.github.com>
Date: Tue, 21 Jan 2025 15:20:09 -0800
Subject: [PATCH] add some wrapped ops and some notes

Added `div.w.wrapped` and `rem.w.wrapped`.
Added `assert.eq` and `assert.neq`, but with a comment that we don't need separate flagged versions.
Added a notes column and some notes for some opcodes.

Signed-off-by: Eric McCarthy <7607035+bendyarm@users.noreply.github.com>
---
 arc-0004/README.md | 27 +++++++++++++++++----------
 1 file changed, 17 insertions(+), 10 deletions(-)

diff --git a/arc-0004/README.md b/arc-0004/README.md
index 05656f6..eccd4df 100644
--- a/arc-0004/README.md
+++ b/arc-0004/README.md
@@ -26,9 +26,12 @@ corresponding to the Aleo Instructions that can halt.
 
 ## Specification
 
-Each flagged operation is identical to the current halting instruction
-except it doesn't halt and it returns another return value that is a
-boolean.
+Each flagged operation is identical to its corresponding current operation
+when called with arguments that would be nonhalting, except it returns
+a second return value of type boolean that is **false** (meaning that the
+current operation would not have halted).  When called with arguments
+that would have been halting, it generally returns 0 (of the appropriate
+output type) and **true** ("would have halted") for the second return value.
 
 The flagged operations are different from wrapped (e.g. `abs.w`) or
 lossy (e.g. `cast.lossy`) operations.  It is important that the flagged
@@ -36,18 +39,21 @@ operation have the same semantics as the current halting instruction
 except for the halting behavior and extra return value, for ease of
 use by compilers.
 
-| Current Halting Opcode | New Flagged Opcode |
-|:-------------------:|:-----------------------:|
+| Current Halting Opcode | New Flagged Opcode | notes |
+|:-------------------:|:-----------------------:|:--------------------------:|
 | abs | abs.flagged |
 | add | add.flagged |
-| cast | cast.flagged |
+| assert.eq | is.eq | We don't need a separate assert.(n)eq.flagged;
+| assert.neq | is.neq | instead, just use the existing is.(n)eq
+| cast | cast.flagged | as of now, docs don't say what causes cast to halt
 | commit.bhp256 | commit.bhp256.flagged |
 | commit.bhp512 | commit.bhp512.flagged |
 | commit.bhp768 | commit.bhp768.flagged |
 | commit.bhp768 | commit.bhp1024.flagged |
 | commit.ped64 | commit.ped64.flagged |
 | commit.ped128 | commit.ped128.flagged |
-| div | div.flagged |
+| div | div.flagged | div can halt on underflow and divide by zero
+| div.w | div.w.flagged | div.w can halt on divide by zero
 | hash.bhp256 | hash.bhp256.flagged |
 | hash.bhp512 | hash.bhp512.flagged |
 | hash.bhp768 | hash.bhp768.flagged |
@@ -59,9 +65,10 @@ use by compilers.
 | mul | mul.flagged |
 | neg | neg.flagged |
 | pow | pow.flagged |
-| rem | rem.flagged |
-| shl | shl.flagged |
-| shr | shr.flagged |
+| rem | rem.flagged | rem can halt on underflow and divide by zero
+| rem.w | rem.w.flagged | rem.w can halt on divide by zero
+| shl | shl.flagged | as of now, docs don't say what causes
+| shr | shr.flagged | shl or shr to halt
 | sqrt | sqrt.flagged |
 | sub | sub.flagged |