Il Collection Blueprint

Oggi KURV funziona su Base Sepolia e Solana Devnet. Questa pagina è la guida pratica tratta da una creazione completa (HANI the Dog, 1.000 pezzi, 20 unici), scritta per un creator che lavora con un agente di IA tramite il connettore KURV su https://mcp.kurv.fun/mcp. Il connettore fornisce la stessa guida agli agenti come risorsa kurv://blueprint, e lo strumento kurv_builder_spec è la fonte di riferimento: dove questa pagina e lo strumento non coincidono, fidati dello strumento.

Collega un agente

1. Aggiungi https://mcp.kurv.fun/mcp come server MCP remoto in un client che supporta MCP remoti con OAuth. Collega un agente con MCP elenca i client e i loro passaggi.
2. Accedi a KURV nel browser e approva il collegamento. Scegli tu che cosa può fare (solo lettura; lettura e bozze; oppure lettura, bozze e preparazione del lancio) e quanto dura.
3. Chiedi all’agente di leggere kurv://blueprint, poi di chiamare kurv_account e kurv_builder_spec per la tua rete. Il connettore offre anche il prompt build-kurv-collection, che guida l’agente lungo questa pagina con ogni sosta per l’approvazione al suo posto.

Chi fa che cosa

L’agente progetta, convalida, crea la bozza, carica le opere, genera le anteprime e prepara il lancio. Tu approvi le opere, i campioni e ogni avviso, poi apri il link di controllo e firmi il lancio con il tuo wallet. L’agente non pubblica mai il contratto, non firma mai e non chiede mai una chiave privata o una frase seed. Una volta che le opere sono finite e approvate, la parte su KURV (convalida, creazione, caricamento, anteprima, preparazione) richiede circa 20 minuti. Fare buone opere richiede più tempo, ed è giusto così.

I limiti

Voce	Limite
Dimensione della collezione	Da 1 a 1.000 pezzi, unici compresi: 980 pezzi casuali e 20 unici fanno una dimensione di 1.000.
Livelli	Fino a 12.
Immagini dei trait	Fino a 240 in totale su tutti i livelli, comprese le opere usate solo dagli unici. Un livello vuoto non costa niente.
Unici	Fino a 32.
Regole	Fino a 48, le stesse su ogni rete.
Dimensione dei file immagine	Fino a 2 MiB per immagine inviata una alla volta; fino a 20 MiB per un’immagine dentro uno zip.
Tela	Quadrata, fino a 2.048 per 2.048 pixel. Ogni file ha esattamente le dimensioni della tela.
Formati	Sfondo: PNG, JPEG o WebP. Ogni altro livello: PNG con una vera trasparenza.
Il nome None	Riservato, con qualsiasi combinazione di maiuscole e minuscole. Mai un trait chiamato None, mai un’immagine vuota: un livello diventa facoltativo tramite noneWeight.
Descrizione	Considerala obbligatoria: da 1 a 2.000 caratteri. Finisce nei metadati di ogni pezzo.
Bozze	20 attive per account. kurv_archive_draft libera subito un posto; le opere della bozza archiviata vengono conservate 30 giorni e poi rimosse.
Anteprime	Fino a 9 campioni casuali per chiamata, oppure fino a 9 numeri di pezzo scelti, da 64 a 512 pixel.

Dopo ogni convalida l’agente legge validCombinations: quanti pezzi distinti permettono i livelli e le regole. Viene contato esattamente per spazi fino a circa 50 milioni di combinazioni, e oltre viene indicato come stima. Tienilo ben al di sopra della dimensione della collezione.

Il percorso, passo per passo

I passaggi segnati Approvazione significano che l’agente si ferma e aspetta il tuo sì esplicito.

