Allow inscriptions to nominate a delegate (ordinals#2912)

torkelrogstad · Mar 11, 2024 · 03d1c98 · 03d1c98
1 parent b3cab9e
commit 03d1c98
Show file tree

Hide file tree

Showing 10 changed files with 215 additions and 59 deletions.
diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md
@@ -5,10 +5,11 @@ Summary
 - [Overview](overview.md)
 - [Digital Artifacts](digital-artifacts.md)
 - [Inscriptions](inscriptions.md)
+  - [Delegate](inscriptions/delegate.md)
   - [Metadata](inscriptions/metadata.md)
+  - [Pointer](inscriptions/pointer.md)
   - [Provenance](inscriptions/provenance.md)
   - [Recursion](inscriptions/recursion.md)
-  - [Pointer](inscriptions/pointer.md)
 - [FAQ](faq.md)
 - [Contributing](contributing.md)
 - [Donate](donate.md)

diff --git a/docs/src/inscriptions.md b/docs/src/inscriptions.md
@@ -79,11 +79,12 @@ two data pushes, a tag and a value.
 Currently, there are six defined fields:
 
 - `content_type`, with a tag of `1`, whose value is the MIME type of the body.
-- `pointer`, with a tag of `2`, see [pointer docs](./inscriptions/pointer.md).
-- `parent`, with a tag of `3`, see [provenance](./inscriptions/provenance.md).
-- `metadata`, with a tag of `5`, see [metadata](./inscriptions/metadata.md).
+- `pointer`, with a tag of `2`, see [pointer docs](inscriptions/pointer.md).
+- `parent`, with a tag of `3`, see [provenance](inscriptions/provenance.md).
+- `metadata`, with a tag of `5`, see [metadata](inscriptions/metadata.md).
 - `metaprotocol`, with a tag of `7`, whose value is the metaprotocol identifier.
 - `content_encoding`, with a tag of `9`, whose value is the encoding of the body.
+- `delegate`, with a tag of `11`, see [delegate](inscriptions/delegate.md).
 
 The beginning of the body and end of fields is indicated with an empty data
 push.

diff --git a/docs/src/inscriptions/delegate.md b/docs/src/inscriptions/delegate.md
@@ -0,0 +1,39 @@
+Delegate
+========
+
+Inscriptions may nominate a delegate inscription. Requests for the content of
+an inscription with a delegate will instead return the content and content type
+of the delegate. This can be used to cheaply create copies of an inscription.
+
+### Specification
+
+To create an inscription I with delegate inscription D:
+
+- Create an inscription D. Note that inscription D does not have to exist when
+  making inscription I. It may be inscribed later. Before inscription D is
+  inscribed, requests for the content of inscription I will return a 404.
+- Include tag `11`, i.e. `OP_PUSH 11`, in I, with the value of the serialized
+  binary inscription ID of D, serialized as the 32-byte `TXID`, followed by the
+  four-byte little-endian `INDEX`, with trailing zeroes omitted.
+
+_NB_ The bytes of a bitcoin transaction ID are reversed in their text
+representation, so the serialized transaction ID will be in the opposite order.
+
+### Example
+
+An example of an inscription which delegates to
+`000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1fi0`:
+
+```
+OP_FALSE
+OP_IF
+  OP_PUSH "ord"
+  OP_PUSH 11
+  OP_PUSH 0x1f1e1d1c1b1a191817161514131211100f0e0d0c0b0a09080706050403020100
+OP_ENDIF
+```
+
+Note that the value of tag `11` is binary, not hex.
+
+The delegate field value uses the same encoding as the parent field. See
+[provenance](provenance.md) for more examples of inscrpition ID encodings;
diff --git a/src/envelope.rs b/src/envelope.rs
@@ -23,6 +23,9 @@ pub(crate) const PARENT_TAG: [u8; 1] = [3];
 pub(crate) const METADATA_TAG: [u8; 1] = [5];
 pub(crate) const METAPROTOCOL_TAG: [u8; 1] = [7];
 pub(crate) const CONTENT_ENCODING_TAG: [u8; 1] = [9];
+pub(crate) const DELEGATE_TAG: [u8; 1] = [11];
+#[allow(unused)]
+pub(crate) const NOP_TAG: [u8; 1] = [255];
 
 type Result<T> = std::result::Result<T, script::Error>;
 type RawEnvelope = Envelope<Vec<Vec<u8>>>;
@@ -89,6 +92,7 @@ impl From<RawEnvelope> for ParsedEnvelope {
 
     let content_encoding = remove_field(&mut fields, &CONTENT_ENCODING_TAG);
     let content_type = remove_field(&mut fields, &CONTENT_TYPE_TAG);
+    let delegate = remove_field(&mut fields, &DELEGATE_TAG);
     let metadata = remove_and_concatenate_field(&mut fields, &METADATA_TAG);
     let metaprotocol = remove_field(&mut fields, &METAPROTOCOL_TAG);
     let parent = remove_field(&mut fields, &PARENT_TAG);
@@ -109,6 +113,7 @@ impl From<RawEnvelope> for ParsedEnvelope {
         }),
         content_encoding,
         content_type,
+        delegate,
         duplicate_field,
         incomplete_field,
         metadata,
@@ -455,7 +460,7 @@ mod tests {
         b"ord",
         &[1],
         b"text/plain;charset=utf-8",
-        &[11],
+        &NOP_TAG,
         b"bar",
         &[],
         b"ord",
@@ -785,7 +790,7 @@ mod tests {
   #[test]
   fn unknown_odd_fields_are_ignored() {
     assert_eq!(
-      parse(&[envelope(&[b"ord", &[11], &[0]])]),
+      parse(&[envelope(&[b"ord", &NOP_TAG, &[0]])]),
       vec![ParsedEnvelope {
         payload: Inscription::default(),
         ..Default::default()

diff --git a/src/index.rs b/src/index.rs
@@ -4780,7 +4780,7 @@ mod tests {
           Inscription {
             content_type: Some("text/plain".into()),
             body: Some("hello".into()),
-            parent: Some(parent_inscription_id.parent_value()),
+            parent: Some(parent_inscription_id.value()),
             ..Default::default()
           }
           .to_witness(),
@@ -4827,7 +4827,7 @@ mod tests {
           Inscription {
             content_type: Some("text/plain".into()),
             body: Some("hello".into()),
-            parent: Some(parent_inscription_id.parent_value()),
+            parent: Some(parent_inscription_id.value()),
             ..Default::default()
           }
           .to_witness(),
@@ -4881,7 +4881,7 @@ mod tests {
             Inscription {
               content_type: Some("text/plain".into()),
               body: Some("hello".into()),
-              parent: Some(parent_inscription_id.parent_value()),
+              parent: Some(parent_inscription_id.value()),
               ..Default::default()
             }
             .to_witness(),
@@ -4935,7 +4935,7 @@ mod tests {
             Inscription {
               content_type: Some("text/plain".into()),
               body: Some("hello".into()),
-              parent: Some(parent_inscription_id.parent_value()),
+              parent: Some(parent_inscription_id.value()),
               ..Default::default()
             }
             .to_witness(),
@@ -4991,7 +4991,7 @@ mod tests {
             body: Some("hello".into()),
             parent: Some(
               parent_inscription_id
-                .parent_value()
+                .value()
                 .into_iter()
                 .chain(iter::once(0))
                 .collect(),
@@ -5176,7 +5176,7 @@ mod tests {
       let child_inscription = Inscription {
         content_type: Some("text/plain".into()),
         body: Some("pointer-child".into()),
-        parent: Some(parent_inscription_id.parent_value()),
+        parent: Some(parent_inscription_id.value()),
         pointer: Some(0u64.to_le_bytes().to_vec()),
         ..Default::default()
       };

diff --git a/src/inscription.rs b/src/inscription.rs
@@ -19,6 +19,7 @@ pub struct Inscription {
   pub body: Option<Vec<u8>>,
   pub content_encoding: Option<Vec<u8>>,
   pub content_type: Option<Vec<u8>>,
+  pub delegate: Option<Vec<u8>>,
   pub duplicate_field: bool,
   pub incomplete_field: bool,
   pub metadata: Option<Vec<u8>>,
@@ -102,7 +103,7 @@ impl Inscription {
       content_encoding,
       metadata,
       metaprotocol: metaprotocol.map(|metaprotocol| metaprotocol.into_bytes()),
-      parent: parent.map(|id| id.parent_value()),
+      parent: parent.map(|id| id.value()),
       pointer: pointer.map(Self::pointer_value),
       ..Default::default()
     })
@@ -151,6 +152,12 @@ impl Inscription {
         .push_slice(PushBytesBuf::try_from(parent).unwrap());
     }
 
+    if let Some(delegate) = self.delegate.clone() {
+      builder = builder
+        .push_slice(envelope::DELEGATE_TAG)
+        .push_slice(PushBytesBuf::try_from(delegate).unwrap());
+    }
+
     if let Some(pointer) = self.pointer.clone() {
       builder = builder
         .push_slice(envelope::POINTER_TAG)
@@ -197,6 +204,41 @@ impl Inscription {
     Inscription::append_batch_reveal_script_to_builder(inscriptions, builder).into_script()
   }
 
+  fn inscription_id_field(field: &Option<Vec<u8>>) -> Option<InscriptionId> {
+    let value = field.as_ref()?;
+
+    if value.len() < Txid::LEN {
+      return None;
+    }
+
+    if value.len() > Txid::LEN + 4 {
+      return None;
+    }
+
+    let (txid, index) = value.split_at(Txid::LEN);
+
+    if let Some(last) = index.last() {
+      // Accept fixed length encoding with 4 bytes (with potential trailing zeroes)
+      // or variable length (no trailing zeroes)
+      if index.len() != 4 && *last == 0 {
+        return None;
+      }
+    }
+
+    let txid = Txid::from_slice(txid).unwrap();
+
+    let index = [
+      index.first().copied().unwrap_or(0),
+      index.get(1).copied().unwrap_or(0),
+      index.get(2).copied().unwrap_or(0),
+      index.get(3).copied().unwrap_or(0),
+    ];
+
+    let index = u32::from_le_bytes(index);
+
+    Some(InscriptionId { txid, index })
+  }
+
   pub(crate) fn media(&self) -> Media {
     if self.body.is_none() {
       return Media::Unknown;
@@ -229,6 +271,10 @@ impl Inscription {
     HeaderValue::from_str(str::from_utf8(self.content_encoding.as_ref()?).unwrap_or_default()).ok()
   }
 
+  pub(crate) fn delegate(&self) -> Option<InscriptionId> {
+    Self::inscription_id_field(&self.delegate)
+  }
+
   pub(crate) fn metadata(&self) -> Option<Value> {
     ciborium::from_reader(Cursor::new(self.metadata.as_ref()?)).ok()
   }
@@ -238,38 +284,7 @@ impl Inscription {
   }
 
   pub(crate) fn parent(&self) -> Option<InscriptionId> {
-    let value = self.parent.as_ref()?;
-
-    if value.len() < Txid::LEN {
-      return None;
-    }
-
-    if value.len() > Txid::LEN + 4 {
-      return None;
-    }
-
-    let (txid, index) = value.split_at(Txid::LEN);
-
-    if let Some(last) = index.last() {
-      // Accept fixed length encoding with 4 bytes (with potential trailing zeroes)
-      // or variable length (no trailing zeroes)
-      if index.len() != 4 && *last == 0 {
-        return None;
-      }
-    }
-
-    let txid = Txid::from_slice(txid).unwrap();
-
-    let index = [
-      index.first().copied().unwrap_or(0),
-      index.get(1).copied().unwrap_or(0),
-      index.get(2).copied().unwrap_or(0),
-      index.get(3).copied().unwrap_or(0),
-    ];
-
-    let index = u32::from_le_bytes(index);
-
-    Some(InscriptionId { txid, index })
+    Self::inscription_id_field(&self.parent)
   }
 
   pub(crate) fn pointer(&self) -> Option<u64> {
@@ -505,6 +520,26 @@ mod tests {
     .is_none());
   }
 
+  #[test]
+  fn inscription_delegate_txid_is_deserialized_correctly() {
+    assert_eq!(
+      Inscription {
+        delegate: Some(vec![
+          0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08, 0x09, 0x0a, 0x0b, 0x0c, 0x0d, 0x0e,
+          0x0f, 0x10, 0x11, 0x12, 0x13, 0x14, 0x15, 0x16, 0x17, 0x18, 0x19, 0x1a, 0x1b, 0x1c, 0x1d,
+          0x1e, 0x1f,
+        ]),
+        ..Default::default()
+      }
+      .delegate()
+      .unwrap()
+      .txid,
+      "1f1e1d1c1b1a191817161514131211100f0e0d0c0b0a09080706050403020100"
+        .parse()
+        .unwrap()
+    );
+  }
+
   #[test]
   fn inscription_parent_txid_is_deserialized_correctly() {
     assert_eq!(

diff --git a/src/inscription_id.rs b/src/inscription_id.rs
@@ -16,7 +16,7 @@ impl Default for InscriptionId {
 }
 
 impl InscriptionId {
-  pub(crate) fn parent_value(self) -> Vec<u8> {
+  pub(crate) fn value(self) -> Vec<u8> {
     let index = self.index.to_le_bytes();
     let mut index_slice = index.as_slice();