solfaces 2.0.0 → 2.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +134 -14
- package/SKILL.md +171 -0
- package/dist/agent/index.cjs +14 -13
- package/dist/agent/index.js +4 -3
- package/dist/agent/mcp-server.cjs +2240 -10
- package/dist/{chunk-TTGJZEPV.js → chunk-77SPWQU5.js} +43 -12
- package/dist/chunk-77SPWQU5.js.map +1 -0
- package/dist/{chunk-JS527VKL.js → chunk-CQWXUU7P.js} +6 -5
- package/dist/chunk-CQWXUU7P.js.map +1 -0
- package/dist/{chunk-46ZEFA6R.cjs → chunk-CXRVPOTI.cjs} +10 -9
- package/dist/chunk-CXRVPOTI.cjs.map +1 -0
- package/dist/{chunk-23XJ5VDX.cjs → chunk-F244Q4KC.cjs} +47 -16
- package/dist/chunk-F244Q4KC.cjs.map +1 -0
- package/dist/{chunk-6UWILY7E.cjs → chunk-HVPGR6G5.cjs} +2 -2
- package/dist/{chunk-6UWILY7E.cjs.map → chunk-HVPGR6G5.cjs.map} +1 -1
- package/dist/{chunk-LRHYF5QN.js → chunk-MGP7F65H.js} +3 -3
- package/dist/{chunk-LRHYF5QN.js.map → chunk-MGP7F65H.js.map} +1 -1
- package/dist/chunk-R3MC2AJZ.cjs +2247 -0
- package/dist/chunk-R3MC2AJZ.cjs.map +1 -0
- package/dist/{chunk-HCEE4K4T.js → chunk-SWML743U.js} +2 -2
- package/dist/{chunk-HCEE4K4T.js.map → chunk-SWML743U.js.map} +1 -1
- package/dist/chunk-SX3FQDKM.js +2238 -0
- package/dist/chunk-SX3FQDKM.js.map +1 -0
- package/dist/{chunk-546TBMAR.cjs → chunk-WTCXTXTV.cjs} +6 -6
- package/dist/{chunk-546TBMAR.cjs.map → chunk-WTCXTXTV.cjs.map} +1 -1
- package/dist/constants-Bi5uTRp5.d.cts +17 -0
- package/dist/constants-Bi5uTRp5.d.ts +17 -0
- package/dist/core/index.cjs +31 -31
- package/dist/core/index.js +3 -3
- package/dist/index.cjs +63 -34
- package/dist/index.d.cts +2 -0
- package/dist/index.d.ts +2 -0
- package/dist/index.js +5 -4
- package/dist/names/index.cjs +40 -0
- package/dist/names/index.cjs.map +1 -0
- package/dist/names/index.d.cts +36 -0
- package/dist/names/index.d.ts +36 -0
- package/dist/names/index.js +3 -0
- package/dist/names/index.js.map +1 -0
- package/dist/react/index.cjs +45 -22
- package/dist/react/index.cjs.map +1 -1
- package/dist/react/index.d.cts +15 -2
- package/dist/react/index.d.ts +15 -2
- package/dist/react/index.js +30 -8
- package/dist/react/index.js.map +1 -1
- package/dist/solfaces.cdn.global.js +2 -2
- package/dist/solfaces.cdn.global.js.map +1 -1
- package/dist/vanilla/index.cjs +5 -5
- package/dist/vanilla/index.js +2 -2
- package/package.json +22 -5
- package/python/solfaces.py +274 -3
- package/reference/integrations.md +166 -0
- package/reference/react.md +108 -0
- package/reference/themes.md +124 -0
- package/dist/chunk-23XJ5VDX.cjs.map +0 -1
- package/dist/chunk-46ZEFA6R.cjs.map +0 -1
- package/dist/chunk-JS527VKL.js.map +0 -1
- package/dist/chunk-TTGJZEPV.js.map +0 -1
- package/skill.md +0 -608
package/README.md
CHANGED
|
@@ -1,11 +1,20 @@
|
|
|
1
1
|
# SolFaces
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
[](https://www.npmjs.com/package/solfaces)
|
|
4
|
+
[](https://www.npmjs.com/package/solfaces)
|
|
5
|
+
[](https://github.com/jorger3301/SolFaces/blob/main/LICENSE)
|
|
6
|
+
[](https://bundlephobia.com/package/solfaces)
|
|
4
7
|
|
|
5
|
-
|
|
8
|
+
**Deterministic wallet avatars and names for the Solana ecosystem.**
|
|
9
|
+
|
|
10
|
+
Every Solana wallet address generates a unique, consistent face and a deterministic name — no API calls, no storage, no randomness. Same wallet = same face, same name, everywhere, forever.
|
|
6
11
|
|
|
7
12
|
Built for dApps, AI agents, social features, leaderboards, and anywhere a wallet needs a visual identity.
|
|
8
13
|
|
|
14
|
+

|
|
15
|
+
|
|
16
|
+
*Default, Light, Dark, and Mono — four of the 11 built-in themes. Each row shows the same 10 wallets rendered in a different theme.*
|
|
17
|
+
|
|
9
18
|
---
|
|
10
19
|
|
|
11
20
|
## Why SolFaces?
|
|
@@ -13,15 +22,15 @@ Built for dApps, AI agents, social features, leaderboards, and anywhere a wallet
|
|
|
13
22
|
- **Deterministic** — Same wallet always produces the same avatar. No database needed.
|
|
14
23
|
- **Zero dependencies** — Core engine has no runtime dependencies.
|
|
15
24
|
- **~2.56B unique faces** — 11 traits with expanded ranges = massive combination space.
|
|
25
|
+
- **SolNames** — Every wallet gets a deterministic, human-friendly name derived via SHA-256 (e.g. "SunnyIcon"). ~1M display names, ~65.5B unique tags.
|
|
26
|
+
- **11 built-in themes** — Default, Dark, Light, Mono, Flat, Transparent, plus 3 Pixel and 2 Glass themes (React).
|
|
16
27
|
- **Gradient-rich rendering** — Skin-luminance-driven colors, specular highlights, cheek blush, gradient hair, glow overlays.
|
|
17
28
|
- **Works everywhere** — React, vanilla JS, Node, Python, CDN script tag, edge functions.
|
|
18
|
-
- **Pixel art mode** — Retro pixelated rendering with optional scanlines (React).
|
|
19
|
-
- **Liquid glass mode** — Backdrop-blur glass effect with rim lighting (React).
|
|
20
29
|
- **Flat mode** — Disable all gradients for simplified rendering.
|
|
21
30
|
- **Detail levels** — Full detail (gradients, specular, cheeks) at size >= 48, simplified below.
|
|
22
31
|
- **Fully customizable** — Every visual element is customizable: 4 color palettes, 8 individual color overrides, 9 per-instance color keys, rendering toggles, layout controls, blink timing, and 30+ React-only pixel/glass fields. No visual element is locked — if you can see it, you can theme it.
|
|
23
32
|
- **Eliminates dead space** — No more blank avatars or generic placeholders. Every wallet gets a unique face instantly.
|
|
24
|
-
- **AI-agent ready** —
|
|
33
|
+
- **AI-agent ready** — AI trading bots and autonomous agents are becoming on-chain users. SolFaces gives every agent a recognizable face and a natural language self-description for system prompts and bios.
|
|
25
34
|
- **PNG rasterization** — Serve real image files for bots, Discord, Telegram, OG images.
|
|
26
35
|
- **SSR-ready** — String renderer works server-side with zero browser APIs.
|
|
27
36
|
|
|
@@ -106,6 +115,24 @@ mountSolFace("#avatar", "7xKXqR...", { size: 48 });
|
|
|
106
115
|
</script>
|
|
107
116
|
```
|
|
108
117
|
|
|
118
|
+
### Name Derivation (SolNames)
|
|
119
|
+
|
|
120
|
+
```ts
|
|
121
|
+
import { deriveName, deriveIdentity } from "solfaces";
|
|
122
|
+
|
|
123
|
+
deriveName("7xKXqR...");
|
|
124
|
+
// → "SunnyIcon" (deterministic, SHA-256 derived)
|
|
125
|
+
|
|
126
|
+
deriveName("7xKXqR...", "tag");
|
|
127
|
+
// → "SunnyIcon#2f95" (unique identifier)
|
|
128
|
+
|
|
129
|
+
deriveName("7xKXqR...", "full");
|
|
130
|
+
// → "SunnyIcon-InfiniteOre" (formal contexts)
|
|
131
|
+
|
|
132
|
+
const id = deriveIdentity("7xKXqR...");
|
|
133
|
+
// → { short, name, tag, full, adjective, noun, hash, discriminator }
|
|
134
|
+
```
|
|
135
|
+
|
|
109
136
|
### Node / SSR / Edge
|
|
110
137
|
|
|
111
138
|
```ts
|
|
@@ -118,13 +145,93 @@ const svg = renderSolFaceSVG("7xKXqR...", { size: 128 });
|
|
|
118
145
|
### Python
|
|
119
146
|
|
|
120
147
|
```python
|
|
121
|
-
from solfaces import generate_traits, render_svg, describe_appearance
|
|
148
|
+
from solfaces import generate_traits, render_svg, describe_appearance, derive_name
|
|
122
149
|
|
|
123
150
|
traits = generate_traits("7xKXqR...")
|
|
124
151
|
svg = render_svg("7xKXqR...", size=256)
|
|
125
152
|
desc = describe_appearance("7xKXqR...")
|
|
153
|
+
name = derive_name("7xKXqR...")
|
|
154
|
+
```
|
|
155
|
+
|
|
156
|
+
---
|
|
157
|
+
|
|
158
|
+
## SolNames — Deterministic Name Derivation
|
|
159
|
+
|
|
160
|
+
Every wallet gets a deterministic, human-friendly name derived via SHA-256 hashing and curated word lists. Nothing like this exists on any blockchain — every other naming system (SNS, ENS, Unstoppable Domains) requires purchase. SolNames derives names automatically — zero registration, zero storage, just math.
|
|
161
|
+
|
|
162
|
+
```
|
|
163
|
+
Wallet: 7PjJ2AHq9BMXWYjt3qqeKwZVLXHYFPmHRYrMF6PpRySD
|
|
164
|
+
│
|
|
165
|
+
↓
|
|
166
|
+
SHA-256("solnames-v1:" + wallet) → 32 bytes
|
|
167
|
+
│
|
|
168
|
+
├─→ Bytes 0-3: seed PRNG → adjective + noun
|
|
169
|
+
└─→ Bytes 8-9: hex discriminator → "2f95"
|
|
170
|
+
|
|
171
|
+
Display: WavingMistral
|
|
172
|
+
Tag: WavingMistral#2f95
|
|
173
|
+
```
|
|
174
|
+
|
|
175
|
+
### Name Formats
|
|
176
|
+
|
|
177
|
+
| Format | Example | Unique Names | Use Case |
|
|
178
|
+
|---------|------------------------------|-------------|-----------------------------|
|
|
179
|
+
| short | "Waving" | 1,000 | Tight UIs, badges |
|
|
180
|
+
| display | "WavingMistral" | ~1,000,000 | Default — profiles, feeds |
|
|
181
|
+
| tag | "WavingMistral#2f95" | ~65.5B | Unique identifier |
|
|
182
|
+
| full | "WavingMistral-InfiniteOre" | ~1T | Formal contexts |
|
|
183
|
+
|
|
184
|
+
### Usage
|
|
185
|
+
|
|
186
|
+
```ts
|
|
187
|
+
import { deriveName, deriveIdentity } from "solfaces";
|
|
188
|
+
// or: import { deriveName } from "solfaces/names";
|
|
189
|
+
|
|
190
|
+
deriveName("7xKXqR..."); // → "SunnyIcon" (display format)
|
|
191
|
+
deriveName("7xKXqR...", "short"); // → "Sunny"
|
|
192
|
+
deriveName("7xKXqR...", "tag"); // → "SunnyIcon#2f95"
|
|
193
|
+
deriveName("7xKXqR...", "full"); // → "SunnyIcon-InfiniteOre"
|
|
194
|
+
|
|
195
|
+
const id = deriveIdentity("7xKXqR...");
|
|
196
|
+
// → { short, name, tag, full, adjective, noun, hash, discriminator }
|
|
197
|
+
```
|
|
198
|
+
|
|
199
|
+
### React Hook
|
|
200
|
+
|
|
201
|
+
```tsx
|
|
202
|
+
import { useSolName } from "solfaces/react";
|
|
203
|
+
|
|
204
|
+
function Profile({ wallet }) {
|
|
205
|
+
const name = useSolName(wallet, "display"); // string
|
|
206
|
+
const identity = useSolName(wallet); // full SolNameIdentity
|
|
207
|
+
return <span>{name}</span>;
|
|
208
|
+
}
|
|
126
209
|
```
|
|
127
210
|
|
|
211
|
+
### Show Name with Avatar
|
|
212
|
+
|
|
213
|
+
```tsx
|
|
214
|
+
import { SolFace } from "solfaces/react";
|
|
215
|
+
|
|
216
|
+
<SolFace walletAddress="7xKXqR..." showName />
|
|
217
|
+
<SolFace walletAddress="7xKXqR..." showName namePosition="above" nameFormat="tag" />
|
|
218
|
+
```
|
|
219
|
+
|
|
220
|
+
### Validation
|
|
221
|
+
|
|
222
|
+
```ts
|
|
223
|
+
import { isValidSolName, parseSolName } from "solfaces/names";
|
|
224
|
+
|
|
225
|
+
isValidSolName("SunnyIcon"); // true
|
|
226
|
+
isValidSolName("SunnyIcon#2f95"); // true
|
|
227
|
+
parseSolName("SunnyIcon#2f95");
|
|
228
|
+
// → { adjective: "Sunny", noun: "Icon", discriminator: "2f95" }
|
|
229
|
+
```
|
|
230
|
+
|
|
231
|
+
- **1000 adjectives + 1000 nouns** — curated positive/neutral PascalCase words
|
|
232
|
+
- **Same name everywhere** — TypeScript, Python, CDN, and server all produce identical output
|
|
233
|
+
- **Blocked combinations** — offensive adjective+noun pairs are automatically skipped
|
|
234
|
+
|
|
128
235
|
---
|
|
129
236
|
|
|
130
237
|
## Rendering Modes
|
|
@@ -188,7 +295,7 @@ import { glassTheme, glassDarkTheme } from "solfaces/themes";
|
|
|
188
295
|
|
|
189
296
|
## AI Agent Identity
|
|
190
297
|
|
|
191
|
-
|
|
298
|
+
AI trading bots, autonomous agents, and on-chain programs are becoming users — they need a visual identity, a personality, and a recognizable presence. SolFaces gives every agent a deterministic face tied to their wallet, plus natural language self-descriptions they can use in system prompts to know and reference what they look like.
|
|
192
299
|
|
|
193
300
|
### System Prompt Integration
|
|
194
301
|
|
|
@@ -487,9 +594,10 @@ const result = await handleToolCall("generate_solface_svg", {
|
|
|
487
594
|
|------|-------------|
|
|
488
595
|
| `generate_solface_svg` | Render SVG avatar from wallet address |
|
|
489
596
|
| `describe_solface` | Natural language description of an avatar |
|
|
490
|
-
| `get_solface_traits` | Raw trait data with labels and
|
|
597
|
+
| `get_solface_traits` | Raw trait data with labels, hash, and name |
|
|
491
598
|
| `get_agent_identity` | System prompt snippet for AI agent identity |
|
|
492
599
|
| `list_solface_themes` | List available preset themes |
|
|
600
|
+
| `derive_solname` | Deterministic name from wallet via SHA-256 |
|
|
493
601
|
|
|
494
602
|
### MCP Server (Claude Code / Cursor)
|
|
495
603
|
|
|
@@ -518,7 +626,7 @@ import {
|
|
|
518
626
|
|
|
519
627
|
### Skill File for AI Agents
|
|
520
628
|
|
|
521
|
-
SolFaces includes a comprehensive `
|
|
629
|
+
SolFaces includes a comprehensive `SKILL.md` (with 3 reference files in `reference/`) that teaches AI agents how to integrate, customize, and use SolFaces. Feed it to any agent (Claude, GPT, custom bots) as context.
|
|
522
630
|
|
|
523
631
|
---
|
|
524
632
|
|
|
@@ -543,11 +651,12 @@ Templates included for: **Next.js App Router**, **Express**, **Hono (Cloudflare
|
|
|
543
651
|
Full Python implementation with identical trait generation to JavaScript. Zero dependencies. Includes gradient-rich rendering matching the TypeScript renderer.
|
|
544
652
|
|
|
545
653
|
```python
|
|
546
|
-
from solfaces import generate_traits, render_svg, describe_appearance
|
|
654
|
+
from solfaces import generate_traits, render_svg, describe_appearance, derive_name
|
|
547
655
|
|
|
548
656
|
traits = generate_traits("7xKXqR...")
|
|
549
657
|
svg = render_svg("7xKXqR...", size=256)
|
|
550
658
|
desc = describe_appearance("7xKXqR...")
|
|
659
|
+
name = derive_name("7xKXqR...")
|
|
551
660
|
prompt = agent_appearance_prompt("7xKXqR...", "Atlas")
|
|
552
661
|
```
|
|
553
662
|
|
|
@@ -586,6 +695,7 @@ For sites without a build step — Webflow, Notion embeds, plain HTML, WordPress
|
|
|
586
695
|
SolFaces.setImg("#pfp", "7xKXqR...");
|
|
587
696
|
const svg = SolFaces.renderSVG("7xKXqR...");
|
|
588
697
|
const desc = SolFaces.describe("7xKXqR...");
|
|
698
|
+
const name = SolFaces.deriveName("7xKXqR...");
|
|
589
699
|
const prompt = SolFaces.agentPrompt("7xKXqR...", "Atlas");
|
|
590
700
|
</script>
|
|
591
701
|
```
|
|
@@ -596,6 +706,8 @@ For sites without a build step — Webflow, Notion embeds, plain HTML, WordPress
|
|
|
596
706
|
|
|
597
707
|
| Function | Returns | Description |
|
|
598
708
|
|----------|---------|-------------|
|
|
709
|
+
| `deriveName(wallet, format?)` | `string` | Deterministic name from wallet (SHA-256) |
|
|
710
|
+
| `deriveIdentity(wallet)` | `SolNameIdentity` | Full identity bundle from wallet |
|
|
599
711
|
| `generateTraits(wallet, overrides?)` | `SolFaceTraits` | Deterministic traits from wallet |
|
|
600
712
|
| `getTraitLabels(traits)` | `Record<string, string>` | Human-readable trait names |
|
|
601
713
|
| `traitHash(wallet)` | `string` | 8-char hex hash |
|
|
@@ -619,7 +731,7 @@ For sites without a build step — Webflow, Notion embeds, plain HTML, WordPress
|
|
|
619
731
|
| `blend(a, b, t)` | `string` | Blend two colors |
|
|
620
732
|
| `luminance(hex)` | `number` | Perceived luminance (0-255) |
|
|
621
733
|
| `deriveSkinColors(skinHex)` | `DerivedColors` | Full skin-luminance color derivation |
|
|
622
|
-
| `SOLFACE_TOOLS` | `SolFaceTool[]` | All
|
|
734
|
+
| `SOLFACE_TOOLS` | `SolFaceTool[]` | All 6 agent tool definitions |
|
|
623
735
|
| `handleToolCall(name, params)` | `unknown` | Universal agent tool dispatcher |
|
|
624
736
|
|
|
625
737
|
### React Component Props
|
|
@@ -693,11 +805,12 @@ Available keys: `skin`, `eyes`, `hair`, `bg`, `mouth`, `eyebrow`, `accessory`, `
|
|
|
693
805
|
|
|
694
806
|
| Path | Contents | React? |
|
|
695
807
|
|------|----------|--------|
|
|
696
|
-
| `solfaces` | Core + colors + themes + describe + rasterize + agent tools | No |
|
|
808
|
+
| `solfaces` | Core + colors + themes + names + describe + rasterize + agent tools | No |
|
|
697
809
|
| `solfaces/core` | Engine only (traits, renderer, colors, describe) | No |
|
|
698
810
|
| `solfaces/react` | React component (base + pixel + glass modes) | Yes |
|
|
699
811
|
| `solfaces/vanilla` | DOM helpers (mount, setImg, autoInit) | No |
|
|
700
812
|
| `solfaces/themes` | 11 preset themes | No |
|
|
813
|
+
| `solfaces/names` | SolNames derivation + validation | No |
|
|
701
814
|
| `solfaces/agent` | AI agent tool definitions + framework adapters | No |
|
|
702
815
|
| `solfaces/cdn` | IIFE for `<script>` tags | No |
|
|
703
816
|
|
|
@@ -738,11 +851,18 @@ solfaces/
|
|
|
738
851
|
│ │ ├── colors.ts # Color math: darken, lighten, blend, deriveSkinColors
|
|
739
852
|
│ │ ├── traits.ts # Types, palettes, theme system, trait generation
|
|
740
853
|
│ │ ├── renderer.ts # SVG string renderer (gradient-rich, detail levels)
|
|
741
|
-
│ │ ├── describe.ts #
|
|
854
|
+
│ │ ├── describe.ts # (no names.ts — moved to names/)
|
|
742
855
|
│ │ ├── rasterize.ts # PNG output (sharp / resvg / canvas)
|
|
743
856
|
│ │ └── index.ts
|
|
857
|
+
│ ├── names/
|
|
858
|
+
│ │ ├── constants.ts # 1000 adjectives, 1000 nouns, blocked combos
|
|
859
|
+
│ │ ├── sha256.ts # Pure-JS SHA-256 (sync, zero deps)
|
|
860
|
+
│ │ ├── derive.ts # deriveName(), deriveIdentity()
|
|
861
|
+
│ │ ├── validate.ts # isValidSolName(), parseSolName()
|
|
862
|
+
│ │ └── index.ts
|
|
744
863
|
│ ├── react/
|
|
745
864
|
│ │ ├── SolFace.tsx # React component (base + pixel art + liquid glass)
|
|
865
|
+
│ │ ├── useSolName.ts # useSolName() hook
|
|
746
866
|
│ │ └── index.ts
|
|
747
867
|
│ ├── vanilla/
|
|
748
868
|
│ │ └── index.ts # mountSolFace, setSolFaceImg, autoInit
|
|
@@ -750,7 +870,7 @@ solfaces/
|
|
|
750
870
|
│ │ ├── presets.ts # 11 preset themes
|
|
751
871
|
│ │ └── index.ts
|
|
752
872
|
│ ├── agent/
|
|
753
|
-
│ │ ├── tools.ts #
|
|
873
|
+
│ │ ├── tools.ts # 6 canonical tool definitions + handlers
|
|
754
874
|
│ │ ├── index.ts # Format adapters (MCP, OpenAI, Anthropic, Vercel AI)
|
|
755
875
|
│ │ └── mcp-server.ts # Standalone MCP server (npx solfaces)
|
|
756
876
|
│ ├── cdn.ts # IIFE bundle for <script> tag
|
package/SKILL.md
ADDED
|
@@ -0,0 +1,171 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: solfaces
|
|
3
|
+
description: Generates deterministic avatars and names for Solana wallet addresses. Use when the user mentions wallet avatars, profile pictures, visual identity, SolFaces, or needs to represent a Solana wallet visually. Provides SVG rendering, natural language descriptions, SHA-256 name derivation, and AI agent identity prompts. 6 tools available.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# SolFaces
|
|
7
|
+
|
|
8
|
+
Deterministic avatar and name generator for Solana wallets. Every wallet address produces a unique, consistent face and name. ~2.56B unique faces, ~1M display names (~65.5B unique tags). Zero dependencies, sub-millisecond, works everywhere.
|
|
9
|
+
|
|
10
|
+
---
|
|
11
|
+
|
|
12
|
+
## Available Tools
|
|
13
|
+
|
|
14
|
+
### `generate_solface_svg`
|
|
15
|
+
Render an SVG avatar from a wallet address.
|
|
16
|
+
|
|
17
|
+
**When to use:** User wants to see an avatar, embed one in a page, or display a wallet's face.
|
|
18
|
+
|
|
19
|
+
| Parameter | Type | Required | Default | Description |
|
|
20
|
+
|-----------|------|----------|---------|-------------|
|
|
21
|
+
| `wallet` | string | Yes | -- | Solana wallet address (base58) |
|
|
22
|
+
| `size` | number | No | 64 | Width/height in pixels. >= 48 uses full detail. |
|
|
23
|
+
| `theme` | string | No | -- | Preset: default, dark, light, mono, flat, transparent, glass, glassDark, pixel, pixelRetro, pixelClean |
|
|
24
|
+
| `enableBlink` | boolean | No | false | CSS eye-blink animation |
|
|
25
|
+
| `detail` | string | No | auto | "full", "simplified", or "auto" (full if size >= 48) |
|
|
26
|
+
|
|
27
|
+
Returns: SVG string. Note: glass/pixel themes are React-only.
|
|
28
|
+
|
|
29
|
+
### `describe_solface`
|
|
30
|
+
Natural language description of a wallet's avatar.
|
|
31
|
+
|
|
32
|
+
**When to use:** User wants alt text, a profile bio, or to know what a face looks like.
|
|
33
|
+
|
|
34
|
+
| Parameter | Type | Required | Default | Description |
|
|
35
|
+
|-----------|------|----------|---------|-------------|
|
|
36
|
+
| `wallet` | string | Yes | -- | Solana wallet address |
|
|
37
|
+
| `format` | string | No | paragraph | paragraph, structured, or compact |
|
|
38
|
+
| `perspective` | string | No | third | third or first |
|
|
39
|
+
| `name` | string | No | -- | Name to use instead of "This SolFace" |
|
|
40
|
+
|
|
41
|
+
### `get_solface_traits`
|
|
42
|
+
Raw trait data with human-readable labels and hash.
|
|
43
|
+
|
|
44
|
+
| Parameter | Type | Required | Description |
|
|
45
|
+
|-----------|------|----------|-------------|
|
|
46
|
+
| `wallet` | string | Yes | Solana wallet address |
|
|
47
|
+
|
|
48
|
+
Returns: `{ traits, labels, hash, name }`
|
|
49
|
+
|
|
50
|
+
### `get_agent_identity`
|
|
51
|
+
System prompt snippet giving an AI agent a visual identity.
|
|
52
|
+
|
|
53
|
+
| Parameter | Type | Required | Description |
|
|
54
|
+
|-----------|------|----------|-------------|
|
|
55
|
+
| `wallet` | string | Yes | Agent's wallet address |
|
|
56
|
+
| `agentName` | string | No | Agent name for personalization |
|
|
57
|
+
|
|
58
|
+
Returns: First-person identity prompt string.
|
|
59
|
+
|
|
60
|
+
### `derive_solname`
|
|
61
|
+
Derive a deterministic name from a wallet via SHA-256 hashing and curated word lists.
|
|
62
|
+
|
|
63
|
+
**When to use:** User needs a name for a wallet, wants to label a wallet, or needs an identity name.
|
|
64
|
+
|
|
65
|
+
| Parameter | Type | Required | Default | Description |
|
|
66
|
+
|-----------|------|----------|---------|-------------|
|
|
67
|
+
| `wallet` | string | Yes | -- | Solana wallet address (base58) |
|
|
68
|
+
| `format` | string | No | -- | "short", "display", "tag", or "full". Omit for full identity object. |
|
|
69
|
+
|
|
70
|
+
Returns: Without format: `SolNameIdentity` object (short/name/tag/full/adjective/noun/hash/discriminator). With format: formatted string.
|
|
71
|
+
|
|
72
|
+
### `list_solface_themes`
|
|
73
|
+
List available preset themes with descriptions.
|
|
74
|
+
|
|
75
|
+
No parameters. Returns: Array of `{ name, description, reactOnly }`.
|
|
76
|
+
|
|
77
|
+
---
|
|
78
|
+
|
|
79
|
+
## Installation
|
|
80
|
+
|
|
81
|
+
```bash
|
|
82
|
+
npm install solfaces
|
|
83
|
+
```
|
|
84
|
+
```html
|
|
85
|
+
<script src="https://unpkg.com/solfaces/dist/solfaces.cdn.global.js"></script>
|
|
86
|
+
```
|
|
87
|
+
```bash
|
|
88
|
+
curl -O https://raw.githubusercontent.com/jorger3301/solfaces/main/python/solfaces.py
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
---
|
|
92
|
+
|
|
93
|
+
## Import Paths
|
|
94
|
+
|
|
95
|
+
| Project Type | Import Path | What You Get |
|
|
96
|
+
|---|---|---|
|
|
97
|
+
| React / Next.js | `solfaces/react` | `<SolFace>` component with pixel art and glass modes |
|
|
98
|
+
| Vanilla JS / Vue / Svelte | `solfaces/vanilla` | `mountSolFace()`, `setSolFaceImg()`, `autoInit()` |
|
|
99
|
+
| Node.js server / API | `solfaces` | `renderSolFaceSVG()`, `renderSolFacePNG()`, descriptions, colors |
|
|
100
|
+
| No build step / CDN | `<script>` tag | `window.SolFaces` global |
|
|
101
|
+
| AI agent framework | `solfaces/agent` | Tool schemas + format adapters |
|
|
102
|
+
| Theme presets only | `solfaces/themes` | 11 preset theme objects |
|
|
103
|
+
| Names only | `solfaces/names` | `deriveName()`, `deriveIdentity()`, validation |
|
|
104
|
+
| Python backend | `from solfaces import ...` | Full Python port |
|
|
105
|
+
|
|
106
|
+
---
|
|
107
|
+
|
|
108
|
+
## Quick Examples
|
|
109
|
+
|
|
110
|
+
### React
|
|
111
|
+
```tsx
|
|
112
|
+
import { SolFace } from "solfaces/react";
|
|
113
|
+
<SolFace walletAddress="7xKXtg..." size={48} enableBlink showName />
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
### Server-side
|
|
117
|
+
```ts
|
|
118
|
+
import { renderSolFaceSVG } from "solfaces";
|
|
119
|
+
const svg = renderSolFaceSVG("7xKXtg...", { size: 256 });
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
### Name derivation
|
|
123
|
+
```ts
|
|
124
|
+
import { deriveName, deriveIdentity } from "solfaces";
|
|
125
|
+
deriveName("7xKXtg..."); // "SunnyIcon"
|
|
126
|
+
deriveName("7xKXtg...", "tag"); // "SunnyIcon#2f95"
|
|
127
|
+
const id = deriveIdentity("7xKXtg..."); // full identity object
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
### CDN
|
|
131
|
+
```html
|
|
132
|
+
<div data-solface="7xKXtg..." data-solface-size="48"></div>
|
|
133
|
+
<script src="https://unpkg.com/solfaces/dist/solfaces.cdn.global.js"></script>
|
|
134
|
+
<script>
|
|
135
|
+
const name = SolFaces.deriveName("7xKXtg...");
|
|
136
|
+
SolFaces.mount("#avatar", "7xKXtg...", { size: 64 });
|
|
137
|
+
</script>
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
---
|
|
141
|
+
|
|
142
|
+
## Rendering Modes
|
|
143
|
+
|
|
144
|
+
- **Full detail** (size >= 48): Gradients, specular highlights, cheek blush, chin shadow, glow.
|
|
145
|
+
- **Simplified** (size < 48): Flat shapes, no gradients. Override with `detail: "full"` or `"simplified"`.
|
|
146
|
+
- **Flat mode**: `theme: { flat: true }` disables all gradients.
|
|
147
|
+
- **Pixel art** (React only): `pixelTheme`, `pixelRetroTheme`, `pixelCleanTheme`.
|
|
148
|
+
- **Liquid glass** (React only): `glassTheme`, `glassDarkTheme`.
|
|
149
|
+
|
|
150
|
+
---
|
|
151
|
+
|
|
152
|
+
## Detailed Reference
|
|
153
|
+
|
|
154
|
+
For comprehensive documentation on specific topics:
|
|
155
|
+
|
|
156
|
+
- **React component**: Full props interface, all rendering modes, `useSolName` hook, `showName` prop, color overrides, blink timing. See [reference/react.md](reference/react.md)
|
|
157
|
+
- **Themes**: All theme fields, pixel art and glass customization, theme recommendations, custom theme examples. See [reference/themes.md](reference/themes.md)
|
|
158
|
+
- **Integrations**: Agent framework adapters (OpenAI, Anthropic, Vercel AI, MCP), server-side routes, bot integration, full API reference, color math utilities, accessibility. See [reference/integrations.md](reference/integrations.md)
|
|
159
|
+
|
|
160
|
+
---
|
|
161
|
+
|
|
162
|
+
## Key Facts
|
|
163
|
+
|
|
164
|
+
- **Deterministic**: Same wallet = same face + same name. djb2 + mulberry32 PRNG (traits), SHA-256 + mulberry32 PRNG (names).
|
|
165
|
+
- **11 traits**: Face shape (4), skin (10), eye style (8), eye color (5), eyebrows (5), nose (4), mouth (8), hair style (10), hair color (10), accessory (10), background (10) = ~2.56B unique faces.
|
|
166
|
+
- **SolNames**: 1000 adjectives + 1000 nouns, SHA-256 derived. Formats: short, display (~1M), tag (~65.5B), full (~1T).
|
|
167
|
+
- **Earring suppression**: Long and bob hairstyles suppress earring accessories.
|
|
168
|
+
- **Cross-language parity**: JS and Python produce identical output.
|
|
169
|
+
- **Zero dependencies**: Core engine has no runtime deps.
|
|
170
|
+
- **SVG viewBox**: All avatars use 64x64 viewBox, scaled by `size`.
|
|
171
|
+
- **Alt text**: `solFaceAltText(wallet)` provides accessible descriptions.
|
package/dist/agent/index.cjs
CHANGED
|
@@ -1,51 +1,52 @@
|
|
|
1
1
|
'use strict';
|
|
2
2
|
|
|
3
|
-
var
|
|
4
|
-
require('../chunk-
|
|
5
|
-
require('../chunk-
|
|
3
|
+
var chunkF244Q4KC_cjs = require('../chunk-F244Q4KC.cjs');
|
|
4
|
+
require('../chunk-CXRVPOTI.cjs');
|
|
5
|
+
require('../chunk-HVPGR6G5.cjs');
|
|
6
6
|
require('../chunk-6QRDULAO.cjs');
|
|
7
|
+
require('../chunk-R3MC2AJZ.cjs');
|
|
7
8
|
|
|
8
9
|
|
|
9
10
|
|
|
10
11
|
Object.defineProperty(exports, "SOLFACE_TOOLS", {
|
|
11
12
|
enumerable: true,
|
|
12
|
-
get: function () { return
|
|
13
|
+
get: function () { return chunkF244Q4KC_cjs.SOLFACE_TOOLS; }
|
|
13
14
|
});
|
|
14
15
|
Object.defineProperty(exports, "allToolsAnthropic", {
|
|
15
16
|
enumerable: true,
|
|
16
|
-
get: function () { return
|
|
17
|
+
get: function () { return chunkF244Q4KC_cjs.allToolsAnthropic; }
|
|
17
18
|
});
|
|
18
19
|
Object.defineProperty(exports, "allToolsMCP", {
|
|
19
20
|
enumerable: true,
|
|
20
|
-
get: function () { return
|
|
21
|
+
get: function () { return chunkF244Q4KC_cjs.allToolsMCP; }
|
|
21
22
|
});
|
|
22
23
|
Object.defineProperty(exports, "allToolsOpenAI", {
|
|
23
24
|
enumerable: true,
|
|
24
|
-
get: function () { return
|
|
25
|
+
get: function () { return chunkF244Q4KC_cjs.allToolsOpenAI; }
|
|
25
26
|
});
|
|
26
27
|
Object.defineProperty(exports, "allToolsVercelAI", {
|
|
27
28
|
enumerable: true,
|
|
28
|
-
get: function () { return
|
|
29
|
+
get: function () { return chunkF244Q4KC_cjs.allToolsVercelAI; }
|
|
29
30
|
});
|
|
30
31
|
Object.defineProperty(exports, "handleToolCall", {
|
|
31
32
|
enumerable: true,
|
|
32
|
-
get: function () { return
|
|
33
|
+
get: function () { return chunkF244Q4KC_cjs.handleToolCall; }
|
|
33
34
|
});
|
|
34
35
|
Object.defineProperty(exports, "toAnthropic", {
|
|
35
36
|
enumerable: true,
|
|
36
|
-
get: function () { return
|
|
37
|
+
get: function () { return chunkF244Q4KC_cjs.toAnthropic; }
|
|
37
38
|
});
|
|
38
39
|
Object.defineProperty(exports, "toMCP", {
|
|
39
40
|
enumerable: true,
|
|
40
|
-
get: function () { return
|
|
41
|
+
get: function () { return chunkF244Q4KC_cjs.toMCP; }
|
|
41
42
|
});
|
|
42
43
|
Object.defineProperty(exports, "toOpenAI", {
|
|
43
44
|
enumerable: true,
|
|
44
|
-
get: function () { return
|
|
45
|
+
get: function () { return chunkF244Q4KC_cjs.toOpenAI; }
|
|
45
46
|
});
|
|
46
47
|
Object.defineProperty(exports, "toVercelAI", {
|
|
47
48
|
enumerable: true,
|
|
48
|
-
get: function () { return
|
|
49
|
+
get: function () { return chunkF244Q4KC_cjs.toVercelAI; }
|
|
49
50
|
});
|
|
50
51
|
//# sourceMappingURL=index.cjs.map
|
|
51
52
|
//# sourceMappingURL=index.cjs.map
|
package/dist/agent/index.js
CHANGED
|
@@ -1,6 +1,7 @@
|
|
|
1
|
-
export { SOLFACE_TOOLS, allToolsAnthropic, allToolsMCP, allToolsOpenAI, allToolsVercelAI, handleToolCall, toAnthropic, toMCP, toOpenAI, toVercelAI } from '../chunk-
|
|
2
|
-
import '../chunk-
|
|
3
|
-
import '../chunk-
|
|
1
|
+
export { SOLFACE_TOOLS, allToolsAnthropic, allToolsMCP, allToolsOpenAI, allToolsVercelAI, handleToolCall, toAnthropic, toMCP, toOpenAI, toVercelAI } from '../chunk-77SPWQU5.js';
|
|
2
|
+
import '../chunk-CQWXUU7P.js';
|
|
3
|
+
import '../chunk-SWML743U.js';
|
|
4
4
|
import '../chunk-DRUSCLEF.js';
|
|
5
|
+
import '../chunk-SX3FQDKM.js';
|
|
5
6
|
//# sourceMappingURL=index.js.map
|
|
6
7
|
//# sourceMappingURL=index.js.map
|