Guides

Blueprint Management#

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);
  }
}