Evolution SDK
Providers

Use Cases

Real-world provider patterns and complete examples

Use Cases

Practical patterns and complete examples showing how to use providers in real applications.

Blockchain Explorer

Query and display address information:

import { ,  } from "@evolution-sdk/evolution";

const  = ({
  : "mainnet",
  : {
    : "blockfrost",
    : "https://cardano-mainnet.blockfrost.io/api/v0",
    : ..!
  }
});

interface AddressInfo {
  : string;
  : bigint;
  : number;
  : number;
}

export async function (
  : string
): <AddressInfo> {
  const  = await .(
    ..()
  );
  
  const  = .(
    (, ) =>  + ..,
    0n
  );
  
  return {
    : ,
    ,
    : () / 1_000_000,
    : .
  };
}

Portfolio Tracker

Track balances across multiple addresses:

import { ,  } from "@evolution-sdk/evolution";

const  = ({
  : "mainnet",
  : {
    : "blockfrost",
    : "https://cardano-mainnet.blockfrost.io/api/v0",
    : ..!
  }
});

interface WalletBalance {
  : string;
  : bigint;
  : number;
  : <{ : string; : bigint }>;
}

interface Portfolio {
  : WalletBalance[];
  : {
    : bigint;
    : number;
  };
}

export async function (
  : string[]
): <Portfolio> {
  const  = await .(
    .(async () => {
      const  = await .(
        ..()
      );
      
      let  = 0n;
      const  = new <string, bigint>();
      
      .(() => {
         += ..;
        // Token tracking would need iteration over Assets
      });
      
      const  = .(.()).(
        ([, ]) => ({ ,  })
      );
      
      return {
        : ,
        ,
        : () / 1_000_000,
        
      };
    })
  );
  
  const  = .(
    (, ) =>  + .,
    0n
  );
  
  return {
    ,
    : {
      : ,
      : () / 1_000_000
    }
  };
}

Transaction Submission API

Backend API endpoint for transaction submission:

import {  } from "@evolution-sdk/evolution";

const  = ({
  : "mainnet",
  : {
    : "blockfrost",
    : "https://cardano-mainnet.blockfrost.io/api/v0",
    : ..!
  }
});

interface SubmissionResponse {
  : boolean;
  ?: string;
  ?: boolean;
  ?: string;
}

export async function (
  : string
): <SubmissionResponse> {
  try {
    // Submit transaction
    const  = await .();
    
    .("Transaction submitted:", );
    
    // Wait for confirmation
    const  = await .(, 5000);
    
    return {
      : true,
      ,
      
    };
  } catch (: any) {
    .("Submission failed:", );
    
    return {
      : false,
      : .message
    };
  }
}

Express.js integration example:

// Express.js example
import express from "express";
const app = express();
app.use(express.json());

app.post("/api/submit", async (req, res) => {
  const { txCbor } = req.body;
  
  if (!txCbor) {
    return res.status(400).json({
      error: "Missing txCbor in request body"
    });
  }
  
  const result = await handleSubmission(txCbor);
  
  if (result.success) {
    res.json(result);
  } else {
    res.status(500).json(result);
  }
});

Token Distribution Tracker

Track token distribution across holders:

import { ,  } from "@evolution-sdk/evolution";

const  = ({
  : "mainnet",
  : {
    : "blockfrost",
    : "https://cardano-mainnet.blockfrost.io/api/v0",
    : ..!
  }
});

interface TokenHolder {
  : string;
  : bigint;
  : number;
}

interface Distribution {
  : bigint;
  : TokenHolder[];
  : number;
}

export async function (
  : string[],
  : string
): <Distribution> {
  const : TokenHolder[] = [];
  let  = 0n;
  
  for (const  of ) {
    const  = ..();
    const  = await .(, );
    
    if (. > 0) {
      // Count UTxOs that contain this token
      const  = (.);
      
       += ;
      .({ : , , : 0 });
    }
  }
  
  // Calculate percentages
  .(() => {
    . =  > 0n
      ? ((. * 10000n) / ) / 100
      : 0;
  });
  
  // Sort by amount descending
  .((, ) => (. - .));
  
  return {
    ,
    ,
    : .
  };
}

NFT Collection Tracker

Track NFT ownership and rarity:

import { ,  } from "@evolution-sdk/evolution";

const  = ({
  : "mainnet",
  : {
    : "blockfrost",
    : "https://cardano-mainnet.blockfrost.io/api/v0",
    : ..!
  }
});

interface NFTOwnership {
  : string;
  : string;
  : string | null;
  ?: string;
  ?: bigint;
}

export async function (
  : string,
  : string[]
): <NFTOwnership[]> {
  const  = await .(
    .(async () => {
      const  =  + ;
      
      try {
        const  = await .();
        
        return {
          : ,
          ,
          : ..(.),
          : ..(.),
          : .
        };
      } catch () {
        return {
          : ,
          ,
          : null
        };
      }
    })
  );
  
  return ;
}

