@feralfile/cli 2.10.0 → 3.0.0

package/dist/src/utilities/token-source-raster.js

@@ -0,0 +1,378 @@
+"use strict";
+/**
+ * Raster token source: the opt-in provider under evaluation (feral-file#3576).
+ *
+ * Reads token rows from Raster's public GraphQL API and maps each one to the
+ * vendor-neutral StandardToken, which token-item.ts turns into a DP-1 item
+ * with the same code the indexer path uses. Item ids, provenance, inline
+ * manifests and timing therefore come out identical in shape to the indexer's.
+ *
+ * What Raster cannot do, and how this provider answers instead of guessing:
+ *   - no contract listing query: listTokensByContract throws a capability
+ *     error rather than inventing a probe;
+ *   - a token it does not cover, or a burned one, comes back null: reported
+ *     as a failure, never filled from another vendor (one vendor per run);
+ *   - Feral File metadata is a snapshot: bare ipfs:// and a retired CDN host
+ *     are fixed up in media-url.ts;
+ *   - `media.contentType` is a category, not a MIME type: rasterTimingMime
+ *     turns it into a timing hint that never reaches the document.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.rasterTokenStandard = rasterTokenStandard;
+exports.rasterTokenName = rasterTokenName;
+exports.rasterTimingMime = rasterTimingMime;
+exports.rasterTokenToStandardToken = rasterTokenToStandardToken;
+exports.itemsFromRasterTokens = itemsFromRasterTokens;
+exports.createRasterTokenSource = createRasterTokenSource;
+const viem_1 = require("viem");
+const logger = __importStar(require("../logger"));
+const raster_client_1 = require("./raster-client");
+const media_url_1 = require("./media-url");
+const token_item_1 = require("./token-item");
+const token_source_contract_1 = require("./token-source-contract");
+/** CAIP-2 chains ff-cli builds items for. Others are skipped and counted. */
+const CAIP_TO_CHAIN = {
+    'eip155:1': 'ethereum',
+    'tezos:NetXdQprcVkpaWU': 'tezos',
+};
+/** Raster standards DP-1 can name; others become `other` (see rasterTokenStandard). */
+const RASTER_STANDARDS = {
+    ERC721: 'erc721',
+    ERC1155: 'erc1155',
+    FA2: 'fa2',
+};
+/** Page size for the wallet walk. 100 matches listArtistArtworks; 200 was probed fine. */
+const OWNED_PAGE_SIZE = 100;
+/** NOT_ON_RASTER explains a null `tokenByRef` in the user's terms. */
+const NOT_ON_RASTER = 'Raster has no record of this token (not indexed, burned, or nonexistent)';
+/**
+ * rasterTokenStandard maps Raster's standard enum to a DP-1 standard.
+ *
+ * CRYPTOPUNKS and ORDINAL_INSCRIPTION have no DP-1 name, so they are `other`;
+ * falling through to detection would call a punk `erc721`, which it is not.
+ * A missing standard uses the caller's assertion, then detection.
+ */
+function rasterTokenStandard(raw, chain, contractAddress, asserted) {
+    if (raw) {
+        return RASTER_STANDARDS[raw.toUpperCase()] ?? 'other';
+    }
+    return (0, token_item_1.resolveTokenStandard)(chain, contractAddress, asserted);
+}
+/**
+ * rasterTokenName picks the display title.
+ *
+ * Raster's GraphQL `Token.name` is empty for Art Blocks tokens (a known Raster
+ * bug, feral-file#3546). Art Blocks token ids are project * 1,000,000 + mint,
+ * so "<series> #<mint>" reproduces the title Art Blocks itself publishes,
+ * e.g. "Fidenza #629".
+ */
+function rasterTokenName(token) {
+    const name = (token.name ?? '').trim();
+    if (name) {
+        return name;
+    }
+    const artwork = token.artworks[0];
+    if (artwork?.platform?.id === 'artblocks' && /^\d+$/.test(token.tokenId)) {
+        return `${artwork.title} #${BigInt(token.tokenId) % 1000000n}`;
+    }
+    return artwork?.title || `Token #${token.tokenId}`;
+}
+/**
+ * rasterTimingMime turns Raster's media category into a timing hint.
+ *
+ * The value only steers DP-1 §4.1 timing (video plays its length, web works
+ * get the generative duration, the rest the static duration); it is never
+ * written into the playlist. `previewType` describes how Raster encoded the
+ * preview, not the work (a web app's preview is an image), so it is consulted
+ * only when it says video. Empty means unknown, and the URL extension decides,
+ * which is the indexer path's behaviour for extensionless URLs too.
+ */
+function rasterTimingMime(media) {
+    switch ((media?.contentType ?? '').toLowerCase()) {
+        case 'video':
+            return 'video/*';
+        case 'webapp':
+            return 'text/html';
+        case 'gif':
+            return 'image/gif';
+        case 'svg':
+            return 'image/svg+xml';
+        case 'image':
+            return 'image/*';
+    }
+    return (media?.previewType ?? '').toLowerCase().startsWith('video/') ? 'video/*' : '';
+}
+/**
+ * RASTER_STILL is deliberately empty: Raster items carry no still image.
+ *
+ * Raster's preview renditions (`bits.raster.art/.../7200.avif`) load for a
+ * browser user agent but answer 403 to curl and to the Feral File app's
+ * default `dart:io` client (verified 2026-10-21), and AVIF decoding outside
+ * browsers is not guaranteed. A still lands in `thumbnails.default` of a
+ * manifest the curator signs, so a URL that is dead for some readers is worse
+ * than none. Set a real rendition here only once Raster confirms access that
+ * does not depend on the user agent, and record that evidence here.
+ */
+const RASTER_STILL = '';
+/**
+ * canonicalContract returns the address as the indexer recorded it.
+ *
+ * Raster lowercases EVM addresses; the indexer returned them checksummed, and
+ * the DP-1 item id is sha256 of the address. Checksumming keeps ids and
+ * provenance identical across vendors. Tezos addresses are case-sensitive
+ * Base58 and Raster keeps them as written.
+ */
+function canonicalContract(chain, address) {
+    if (chain !== 'ethereum') {
+        return address;
+    }
+    try {
+        return (0, viem_1.getAddress)(address);
+    }
+    catch {
+        return address;
+    }
+}
+/**
+ * rasterTokenToStandardToken maps one Raster row to the vendor-neutral token.
+ *
+ * @param token - Raster row selected through TOKEN_FIELDS
+ * @param gateways - IPFS gateways for bare ipfs:// sources
+ * @param requested - The coordinate asked for, when there was one
+ * @returns TokenData ready for convertToDP1Item
+ */
+function rasterTokenToStandardToken(token, gateways, requested) {
+    const chain = CAIP_TO_CHAIN[token.chainId];
+    const rawAddress = token.contractAddress ?? requested?.contractAddress;
+    if (!chain || !rawAddress) {
+        return { success: false, error: `Unsupported chain ${token.chainId}` };
+    }
+    const contractAddress = canonicalContract(chain, rawAddress);
+    const artwork = token.artworks[0];
+    const platformId = artwork?.platform?.id ?? null;
+    const name = rasterTokenName(token);
+    const description = (token.description || artwork?.description || '').trim();
+    const artistName = (token.artists[0] ?? artwork?.artists?.[0])?.name ?? '';
+    const sourceUrl = (0, media_url_1.fixUpMediaUrl)(token.media?.contentUrl || token.media?.normalizedContentUrl, platformId, gateways);
+    return {
+        success: true,
+        token: {
+            chain,
+            caip2Chain: token.chainId,
+            contractAddress,
+            tokenId: token.tokenId,
+            standard: rasterTokenStandard(token.tokenStandard, chain, contractAddress, requested?.standard),
+            name,
+            description,
+            image: {
+                url: sourceUrl,
+                mimeType: rasterTimingMime(token.media),
+                thumbnail: RASTER_STILL,
+            },
+            metadata: { attributes: [], artistName },
+            collection: { name: artwork?.title || name, description },
+            burned: false,
+        },
+    };
+}
+/**
+ * itemsFromRasterTokens builds results from rows already in hand.
+ *
+ * Used by the series path of `find`, whose `artwork.tokens` page already
+ * carries every field, and by the wallet walk, so neither pays a second
+ * round trip.
+ */
+function itemsFromRasterTokens(entries, gateways, duration) {
+    return entries.map(({ token, requested }) => {
+        const tokenData = rasterTokenToStandardToken(token, gateways, requested);
+        const coordinate = requested ?? coordinateOf(tokenData, token);
+        if (!tokenData.success) {
+            return { success: false, coordinate, error: tokenData.error ?? 'Unmappable token' };
+        }
+        const converted = (0, token_item_1.convertToDP1Item)(tokenData, duration);
+        if (!converted.success || !converted.item) {
+            return { success: false, coordinate, error: converted.error ?? 'Item build failed' };
+        }
+        return { success: true, coordinate, item: converted.item, still: converted.still ?? '' };
+    });
+}
+/** coordinateOf names the coordinate a row describes when nobody asked for it. */
+function coordinateOf(tokenData, token) {
+    return {
+        chain: tokenData.token?.chain ?? token.chainId,
+        contractAddress: tokenData.token?.contractAddress ?? token.contractAddress ?? '',
+        tokenId: token.tokenId,
+    };
+}
+/**
+ * normalizeChain maps a coordinate's chain to Raster's vocabulary, or null.
+ *
+ * The address prefix outranks the caller's chain name: `KT…` is Tezos and
+ * `0x…` is EVM whatever the caller said, mirroring the auto-correction the
+ * indexer path applied. Only Ethereum and Tezos mainnet are supported.
+ */
+function normalizeChain(coord) {
+    if (coord.contractAddress.startsWith('KT')) {
+        return 'tezos';
+    }
+    if (coord.contractAddress.startsWith('0x')) {
+        const chain = coord.chain.toLowerCase();
+        return chain === 'ethereum' || chain === 'eth' || chain === 'evm' ? 'ethereum' : null;
+    }
+    return null;
+}
+/** reportProgress calls a progress callback, which must never break a run. */
+function reportProgress(opts, done, total) {
+    try {
+        opts.onProgress?.(done, total);
+    }
+    catch {
+        /* progress display is best-effort */
+    }
+}
+/** DECIMAL_TOKEN_ID is the only token id shape Raster's BigInt scalar accepts. */
+const DECIMAL_TOKEN_ID = /^\d+$/;
+/**
+ * rejectionFor explains why a coordinate cannot be sent to Raster, or ''.
+ *
+ * Checked before batching because Raster validates every variable of a query
+ * together: one non-decimal token id (`0x1f`, `#12`, a typo) rejects the whole
+ * request, which would fail up to 39 valid neighbours with an unrelated error.
+ */
+function rejectionFor(coord) {
+    if (normalizeChain(coord) === null) {
+        return `Unsupported chain "${coord.chain}" (Ethereum and Tezos mainnet only)`;
+    }
+    if (!DECIMAL_TOKEN_ID.test(String(coord.tokenId ?? '').trim())) {
+        return `Invalid token id "${coord.tokenId}" (expected a decimal integer)`;
+    }
+    return '';
+}
+/**
+ * resolveBatch looks up one batch and turns each answer into a result.
+ * Coordinates that cannot be sent fail on their own; a failed request fails
+ * every coordinate it carried with the same reason.
+ */
+async function resolveBatch(batch, gateways, duration) {
+    const lookups = batch.filter((coord) => rejectionFor(coord) === '');
+    let rows;
+    try {
+        rows = await (0, raster_client_1.fetchTokensByRef)(lookups.map((coord) => ({
+            chain: normalizeChain(coord),
+            contractAddress: coord.contractAddress,
+            tokenId: String(coord.tokenId).trim(),
+        })));
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return batch.map((coordinate) => {
+            const rejection = rejectionFor(coordinate);
+            return { success: false, coordinate, error: rejection || message };
+        });
+    }
+    const byCoord = new Map(lookups.map((coord, i) => [coord, rows[i]]));
+    return batch.map((coordinate) => resolveOne(coordinate, byCoord, gateways, duration));
+}
+/** resolveOne turns one coordinate's row (or its absence) into a result. */
+function resolveOne(coordinate, rows, gateways, duration) {
+    const rejection = rejectionFor(coordinate);
+    if (rejection) {
+        return { success: false, coordinate, error: rejection };
+    }
+    const row = rows.get(coordinate);
+    if (!row) {
+        return { success: false, coordinate, error: NOT_ON_RASTER };
+    }
+    return itemsFromRasterTokens([{ token: row, requested: coordinate }], gateways, duration)[0];
+}
+/**
+ * walkOwnedTokens pages through an address's holdings until `limit` supported
+ * tokens are collected or the walk ends. Any page failure throws: a silently
+ * truncated wallet would look like a complete one.
+ */
+async function walkOwnedTokens(address, limit) {
+    const tokens = [];
+    let skippedUnsupported = 0;
+    let after;
+    do {
+        const page = await (0, raster_client_1.fetchTokensOwned)(address, { first: OWNED_PAGE_SIZE, after });
+        for (const token of page.tokens) {
+            if (!CAIP_TO_CHAIN[token.chainId] || !token.contractAddress) {
+                skippedUnsupported += 1;
+            }
+            else if (limit === 'all' || tokens.length < limit) {
+                tokens.push(token);
+            }
+        }
+        after = page.nextCursor ?? undefined;
+    } while (after && (limit === 'all' || tokens.length < limit));
+    return { tokens, skippedUnsupported };
+}
+/**
+ * createRasterTokenSource builds the Raster provider.
+ *
+ * Batches run one after another: 40 tokens per request already turns the
+ * ff-cli#132 case (43 tokens, ~10 minutes on the indexer) into two requests,
+ * and sequential batches keep load on an unmetered beta API predictable.
+ *
+ * @param gateways - Resolved IPFS gateways from config
+ */
+function createRasterTokenSource(gateways) {
+    return {
+        name: 'raster',
+        async resolveTokens(coords, opts = {}) {
+            const results = [];
+            for (let i = 0; i < coords.length; i += raster_client_1.RASTER_TOKEN_BATCH_SIZE) {
+                const batch = coords.slice(i, i + raster_client_1.RASTER_TOKEN_BATCH_SIZE);
+                results.push(...(await resolveBatch(batch, gateways, opts.duration)));
+                reportProgress(opts, results.length, coords.length);
+            }
+            logger.debug(`[Raster] Resolved ${results.filter((r) => r.success).length}/${coords.length}`);
+            return results;
+        },
+        async listTokensByOwner(address, opts) {
+            const walked = await walkOwnedTokens(address, opts.limit);
+            const entries = walked.tokens.map((token) => ({ token }));
+            return {
+                results: itemsFromRasterTokens(entries, gateways, opts.duration),
+                skippedUnsupported: walked.skippedUnsupported,
+            };
+        },
+        async listTokensByContract() {
+            throw new token_source_contract_1.TokenSourceCapabilityError(token_source_contract_1.RASTER_CANNOT_LIST_CONTRACT);
+        },
+    };
+}