1. Foto. Raccogli da 3 a 10 foto nitide dell’animale o del personaggio reale: muso, occhi, denti e bocca, macchie, orecchie. Scegline una principale con il muso di tre quarti.
2. Direzione artistica. Uno stile, una posa (quella di tre quarti funziona meglio), una tela quadrata (2.048 per 2.048 consigliata), una breve scheda di stile: linee, ombreggiatura, palette, atmosfera. Approvazione: il personaggio principale, prima di creare qualsiasi trait.
3. La base principale. Il personaggio nella posa finale su uno sfondo piatto di un solo colore, centrato, a piena dimensione della tela, riconoscibile all’istante come l’animale reale. Ogni trait è una modifica di questa base, con la stessa posa, la stessa scala e la stessa inquadratura.
4. Livelli. I livelli si dipingono dal basso verso l’alto: Background, Skin (il livello base), Collar, Teeth, Eyes, Headwear (facoltativo). Circa sei livelli; è il personaggio a reggere la collezione, non gli accessori. L’agente indica il livello base in base_layer e dà a ogni livello un riquadro di ancoraggio in cui devono stare i suoi trait.
5. Trait. Ogni trait è una modifica di una copia della base, ritagliata in modo che siano visibili solo i pixel del trait e tutto il resto sia trasparente. Generare i trait su una copia del corpo in tinta unita tiene fuori il pelo. Un trait che si sposta di posizione o di scala viene rifiutato.
6. Unici. Corpi trasformati del tutto (diamante, cromo, lava, bronzo), ognuno con uno sfondo abbinato e senza collare. Le loro opere entrano nel proprio livello come trait con un peso di 0, così non compaiono mai nei pezzi casuali; contano per le 240 immagini.
7. Regole. Fogli di contatto di ogni pelle con ogni collare, dentatura, occhi e copricapo. Ogni coppia sbagliata (sovrapposta, invisibile, brutta) diventa una regola di esclusione raggruppata, con una nota che spiega perché.
8. Approvazione: i fogli dei livelli, almeno 9 campioni composti, il foglio degli unici, la configurazione e le condizioni di vendita, prima che la bozza venga creata.
9. Configurazione e convalida. kurv_builder_spec con la rete, poi kurv_validate_collection con la configurazione finché il suo elenco issues non contiene più errori. Gli avvisi indicano ciò di cui dovresti essere informato. La risposta riporta required_assets, le chiavi esatte da caricare, e validCombinations.
10. La bozza. kurv_create_collection con version: 3, la rete, la configurazione, le condizioni di vendita e una chiave di idempotenza, prima con check_only impostato a true, poi per davvero. Una chiamata non riuscita si ripete con la stessa chiave. Le condizioni di vendita hanno la stessa forma su ogni rete: vedi Condizioni di vendita.
11. Le opere. Una alla volta con kurv_upload_trait (prima lo sfondo, la base e un trait per livello, poi un’anteprima, poi il resto), oppure tutte insieme nel formato a cartelle del sito tramite kurv_upload_collection_zip. Un livello vuoto è un noneWeight, mai un PNG trasparente.
12. Controllo e anteprima. kurv_validate_collection con la bozza esegue i controlli delle opere. kurv_preview_collection con 9 campioni dopo l’ultimo caricamento, più i numeri di pezzo di ogni unico e delle combinazioni più a rischio. L’agente guarda ogni immagine. Una prima anteprima lunga risponde con retry_after e i campioni in attesa; l’agente chiama di nuovo.
13. Correzioni senza una nuova bozza. kurv_update_collection cambia sul posto regole, unici, pesi, suggerimenti o la descrizione; la tela non può cambiare. kurv_replace_trait_image sostituisce un’immagine, kurv_rename_trait rinomina un trait e aggiorna le sue regole e i suoi unici, kurv_delete_trait rimuove un trait a cui niente fa riferimento. Poi una nuova anteprima.
14. Approvazione: i campioni finali e ogni avviso, letti per te.
15. Preparazione. kurv_prepare_launch con la bozza. Con warnings_need_review l’agente spiega ogni avviso; solo dopo che hai accettato chiama di nuovo con acknowledge_warnings impostato a true. Ricevi un link per il browser.
16. Firmi tu. Apri l’unico link, controlla ciò che è compilato, scegli Pubblica e lancia e firma con il tuo portafoglio nell’ultimo passaggio. Ogni risposta è a un Indietro di distanza. Nessuno strumento firma per te.

Regole

Una regola tiene separati o insieme i trait di due livelli: {"type", "when", "target", "note"}, dove type è exclude oppure require, e when e target indicano ciascuno un livello e, facoltativamente, un trait: un nome o un elenco di nomi. Nessun trait significa l’intero livello, e when e target devono essere livelli diversi. La chiave è trait: una regola scritta con traits viene rifiutata indicando la chiave giusta, invece di applicarsi in silenzio all’intero livello. None può indicare un livello vuoto solo dove quel livello ha un noneWeight maggiore di 0. Raggruppa le coppie in elenchi per restare sotto le 48: una regola per ogni gruppo di pelli, con l’elenco di tutti i collari che non devono mai indossare.

{"type": "exclude", "note": "Thick fur hides these collars", "when": {"layer": "Skin", "trait": ["Lion Mane", "Fire Fur"]}, "target": {"layer": "Collar", "trait": ["Bow Tie", "Name Tag"]}}

