@fizzyflow/endless-vector 0.0.7 → 0.0.10

package/EndlessVectorArchive.js

@@ -1,8 +1,7 @@
 import EndlessVectorHistory from './EndlessVectorHistory.js';
 
 /**
- * @typedef {import('@mysten/sui/client').SuiClient} SuiClient
- * @typedef {import('@mysten/sui/client').GetDynamicFieldsParams} GetDynamicFieldsParams
+ * @typedef {import('@mysten/sui/grpc').SuiGrpcClient} SuiGrpcClient
  * @typedef {import('./EndlessVector.js').default} EndlessVector
  */
 
@@ -10,14 +9,14 @@ export default class EndlessVectorArchive {
     /**
      * Creates a new EndlessVectorArchive instance.
      * @param {Object} params - Configuration parameters
-     * @param {SuiClient} [params.suiClient] - Sui client instance for blockchain interactions
+     * @param {SuiGrpcClient} [params.suiClient] - Sui gRPC client instance for blockchain interactions
      * @param {string} [params.id] - ID or address of the EndlessVectorArchive on the Sui blockchain
      * @param {number} [params.index=0] - Index position of this archive item in the sequence
      * @param {EndlessVector} [params.endlessVector] - Reference to the parent EndlessVector instance
      * @param {Object} [params.fields] - Raw field data from the blockchain object
      */
     constructor(params = {}) {
-        /** @type {SuiClient} */
+        /** @type {SuiGrpcClient} */
         this.suiClient = params.suiClient;
         /** @type {string} */
         this.id = params.id;
@@ -47,8 +46,8 @@ export default class EndlessVectorArchive {
      */
     setFields(fields) {
         this._fields = fields;
-        this.historyTableId = fields?.history?.fields?.id?.id;
-        this.historyItemsCount = parseInt(fields?.history?.fields?.size || '0');
+        this.historyTableId = fields?.history?.id;
+        this.historyItemsCount = parseInt(fields?.history?.size || '0');
     }
 
     /**
@@ -75,7 +74,7 @@ export default class EndlessVectorArchive {
      * @returns {number} The starting index (inclusive)
      */
     get startsAt() {
-        return this.endsAt - this.length;
+        return this.endsAt - this.length + 1;
     }
 
     /**
@@ -134,40 +133,30 @@ export default class EndlessVectorArchive {
             throw new Error('historyTableId is not set');
         }
 
-        /** @type {GetDynamicFieldsParams} */
-        const getDynamicFieldsParams  = {
-            parentId: this.historyTableId,
-            options: {
-                showContent: true,
-                showType: true,
-            },
-        };
-
-        let resp = null;
+        let cursor = undefined;
         let haveToLookMore = true;
 
         do {
-            resp  = await this.suiClient.getDynamicFields(getDynamicFieldsParams);
-            if (resp && resp.data && resp.data.length) {
-                for (const df of resp.data) {
-                    if (df?.objectId) {
-                        const itemHistoryIndex = parseInt(df.name.value);
-                        const endlessVectorHistory = new EndlessVectorHistory({
-                            suiClient: this.suiClient,
-                            id: df.objectId,
-                            index: itemHistoryIndex,
-                            endlessVector: this._endlessVector,
-                            endlessVectorArchive: this,
-                        });
-                        this._history[itemHistoryIndex] = endlessVectorHistory;
-                        if (itemHistoryIndex === historyIndexInt) {
-                            haveToLookMore = false;
-                        }
+            const resp = await this.suiClient.listDynamicFields({ parentId: this.historyTableId, cursor });
+            for (const df of resp.dynamicFields ?? []) {
+                if (df?.fieldId) {
+                    const itemHistoryIndex = EndlessVectorArchive._decodeBcsU64(df.name.bcs);
+                    const endlessVectorHistory = new EndlessVectorHistory({
+                        suiClient: this.suiClient,
+                        id: df.fieldId,
+                        index: itemHistoryIndex,
+                        endlessVector: this._endlessVector,
+                        endlessVectorArchive: this,
+                    });
+                    this._history[itemHistoryIndex] = endlessVectorHistory;
+                    if (itemHistoryIndex === historyIndexInt) {
+                        haveToLookMore = false;
                     }
                 }
-                getDynamicFieldsParams.cursor = resp.nextCursor;
             }
-        } while (resp?.hasNextPage && haveToLookMore);
+            cursor = resp.cursor;
+            if (!resp.hasNextPage) break;
+        } while (haveToLookMore);
 
         if (!this._history[historyIndexInt]) {
             throw new Error(`History not found for index ${historyIndexInt}`);
@@ -206,11 +195,17 @@ export default class EndlessVectorArchive {
      * @returns {Promise<Uint8Array>} The suffix bytes from the history item
      * @throws {Error} If the index is out of range for this archive item
      */
+    static _decodeBcsU64(bcsBytes) {
+        const b = bcsBytes instanceof Uint8Array ? bcsBytes : new Uint8Array(bcsBytes);
+        const dv = new DataView(b.buffer, b.byteOffset, b.byteLength);
+        return Number(dv.getBigUint64(0, true));
+    }
+
     async getSuffixFromHistoryItemOfIndex(i) {
         if (i < this.historyItemsCount) {
             const historyItem = await this.getHistory(i);
             if (historyItem) {
-                return historyItem.getSuffixStoredBytes();
+                return await historyItem.getSuffixStoredBytes();
             }
         }
 

package/EndlessVectorHistory.js

@@ -1,6 +1,8 @@
 
+import EndlessVectorItem from './EndlessVectorItem.js';
+
 /**
- * @typedef {import('@mysten/sui/client').SuiClient} SuiClient
+ * @typedef {import('@mysten/sui/grpc').SuiGrpcClient} SuiGrpcClient
  * @typedef {import('./EndlessVector.js').default} EndlessVector
  * @typedef {import('./EndlessVectorArchive.js').default} EndlessVectorArchive
  */
@@ -14,7 +16,7 @@ export default class EndlessVectorHistory {
     /**
      * Creates a new EndlessVectorHistory instance.
      * @param {Object} params - Configuration parameters
-     * @param {SuiClient} [params.suiClient] - Sui client instance for blockchain interactions
+     * @param {SuiGrpcClient} [params.suiClient] - Sui gRPC client instance for blockchain interactions
      * @param {string} [params.id] - Unique identifier for this history item
      * @param {number} [params.index=0] - Index position of this history item in the sequence
      * @param {?Object} [params.fields] - Raw field data from the blockchain object
@@ -22,7 +24,7 @@ export default class EndlessVectorHistory {
      * @param {?EndlessVectorArchive} [params.endlessVectorArchive] - Reference to the parent EndlessVectorArchive instance
      */
     constructor(params = {}) {
-        /** @type {SuiClient} */
+        /** @type {SuiGrpcClient} */
         this.suiClient = params.suiClient;
         /** @type {string} */
         this.id = params.id;
@@ -146,12 +148,14 @@ export default class EndlessVectorHistory {
                 indexInItems = i - this.startsAt + 1;
             }
 
+            const context = { endlessVector: this._endlessVector, endlessVectorHistory: this };
+
             if (indexInItems < (this._fields.items.length - 1)) {
-                return new Uint8Array(this._fields.items[indexInItems]);
+                return await EndlessVectorItem.fromGrpcJson(this._fields.items[indexInItems], context).bytes();
             } else if (indexInItems === (this._fields.items.length - 1)) {
                 if (this.followedByNextBytes) {
                     // if this item is child of archive, get suffix from next item of archive, otherwise from endless vector
-                    const suffix = this._endlessVectorArchive ? 
+                    const suffix = this._endlessVectorArchive ?
                         (await this._endlessVectorArchive.getSuffixFromHistoryItemOfIndex(this.index + 1)) :
                         (await this._endlessVector.getSuffixFromHistoryItemOfIndex(this.index + 1));
 
@@ -159,13 +163,11 @@ export default class EndlessVectorHistory {
                         throw new Error('suffix bytes length mismatch');
                     }
 
-                    const current = new Uint8Array(this._fields.items[indexInItems]);
-                    const combined = new Uint8Array(current.length + suffix.length);
-                    combined.set(current);
-                    combined.set(suffix, current.length);
-                    return combined;
+                    const head = EndlessVectorItem.fromGrpcJson(this._fields.items[indexInItems], context);
+                    const tail = new EndlessVectorItem({ type: 'bytes', bytes: suffix });
+                    return EndlessVectorItem.concatBytes(head, tail);
                 } else {
-                    return new Uint8Array(this._fields.items[indexInItems]);
+                    return await EndlessVectorItem.fromGrpcJson(this._fields.items[indexInItems], context).bytes();
                 }
             }
         }
@@ -178,10 +180,12 @@ export default class EndlessVectorHistory {
      * to the last item of the previous history segment.
      * @returns {Uint8Array} The suffix bytes, or empty array if none stored
      */
-    getSuffixStoredBytes() {
+    async getSuffixStoredBytes() {
         if (this.firstItemIsFromPreviousHistory) {
-            return new Uint8Array(this._fields.items[0]);
+            const context = { endlessVector: this._endlessVector, endlessVectorHistory: this };
+            return await EndlessVectorItem.fromGrpcJson(this._fields.items[0], context).bytes();
         }
         return new Uint8Array();
     }
+
 }

package/EndlessVectorItem.js

@@ -0,0 +1,160 @@
+/**
+ * Represents a single item stored in an EndlessVector.
+ *
+ * Currently only bytes items are supported. Blob items (Walrus-stored payloads)
+ * are recognised and preserved but cannot yet be read — calling bytes() on a
+ * blob item throws. This design lets the rest of the SDK work today while
+ * leaving a clear extension point for blob support.
+ *
+ * gRPC JSON shape of EndlessWalrusItem:
+ *   bytes item  → { bytes: "<base64>", blob: null,  meta: "<base64>" }
+ *   blob  item  → { bytes: null,       blob: {...},  meta: "<base64>" }
+ *   empty item  → { bytes: null,       blob: null,  meta: "<base64>" }
+ */
+function decodeBase64(value) {
+    if (typeof Buffer !== 'undefined') {
+        return new Uint8Array(Buffer.from(value, 'base64'));
+    }
+    const binary = atob(value);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i += 1) {
+        bytes[i] = binary.charCodeAt(i);
+    }
+    return bytes;
+}
+
+export default class EndlessVectorItem {
+    /**
+     * @param {Object} params
+     * @param {'bytes'|'blob'|'empty'} params.type
+     * @param {Uint8Array|null} [params.bytes]
+     * @param {Object|null} [params.blobData] - raw gRPC blob fields, preserved for future use
+     * @param {Uint8Array} [params.meta]
+     * @param {import('./EndlessVector.js').default|null} [params.endlessVector] - parent EndlessVector instance
+     * @param {import('./EndlessVectorHistory.js').default|null} [params.endlessVectorHistory] - parent EndlessVectorHistory instance
+     */
+    constructor(params = {}) {
+        /** @type {'bytes'|'blob'|'empty'} */
+        this.type = params.type || 'empty';
+        /** @type {Uint8Array|null} */
+        this._bytes = params.bytes || null;
+        /** @type {Object|null} */
+        this._blobData = params.blobData || null;
+        /** @type {Uint8Array} */
+        this.meta = params.meta || new Uint8Array();
+        /** @type {import('./EndlessVector.js').default|null} */
+        this._endlessVector = params.endlessVector || null;
+        /** @type {import('./EndlessVectorHistory.js').default|null} */
+        this._endlessVectorHistory = params.endlessVectorHistory || null;
+    }
+
+    /** @returns {boolean} */
+    get isBytes() { return this.type === 'bytes'; }
+    /** @returns {boolean} */
+    get isBlob()  { return this.type === 'blob'; }
+    /** @returns {boolean} */
+    get isEmpty() { return this.type === 'empty'; }
+
+    /**
+     * Returns the binary size of this item in bytes.
+     * For bytes items, returns the byte array length.
+     * For blob items, returns the size from on-chain Blob object data.
+     * @returns {number}
+     */
+    get size() {
+        if (this.type === 'bytes') return this._bytes?.length || 0;
+        if (this.type === 'blob') return parseInt(this._blobData?.size || 0);
+        return 0;
+    }
+
+    /**
+     * Returns the raw bytes payload.
+     * @returns {Uint8Array}
+     * @throws {Error} If the item is a blob (not yet supported) or empty
+     */
+    async bytes() {
+        if (this.type === 'bytes') return this._bytes;
+        if (this.type === 'blob') {
+            if (this._endlessVector?.walrus?.readBlobBytes) {
+                return await this._endlessVector.walrus.readBlobBytes(this._blobData);
+            }
+            throw new Error('Blob items require walrusClient or aggregatorUrl to be configured on the EndlessVector');
+        }
+        throw new Error('Item is empty');
+    }
+
+    /**
+     * Returns the raw gRPC blob fields for blob items (future Walrus support).
+     * @returns {Object|null}
+     */
+    blobData() {
+        return this._blobData;
+    }
+
+    /**
+     * Parses an EndlessWalrusItem from its gRPC JSON representation.
+     *
+     * Handles three historical wire formats:
+     *   - gRPC JSON struct  { bytes: "<base64>"|null, blob: {...}|null, meta: "<base64>" }
+     *   - Legacy base64 string  "<base64>"
+     *   - Legacy plain number array  [1, 2, 3]
+     *
+     * @param {Object|string|number[]|null} raw
+     * @param {Object} [context={}]
+     * @param {import('./EndlessVector.js').default|null} [context.endlessVector]
+     * @param {import('./EndlessVectorHistory.js').default|null} [context.endlessVectorHistory]
+     * @returns {EndlessVectorItem}
+     */
+    static fromGrpcJson(raw, context = {}) {
+        if (raw == null) {
+            return new EndlessVectorItem({ type: 'empty', ...context });
+        }
+
+        // Legacy: plain number array
+        if (Array.isArray(raw)) {
+            return new EndlessVectorItem({ type: 'bytes', bytes: new Uint8Array(raw), ...context });
+        }
+
+        // Legacy: bare base64 string (whole item serialised as base64)
+        if (typeof raw === 'string') {
+            return new EndlessVectorItem({ type: 'bytes', bytes: decodeBase64(raw), ...context });
+        }
+
+        // gRPC JSON struct
+        const meta = raw.meta
+            ? decodeBase64(raw.meta)
+            : new Uint8Array();
+
+        if (raw.blob != null) {
+            return new EndlessVectorItem({ type: 'blob', blobData: raw.blob, meta, ...context });
+        }
+
+        if (raw.bytes != null) {
+            const bytes = typeof raw.bytes === 'string'
+                ? decodeBase64(raw.bytes)
+                : new Uint8Array(raw.bytes);
+            return new EndlessVectorItem({ type: 'bytes', bytes, meta, ...context });
+        }
+
+        return new EndlessVectorItem({ type: 'empty', meta, ...context });
+    }
+
+    /**
+     * Concatenates two bytes items into one. Used when a split item spans two
+     * history segments (followed_by_next_bytes / firstItemIsFromPreviousHistory).
+     *
+     * @param {EndlessVectorItem} head
+     * @param {EndlessVectorItem} tail
+     * @returns {Uint8Array}
+     * @throws {Error} If either item is not a bytes item
+     */
+    static concatBytes(head, tail) {
+        if (head.type !== 'bytes' || tail.type !== 'bytes') {
+            throw new Error('concatBytes requires two bytes items');
+        }
+        const combined = new Uint8Array(head._bytes.length + tail._bytes.length);
+        combined.set(head._bytes);
+        combined.set(tail._bytes, head._bytes.length);
+        return combined;
+    }
+}

package/EndlessVectorSeal.js

@@ -0,0 +1,192 @@
+import { Transaction } from '@mysten/sui/transactions';
+import { fromHex } from '@mysten/sui/utils';
+import { SessionKey } from '@mysten/seal';
+import { gcm } from '@noble/ciphers/aes.js';
+import { randomBytes } from '@noble/ciphers/utils.js';
+
+/**
+ * @typedef {import('@mysten/seal').SealClient} SealClient
+ * @typedef {import('@mysten/seal').SessionKey} SessionKey_T
+ * @typedef {import('./EndlessVector.js').default} EndlessVector
+ */
+
+const AES_KEY_BYTES   = 32;
+const AES_NONCE_BYTES = 12;
+const AES_TAG_BYTES   = 16;
+const DEFAULT_TTL_MIN = 5;
+
+/**
+ * Seal-layered encryption companion for EndlessVector.
+ * Attached as `endlessVector.seal` on every EndlessVector instance; only "enabled"
+ * when a sealClient is supplied at construction time.
+ *
+ * When enabled, the parent EndlessVector encrypts every pushed item with a per-vector
+ * AES-256-GCM key and decrypts on read. The AES key itself is Seal-encrypted scoped
+ * to the vector's object id and stored on-chain as `EndlessWalrusVector.seal_encrypted_key`.
+ * Access policy: `seal_approve_endless_vector_owner` (only the vector owner can decrypt
+ * the AES key — anyone else gets ciphertext only).
+ *
+ * AES payload layout: `nonce(12B) || ciphertext || tag(16B)` (28B overhead per item).
+ */
+export default class EndlessVectorSeal {
+    /**
+     * @param {Object} params
+     * @param {EndlessVector} params.endlessVector - parent EndlessVector
+     * @param {SealClient} [params.sealClient]
+     * @param {SessionKey_T} [params.sessionKey] - optional pre-built SessionKey
+     * @param {any} [params.signer] - keypair/signer to mint a SessionKey when needed
+     * @param {number} [params.sealTtlMin=5] - SessionKey ttl in minutes
+     */
+    constructor(params = {}) {
+        /** @type {EndlessVector} */
+        this._endlessVector = params.endlessVector || null;
+        /** @type {?SealClient} */
+        this._sealClient = params.sealClient || null;
+        /** @type {?SessionKey_T} */
+        this._sessionKey = params.sessionKey || null;
+        /** @type {?any} */
+        this._signer = params.signer || null;
+        /** @type {number} */
+        this._ttlMin = params.sealTtlMin || DEFAULT_TTL_MIN;
+
+        /** @type {?Uint8Array} - cached plaintext AES key (after key unwrap) */
+        this._aesKey = null;
+    }
+
+    /** True iff a sealClient was supplied. Callers gate behavior on this. */
+    get isEnabled() {
+        return !!this._sealClient;
+    }
+
+    /** Generate a fresh AES-256 key — used at `create()` time when sealing a new vector. */
+    static generateAesKey() {
+        return randomBytes(AES_KEY_BYTES);
+    }
+
+    /** Cache a plaintext AES key (e.g. immediately after `create()` so the first push needn't unwrap). */
+    setAesKey(key) {
+        if (!(key instanceof Uint8Array) || key.length !== AES_KEY_BYTES) {
+            throw new Error(`seal: key must be a ${AES_KEY_BYTES}-byte Uint8Array`);
+        }
+        this._aesKey = key;
+    }
+
+    /**
+     * Seal-encrypt the AES key scoped to the vector's object id.
+     * Caller is responsible for storing the returned bytes on-chain via
+     * `set_seal_encrypted_key` on the vector.
+     *
+     * @param {Uint8Array} aesKey
+     * @returns {Promise<Uint8Array>} the Seal-encrypted (wrapped) key
+     */
+    async wrapAesKey(aesKey) {
+        this._assertEnabled();
+        const ev = this._endlessVector;
+        if (!ev._packageId) throw new Error('seal.wrapAesKey requires packageId on the vector');
+        if (!ev.id) throw new Error('seal.wrapAesKey requires the vector id (call after create())');
+
+        const idHex = EndlessVectorSeal._objectIdToHex(ev.id);
+        const { encryptedObject } = await this._sealClient.encrypt({
+            threshold: 1,
+            packageId: ev._packageId,
+            id: idHex,
+            data: aesKey,
+        });
+        return new Uint8Array(encryptedObject);
+    }
+
+    /** Encrypt a single item before push. */
+    async encryptItem(plaintext) {
+        this._assertEnabled();
+        const key = await this._ensureAesKey();
+        const nonce = randomBytes(AES_NONCE_BYTES);
+        const ct = gcm(key, nonce).encrypt(plaintext);
+        const out = new Uint8Array(AES_NONCE_BYTES + ct.length);
+        out.set(nonce, 0);
+        out.set(ct, AES_NONCE_BYTES);
+        return out;
+    }
+
+    /** Decrypt a single item after read. */
+    async decryptItem(payload) {
+        this._assertEnabled();
+        if (payload.length < AES_NONCE_BYTES + AES_TAG_BYTES) {
+            throw new Error(`seal.decryptItem: payload too short (${payload.length})`);
+        }
+        const key = await this._ensureAesKey();
+        const nonce = payload.subarray(0, AES_NONCE_BYTES);
+        const ct = payload.subarray(AES_NONCE_BYTES);
+        return gcm(key, nonce).decrypt(ct);
+    }
+
+    /**
+     * Resolve the plaintext AES key. If it's already cached, return it; otherwise fetch
+     * the wrapped key from the vector's on-chain state, build a PTB proving ownership via
+     * `seal_approve_endless_vector_owner`, and run `sealClient.decrypt`.
+     */
+    async _ensureAesKey() {
+        if (this._aesKey) return this._aesKey;
+
+        const ev = this._endlessVector;
+        await ev.initialize();
+        const wrapped = ev.sealEncryptedKey;
+        if (!wrapped) throw new Error('seal: vector has no seal_encrypted_key on-chain');
+
+        const idHex = EndlessVectorSeal._objectIdToHex(ev.id);
+        const tx = new Transaction();
+        tx.moveCall({
+            target: `${ev._packageId}::endless_walrus::seal_approve_endless_vector_owner`,
+            arguments: [
+                tx.pure.vector('u8', Array.from(fromHex(idHex))),
+                tx.object(ev.id),
+            ],
+        });
+
+        const senderAddress = this._senderAddress();
+        if (senderAddress) tx.setSender(senderAddress);
+        const txBytes = await tx.build({ client: ev.suiClient, onlyTransactionKind: true });
+
+        const sessionKey = await this._ensureSessionKey();
+        const aesKey = await this._sealClient.decrypt({
+            data: wrapped,
+            sessionKey,
+            txBytes,
+        });
+        this._aesKey = new Uint8Array(aesKey);
+        return this._aesKey;
+    }
+
+    async _ensureSessionKey() {
+        if (this._sessionKey && !this._sessionKey.isExpired?.()) return this._sessionKey;
+        if (!this._signer) throw new Error('seal: signer or sessionKey is required to mint a SessionKey');
+
+        const ev = this._endlessVector;
+        const senderAddress = this._senderAddress();
+        if (!senderAddress) throw new Error('seal: senderAddress is required to mint a SessionKey');
+
+        this._sessionKey = await SessionKey.create({
+            address: senderAddress,
+            packageId: ev._packageId,
+            ttlMin: this._ttlMin,
+            signer: this._signer,
+            suiClient: ev.suiClient,
+        });
+        return this._sessionKey;
+    }
+
+    _senderAddress() {
+        // Prefer an explicit walrus.senderAddress (already plumbed for blob writes);
+        // fall back to the suiClient address if present.
+        return this._endlessVector?.walrus?._senderAddress
+            ?? this._endlessVector?.suiClient?.address
+            ?? null;
+    }
+
+    _assertEnabled() {
+        if (!this.isEnabled) throw new Error('seal: sealClient not configured on this EndlessVector');
+    }
+
+    static _objectIdToHex(objectId) {
+        return String(objectId).replace(/^0x/, '').padStart(64, '0');
+    }
+}