package/dist/src/utilities/token-source.js

@@ -0,0 +1,48 @@
+"use strict";
+/**
+ * Token source factory: the one place that decides which vendor answers.
+ *
+ * Commands call getTokenSource() and see only the TokenSource contract.
+ * The Feral File indexer (ff-indexer-v2) is the default. Raster is opt-in with
+ * `tokenSource: "raster"` (or FF_TOKEN_SOURCE=raster) while it is evaluated:
+ * its data still has open bugs (feral-file#3546), so it is not the default
+ * until they are fixed (owner decision, 2026-10-22). There is no fallback
+ * between providers: one vendor answers a whole run (feral-file#3576).
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createTokenSource = createTokenSource;
+exports.getTokenSource = getTokenSource;
+const config_1 = require("../config");
+const token_source_indexer_1 = require("./token-source-indexer");
+const token_source_raster_1 = require("./token-source-raster");
+__exportStar(require("./token-source-contract"), exports);
+/**
+ * createTokenSource builds the provider a configuration selects.
+ *
+ * @param config - Resolved token source configuration
+ * @returns The selected provider
+ */
+function createTokenSource(config) {
+    if (config.source === 'raster') {
+        return (0, token_source_raster_1.createRasterTokenSource)(config.ipfsGateways);
+    }
+    return (0, token_source_indexer_1.createIndexerTokenSource)();
+}
+/** getTokenSource builds the provider from the current configuration. */
+function getTokenSource() {
+    return createTokenSource((0, config_1.getTokenSourceConfig)());
+}

