7.did-plc-lookups.md

title	DID PLC Lookups
description	Resolve DID documents, inspect operation logs, and stream PLC directory exports.

Use poptart_did_plc when your app only needs PLC directory data. It is independent of the higher-level PoptartClient, so it is a good fit for identity resolution, audits, analytics, and background synchronization.

Install

dart pub add poptart_did_plc

import 'package:poptart_did_plc/poptart_did_plc.dart';

Resolve A DID Document

Create a PLC client and call getDocument.

Future<void> main() async {
  final plc = PLC();

  try {
    final document = await plc.getDocument(
      'did:plc:iijrtk7ocored6zuziwmqq3c',
    );

    print(document.id);
    print(document.alsoKnownAs);

    for (final service in document.service) {
      print('${service.type}: ${service.serviceEndpoint}');
    }
  } finally {
    plc.close();
  }
}

Always close the client when you are done so network resources are released.

Read Document Data

getDocument returns the DID document shape. Use getDocumentData when you want the structured PLC data behind that document, including rotation keys, verification methods, handles, and service declarations.

final data = await plc.getDocumentData('did:plc:iijrtk7ocored6zuziwmqq3c');

print(data.rotationKeys);
print(data.alsoKnownAs);
print(data.services.keys);

Use this when you are building diagnostics or identity tooling and need to explain how the DID document is assembled.

Inspect Operation History

Every DID PLC document is the result of an operation log. Fetch the log when you need to audit handle changes, service endpoint changes, or key rotations.

final log = await plc.getOperationLog('did:plc:iijrtk7ocored6zuziwmqq3c');

for (final entry in log.log) {
  final type = entry.when(
    op: (op) => op.type,
    tombstone: (_) => 'tombstone',
    createOpV1: (_) => 'create_v1',
    unknown: (_) => 'unknown',
  );

  print(type);
}

Use getLastOp when you only need the current terminal operation:

final last = await plc.getLastOp('did:plc:iijrtk7ocored6zuziwmqq3c');

last.when(
  op: (op) => print('last operation: ${op.type}'),
  tombstone: (_) => print('DID is deactivated'),
  createOpV1: (_) => print('legacy create operation'),
  unknown: (_) => print('unknown operation'),
);

Fetch Audit Metadata

The auditable log includes additional directory metadata such as CIDs, timestamps, and nullification state.

final auditLog = await plc.getAuditableLog(
  'did:plc:iijrtk7ocored6zuziwmqq3c',
);

for (final entry in auditLog.log) {
  print(entry.cid);
  print(entry.createdAt);
  print(entry.isNullified);
}

Use the auditable log when you are showing change history or building compliance/debugging tools.

Batch Lookups

Use getDocuments when you want successful lookups only:

final documents = await plc.getDocuments([
  'did:plc:first',
  'did:plc:second',
  'did:plc:third',
]);

print('resolved ${documents.length} documents');

Use getDocumentsBatch when you also need to inspect failures:

final result = await plc.getDocumentsBatch([
  'did:plc:first',
  'did:plc:bad',
]);

print('successes: ${result.successes.length}');
print('failures: ${result.failures.length}');

Batch APIs are useful for profile hydration, moderation tools, and offline audits where one bad DID should not stop the entire job.

Stream Directory Exports

Use exportOpsStream for memory-efficient processing of PLC directory exports.

await for (final operation in plc.exportOpsStream(count: 1000)) {
  print(operation.did);
  print(operation.cid);
  print(operation.createdAt);
}

Use exportAuditableOpsStream when you need raw operation maps:

await for (final raw in plc.exportAuditableOpsStream(count: 1000)) {
  final did = raw['did'] as String;
  final cid = raw['cid'] as String;

  print('$did $cid');
}

Streaming is better than fetching a large export into memory when you are building analytics, mirrors, or long-running processors.

Handle PLC Errors

The PLC package exposes specific exception types. Catch them when you need to distinguish bad input, missing DIDs, network failures, and unexpected service responses.

try {
  final document = await plc.getDocument('did:plc:example');
  print(document.id);
} on ValidationException catch (error) {
  print('Invalid DID: ${error.message}');
} on NotFoundException catch (error) {
  print('DID was not found: ${error.message}');
} on NetworkException catch (error) {
  print('Network error: ${error.message}');
} on PlcException catch (error) {
  print('PLC error: ${error.message}');
}

For user-facing screens, turn these into clear messages. For background jobs, log the DID, operation, and exception class so the failure can be replayed.