@decentnetwork/peer 0.1.140 → 0.1.142

package/dist/compat/dnft1.d.ts

@@ -0,0 +1,62 @@
+/** "\u{1E}DNFT1" — the leading bytes of every frame. */
+export declare const DNFT1_MAGIC: Uint8Array<ArrayBuffer>;
+/** magic(6) + packetId(1) + payloadLen(4). */
+export declare const DNFT1_HEADER_LENGTH = 11;
+/** Wrap one file-transfer packet payload in a DNFT1 frame. */
+export declare function encodeDnft1Frame(packetId: number, payload: Uint8Array): Uint8Array;
+/**
+ * Parse a DNFT1 frame out of a received message body.
+ *
+ * Returns null for anything that is not a file-transfer frame (ordinary chat
+ * data — the common case, so this must stay cheap), and for a frame truncated
+ * below its declared payload length: dropped rather than half-parsed, since a
+ * short read would hand the engine a chunk with missing bytes. Bytes past
+ * payloadLen are transport junk and are ignored.
+ */
+export declare function parseDnft1Frame(raw: Uint8Array): {
+    packetId: number;
+    payload: Uint8Array;
+} | null;
+/**
+ * Picks the transport for each friend's file packets: raw messenger packets
+ * (a JS peer, which is faster — no envelope, no message-channel framing) or
+ * DNFT1 frames (a native peer, the only thing that reaches its app layer).
+ *
+ * There is no reliable capability handshake to key this off — appVersion is
+ * absent for older builds and lies across forks — so the mode is LEARNED from
+ * what actually works, which needs no negotiation and self-corrects:
+ *
+ *   - The engine already retransmits an unanswered OFFER until the receiver
+ *     responds. Every UNANSWERED_OFFERS_BEFORE_SWITCH of those with no inbound
+ *     file packet flips the transport. Alternating (rather than a one-way
+ *     downgrade) matters: an old JS peer that cannot parse DNFT1 must not be
+ *     stranded there by one slow response, and a native peer must not be
+ *     stranded on raw. Each transport keeps getting tried until one answers.
+ *   - The first inbound file packet PINS the mode to the transport it arrived
+ *     on and stops the alternation. That is ground truth about what the peer
+ *     speaks, so later transfers to that friend start on the right one.
+ *
+ * At the engine's offer cadence (~450ms) a switch costs about 1.4s, well
+ * inside the 60s give-up window, so the wrong initial guess is invisible.
+ */
+export declare class Dnft1TransportPolicy {
+    #private;
+    /** Consecutive unanswered offers before trying the other transport. */
+    static readonly UNANSWERED_OFFERS_BEFORE_SWITCH = 3;
+    /** True when this friend's file packets should be sent as DNFT1 frames. */
+    useDnft1(friendId: string): boolean;
+    /** True once a real inbound file packet has settled the transport. */
+    isPinned(friendId: string): boolean;
+    /**
+     * Called for every outbound OFFER (packet 80). Returns true when this offer
+     * flipped the transport — the caller should send THIS offer on the new one.
+     */
+    noteOfferSent(friendId: string): boolean;
+    /**
+     * Called for every inbound file packet, with the transport it arrived on.
+     * Pins the mode: the peer just proved which one it speaks.
+     */
+    noteInbound(friendId: string, viaDnft1: boolean): void;
+    /** Drop all state for a friend (removed, or session torn down). */
+    forget(friendId: string): void;
+}

package/dist/compat/dnft1.js