Le regole arrivano fino ai pezzi: lo stesso motore genera l’anteprima e i file pubblicati, e il mint consegna quei file. Un unico può saltare le regole con ignoreRules impostato a true; l’unicità resta garantita.

Unici

Gli unici sono specials: un nome, ogni livello con il suo trait oppure None, un numero di pezzo fissato facoltativo e una descrizione facoltativa. Un unico che lascia fuori un livello riceve quel livello a caso, e la convalida avvisa quali sono quei livelli. null viene rifiutato, e lo stesso vale per il nome di un trait che non esiste.

{"name": "Diamond Grail", "tokenId": 1, "traits": {"Background": "Diamond Vault", "Skin": "Pave Diamond", "Collar": "None", "Teeth": "Diamond Grill", "Eyes": "None"}}

Opere che la gente vuole

• Opere curate, frutto di molto lavoro. Niente aspetto piatto, impastato o palesemente generato.
• Sfondi forti: colori decisi o scene ricche. Evita i temi di luogo (città, spiagge), a meno che non siano voluti.
• Posa di tre quarti e una somiglianza riconoscibile con l’animale reale: macchie, colore degli occhi, forma delle orecchie.
• Trait decisi, adattati al corpo del personaggio, disegnati sulla forma della base. I denti combaciano esattamente con la bocca.
• Niente copricapi sospesi. I cappelli poggiano sulla testa con un’ombra di contatto; le orecchie grandi passano sopra la tesa.
• Di solito i vestiti stanno male agli animali. Preferisci collari, catene e accessori per il collo, e verificali su ogni pelle.
• Gli unici di pregio sono trasformati del tutto, con sfondi abbinati e senza collare.

Il connettore controlla le opere man mano che arrivano. Gli errori rifiutano un caricamento: una dimensione della tela diversa, un livello sopra lo sfondo che non è un PNG con trasparenza, un’immagine senza pixel visibili. Gli avvisi tornano a te per un controllo: un trait fuori dal suo ancoraggio, un trait a una scala diversa da quella del suo livello, un trait fuori dalla griglia di pixel della base, un trait che contiene ancora in tutto o in parte l’immagine della base, un trait che copre l’intera tela. Un avviso può essere falso: occhi naturali nello stesso livello degli occhiali da sole hanno di proposito una dimensione diversa. L’agente imposta mixedScales su quel livello, oppure acknowledge sul trait quando sei d’accordo, e le opere restano come devono essere.

Che cosa riceve l’agente

Ogni strumento di convalida risponde a tutti i problemi in una volta in un unico elenco issues, ciascuno con un percorso, un codice, una gravità, un messaggio e un rimedio. Una chiave sconosciuta viene rifiutata per nome, con la più vicina chiave valida. La rete viene indicata (base-sepolia, solana-devnet, solana-localnet), e una bozza senza rete usa Base Sepolia e lo dice. I metodi di vendita usano i nomi del sito (fixed, mystery, rising, falling, auction): tramite il connettore Base offre fixed, mystery e rising, Solana offre fixed e rising, e le vendite falling e auction si configurano sul sito. Un campo di vendita che la rete non ha, come un simbolo su Solana, viene rifiutato per nome. I metadati sono verificati in automatico: ogni pezzo rispetta le regole, un unico finisce sul pezzo a cui è fissato, e un livello vuoto viene scritto come {"trait_type": "<layer>", "value": "None"}.

Pezzi finiti

I pezzi che esistono già come immagini finite saltano i livelli: kurv_finished_art_limits, poi kurv_upload_finished_file_part per ogni immagine e per il metadata.json, poi kurv_import_finished_collection. I byte vengono conservati così come arrivano, animazione compresa, e i limiti dei livelli non si applicano; si applicano invece gli attuali limiti di pubblicazione del sito. Porta le opere che hai già spiega i file.

Limiti noti di questa versione

• I valori di una vendita Solana in versione 2 vengono controllati dal parser dell’app dopo le chiavi, uno alla volta; una vendita in versione 3 risponde a tutti i problemi in una volta.
• Una bozza di opere finite non si può modificare sul posto; una correzione è un nuovo caricamento con una nuova chiave.
• Una bozza archiviata non si può ripristinare tramite il connettore; le sue opere vengono conservate 30 giorni.
• Robinhood Chain non è disponibile tramite il connettore: nessuna configurazione di rete e nessuno schema di vendita. Arriva dopo i lanci su Base e Solana.

I dati delle collezioni sono istantanee, e un lancio sposta valore reale sulla sua rete; leggi Rischi e avvertenze prima di consigliare chiunque su questioni di denaro.