feat(iota): allow // comments in iota client ptb commands

crates/iota/src/client_ptb/lexer.rs

@@ -54,6 +54,31 @@ impl<'l, I: Iterator<Item = &'l str>> Lexer<'l, I> {
         }
     }
 
+    /// Skip the rest of the current shell token (used for comments).
+    fn skip_rest_of_token(&mut self) {
+        let len = self.buf.len();
+        self.offset += len;
+        self.buf = "";
+    }
+
+    /// Skip comment tokens until we hit a command (starts with --) or EOF.
+    /// This handles multi-word comments like "// this is a comment".
+    fn skip_comment(&mut self) {
+        self.skip_rest_of_token();
+        // Skip subsequent tokens until we hit a command or EOF
+        for next in self.tokens.by_ref() {
+            self.offset += next.len() + 1; // +1 for space between tokens
+            if next.starts_with("--") || next.starts_with("//") {
+                // Found next command or another comment, set buffer to this token
+                self.buf = next;
+                return;
+            }
+            // Otherwise skip this token (it's part of the comment)
+        }
+        // Reached EOF
+        self.buf = "";
+    }
+
     /// Checks whether the current shell token starts with the prefix `patt`,
     /// and consumes it if so, returning a spanned slice of the consumed
     /// prefix.
@@ -226,6 +251,13 @@ impl<'l, I: Iterator<Item = &'l str>> Iterator for Lexer<'l, I> {
         }
 
         Some(match c {
+            // Comment: skip all tokens until we hit a command (--) or EOF
+            // Using // style comments as they work with shell line continuations
+            sp!(_, "/") if self.buf.starts_with("//") => {
+                self.skip_comment();
+                return self.next();
+            }
+
             // Single character tokens
             sp!(_, ",") => token!(T::Comma),
             sp!(_, "[") => token!(T::LBracket),
@@ -518,4 +550,25 @@ mod tests {
         let unexpected = vec!["4 * 5"];
         insta::assert_debug_snapshot!(lex(unexpected));
     }
+
+    #[test]
+    fn slash_comments() {
+        // C-style // comments work with shell line continuations
+        // Each word becomes a separate shell token, so we test multi-word comments
+        let with_slash_comments = vec![
+            "//",
+            "this",
+            "is",
+            "a",
+            "comment",
+            "--split-coins",
+            "gas",
+            "[1000]",
+            "//another",
+            "comment",
+            "--assign",
+            "result",
+        ];
+        insta::assert_debug_snapshot!(lex(with_slash_comments));
+    }
 }

crates/iota/src/client_ptb/ptb.rs

@@ -342,6 +342,7 @@ pub fn ptb_description() -> clap::Command {
         .about(
             "Build, preview, and execute programmable transaction blocks. Depending on your \
             shell, you might have to use quotes around arrays or other passed values. \
+            Use // for comments (with trailing \\). \
             Use --help to see examples for how to use the core functionality of this command.")
         .arg(arg!(
                 --"assign" <ASSIGN>

crates/iota/src/client_ptb/snapshots/iota__client_ptb__lexer__tests__slash_comments.snap

@@ -0,0 +1,87 @@
+---
+source: crates/iota/src/client_ptb/lexer.rs
+assertion_line: 572
+expression: lex(with_slash_comments)
+---
+[
+    Spanned {
+        span: Span {
+            start: 34,
+            end: 47,
+        },
+        value: Lexeme(
+            Command,
+            "split-coins",
+        ),
+    },
+    Spanned {
+        span: Span {
+            start: 48,
+            end: 51,
+        },
+        value: Lexeme(
+            Ident,
+            "gas",
+        ),
+    },
+    Spanned {
+        span: Span {
+            start: 52,
+            end: 53,
+        },
+        value: Lexeme(
+            LBracket,
+            "[",
+        ),
+    },
+    Spanned {
+        span: Span {
+            start: 53,
+            end: 57,
+        },
+        value: Lexeme(
+            Number,
+            "1000",
+        ),
+    },
+    Spanned {
+        span: Span {
+            start: 57,
+            end: 58,
+        },
+        value: Lexeme(
+            RBracket,
+            "]",
+        ),
+    },
+    Spanned {
+        span: Span {
+            start: 85,
+            end: 93,
+        },
+        value: Lexeme(
+            Command,
+            "assign",
+        ),
+    },
+    Spanned {
+        span: Span {
+            start: 94,
+            end: 100,
+        },
+        value: Lexeme(
+            Ident,
+            "result",
+        ),
+    },
+    Spanned {
+        span: Span {
+            start: 100,
+            end: 100,
+        },
+        value: Lexeme(
+            Eof,
+            "",
+        ),
+    },
+]

docs/content/developer/references/cli/ptb.mdx

@@ -15,7 +15,7 @@ The `client ptb` command allows you to specify the transactions for execution in
 The following list itemizes all the available args for the `iota client ptb` command. Use the `--help` for a long help version that includes some examples on how to use this command.
 
 ```
-Build, preview, and execute programmable transaction blocks. Depending on your shell, you might have to use quotes around arrays or other passed values. Use --help to see examples for how to use the core functionality of this command.
+Build, preview, and execute programmable transaction blocks. Depending on your shell, you might have to use quotes around arrays or other passed values. Use // for comments (with trailing \). Use --help to see examples for how to use the core functionality of this command.
 
 Usage: iota client ptb [OPTIONS]
 
@@ -127,6 +127,29 @@ Here are some examples for `transfer-objects` and `gas-coin`:
 iota client ptb --transfer-objects [ARRAY_OF_OBJECTS] @0x02a212de6a9dfa3a69e22387acfbafbb1a9e591bd9d636e7895dcfc8de05f331 --gas-coin @0x00002819ee07a66e53800495ccf5eeade8a02054a2e0827546c70e4b226f0495
 ```
 
+### Comments
+
+You can add comments to multi-line PTB commands using `//` (with trailing `\`). This is useful for documenting complex transaction blocks:
+
+```bash
+iota client ptb \
+// Get the sender address \
+--move-call iota::tx_context::sender \
+--assign sender \
+// Split 1 NANOS from gas coin \
+--split-coins gas "[1]" \
+--assign coin \
+// Transfer the new coin to the sender \
+--transfer-objects "[coin]" sender \
+--dry-run
+```
+
+:::note
+
+Use `//` for comments instead of `#`. The `#` character is interpreted by bash/zsh as a shell comment, which breaks line continuations. Remember to add `\` at the end of comment lines to continue the command.
+
+:::
+
 ### Assign
 
 Use the `--assign` argument to bind values to variables. There are two ways you can use it: