cartesi · brunomenezes · Jun 22, 2026 · Jun 22, 2026
diff --git a/.env.development b/.env.development
@@ -2,6 +2,8 @@ NEXT_PUBLIC_ENVIRONMENT=development
 NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID=YOUR_WALLETCONNECT_PROJECT_ID
 NEXT_PUBLIC_MAINNET_GRAPHQL_URL=YOUR_MAINNET_SUBGRAPH_GRAPHQL_ENDPOINT
 NEXT_PUBLIC_SEPOLIA_GRAPHQL_URL=YOUR_SEPOLIA_SUBGRAPH_GRAPHQL_ENDPOINT
+# Your tinygraphs service url if necessary 
+# NEXT_PUBLIC_TINYGRAPHS_URL=""
 NEXT_PUBLIC_DAPP_URL=http://localhost:3000
 NEXT_PUBLIC_RPC_URL_1=YOUR_MAINNET_RPC_NODE_ENDPOINT
 NEXT_PUBLIC_RPC_URL_11155111=YOUR_SEPOLIA_RPC_NODE_ENDPOINT

diff --git a/.env.production b/.env.production
@@ -3,6 +3,8 @@ NEXT_PUBLIC_GOOGLE_TAG_MANAGER_ID=GTM-MS89D9K
 NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID=YOUR_WALLETCONNECT_PROJECT_ID
 NEXT_PUBLIC_MAINNET_GRAPHQL_URL=YOUR_MAINNET_SUBGRAPH_GRAPHQL_ENDPOINT
 NEXT_PUBLIC_SEPOLIA_GRAPHQL_URL=YOUR_SEPOLIA_SUBGRAPH_GRAPHQL_ENDPOINT
+# Your tinygraphs service url if necessary
+# NEXT_PUBLIC_TINYGRAPHS_URL=""
 NEXT_PUBLIC_DAPP_URL=https://$NEXT_PUBLIC_VERCEL_URL
 NEXT_PUBLIC_RPC_URL_1=YOUR_MAINNET_RPC_NODE_ENDPOINT
 NEXT_PUBLIC_RPC_URL_11155111=YOUR_SEPOLIA_RPC_NODE_ENDPOINT

diff --git a/.gitignore b/.gitignore
@@ -37,5 +37,7 @@ yarn-error.log*
 
 #local libsql
 *.db
+*.db-shm
+*.db-wal
 
 *storybook.log
diff --git a/__tests__/utils/tinygraph.test.ts b/__tests__/utils/tinygraph.test.ts
@@ -9,8 +9,8 @@
 // WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
 // PARTICULAR PURPOSE. See the GNU General Public License for more details.
 
-import { tinyGraphUrl, themes, shapes } from '../../src/utils/tinygraph';
 import { Block } from '../../src/graphql/models';
+import { shapes, themes, tinyGraphUrl } from '../../src/utils/tinygraph';
 
 const block = {
     chain: {
@@ -41,7 +41,22 @@ describe('tinygraph util', () => {
         const shapeId = (block.chain.protocol.version - 1) % shapes.length;
 
         expect(tinyGraphUrl(block)).toBe(
-            `https://tinygraphs.cartesi.io/${shapes[shapeId]}/${block.producer.id}?theme=${themes[themeId]}&numcolors=4&size=220&fmt=svg`
+            `https://tinygraph.cartesi.io/${shapes[shapeId]}/${block.producer.id}?theme=${themes[themeId]}&numcolors=4&size=220&fmt=svg`
         );
     });
+
+    it('should override the tiny-graph url with env variable set', () => {
+        const customEndpoint = 'https://custom-tinygraphs.fly.dev';
+        const originalValue = process.env.NEXT_PUBLIC_TINYGRAPHS_URL;
+        process.env.NEXT_PUBLIC_TINYGRAPHS_URL = customEndpoint;
+
+        const themeId = block.chain.number % themes.length;
+        const shapeId = (block.chain.protocol.version - 1) % shapes.length;
+
+        expect(tinyGraphUrl(block)).toBe(
+            `${customEndpoint}/${shapes[shapeId]}/${block.producer.id}?theme=${themes[themeId]}&numcolors=4&size=220&fmt=svg`
+        );
+
+        process.env.NEXT_PUBLIC_TINYGRAPHS_URL = originalValue;
+    });
 });
diff --git a/additional.d.ts b/additional.d.ts
@@ -81,5 +81,11 @@ declare namespace NodeJS {
          * functions under /api/cron/*. It can be any agreed value.
          */
         CRON_SECRET: string;
+
+        /**
+         * The URL of the tinygraphs service, which provides user avatars based on their Ethereum address.
+         * It can be a custom deployment or a public instance.
+         */
+        NEXT_PUBLIC_TINYGRAPHS_URL: string;
     }
 }
diff --git a/src/app/layout.tsx b/src/app/layout.tsx
@@ -1,7 +1,8 @@
-import { FC, ReactNode } from 'react';
 import { SpeedInsights } from '@vercel/speed-insights/next';
-import Providers from '../providers/Providers';
 import { Metadata } from 'next';
+import { FC, ReactNode } from 'react';
+import Providers from '../providers/Providers';
+import { getTinyGraphsServiceUrl } from '../utils/tinygraph';
 
 export const metadata: Metadata = {
     title: {
@@ -22,7 +23,7 @@ const Layout: FC<LayoutProps> = async ({ children }) => {
     return (
         <html lang="en">
             <head>
-                <link rel="preconnect" href="https://tinygraphs.cartesi.io" />
+                <link rel="preconnect" href={getTinyGraphsServiceUrl()} />
             </head>
             <body>
                 <Providers>{children}</Providers>

diff --git a/src/components/PageHead.tsx b/src/components/PageHead.tsx
@@ -1,6 +1,7 @@
-import React, { FC } from 'react';
-import Head from 'next/head';
 import { isString } from 'lodash';
+import Head from 'next/head';
+import { FC } from 'react';
+import { getTinyGraphsServiceUrl } from '../utils/tinygraph';
 
 export interface PageHead {
     name?: string;
@@ -25,7 +26,7 @@ const PageHead: FC<PageHead> = ({
                 <meta name="description" content={description} />
             )}
             <link rel="icon" href="/favicon.ico" />
-            <link rel="preconnect" href="https://tinygraphs.cartesi.io" />.
+            <link rel="preconnect" href={getTinyGraphsServiceUrl()} />.
         </Head>
     );
 };

diff --git a/src/utils/tinygraph.ts b/src/utils/tinygraph.ts
@@ -31,9 +31,29 @@ export const shapes = [
     'labs/isogrids/hexa16', // Hexa rotation 1/6
 ];
 
+/**
+ * Returns the base URL for the tinygraphs service,
+ * which can be configured through the environment variable NEXT_PUBLIC_TINYGRAPHS_URL.
+ * If the environment variable is not set, it defaults to the Cartesi provided service.
+ * @returns The base URL for the tinygraphs service.
+ */
+export const getTinyGraphsServiceUrl = () => {
+    return (
+        process.env.NEXT_PUBLIC_TINYGRAPHS_URL || 'https://tinygraph.cartesi.io'
+    );
+};
+
+/**
+ * Generates a URL for a tiny graph image based on ethereum address and optional shape index.
+ * The URL is constructed using the block's producer ID, chain number, and protocol version to determine the theme and shape of the graph.
+ * @param block The block object containing information about the producer, chain, and protocol version.
+ * @param shapeIndex Optional index to override the default shape selection.
+ * @returns The URL of the generated tiny graph image.
+ */
 export const tinyGraphUrl = (block: Block, shapeIndex?: number): string => {
     const themeId = block.chain.number % themes.length;
+    const tinyGraphsBaseUrl = getTinyGraphsServiceUrl();
     const shapeId =
         shapeIndex ?? (block.chain.protocol.version - 1) % shapes.length;
-    return `https://tinygraphs.cartesi.io/${shapes[shapeId]}/${block.producer.id}?theme=${themes[themeId]}&numcolors=4&size=220&fmt=svg`;
+    return `${tinyGraphsBaseUrl}/${shapes[shapeId]}/${block.producer.id}?theme=${themes[themeId]}&numcolors=4&size=220&fmt=svg`;
 };