Package com.frostwire.jlibtorrent

Class SessionManager.MutableItem

java.lang.Object
com.frostwire.jlibtorrent.SessionManager.MutableItem
Enclosing class:
SessionManager
public static final class SessionManager.MutableItem extends Object
Mutable DHT item with signature and sequence number.

MutableItem represents a mutable distributed hash table (DHT) item retrieved from the DHT network. Mutable items are identified by a public key and can be updated by the key owner. Each item includes the data, a digital signature proving ownership, and a sequence number for versioning.

Understanding Mutable DHT Items:
BitTorrent's DHT supports two types of items:

  • Immutable Items: Identified by SHA-1 hash, immutable, no ownership
  • Mutable Items: Identified by public key, updateable, signed by owner
Mutable items allow key holders to publish data that can be updated over time.

Item Structure:

  • item: Bencoded Entry containing the actual data
  • signature: Ed25519 signature proving key holder's ownership
  • seq: Sequence number for versioning (causally ordered updates)

Retrieving Mutable Items: 

 // Retrieve a mutable DHT item by public key
 byte[] publicKey = ...; // Ed25519 public key (32 bytes)
 byte[] salt = ...; // Optional salt (empty byte array if unused)

 SessionManager sm = new SessionManager();
 sm.start();

 // Request item from DHT
 sm.dhtGetItem(publicKey, salt);

 // Listen for response
 sm.addListener(new AlertListener() {
     public int[] types() {
         return new int[] {AlertType.DHT_MUTABLE_ITEM.swig()};
     }

     public void alert(Alert<?> alert) {
         DhtMutableItemAlert mia = (DhtMutableItemAlert) alert;
         SessionManager.MutableItem item = mia.item();

         // Access the item data
         Entry data = item.item;
         byte[] signature = item.signature;
         long version = item.seq;
     }
 });

Verifying Item Authenticity:

The signature field contains an Ed25519 signature of the item data and sequence number. The signature proves that only the holder of the corresponding private key could have created or updated this item.

Sequence Number:

The sequence number ensures causally ordered updates. A newer item has a higher sequence number. DHT nodes use this to detect which version is newest and accept updates with higher sequence numbers. 

 SessionManager.MutableItem item = ...;

 // Version information
 long version = item.seq;
 System.out.println(\"Item version: \" + version);

 // Newer items have higher sequence numbers
 if (newItem.seq > oldItem.seq) {
     System.out.println(\"newItem is newer\");
 }

Publishing Updates: 

 // To publish a new version (requires private key)
 byte[] newData = bencodeData(...);
 long newSeq = existingItem.seq + 1;
 byte[] signature = signData(newData, newSeq, privateKey);

 // Call dhtPutItem() with new data, signature, and sequence
 sm.dhtPutItem(publicKey, newData, signature, newSeq, salt);

Public Key Format:

The public key is a 32-byte Ed25519 key. To identify a mutable item, combine the public key with the optional salt to create a unique content ID within the DHT.

Performance Notes:

  • Retrieval is asynchronous; DHT queries typically complete within 10-30 seconds
  • Signature verification is performed by DHT nodes before storing
  • Updates with identical or lower sequence numbers are rejected
  • Storage is replicated across DHT nodes for redundancy
See Also:

  • Field Details

    • item

      public final Entry item
      The bencoded item data stored in the DHT.

    • signature

      public final byte[] signature
      Ed25519 signature proving ownership and authenticity of the item. The signature is computed over the serialized item and sequence number.

    • seq

      public final long seq
      Version number of this item (sequence number). Higher sequence numbers indicate newer versions. Used to detect and reject stale updates.