package/docs/CONFIGURATION.md

@@ -27,6 +27,10 @@ npm run dev -- config show
 - **generativeDuration** (number, seconds)
   - Display duration stamped on generative/interactive (HTML) works, which have no intrinsic runtime and no end-of-stream event. Defaults to **60s** (override via `DEFAULT_GENERATIVE_DURATION`).
   - Set to **0** to omit the duration entirely, so a conformant player parks on the work open-ended instead of rotating. Note: some players (including FF1) require every item to carry a `duration` and will reject a playlist whose items omit it — keep this non-zero unless you know your player tolerates an absent duration.
+- **tokenSource** (`"raster"` | `"indexer"`)
+  - Which service `find`, `build`, and `enrich` read token data from. Defaults to `indexer`. See [tokenSource](#tokensource).
+- **ipfsGateways** (object)
+  - Gateways used to turn bare `ipfs://` sources into HTTPS URLs. See [ipfsGateways](#ipfsgateways).
 
 ## browser
 
@@ -215,9 +219,59 @@ Environment variable alternative:
 FEED_BASE_URLS=https://dp1-feed-operator-api-prod.autonomy-system.workers.dev/api/v1,https://dp1-feed-operator-api-prod.autonomy-system.workers.dev/api/v1
 ```
 
-## find (Raster API)
+## tokenSource
 
-`ff-cli find` resolves tokens, series, and artist addresses through Raster's public GraphQL API ([docs.api.raster.art](https://docs.api.raster.art/)). No configuration is required; two environment variables adjust the integration:
+Token data for `find`, `build`, and `enrich` (title, artist, description, playable source, on-chain provenance, and a still image where the service supplies one) comes from one service per run:
+
+- `indexer` (default): the Feral File indexer (ff-indexer-v2). A token it has not seen yet triggers an indexing job, so a first build of unseen tokens can take minutes.
+- `raster` (opt-in, under evaluation): Raster's public GraphQL API. Tokens are looked up 40 per request, so a build does not wait for indexing jobs. Raster's data still has known bugs, tracked on [feral-file#3546](https://github.com/feral-file/feral-file/issues/3546): some Feral File works point at a retired image host and play black, and evolving works play an older snapshot. No still image is supplied: Raster's preview renditions refuse non-browser clients, so items and `enrich` get no thumbnail from Raster.
+
+```json
+{ "tokenSource": "raster" }
+```
+
+Omit the key, or set `"indexer"`, to use the default.
+
+Environment variable alternative:
+
+```env
+FF_TOKEN_SOURCE=raster
+```
+
+There is no fallback between the two. A token Raster does not cover, or one that was burned, is reported as unresolved rather than looked up elsewhere.
+
+Raster has no way to list a contract's tokens. With `tokenSource: "raster"`, a `build_playlist` requirement without `tokenIds` fails with a message saying so, and a `query_address` requirement for an address that holds nothing is not retried as a contract. Give token ids, an owner address, or run `find` on the series URL instead.
+
+Only Ethereum mainnet and Tezos mainnet tokens are built. Tokens on other chains in a wallet or series are skipped and counted.
+
+## ipfsGateways
+
+With `tokenSource: "raster"`, many sources come back as bare `ipfs://` CIDs, which the FF1 cannot load. ff-cli rewrites them through a gateway:
+
+- `ipfsGateways.feralFile`: used for Feral File works. Default `https://ipfs.feralfile.com/ipfs/`.
+- `ipfsGateways.default`: used for everything else. Default `https://ipfs.filebase.io/ipfs/`.
+
+A bare origin such as `https://gateway.example` is accepted and normalized to `https://gateway.example/ipfs/`. Sources on the retired `cdn.feralfileassets.com` host are rewritten to `cdn.artworks.feralfile.io`. Sources on the legacy `ipfs.bitmark.com` gateway go through `ipfsGateways.feralFile` instead.
+
+```json
+{
+  "ipfsGateways": {
+    "feralFile": "https://ipfs.feralfile.com/ipfs/",
+    "default": "https://ipfs.filebase.io/ipfs/"
+  }
+}
+```
+
+Environment variable alternative:
+
+```env
+IPFS_GATEWAY_FERAL_FILE=https://ipfs.feralfile.com/ipfs/
+IPFS_GATEWAY_DEFAULT=https://ipfs.filebase.io/ipfs/
+```
+
+## Raster API
+
+`find` resolves tokens, series, and artist addresses through Raster's public GraphQL API ([docs.api.raster.art](https://docs.api.raster.art/)), and with the default `tokenSource` so do `build` and `enrich`. No configuration is required; two environment variables adjust the integration:
 
 ```env
 # API key sent as the x-api-key header. The API currently answers without
@@ -262,6 +316,13 @@ You can also manage devices independently with:
 
 Setup and `device add` both preserve existing devices. Adding a device with the same host as an existing one updates it in place.
 
+For an explicitly enrolled owner Tailscale connection, use the FF1's Tailscale IPv4
+address with the **same physical `--id` and existing `--name`**. Save its old
+host first. This updates that device in place, preserving its list position,
+API key and ID; relayer credentials remain in the vault under the same ID.
+The configured host is replaced, with no automatic LAN/Tailscale failover.
+See the [owner-access procedure](https://github.com/feral-file/ffos/blob/36e25cec84505271a7232d6936bb46a19fab5cfd/docs/OWNER_TAILSCALE.md).
+
 Selection rules when sending:
 
 - If you omit `-d`, the first configured device is used.

package/docs/EXAMPLES.md

@@ -64,6 +64,9 @@ npm run dev -- find https://objkt.com/tokens/hicetnunc/111068 --publish
 
 # Build, play on a named device, and skip interactive prompts
 npm run dev -- find https://objkt.com/tokens/hicetnunc/111068 --play -d "Living Room Display" -y
+
+# -y alone also plays (the scripted default); add --no-play to build and save without casting
+npm run dev -- find https://objkt.com/tokens/hicetnunc/111068 -y --no-play
 ```
 
 OpenSea and Verse accept both item and collection/series URLs:
@@ -258,14 +261,14 @@ the flag; without it those items are skipped rather than guessed at, because
 the wrong network returns a different artwork's metadata. A Tezos playlist
 needs no flag.
 
-Items the indexer cannot resolve are listed rather than guessed at:
+Items the token source cannot resolve are listed rather than guessed at:
 
 ```text
 Nothing to enrich
 
   Skipped 3:
     Kim Asendorf — PXL NET — no provenance.contract chain/address/tokenId to look up
-    Untitled — the indexer returned nothing for it
+    Untitled — the token source returned nothing for it
     Pre-Process — chain "evm" names a family; pass --assume-ethereum to assert the network
 ```
 

package/docs/PROJECT_SPEC.md

@@ -81,7 +81,7 @@ The current code and internal context imply these practical goals:
 
 ### Current behavior
 
-The current implementation still depends on Feral File-operated infrastructure for some data retrieval paths, including the hardcoded production indexer endpoint used for NFT lookup.
+Token data for `find`, `build`, and `enrich` comes from the Feral File indexer (ff-indexer-v2) by default. Raster's public GraphQL API is selectable with `tokenSource: "raster"` and is under evaluation as the replacement (feral-file#3576); it stays opt-in until the data bugs reported on feral-file#3546 are fixed. One token source answers a whole run; there is no fallback between them.
 
 ### Design direction
 
@@ -105,7 +105,7 @@ Based on the code today, the CLI is responsible for:
 - resolving marketplace URLs, on-chain coordinates, and wallet addresses into playlists (`find`)
 - running feed fetches, address queries, contract-based NFT queries, domain resolution, playlist building, verification, publishing, and playback
 - supporting a deterministic build path from structured JSON (`build`)
-- building DP-1 playlist envelopes from NFT metadata or direct media URLs via `dp1-js` document and leaf builders (so constructed playlists stay schema-conformant), including inline Ref Manifests on items that carry indexer metadata
+- building DP-1 playlist envelopes from NFT metadata or direct media URLs via `dp1-js` document and leaf builders (so constructed playlists stay schema-conformant), including inline Ref Manifests on items that carry token-source metadata
 - validating and verifying playlist structure and signatures
 - signing playlists when a private key is configured
 - publishing validated playlists to configured feed servers
@@ -159,13 +159,17 @@ Today the CLI groups into these workflow areas:
 - `find`
 - `build`
 
-An item's `provenance.contract` is read from the indexer row, not inferred. Each
-row carries the token's own `standard` (`erc721`, `erc1155`, `fa2`) and its
-CAIP-2 `chain` (`eip155:1`, `tezos:mainnet`), and both are written through. The
-client's own detection sees a chain name and an address and nothing else, so it
-answers `erc721` for every EVM contract; it applies only to rows that carry no
-standard, and to the CID a lookup by coordinate must build before the indexer
-has been asked anything. A row naming a chain DP-1 has no word for is recorded
+An item's `provenance.contract` is read from the token source's row, not
+inferred. Each row carries the token's own standard and its CAIP-2 `chain`
+(`eip155:1`, `tezos:NetXdQprcVkpaWU` on Raster, `tezos:mainnet` on the
+indexer), and both are written through. Raster standards DP-1 cannot name
+(`CRYPTOPUNKS`, `ORDINAL_INSCRIPTION`) are written as `other`. Raster
+lowercases EVM addresses; they are checksummed before use, so an item's `id`
+(derived from the address and token id) and its provenance are the same
+whichever source built it. The client's own detection sees a chain name and an
+address and nothing else, so it answers `erc721` for every EVM contract; it
+applies only to rows that carry no standard, and to the CID a lookup by
+coordinate must build before the indexer has been asked anything. A row naming a chain DP-1 has no word for is recorded
 as `other` — the item is still built, and the client's guess is never
 substituted for a chain the row already named.
 
@@ -284,13 +288,13 @@ and nothing else. `enrich` is the repair path for those.
 - It writes `inlineManifest` and nothing else. `source`, `duration`, `title`,
   `id`, and `display` are curator decisions and survive untouched even when the
   indexer disagrees with them.
-- An item the indexer cannot resolve is reported, never synthesized. The same
+- An item the token source cannot resolve is reported, never synthesized. The same
   rule the manifest mapping follows applies here: the CLI does not invent fields
   it cannot substantiate, and an invented artist line inside a signed document
   is worse than an absent one.
-- DP-1 names the EVM family `evm`; the FF indexer names it `ethereum`. Enrich
-  translates between the two. Unlisted chain names pass through so the indexer
-  decides what it supports.
+- DP-1 names the EVM family `evm`; the token sources name it `ethereum`. Enrich
+  translates between the two. Unlisted chain names pass through so the token
+  source decides what it supports.
 - Enrichment changes the document, so both the `signatures[]` envelope and the
   legacy flat `signature` are removed and the playlist must be re-signed.
   Leaving a stale envelope in place would produce a file that fails
@@ -302,9 +306,10 @@ and nothing else. `enrich` is the repair path for those.
   discards the integrity hash the remote manifest is checked against. That
   conversion, if ever wanted, belongs behind its own flag.
 - Enrichment looks each distinct coordinate up once, however many items share
-  it. A token the indexer has not seen triggers an indexing job and a poll that
-  can take minutes, and a playlist that repeats a work would otherwise submit
-  that job once per appearance.
+  it. On Raster the lookups are batched; on the indexer a token it
+  has not seen triggers an indexing job and a poll that can take minutes, and a
+  playlist that repeats a work would otherwise submit that job once per
+  appearance.
 - Overriding an item's title changes the manifest's content, so it also changes
   the manifest's `id`. The indexer derives that id from the token coordinate,
   so two items of one artwork receive the same one; leaving it alone while
@@ -352,7 +357,8 @@ and nothing else. `enrich` is the repair path for those.
   nor the response can say which network is meant. Ethereum is chosen because
   it is the only EVM network this client can reach — `buildTokenCID` maps
   ethereum to `eip155:1` and tezos to `tezos:mainnet` and throws for anything
-  else. The residual risk is narrow: an L2 work whose address and token id also
+  else, and the Raster token source likewise builds Ethereum and Tezos mainnet
+  only. The residual risk is narrow: an L2 work whose address and token id also
   exist on Ethereum would take the Ethereum work's metadata. The command
   is the operator's to make: `--assume-ethereum` asserts it, and without that
   flag `evm` items are skipped with a reason that names the flag. The warning