solfaces 2.0.0 → 2.1.1
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 +155 -14
- package/SKILL.md +180 -0
- package/dist/agent/index.cjs +14 -13
- package/dist/agent/index.js +4 -3
- package/dist/agent/mcp-server.cjs +2248 -13
- package/dist/{chunk-HCEE4K4T.js → chunk-3CE7Q44S.js} +6 -5
- package/dist/chunk-3CE7Q44S.js.map +1 -0
- package/dist/{chunk-23XJ5VDX.cjs → chunk-4YFZ4W2Y.cjs} +47 -16
- package/dist/chunk-4YFZ4W2Y.cjs.map +1 -0
- package/dist/{chunk-LRHYF5QN.js → chunk-5DT27HMT.js} +3 -3
- package/dist/{chunk-LRHYF5QN.js.map → chunk-5DT27HMT.js.map} +1 -1
- package/dist/{chunk-TTGJZEPV.js → chunk-66PSL4YO.js} +43 -12
- package/dist/chunk-66PSL4YO.js.map +1 -0
- package/dist/{chunk-JS527VKL.js → chunk-CKHLRORB.js} +6 -5
- package/dist/chunk-CKHLRORB.js.map +1 -0
- package/dist/{chunk-6UWILY7E.cjs → chunk-F54WHRCE.cjs} +6 -5
- package/dist/chunk-F54WHRCE.cjs.map +1 -0
- package/dist/chunk-N5DDJ3WQ.js +2242 -0
- package/dist/chunk-N5DDJ3WQ.js.map +1 -0
- package/dist/{chunk-46ZEFA6R.cjs → chunk-TYTBYDQU.cjs} +10 -9
- package/dist/chunk-TYTBYDQU.cjs.map +1 -0
- package/dist/{chunk-546TBMAR.cjs → chunk-WIXGHS77.cjs} +6 -6
- package/dist/{chunk-546TBMAR.cjs.map → chunk-WIXGHS77.cjs.map} +1 -1
- package/dist/chunk-XXJJH56O.cjs +2251 -0
- package/dist/chunk-XXJJH56O.cjs.map +1 -0
- 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.d.cts +2 -2
- package/dist/core/index.d.ts +2 -2
- package/dist/core/index.js +3 -3
- package/dist/index.cjs +63 -34
- package/dist/index.d.cts +3 -1
- package/dist/index.d.ts +3 -1
- 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 +48 -0
- package/dist/names/index.d.ts +48 -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 +16 -3
- package/dist/react/index.d.ts +16 -3
- 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/themes/index.d.cts +1 -1
- package/dist/themes/index.d.ts +1 -1
- package/dist/{traits-QlWuxZDD.d.cts → traits-sfe7rM9C.d.cts} +1 -0
- package/dist/{traits-QlWuxZDD.d.ts → traits-sfe7rM9C.d.ts} +1 -0
- package/dist/vanilla/index.cjs +5 -5
- package/dist/vanilla/index.d.cts +1 -1
- package/dist/vanilla/index.d.ts +1 -1
- package/dist/vanilla/index.js +2 -2
- package/package.json +22 -5
- package/python/solfaces.py +274 -3
- package/reference/integrations.md +211 -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-6UWILY7E.cjs.map +0 -1
- package/dist/chunk-HCEE4K4T.js.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,114 @@ 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 }
|
|
126
197
|
```
|
|
127
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
|
+
}
|
|
209
|
+
```
|
|
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
|
+
### Custom Word Lists
|
|
232
|
+
|
|
233
|
+
Both `deriveName` and `deriveIdentity` accept an optional `DeriveOptions` parameter to fully customize name generation:
|
|
234
|
+
|
|
235
|
+
```ts
|
|
236
|
+
import { deriveName, deriveIdentity } from "solfaces";
|
|
237
|
+
import type { DeriveOptions } from "solfaces";
|
|
238
|
+
|
|
239
|
+
const opts: DeriveOptions = {
|
|
240
|
+
adjectives: ["Fast", "Bold", "Calm", "Keen", "Wise"],
|
|
241
|
+
nouns: ["Tiger", "Eagle", "Bear", "Wolf", "Hawk"],
|
|
242
|
+
domain: "my-app-v1", // Custom domain prefix (default: "solnames-v1")
|
|
243
|
+
blockedCombos: new Set(["BoldBear"]), // Custom blocked pairs
|
|
244
|
+
};
|
|
245
|
+
|
|
246
|
+
deriveName("7xKXqR...", "display", opts); // Uses custom word lists
|
|
247
|
+
deriveIdentity("7xKXqR...", opts); // Full identity with custom lists
|
|
248
|
+
```
|
|
249
|
+
|
|
250
|
+
All fields are optional — omit any to use the built-in defaults.
|
|
251
|
+
|
|
252
|
+
- **1000 adjectives + 1000 nouns** — curated positive/neutral PascalCase words (customizable via `DeriveOptions`)
|
|
253
|
+
- **Same name everywhere** — TypeScript, Python, CDN, and server all produce identical output
|
|
254
|
+
- **Blocked combinations** — offensive adjective+noun pairs are automatically skipped (customizable via `DeriveOptions`)
|
|
255
|
+
|
|
128
256
|
---
|
|
129
257
|
|
|
130
258
|
## Rendering Modes
|
|
@@ -188,7 +316,7 @@ import { glassTheme, glassDarkTheme } from "solfaces/themes";
|
|
|
188
316
|
|
|
189
317
|
## AI Agent Identity
|
|
190
318
|
|
|
191
|
-
|
|
319
|
+
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
320
|
|
|
193
321
|
### System Prompt Integration
|
|
194
322
|
|
|
@@ -487,9 +615,10 @@ const result = await handleToolCall("generate_solface_svg", {
|
|
|
487
615
|
|------|-------------|
|
|
488
616
|
| `generate_solface_svg` | Render SVG avatar from wallet address |
|
|
489
617
|
| `describe_solface` | Natural language description of an avatar |
|
|
490
|
-
| `get_solface_traits` | Raw trait data with labels and
|
|
618
|
+
| `get_solface_traits` | Raw trait data with labels, hash, and name |
|
|
491
619
|
| `get_agent_identity` | System prompt snippet for AI agent identity |
|
|
492
620
|
| `list_solface_themes` | List available preset themes |
|
|
621
|
+
| `derive_solname` | Deterministic name from wallet via SHA-256 |
|
|
493
622
|
|
|
494
623
|
### MCP Server (Claude Code / Cursor)
|
|
495
624
|
|
|
@@ -518,7 +647,7 @@ import {
|
|
|
518
647
|
|
|
519
648
|
### Skill File for AI Agents
|
|
520
649
|
|
|
521
|
-
SolFaces includes a comprehensive `
|
|
650
|
+
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
651
|
|
|
523
652
|
---
|
|
524
653
|
|
|
@@ -543,11 +672,12 @@ Templates included for: **Next.js App Router**, **Express**, **Hono (Cloudflare
|
|
|
543
672
|
Full Python implementation with identical trait generation to JavaScript. Zero dependencies. Includes gradient-rich rendering matching the TypeScript renderer.
|
|
544
673
|
|
|
545
674
|
```python
|
|
546
|
-
from solfaces import generate_traits, render_svg, describe_appearance
|
|
675
|
+
from solfaces import generate_traits, render_svg, describe_appearance, derive_name
|
|
547
676
|
|
|
548
677
|
traits = generate_traits("7xKXqR...")
|
|
549
678
|
svg = render_svg("7xKXqR...", size=256)
|
|
550
679
|
desc = describe_appearance("7xKXqR...")
|
|
680
|
+
name = derive_name("7xKXqR...")
|
|
551
681
|
prompt = agent_appearance_prompt("7xKXqR...", "Atlas")
|
|
552
682
|
```
|
|
553
683
|
|
|
@@ -586,6 +716,7 @@ For sites without a build step — Webflow, Notion embeds, plain HTML, WordPress
|
|
|
586
716
|
SolFaces.setImg("#pfp", "7xKXqR...");
|
|
587
717
|
const svg = SolFaces.renderSVG("7xKXqR...");
|
|
588
718
|
const desc = SolFaces.describe("7xKXqR...");
|
|
719
|
+
const name = SolFaces.deriveName("7xKXqR...");
|
|
589
720
|
const prompt = SolFaces.agentPrompt("7xKXqR...", "Atlas");
|
|
590
721
|
</script>
|
|
591
722
|
```
|
|
@@ -596,6 +727,8 @@ For sites without a build step — Webflow, Notion embeds, plain HTML, WordPress
|
|
|
596
727
|
|
|
597
728
|
| Function | Returns | Description |
|
|
598
729
|
|----------|---------|-------------|
|
|
730
|
+
| `deriveName(wallet, format?, options?)` | `string` | Deterministic name from wallet (SHA-256) |
|
|
731
|
+
| `deriveIdentity(wallet, options?)` | `SolNameIdentity` | Full identity bundle from wallet |
|
|
599
732
|
| `generateTraits(wallet, overrides?)` | `SolFaceTraits` | Deterministic traits from wallet |
|
|
600
733
|
| `getTraitLabels(traits)` | `Record<string, string>` | Human-readable trait names |
|
|
601
734
|
| `traitHash(wallet)` | `string` | 8-char hex hash |
|
|
@@ -619,7 +752,7 @@ For sites without a build step — Webflow, Notion embeds, plain HTML, WordPress
|
|
|
619
752
|
| `blend(a, b, t)` | `string` | Blend two colors |
|
|
620
753
|
| `luminance(hex)` | `number` | Perceived luminance (0-255) |
|
|
621
754
|
| `deriveSkinColors(skinHex)` | `DerivedColors` | Full skin-luminance color derivation |
|
|
622
|
-
| `SOLFACE_TOOLS` | `SolFaceTool[]` | All
|
|
755
|
+
| `SOLFACE_TOOLS` | `SolFaceTool[]` | All 6 agent tool definitions |
|
|
623
756
|
| `handleToolCall(name, params)` | `unknown` | Universal agent tool dispatcher |
|
|
624
757
|
|
|
625
758
|
### React Component Props
|
|
@@ -693,11 +826,12 @@ Available keys: `skin`, `eyes`, `hair`, `bg`, `mouth`, `eyebrow`, `accessory`, `
|
|
|
693
826
|
|
|
694
827
|
| Path | Contents | React? |
|
|
695
828
|
|------|----------|--------|
|
|
696
|
-
| `solfaces` | Core + colors + themes + describe + rasterize + agent tools | No |
|
|
829
|
+
| `solfaces` | Core + colors + themes + names + describe + rasterize + agent tools | No |
|
|
697
830
|
| `solfaces/core` | Engine only (traits, renderer, colors, describe) | No |
|
|
698
831
|
| `solfaces/react` | React component (base + pixel + glass modes) | Yes |
|
|
699
832
|
| `solfaces/vanilla` | DOM helpers (mount, setImg, autoInit) | No |
|
|
700
833
|
| `solfaces/themes` | 11 preset themes | No |
|
|
834
|
+
| `solfaces/names` | SolNames derivation + validation | No |
|
|
701
835
|
| `solfaces/agent` | AI agent tool definitions + framework adapters | No |
|
|
702
836
|
| `solfaces/cdn` | IIFE for `<script>` tags | No |
|
|
703
837
|
|
|
@@ -738,11 +872,18 @@ solfaces/
|
|
|
738
872
|
│ │ ├── colors.ts # Color math: darken, lighten, blend, deriveSkinColors
|
|
739
873
|
│ │ ├── traits.ts # Types, palettes, theme system, trait generation
|
|
740
874
|
│ │ ├── renderer.ts # SVG string renderer (gradient-rich, detail levels)
|
|
741
|
-
│ │ ├── describe.ts #
|
|
875
|
+
│ │ ├── describe.ts # (no names.ts — moved to names/)
|
|
742
876
|
│ │ ├── rasterize.ts # PNG output (sharp / resvg / canvas)
|
|
743
877
|
│ │ └── index.ts
|
|
878
|
+
│ ├── names/
|
|
879
|
+
│ │ ├── constants.ts # 1000 adjectives, 1000 nouns, blocked combos
|
|
880
|
+
│ │ ├── sha256.ts # Pure-JS SHA-256 (sync, zero deps)
|
|
881
|
+
│ │ ├── derive.ts # deriveName(), deriveIdentity()
|
|
882
|
+
│ │ ├── validate.ts # isValidSolName(), parseSolName()
|
|
883
|
+
│ │ └── index.ts
|
|
744
884
|
│ ├── react/
|
|
745
885
|
│ │ ├── SolFace.tsx # React component (base + pixel art + liquid glass)
|
|
886
|
+
│ │ ├── useSolName.ts # useSolName() hook
|
|
746
887
|
│ │ └── index.ts
|
|
747
888
|
│ ├── vanilla/
|
|
748
889
|
│ │ └── index.ts # mountSolFace, setSolFaceImg, autoInit
|
|
@@ -750,7 +891,7 @@ solfaces/
|
|
|
750
891
|
│ │ ├── presets.ts # 11 preset themes
|
|
751
892
|
│ │ └── index.ts
|
|
752
893
|
│ ├── agent/
|
|
753
|
-
│ │ ├── tools.ts #
|
|
894
|
+
│ │ ├── tools.ts # 6 canonical tool definitions + handlers
|
|
754
895
|
│ │ ├── index.ts # Format adapters (MCP, OpenAI, Anthropic, Vercel AI)
|
|
755
896
|
│ │ └── mcp-server.ts # Standalone MCP server (npx solfaces)
|
|
756
897
|
│ ├── cdn.ts # IIFE bundle for <script> tag
|
package/SKILL.md
ADDED
|
@@ -0,0 +1,180 @@
|
|
|
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
|
+
Returns: description string. Auto-populates `name` from `deriveName(wallet, "display")` if no name provided.
|
|
42
|
+
|
|
43
|
+
### `get_solface_traits`
|
|
44
|
+
Raw trait data with human-readable labels and hash.
|
|
45
|
+
|
|
46
|
+
| Parameter | Type | Required | Description |
|
|
47
|
+
|-----------|------|----------|-------------|
|
|
48
|
+
| `wallet` | string | Yes | Solana wallet address |
|
|
49
|
+
|
|
50
|
+
Returns: `{ traits: SolFaceTraits, labels: Record<string, string>, hash: string, name: string }`. Name is auto-populated from `deriveName(wallet, "display")`.
|
|
51
|
+
|
|
52
|
+
### `get_agent_identity`
|
|
53
|
+
System prompt snippet giving an AI agent a visual identity.
|
|
54
|
+
|
|
55
|
+
| Parameter | Type | Required | Description |
|
|
56
|
+
|-----------|------|----------|-------------|
|
|
57
|
+
| `wallet` | string | Yes | Agent's wallet address |
|
|
58
|
+
| `agentName` | string | No | Agent name for personalization |
|
|
59
|
+
|
|
60
|
+
Returns: First-person identity prompt string. Auto-populates agent name from `deriveName(wallet, "display")` if no `agentName` provided.
|
|
61
|
+
|
|
62
|
+
### `derive_solname`
|
|
63
|
+
Derive a deterministic name from a wallet via SHA-256 hashing and curated word lists.
|
|
64
|
+
|
|
65
|
+
**When to use:** User needs a name for a wallet, wants to label a wallet, or needs an identity name.
|
|
66
|
+
|
|
67
|
+
| Parameter | Type | Required | Default | Description |
|
|
68
|
+
|-----------|------|----------|---------|-------------|
|
|
69
|
+
| `wallet` | string | Yes | -- | Solana wallet address (base58) |
|
|
70
|
+
| `format` | string | No | -- | "short", "display", "tag", or "full". Omit for full identity object. |
|
|
71
|
+
|
|
72
|
+
Returns: Without format: `SolNameIdentity` object (short/name/tag/full/adjective/noun/hash/discriminator). With format: formatted string.
|
|
73
|
+
|
|
74
|
+
### `list_solface_themes`
|
|
75
|
+
List available preset themes with descriptions.
|
|
76
|
+
|
|
77
|
+
No parameters. Returns: Array of `{ name, description, reactOnly }`.
|
|
78
|
+
|
|
79
|
+
---
|
|
80
|
+
|
|
81
|
+
## Installation
|
|
82
|
+
|
|
83
|
+
```bash
|
|
84
|
+
npm install solfaces
|
|
85
|
+
```
|
|
86
|
+
```html
|
|
87
|
+
<script src="https://unpkg.com/solfaces/dist/solfaces.cdn.global.js"></script>
|
|
88
|
+
```
|
|
89
|
+
```bash
|
|
90
|
+
curl -O https://raw.githubusercontent.com/jorger3301/solfaces/main/python/solfaces.py
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
---
|
|
94
|
+
|
|
95
|
+
## Import Paths
|
|
96
|
+
|
|
97
|
+
| Project Type | Import Path | What You Get |
|
|
98
|
+
|---|---|---|
|
|
99
|
+
| React / Next.js | `solfaces/react` | `<SolFace>` component with pixel art and glass modes |
|
|
100
|
+
| Vanilla JS / Vue / Svelte | `solfaces/vanilla` | `mountSolFace()`, `setSolFaceImg()`, `autoInit()` |
|
|
101
|
+
| Node.js server / API | `solfaces` | `renderSolFaceSVG()`, `renderSolFacePNG()`, descriptions, colors |
|
|
102
|
+
| No build step / CDN | `<script>` tag | `window.SolFaces` global |
|
|
103
|
+
| AI agent framework | `solfaces/agent` | Tool schemas + format adapters |
|
|
104
|
+
| Theme presets only | `solfaces/themes` | 11 preset theme objects |
|
|
105
|
+
| Names only | `solfaces/names` | `deriveName()`, `deriveIdentity()`, validation |
|
|
106
|
+
| Python backend | `from solfaces import ...` | Full Python port |
|
|
107
|
+
|
|
108
|
+
---
|
|
109
|
+
|
|
110
|
+
## Quick Examples
|
|
111
|
+
|
|
112
|
+
### React
|
|
113
|
+
```tsx
|
|
114
|
+
import { SolFace } from "solfaces/react";
|
|
115
|
+
<SolFace walletAddress="7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU" size={48} enableBlink showName />
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
### Server-side
|
|
119
|
+
```ts
|
|
120
|
+
import { renderSolFaceSVG } from "solfaces";
|
|
121
|
+
const svg = renderSolFaceSVG("7xKXtg...", { size: 256 });
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
### Name derivation
|
|
125
|
+
```ts
|
|
126
|
+
import { deriveName, deriveIdentity } from "solfaces";
|
|
127
|
+
deriveName("7xKXtg..."); // "SunnyIcon"
|
|
128
|
+
deriveName("7xKXtg...", "tag"); // "SunnyIcon#2f95"
|
|
129
|
+
const id = deriveIdentity("7xKXtg..."); // full identity object
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
### CDN
|
|
133
|
+
```html
|
|
134
|
+
<div data-solface="7xKXtg..." data-solface-size="48"></div>
|
|
135
|
+
<script src="https://unpkg.com/solfaces/dist/solfaces.cdn.global.js"></script>
|
|
136
|
+
<script>
|
|
137
|
+
const name = SolFaces.deriveName("7xKXtg...");
|
|
138
|
+
SolFaces.mount("#avatar", "7xKXtg...", { size: 64 });
|
|
139
|
+
</script>
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
### Python
|
|
143
|
+
```python
|
|
144
|
+
from solfaces import render_svg, describe_appearance, derive_name
|
|
145
|
+
svg = render_svg("7xKXtg...", size=256)
|
|
146
|
+
name = derive_name("7xKXtg...")
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
---
|
|
150
|
+
|
|
151
|
+
## Rendering Modes
|
|
152
|
+
|
|
153
|
+
- **Full detail** (size >= 48): Gradients, specular highlights, cheek blush, chin shadow, glow.
|
|
154
|
+
- **Simplified** (size < 48): Flat shapes, no gradients. Override with `detail: "full"` or `"simplified"`.
|
|
155
|
+
- **Flat mode**: `theme: { flat: true }` disables all gradients.
|
|
156
|
+
- **Pixel art** (React only): `pixelTheme`, `pixelRetroTheme`, `pixelCleanTheme`.
|
|
157
|
+
- **Liquid glass** (React only): `glassTheme`, `glassDarkTheme`.
|
|
158
|
+
|
|
159
|
+
---
|
|
160
|
+
|
|
161
|
+
## Detailed Reference
|
|
162
|
+
|
|
163
|
+
For comprehensive documentation on specific topics:
|
|
164
|
+
|
|
165
|
+
- **React component**: Full props interface, all rendering modes, `useSolName` hook, `showName` prop, color overrides, blink timing. See [reference/react.md](reference/react.md)
|
|
166
|
+
- **Themes**: All theme fields, pixel art and glass customization, theme recommendations, custom theme examples. See [reference/themes.md](reference/themes.md)
|
|
167
|
+
- **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)
|
|
168
|
+
|
|
169
|
+
---
|
|
170
|
+
|
|
171
|
+
## Key Facts
|
|
172
|
+
|
|
173
|
+
- **Deterministic**: Same wallet = same face + same name. djb2 + mulberry32 PRNG (traits), SHA-256 + mulberry32 PRNG (names).
|
|
174
|
+
- **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.
|
|
175
|
+
- **SolNames**: 1000 adjectives + 1000 nouns, SHA-256 derived. Formats: short, display (~1M), tag (~65.5B), full (~1T). Custom word lists supported via `DeriveOptions`.
|
|
176
|
+
- **Earring suppression**: Long and bob hairstyles suppress earring accessories.
|
|
177
|
+
- **Cross-language parity**: JS and Python produce identical output.
|
|
178
|
+
- **Zero dependencies**: Core engine has no runtime deps.
|
|
179
|
+
- **SVG viewBox**: All avatars use 64x64 viewBox, scaled by `size`.
|
|
180
|
+
- **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 chunk4YFZ4W2Y_cjs = require('../chunk-4YFZ4W2Y.cjs');
|
|
4
|
+
require('../chunk-TYTBYDQU.cjs');
|
|
5
|
+
require('../chunk-F54WHRCE.cjs');
|
|
6
6
|
require('../chunk-6QRDULAO.cjs');
|
|
7
|
+
require('../chunk-XXJJH56O.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 chunk4YFZ4W2Y_cjs.SOLFACE_TOOLS; }
|
|
13
14
|
});
|
|
14
15
|
Object.defineProperty(exports, "allToolsAnthropic", {
|
|
15
16
|
enumerable: true,
|
|
16
|
-
get: function () { return
|
|
17
|
+
get: function () { return chunk4YFZ4W2Y_cjs.allToolsAnthropic; }
|
|
17
18
|
});
|
|
18
19
|
Object.defineProperty(exports, "allToolsMCP", {
|
|
19
20
|
enumerable: true,
|
|
20
|
-
get: function () { return
|
|
21
|
+
get: function () { return chunk4YFZ4W2Y_cjs.allToolsMCP; }
|
|
21
22
|
});
|
|
22
23
|
Object.defineProperty(exports, "allToolsOpenAI", {
|
|
23
24
|
enumerable: true,
|
|
24
|
-
get: function () { return
|
|
25
|
+
get: function () { return chunk4YFZ4W2Y_cjs.allToolsOpenAI; }
|
|
25
26
|
});
|
|
26
27
|
Object.defineProperty(exports, "allToolsVercelAI", {
|
|
27
28
|
enumerable: true,
|
|
28
|
-
get: function () { return
|
|
29
|
+
get: function () { return chunk4YFZ4W2Y_cjs.allToolsVercelAI; }
|
|
29
30
|
});
|
|
30
31
|
Object.defineProperty(exports, "handleToolCall", {
|
|
31
32
|
enumerable: true,
|
|
32
|
-
get: function () { return
|
|
33
|
+
get: function () { return chunk4YFZ4W2Y_cjs.handleToolCall; }
|
|
33
34
|
});
|
|
34
35
|
Object.defineProperty(exports, "toAnthropic", {
|
|
35
36
|
enumerable: true,
|
|
36
|
-
get: function () { return
|
|
37
|
+
get: function () { return chunk4YFZ4W2Y_cjs.toAnthropic; }
|
|
37
38
|
});
|
|
38
39
|
Object.defineProperty(exports, "toMCP", {
|
|
39
40
|
enumerable: true,
|
|
40
|
-
get: function () { return
|
|
41
|
+
get: function () { return chunk4YFZ4W2Y_cjs.toMCP; }
|
|
41
42
|
});
|
|
42
43
|
Object.defineProperty(exports, "toOpenAI", {
|
|
43
44
|
enumerable: true,
|
|
44
|
-
get: function () { return
|
|
45
|
+
get: function () { return chunk4YFZ4W2Y_cjs.toOpenAI; }
|
|
45
46
|
});
|
|
46
47
|
Object.defineProperty(exports, "toVercelAI", {
|
|
47
48
|
enumerable: true,
|
|
48
|
-
get: function () { return
|
|
49
|
+
get: function () { return chunk4YFZ4W2Y_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-66PSL4YO.js';
|
|
2
|
+
import '../chunk-CKHLRORB.js';
|
|
3
|
+
import '../chunk-3CE7Q44S.js';
|
|
4
4
|
import '../chunk-DRUSCLEF.js';
|
|
5
|
+
import '../chunk-N5DDJ3WQ.js';
|
|
5
6
|
//# sourceMappingURL=index.js.map
|
|
6
7
|
//# sourceMappingURL=index.js.map
|