@@ -0,0 +1,146 @@
+// DNFT1 — carrying file-transfer packets 80–83 inside ordinary friend messages.
+//
+// Why this exists: the JS peer speaks toxcore messenger packets 80–83 natively,
+// but a native app never sees them. The precompiled Carrier C SDK consumes
+// 80/81/82 internally (they feed its own file state machine, which registers no
+// app callbacks) and discards 83 (FEC — it does not know the id). A P0 probe on
+// iOS confirmed it: raw packets never reach the mobile app layer, so JS↔iOS
+// file transfer could not work at all.
+//
+// The fix keeps the SDK untouched: both ends carry the SAME packet payloads
+// inside ordinary friend messages, wrapped in a frame no chat text can produce.
+// iOS implemented it first (FileTransferWire.swift in the Beagle app); this is
+// the byte-exact JS counterpart — read that file before changing anything here.
+//
+//   [0x1E]["DNFT1"][packetId u8][payloadLen u32 BE][payload]
+//
+// - 0x1E (record separator) leads, mirroring the "\u{1E}DNPACK1:" text-ack
+//   envelope convention — a one-byte reject for ordinary chat text.
+// - payloadLen is explicit because the carrier/express path can append junk
+//   past the real payload. Trailing junk after a binary chunk would corrupt the
+//   file, so the frame carries its own length and anything past it is ignored.
+//
+// The payloads inside are UNCHANGED — the same bytes filetransfer.ts already
+// builds. This module only adds and removes the envelope, so the engine, the
+// FEC layer and the conformance fixtures stay transport-agnostic.
+import { PACKET_ID_FILE_SENDREQUEST, PACKET_ID_FILE_FEC, } from "./filetransfer.js";
+/** "\u{1E}DNFT1" — the leading bytes of every frame. */
+export const DNFT1_MAGIC = Uint8Array.from([0x1e, 0x44, 0x4e, 0x46, 0x54, 0x31]);
+/** magic(6) + packetId(1) + payloadLen(4). */
+export const DNFT1_HEADER_LENGTH = 11;
+/** Wrap one file-transfer packet payload in a DNFT1 frame. */
+export function encodeDnft1Frame(packetId, payload) {
+    const out = new Uint8Array(DNFT1_HEADER_LENGTH + payload.length);
+    out.set(DNFT1_MAGIC, 0);
+    out[6] = packetId & 0xff;
+    const n = payload.length;
+    out[7] = (n >>> 24) & 0xff;
+    out[8] = (n >>> 16) & 0xff;
+    out[9] = (n >>> 8) & 0xff;
+    out[10] = n & 0xff;
+    out.set(payload, DNFT1_HEADER_LENGTH);
+    return out;
+}
+/**
+ * Parse a DNFT1 frame out of a received message body.
+ *
+ * Returns null for anything that is not a file-transfer frame (ordinary chat
+ * data — the common case, so this must stay cheap), and for a frame truncated
+ * below its declared payload length: dropped rather than half-parsed, since a
+ * short read would hand the engine a chunk with missing bytes. Bytes past
+ * payloadLen are transport junk and are ignored.
+ */
+export function parseDnft1Frame(raw) {
+    if (raw.length < DNFT1_HEADER_LENGTH)
+        return null;
+    for (let i = 0; i < DNFT1_MAGIC.length; i++) {
+        if (raw[i] !== DNFT1_MAGIC[i])
+            return null;
+    }
+    const packetId = raw[6];
+    if (packetId < PACKET_ID_FILE_SENDREQUEST || packetId > PACKET_ID_FILE_FEC)
+        return null;
+    // >>> 0 keeps the length unsigned: a hostile 0xFFFFFFFF must compare as
+    // 4294967295 (and fail the bounds check), not as -1 (which would pass it).
+    const length = ((raw[7] << 24) | (raw[8] << 16) | (raw[9] << 8) | raw[10]) >>> 0;
+    if (raw.length - DNFT1_HEADER_LENGTH < length)
+        return null;
+    return {
+        packetId,
+        payload: raw.subarray(DNFT1_HEADER_LENGTH, DNFT1_HEADER_LENGTH + length),
+    };
+}
+/**
+ * Picks the transport for each friend's file packets: raw messenger packets
+ * (a JS peer, which is faster — no envelope, no message-channel framing) or
+ * DNFT1 frames (a native peer, the only thing that reaches its app layer).
+ *
+ * There is no reliable capability handshake to key this off — appVersion is
+ * absent for older builds and lies across forks — so the mode is LEARNED from
+ * what actually works, which needs no negotiation and self-corrects:
+ *
+ *   - The engine already retransmits an unanswered OFFER until the receiver
+ *     responds. Every UNANSWERED_OFFERS_BEFORE_SWITCH of those with no inbound
+ *     file packet flips the transport. Alternating (rather than a one-way
+ *     downgrade) matters: an old JS peer that cannot parse DNFT1 must not be
+ *     stranded there by one slow response, and a native peer must not be
+ *     stranded on raw. Each transport keeps getting tried until one answers.
+ *   - The first inbound file packet PINS the mode to the transport it arrived
+ *     on and stops the alternation. That is ground truth about what the peer
+ *     speaks, so later transfers to that friend start on the right one.
+ *
+ * At the engine's offer cadence (~450ms) a switch costs about 1.4s, well
+ * inside the 60s give-up window, so the wrong initial guess is invisible.
+ */
+export class Dnft1TransportPolicy {
+    /** Consecutive unanswered offers before trying the other transport. */
+    static UNANSWERED_OFFERS_BEFORE_SWITCH = 3;
+    #dnft1 = new Set();
+    #pinned = new Set();
+    #unanswered = new Map();
+    /** True when this friend's file packets should be sent as DNFT1 frames. */
+    useDnft1(friendId) {
+        return this.#dnft1.has(friendId);
+    }
+    /** True once a real inbound file packet has settled the transport. */
+    isPinned(friendId) {
+        return this.#pinned.has(friendId);
+    }
+    /**
+     * Called for every outbound OFFER (packet 80). Returns true when this offer
+     * flipped the transport — the caller should send THIS offer on the new one.
+     */
+    noteOfferSent(friendId) {
+        if (this.#pinned.has(friendId))
+            return false;
+        const n = (this.#unanswered.get(friendId) ?? 0) + 1;
+        if (n < Dnft1TransportPolicy.UNANSWERED_OFFERS_BEFORE_SWITCH) {
+            this.#unanswered.set(friendId, n);
+            return false;
+        }
+        this.#unanswered.set(friendId, 0);
+        if (this.#dnft1.has(friendId))
+            this.#dnft1.delete(friendId);
+        else
+            this.#dnft1.add(friendId);
+        return true;
+    }
+    /**
+     * Called for every inbound file packet, with the transport it arrived on.
+     * Pins the mode: the peer just proved which one it speaks.
+     */
+    noteInbound(friendId, viaDnft1) {
+        this.#unanswered.delete(friendId);
+        this.#pinned.add(friendId);
+        if (viaDnft1)
+            this.#dnft1.add(friendId);
+        else
+            this.#dnft1.delete(friendId);
+    }
+    /** Drop all state for a friend (removed, or session torn down). */
+    forget(friendId) {
+        this.#dnft1.delete(friendId);
+        this.#pinned.delete(friendId);
+        this.#unanswered.delete(friendId);
+    }
+}

package/dist/peer.d.ts

@@ -335,11 +335,13 @@ export declare class Peer {
     setUserInfo(info: {
         name?: string;
         description?: string;
+        punkId?: number | null;
     }): void;
     /** Our current display name + status-message description. */
     userInfo(): {
         name: string;
         description: string;
+        punkId?: number;
     };
     /**
      * Tell a friend our public UDP endpoint over the (already-working,

package/dist/peer.js

@@ -13,6 +13,7 @@ import { NET_PACKET_ONION_ANNOUNCE_RESPONSE, NET_PACKET_ONION_DATA_RESPONSE, ONI
 import { CRYPTO_PACKET_DHTPK, CRYPTO_PACKET_FRIEND_REQ, NET_PACKET_CRYPTO, createToxDhtCryptoRequest, openToxDhtCryptoRequest } from "./compat/tox-dht-crypto.js";
 import { NET_PACKET_PING_REQUEST, NET_PACKET_PING_RESPONSE, NET_PACKET_GET_NODES, NET_PACKET_SEND_NODES, encodeDhtRpc, decodeDhtRpc, buildPingPlain, parsePingPlain, buildGetNodesPlain, parseGetNodesPlain, buildSendNodesPlain, parseSendNodesNodeBytes, packUdpNodeV4 } from "./compat/dht-rpc.js";
 import { FileTransferManager, PACKET_ID_FILE_SENDREQUEST, PACKET_ID_FILE_CONTROL, PACKET_ID_FILE_DATA, PACKET_ID_FILE_FEC } from "./compat/filetransfer.js";
+import { Dnft1TransportPolicy, encodeDnft1Frame, parseDnft1Frame } from "./compat/dnft1.js";
 import { NET_PACKET_CRYPTO_DATA, NET_PACKET_CRYPTO_HS, NET_PACKET_COOKIE_REQUEST, NET_PACKET_COOKIE_RESPONSE, createCookieRequest, createCookieResponse, createCryptoDataPacket, createCryptoHandshake, openCookieRequest, openCookieResponse, openCryptoDataPacket, openCryptoHandshake, incrementNonce } from "./compat/net-crypto.js";
 import { LegacyExpressClient } from "./compat/express.js";
 import { TcpRelayPool } from "./compat/tcp-relay-pool.js";
@@ -285,6 +286,19 @@ const RECV_REORDER_WINDOW = 8192;
 // Minimum gap between PACKET_ID_REQUEST packets we send for our own receive gaps
 // (toxcore paces requests ~ once per RTT; this floor avoids flooding on a burst).
 const RECV_REQUEST_MIN_INTERVAL_MS = 200;
+/** Read a CryptoPunks id out of the userinfo `gender` field.
+ *
+ *  Beagle writes the bare nft id there. Anything else — an empty string, or a
+ *  real gender from a non-Beagle Carrier client — is not a punk and must not
+ *  be rendered as one. */
+function parsePunkField(value) {
+    if (!value)
+        return undefined;
+    const n = Number(value.trim());
+    if (!Number.isInteger(n) || n < 0 || n > 9999)
+        return undefined;
+    return n;
+}
 export class Peer {
     #opts;
     #events = new EventEmitter();
@@ -295,12 +309,22 @@ export class Peer {
      *  old peer returns ACCEPT/ACK over its reliable TCP relay. */
     #fileRelayNegotiationUntil = new Map();
     // Toxcore-standard file transfer (wire-compatible with native Carrier/toxcore).
+    /** Which transport carries each friend's file packets — raw messenger
+     *  packets (JS peers) or DNFT1 frames inside friend messages (native peers,
+     *  whose Carrier SDK swallows 80-82 and drops 83). See compat/dnft1.ts. */
+    #dnft1 = new Dnft1TransportPolicy();
     #fileTransfer = new FileTransferManager((friendId, packetId, payload) => {
         if (packetId === PACKET_ID_FILE_SENDREQUEST) {
             const session = this.#friendSessions.get(friendId);
             const lan = !!session?.lanRemoteHost && session.remote?.host === session.lanRemoteHost;
             if (!lan)
                 this.#fileRelayNegotiationUntil.set(friendId, Date.now() + 6_000);
+            // Every unanswered offer is evidence the peer cannot hear this
+            // transport; the policy alternates until one of them answers.
+            this.#dnft1.noteOfferSent(friendId);
+        }
+        if (this.#dnft1.useDnft1(friendId)) {
+            return this.#sendDnft1Frame(friendId, packetId, payload);
         }
         return this.#sendMessengerPacket(friendId, packetId, payload);
     }, (event, payload) => { this.#events.emit(event, payload); }, (friendId) => {
@@ -1180,6 +1204,7 @@ export class Peer {
         const existed = this.#friends.delete(friendId);
         this.#friendSessions.delete(friendId);
         this.#fileRelayNegotiationUntil.delete(friendId);
+        this.#dnft1.forget(friendId);
         this.#pendingFriendRequests.delete(friendId);
         this.#cookieRetryCount.delete(friendId);
         this.#lastCookieSentKey.delete(friendId);
@@ -1751,6 +1776,37 @@ export class Peer {
     onCustomPacket(cb) {
         this.#events.on("customPacket", cb);
     }
+    /**
+     * Send one file-transfer packet as a DNFT1 frame inside a friend message —
+     * the only route that reaches a native app's layer (its Carrier SDK
+     * swallows packets 80-82 and drops 83). Payload bytes are unchanged; see
+     * compat/dnft1.ts for the envelope and the iOS counterpart.
+     *
+     * Deliberately live-session only, and never express: express is
+     * store-and-forward for chat, and 100 MB of file chunks has no business in
+     * a mailbox. Control loss is already covered by the engine's offer/ack
+     * retransmits, so a failed send here is a dropped packet the engine will
+     * redo — not a lost transfer.
+     */
+    async #sendDnft1Frame(friendId, packetId, payload) {
+        const frame = encodeDnft1Frame(packetId, payload);
+        // A full DATA frame (11 + 5 + 1367 = 1383 B) exceeds the 1024-byte
+        // friendmsg unit, so it rides BULKMSG fragments — exactly what the C SDK
+        // does when iOS hands the same frame to sendFriendMessage.
+        if (frame.length <= CARRIER_MAX_APP_MESSAGE_LEN) {
+            await this.#sendMessengerPacket(friendId, PACKET_ID_MESSAGE, encodeFriendMessagePacket(frame));
+            return;
+        }
+        const tid = (BigInt(Date.now()) << 20n) ^ BigInt(Math.floor(Math.random() * 0xfffff));
+        for (let off = 0; off < frame.length; off += CARRIER_MAX_APP_MESSAGE_LEN) {
+            const end = Math.min(off + CARRIER_MAX_APP_MESSAGE_LEN, frame.length);
+            await this.#sendMessengerPacket(friendId, PACKET_ID_MESSAGE, encodeBulkMsgPacket({
+                totalsz: off === 0 ? frame.length : 0,
+                tid,
+                data: frame.subarray(off, end)
+            }));
+        }
+    }
     // ───────────────────── file transfer (toxcore-standard, native-ready) ─────
     /**
      * Offer a file to a friend (by userid). Returns the fileId (hex) or null if
@@ -3093,6 +3149,14 @@ export class Peer {
             // the very same packFilePayload as the online path).
             if (this.#tryEmitBinaryInlineFile(fromUserId, decoded.data, "offline"))
                 return;
+            // Neither end routes DNFT1 through express on purpose — a 100 MB stream
+            // has no business in a store-and-forward mailbox, and the engine's
+            // retransmits already cover control loss. But if a frame does surface
+            // here, swallow it rather than rendering the binary as chat mojibake.
+            if (parseDnft1Frame(decoded.data)) {
+                this.#debugLog(`ignoring DNFT1 frame from ${fromUserId} on the express path`);
+                return;
+            }
             if (this.#tryEmitInlineFile(fromUserId, text, "offline"))
                 return;
             void this.#dispatchTextMessage({ pubkey: fromUserId, text, via: "offline" });
@@ -4121,6 +4185,11 @@ export class Peer {
         if (kind === PACKET_ID_FILE_CONTROL)
             this.#fileRelayNegotiationUntil.delete(friendId);
         // Toxcore file transfer (FILE_SENDREQUEST/CONTROL/DATA = 80/81/82).
+        if (kind >= PACKET_ID_FILE_SENDREQUEST && kind <= PACKET_ID_FILE_FEC) {
+            // A raw file packet arrived, so this peer speaks raw — pin it and stop
+            // alternating toward DNFT1.
+            this.#dnft1.noteInbound(friendId, false);
+        }
         if (this.#fileTransfer.handlePacket(friendId, kind, inner))
             return;
         if (kind === PACKET_ID_ONLINE) {
@@ -4194,12 +4263,17 @@ export class Peer {
             // back to plain UTF-8 for compatibility.
             let userInfoName;
             let userInfoDescr;
+            let userInfoPunk;
             let clientMeta;
             try {
                 const decoded = decodeCarrierPacket(inner);
                 if (decoded.type === PACKET_TYPE_USERINFO) {
                     userInfoName = decoded.name;
                     userInfoDescr = decoded.descr;
+                    // The friend's avatar. `gender` is where Beagle puts the punk id —
+                    // it was decoded here and thrown away, which is the whole reason a
+                    // friend's picture could only ever come from beagles.eth.
+                    userInfoPunk = parsePunkField(decoded.gender);
                     // AgentNet appended fields — present only for updated peers.
                     if (decoded.protoVersion || decoded.platform || decoded.appVersion) {
                         clientMeta = {
@@ -4218,19 +4292,23 @@ export class Peer {
                 const friend = this.#friends.get(friendId);
                 const newName = userInfoName && userInfoName.length > 0 ? userInfoName : friend?.name;
                 const newDescr = userInfoDescr ?? friend?.description;
+                // Keep what we had when this packet carried no punk: a peer that
+                // stops sending one has not taken their avatar off.
+                const newPunk = userInfoPunk ?? friend?.punkId;
                 const metaChanged = friend != null && clientMeta != null &&
                     (friend.protoVersion !== clientMeta.protoVersion ||
                         friend.platform !== clientMeta.platform ||
                         friend.osVersion !== clientMeta.osVersion ||
                         friend.appVersion !== clientMeta.appVersion);
-                if (friend && (friend.name !== newName || friend.description !== newDescr || metaChanged)) {
-                    this.#friends.set(friendId, { ...friend, name: newName, description: newDescr, ...(clientMeta ?? {}) });
+                if (friend && (friend.name !== newName || friend.description !== newDescr || friend.punkId !== newPunk || metaChanged)) {
+                    this.#friends.set(friendId, { ...friend, name: newName, description: newDescr, punkId: newPunk, ...(clientMeta ?? {}) });
                     this.#persistFriends();
                     this.#events.emit("friendInfo", {
                         pubkey: friendId,
                         userid: friend.userid ?? friendId,
                         name: newName,
                         description: newDescr,
+                        punkId: newPunk,
                         ...(clientMeta ?? {})
                     });
                 }
@@ -4319,6 +4397,18 @@ export class Peer {
             else {
                 raw = inner;
             }
+            // DNFT1: a file-transfer packet carried inside a friend message (the
+            // native-interop path — see compat/dnft1.ts). Like the Android binary
+            // envelope below, this MUST run on the undecoded bytes: raw chunk bytes
+            // do not survive a UTF-8 decode.
+            const ft = parseDnft1Frame(raw);
+            if (ft) {
+                this.#dnft1.noteInbound(friendId, true);
+                if (ft.packetId === PACKET_ID_FILE_CONTROL)
+                    this.#fileRelayNegotiationUntil.delete(friendId);
+                this.#fileTransfer.handlePacket(friendId, ft.packetId, ft.payload);
+                return;
+            }
             if (this.#tryEmitBinaryInlineFile(friendId, raw, "online"))
                 return;
             text = decodeUtf8Best(raw);
@@ -4890,6 +4980,11 @@ export class Peer {
             opts.nickname = info.name;
         if (info.description !== undefined)
             opts.statusMessage = info.description;
+        // null clears it explicitly; undefined means "not changing it". Everything
+        // below re-sends the profile to every established friend, which is what
+        // makes an avatar change visible without a reconnect.
+        if (info.punkId !== undefined)
+            opts.punkId = info.punkId ?? undefined;
         this.#profileSentTo.clear();
         for (const timer of this.#profileRetryTimers.values())
             clearTimeout(timer);
@@ -4906,6 +5001,9 @@ export class Peer {
         return {
             name: opts.nickname ?? PEER_NICKNAME,
             description: opts.statusMessage ?? PEER_STATUS_MESSAGE,
+            // Reported so "what am I actually advertising" is answerable without
+            // reading a packet capture — the UI surfaces this as `me.advertised`.
+            punkId: opts.punkId,
         };
     }
     #scheduleProfileRetry(friendId) {
@@ -4962,7 +5060,12 @@ export class Peer {
                         protoVersion: AGENTNET_PROTO_VERSION,
                         platform: this.#opts.platform ?? process.platform,
                         osVersion: this.#opts.osVersion ?? `node-${process.versions?.node ?? ""}`,
-                        appVersion: this.#opts.appVersion ?? `peer-${PEER_PKG_VERSION}`
+                        appVersion: this.#opts.appVersion ?? `peer-${PEER_PKG_VERSION}`,
+                        // The avatar, in the field Beagle uses for it (see punkId on
+                        // FriendInfoEvent). OMITTED when we have none, never sent as "":
+                        // an empty string would clear an avatar the friend already
+                        // resolved. Without this, iOS shows us no picture at all.
+                        ...(this.#opts.punkId != null ? { gender: String(this.#opts.punkId) } : {})
                     });
                     await this.#sendMessengerPacket(friendId, PACKET_ID_STATUSMESSAGE, userInfo);
                     this.#debugLog(`userinfo sent to ${friendId} (name="${nick}", descr="${descr}", proto=${AGENTNET_PROTO_VERSION}, platform=${this.#opts.platform ?? process.platform})`);

package/dist/store/friends.d.ts

@@ -5,6 +5,10 @@ export type FriendRecord = {
     nospam?: number;
     name?: string;
     description?: string;
+    /** The friend's CryptoPunks id, from the userinfo `gender` field. Persisted
+     *  so their avatar survives a restart instead of waiting for the next
+     *  profile packet. See FriendInfoEvent.punkId. */
+    punkId?: number;
     status: "requested" | "offline" | "online";
     remoteHost?: string;
     remotePort?: number;

package/dist/types/peer.d.ts

@@ -88,6 +88,11 @@ export type PeerOptions = {
      * version.
      */
     appVersion?: string;
+    /** Our own CryptoPunks id, advertised to friends in the userinfo `gender`
+     *  field — the only way an avatar travels over Carrier itself. Leave unset
+     *  and the field is omitted entirely (never sent as ""), so a friend keeps
+     *  whatever picture they already have for us. */
+    punkId?: number;
     compatibilityMode?: CompatibilityMode;
     debugLabel?: string;
 };
@@ -110,6 +115,18 @@ export type FriendInfoEvent = {
     userid?: string;
     name?: string;
     description?: string;
+    /** The friend's CryptoPunks id — their avatar.
+     *
+     *  Carried in the userinfo packet's `gender` field, which is not a mistake
+     *  and not ours to rename. The protocol has no avatar field: `has_avatar`
+     *  is a bool in all four implementations and the image exchange was never
+     *  built. Beagle borrowed `gender` because a punk carries a gender anyway.
+     *  Defined in WalletForBeagleV2/docs/profile.md — set with
+     *  userinfo.setGender(nftid), read back off friendInfo.gender.
+     *
+     *  Undefined when the friend sent no punk, or sent something that is not a
+     *  punk id (a real gender from a non-Beagle Carrier client). */
+    punkId?: number;
     /** Peer's advertised client metadata (from the userinfo profile). Present
      *  only once the friend has sent a profile with these fields — a legacy
      *  peer (native C SDK before the extension, or an old JS build) leaves them

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decentnetwork/peer",
-  "version": "0.1.140",
+  "version": "0.1.142",
   "description": "Pure TypeScript port of Elastos Carrier (toxcore-derived) P2P messaging. DHT, onion routing, TCP relay, FlatBuffers app payloads, Express offline relay. Wire-compatible with iOS Beagle and the Carrier C SDK.",
   "type": "module",
   "main": "./dist/index.js",