Blueprint Management (CIP-57)

Guide to managing smart contract blueprints with the Anvil API - creating, finding, and deleting blueprints.

Overview

The Anvil API provides powerful endpoints for managing Cardano smart contract blueprints. These endpoints allow you to create, retrieve, update, and delete CIP-57 compliant blueprints in a standardized way. This is usually the compiled plutus.json file from an Aiken build.

SECURITY NOTE

All blueprint operations require an API key, which serves as your authentication credential and determines which blueprints you can access. The system maintains blueprint isolation between users, ensuring that:

• When you create a blueprint, it's associated with your API key

• When you search for blueprints, you only see blueprints created with your API key

• When you delete blueprints, you can only remove blueprints you own

This security model ensures that your smart contract blueprints remain private to your account while still enabling collaboration through controlled sharing mechanisms.

Blueprint Management API Endpoints

Endpoint	Method	Description	Required Parameters	Optional Parameters
/blueprints	POST	Create or update a blueprint	blueprint: CIP-57 compliant blueprint	refs: Reference UTXOs
/blueprints	GET	Find blueprints matching criteria	None	title, version, limit, offset, sortBy, order
/blueprints	DELETE	Remove blueprints	title: Blueprint title	version: Blueprint version
/blueprints/apply-params	POST	Apply parameters to validators - See Documentation	params: Validator hash to params mapping	blueprint: CIP-57 blueprint (if not uploaded)

Common Setup

The following setup is common to all blueprint operations:

// Import your blueprint (typically from an Aiken build)
import plutusJson from "../hello-world/plutus.json" with { type: "json" };

// Setup API key and content type
const headers = {
  "x-api-key": "YOUR_API_KEY",
  "Content-Type": "application/json",
};

// Define the API endpoint
const blueprintsUrl = "https://preprod.api.ada-anvil.app/v2/services/blueprints";

Creating or Updating Blueprints

Use the POST method to upload a new blueprint or update an existing one. The API automatically determines whether to create or update based on the blueprint's title and version.

async function upsertBlueprint() {
  try {
    // Prepare the request body with your CIP-57 blueprint
    const input = { blueprint: plutusJson };
    
    const res = await fetch(blueprintsUrl, {
      method: "POST",
      body: JSON.stringify(input),
      headers,
    });
    
    const json = await res.json();
    
    // The response contains:
    // - jsonSchema: Generated JSON schema from the blueprint
    // - scriptAddresses: Record of validator hashes and their addresses
    // - blueprintId: ID of the created/updated blueprint
    console.log("json", JSON.stringify(json, null, 2));
  } catch (error) {
    console.log("error", error);
  }
}

Finding Blueprints

Use the GET method to search for blueprints by title, version, or other criteria.

async function findBlueprints() {
  try {
    const url = new URL(blueprintsUrl);
    
    // Optional search parameters
    url.searchParams.set("title", "cardano-forge/vesting-contract"); // Filter by title
    url.searchParams.set("version", "0.0.0"); // Filter by version
    // Additional optional parameters: limit, offset, sortBy, order
    
    const res = await fetch(url, {
      method: "GET",
      headers,
    });
    
    const json = await res.json();
    
    // The response contains:
    // - results: Array of matching blueprints
    // - total: Total count of matching blueprints
    console.log("json", JSON.stringify(json, null, 2));
  } catch (error) {
    console.log("error", error);
  }
}

Deleting Blueprints

Use the DELETE method to remove blueprints from the system.

async function deleteBlueprint() {
  try {
    const url = new URL(blueprintsUrl);
    
    // Required parameter
    url.searchParams.set("title", "cardano-forge/vesting-contract");
    
    // Optional parameter - if omitted, all versions with the specified title will be deleted
    url.searchParams.set("version", "0.0.0");
    
    const res = await fetch(url, {
      method: "DELETE",
      headers,
    });
    
    const json = await res.json();
    
    // The response contains:
    // - deleted: Array of strings identifying the deleted blueprints
    console.log("json", JSON.stringify(json, null, 2));
  } catch (error) {
    console.log("error", error);
  }
}