// Get collection statistics
export async function (
  : string,
  : string[]
) {
  const  = await (, );
  
  const  = .(() => . !== null);
  const  = .(() => . === null);
  
  // Count unique owners
  const  = new (
    .(() => .).()
  );
  
  return {
    : .,
    : .,
    : .,
    : .,
    
  };
}

Staking Pool Delegator Tracker

Track delegators to a specific stake pool:

import {  } from "@evolution-sdk/evolution";

const  = ({
  : "mainnet",
  : {
    : "blockfrost",
    : "https://cardano-mainnet.blockfrost.io/api/v0",
    : ..!
  }
});

interface Delegator {
  : string;
  : string | undefined;
  : bigint;
}

export async function (
  : string[],
  : string
): <Delegator[]> {
  const  = await .(
    .(async () => {
      try {
        const  = await .();
        
        return {
          ,
          : .,
          : .
        };
      } catch () {
        return null;
      }
    })
  );
  
  // Filter to only target pool delegators
  return .(
    () =>  !== null && . === 
  ) as Delegator[];
}

// Get pool statistics
export async function (
  : string[],
  : string
) {
  const  = await (
    ,
    
  );
  
  const  = .(
    (, ) =>  + .,
    0n
  );
  
  return {
    : .,
    ,
    : () / 1_000_000
  };
}

Protocol Parameter Monitor

Monitor network parameters for changes:

import {  } from "@evolution-sdk/evolution";

const  = ({
  : "mainnet",
  : {
    : "blockfrost",
    : "https://cardano-mainnet.blockfrost.io/api/v0",
    : ..!
  }
});

interface ParameterSnapshot {
  : Date;
  : number;
  : number;
  : number;
  : bigint;
  : bigint;
}

export async function (): <ParameterSnapshot> {
  const  = await .();
  
  return {
    : new (),
    : .,
    : .,
    : .,
    : .,
    : .
  };
}

// Monitor with periodic snapshots
export class  {
  private : ParameterSnapshot[] = [];
  private : NodeJS. | null = null;
  
  (: number = 3600000) {
    this. = (async () => {
      const  = await ();
      this..();
      
      .("Parameter snapshot:", );
      
      // Check for changes
      if (this.. > 1) {
        const  = this.[this.. - 2];
        this.(, );
      }
    }, );
  }
  
  () {
    if (this.) {
      (this.);
      this. = null;
    }
  }
  
  private (
    : ParameterSnapshot,
    : ParameterSnapshot
  ) {
    if (. !== .) {
      .("Fee A changed:", {
        : .,
        : .
      });
    }
    
    if (. !== .) {
      .("Pool deposit changed:", {
        : .,
        : .
      });
    }
  }
}

Multi-Provider Fallback

Implement provider failover for reliability:

import { ,  } from "@evolution-sdk/evolution";

// Type for clients with common provider methods
interface ProviderClient {
  : (: ..) => <any>;
  : (: string) => <string>;
  : () => <any>;
}

class  {
  private : ProviderClient[];
  private  = 0;
  
  constructor(
    : <{
      : "mainnet" | "preprod" | "preview";
      :
        | { : "blockfrost"; : string; : string }
        | { : "maestro"; : string; : string }
        | { : "kupmios"; : string; : string }
        | { : "koios"; : string };
    }>
  ) {
    this. = .(({ ,  }) =>
      ({ ,  })
    );
  }
  
  private async <>(
    : (: ProviderClient) => <>
  ): <> {
    let : Error | undefined;
    
    for (let  = 0;  < this..; ++) {
      const  = this.[this.];
      
      try {
        const  = await ();
        return ;
      } catch () {
        .(`Provider ${this.} failed:`, );
         =  as Error;
        
        // Try next provider
        this. = (this. + 1) % this..;
      }
    }
    
    throw ;
  }
  
  async (: ..) {
    return this.(() => .());
  }
  
  async (: string) {
    return this.(() => .());
  }
  
  async () {
    return this.(() =>
      .()
    );
  }
}

// Usage
const  = new ([
  {
    : "mainnet",
    : {
      : "blockfrost",
      : "https://cardano-mainnet.blockfrost.io/api/v0",
      : ..!
    }
  },
  {
    : "mainnet",
    : {
      : "maestro",
      : "https://mainnet.gomaestro-api.org/v1",
      : ..!
    }
  }
]);

const  = ..("addr1qxy8sclc58rsck0pzsc0v4skmqjwuqsqpwfcvrdldl5sjvvhyltp7fk0fmtmrlnykgmhnzcns2msa2cmpvllzgqd2azqhpv8e4");
const  = await .();

Next Steps

Now that you understand provider use cases: