acapy_agent.ledger package

Subpackages

• acapy_agent.ledger.merkel_validation package
  • Submodules
  • acapy_agent.ledger.merkel_validation.constants module
  • acapy_agent.ledger.merkel_validation.domain_txn_handler module
    • decode_state_value()
    • encode_state_value()
    • extract_params_write_request()
    • get_proof_nodes()
    • hash_of()
    • make_state_path_for_attr()
    • make_state_path_for_claim_def()
    • make_state_path_for_nym()
    • make_state_path_for_revoc_def()
    • make_state_path_for_revoc_reg_entry()
    • make_state_path_for_revoc_reg_entry_accum()
    • make_state_path_for_schema()
    • parse_attr_txn()
    • prepare_attr_for_state()
    • prepare_claim_def_for_state()
    • prepare_for_state_read()
    • prepare_for_state_write()
    • prepare_get_attr_for_state()
    • prepare_get_claim_def_for_state()
    • prepare_get_nym_for_state()
    • prepare_get_revoc_def_for_state()
    • prepare_get_revoc_reg_delta_for_state()
    • prepare_get_revoc_reg_entry_accum_for_state()
    • prepare_get_revoc_reg_entry_for_state()
    • prepare_get_schema_for_state()
    • prepare_nym_for_state()
    • prepare_revoc_def_for_state()
    • prepare_revoc_reg_entry_accum_for_state()
    • prepare_revoc_reg_entry_for_state()
    • prepare_schema_for_state()
  • acapy_agent.ledger.merkel_validation.hasher module
    • HexTreeHasher
      • HexTreeHasher.hash_children()
      • HexTreeHasher.hash_leaf()
    • TreeHasher
      • TreeHasher.hash_children()
      • TreeHasher.hash_leaf()
  • acapy_agent.ledger.merkel_validation.merkel_verifier module
    • MerkleVerifier
      • MerkleVerifier.calculate_root_hash()
      • MerkleVerifier.lsb()
  • acapy_agent.ledger.merkel_validation.trie module
    • SubTrie
      • SubTrie.get_new_trie_with_proof_nodes()
      • SubTrie.root_hash
      • SubTrie.set_root_hash()
      • SubTrie.verify_spv_proof()
  • acapy_agent.ledger.merkel_validation.utils module
    • ascii_chr()
    • audit_path_length()
    • bin_to_nibbles()
    • encode_hex()
    • sha3_256()
    • unpack_to_nibbles()
• acapy_agent.ledger.multiple_ledger package
  • Submodules
  • acapy_agent.ledger.multiple_ledger.base_manager module
  • acapy_agent.ledger.multiple_ledger.indy_vdr_manager module
  • acapy_agent.ledger.multiple_ledger.ledger_config_schema module
    • ConfigurableWriteLedgersSchema
    • LedgerConfigInstance
      • LedgerConfigInstance.Meta
    • LedgerConfigInstanceSchema
      • LedgerConfigInstanceSchema.Meta
      • LedgerConfigInstanceSchema.set_defaults()
      • LedgerConfigInstanceSchema.validate_id()
    • LedgerConfigListSchema
    • MultipleLedgerModuleResultSchema
    • WriteLedgerSchema
  • acapy_agent.ledger.multiple_ledger.ledger_requests_executor module
  • acapy_agent.ledger.multiple_ledger.manager_provider module

Submodules

acapy_agent.ledger.base module

Ledger base class.

class acapy_agent.ledger.base.BaseLedger

Bases: ABC

Base class for ledger.

BACKEND_NAME: str | None = None

abstractmethod async accept_txn_author_agreement(taa_record: dict, mechanism: str, accept_time: int | None = None)

Save a new record recording the acceptance of the TAA.

property backend: str

Accessor for the ledger backend name.

async check_existing_schema(public_did: str, schema_name: str, schema_version: str, attribute_names: Sequence[str]) → Tuple[str, dict]

Check if a schema has already been published.

async check_existing_schema_anoncreds(schema_id: str, attribute_names: Sequence[str]) → Tuple[str, dict]

Check if a schema has already been published.

async create_and_send_credential_definition(issuer: IndyIssuer, schema_id: str, signature_type: str | None = None, tag: str | None = None, support_revocation: bool = False, write_ledger: bool = True, endorser_did: str | None = None) → Tuple[str, dict, bool]

Send credential definition to ledger and store relevant key matter in wallet.

Parameters:

• issuer – The issuer instance to use for credential definition creation

• schema_id – The schema id of the schema to create cred def for

• signature_type – The signature type to use on the credential definition

• tag – Optional tag to distinguish multiple credential definitions

• support_revocation – Optional flag to enable revocation for this cred def

• write_ledger – Flag to write the cred def to the ledger

• endorser_did – Optional DID of the endorser

Returns:

Tuple with cred def id, cred def structure, and whether it’s novel

async create_and_send_schema(issuer: IndyIssuer, schema_name: str, schema_version: str, attribute_names: Sequence[str], write_ledger: bool = True, endorser_did: str | None = None) → Tuple[str, dict]

Send schema to ledger.

Parameters:

• issuer – The issuer instance to use for schema creation

• schema_name – The schema name

• schema_version – The schema version

• attribute_names – A list of schema attributes

• write_ledger – Flag to write the schema to the ledger

• endorser_did – Optional DID of the endorser

abstractmethod async fetch_schema_by_id(schema_id: str) → dict

Get schema from ledger.

Parameters:

schema_id – The schema id (or stringified sequence number) to retrieve

Returns:

Indy schema dict

abstractmethod async fetch_schema_by_seq_no(seq_no: int) → dict

Fetch a schema by its sequence number.

Parameters:

seq_no – schema ledger sequence number

Returns:

Indy schema dict

abstractmethod async fetch_txn_author_agreement() → dict

Fetch the current AML and TAA from the ledger.

abstractmethod async get_all_endpoints_for_did(did: str) → dict

Fetch all endpoints for a ledger DID.

Parameters:

did – The DID to look up on the ledger or in the cache

abstractmethod async get_credential_definition(credential_definition_id: str) → dict

Get a credential definition from the cache if available, otherwise the ledger.

Parameters:

credential_definition_id – The schema id of the schema to fetch cred def for

abstractmethod async get_endpoint_for_did(did: str, endpoint_type: EndpointType = EndpointType.ENDPOINT) → str

Fetch the endpoint for a ledger DID.

Parameters:

• did – The DID to look up on the ledger or in the cache

• endpoint_type – The type of the endpoint (default ‘endpoint’)

abstractmethod async get_key_for_did(did: str) → str

Fetch the verkey for a ledger DID.

Parameters:

did – The DID to look up on the ledger or in the cache

abstractmethod async get_latest_txn_author_acceptance() → dict

Look up the latest TAA acceptance.

abstractmethod async get_nym_role(did: str)

Return the role registered to input public DID on the ledger.

Parameters:

did – DID to register on the ledger.

abstractmethod async get_revoc_reg_def(revoc_reg_id: str) → dict

Look up a revocation registry definition by ID.

abstractmethod async get_revoc_reg_delta(revoc_reg_id: str, timestamp_from=0, timestamp_to=None) → Tuple[dict, int]

Look up a revocation registry delta by ID.

abstractmethod async get_revoc_reg_entry(revoc_reg_id: str, timestamp: int) → Tuple[dict, int]

Get revocation registry entry by revocation registry ID and timestamp.

abstractmethod async get_schema(schema_id: str) → dict

Get a schema from the cache if available, otherwise fetch from the ledger.

Parameters:

schema_id – The schema id (or stringified sequence number) to retrieve

abstractmethod async get_txn_author_agreement(reload: bool = False) → dict

Get the current transaction author agreement, fetching it if necessary.

abstractmethod async get_wallet_public_did() → DIDInfo

Fetch the public DID from the wallet.

abstractmethod async is_ledger_read_only() → bool

Check if ledger is read-only including TAA.

abstractmethod nym_to_did(nym: str) → str

Format a nym with the ledger’s DID prefix.

abstract property read_only: bool

Accessor for the ledger read-only flag.

abstractmethod async register_nym(did: str, verkey: str, alias: str | None = None, role: str | None = None, write_ledger: bool = True, endorser_did: str | None = None) → Tuple[bool, dict]

Register a nym on the ledger.

Parameters:

• did – DID to register on the ledger.

• verkey – The verification key of the keypair.

• alias – Human-friendly alias to assign to the DID.

• role – For permissioned ledgers, what role should the new DID have.

• write_ledger – Flag to write the nym to the ledger

• endorser_did – Optional DID of the endorser

abstractmethod async rotate_public_did_keypair(next_seed: str | None = None) → None

Rotate keypair for public DID: create new key, submit to ledger, update wallet.

Parameters:

next_seed – seed for incoming ed25519 keypair (default random)

async send_credential_definition_anoncreds(schema_id: str, cred_def_id: str, cred_def: dict, write_ledger: bool = True, endorser_did: str | None = None) → Tuple[str, dict, bool]

Send credential definition to ledger and store relevant key matter in wallet.

Parameters:

• schema_id (str) – The schema id of the schema to create credential definition for.

• cred_def_id (str) – The credential definition id.

• cred_def (dict) – The credential definition structure.

• write_ledger (bool, optional) – Flag indicating whether to write the credential definition to the ledger. Defaults to True.

• endorser_did (str, optional) – The DID of the endorser. Defaults to None.

Returns:

A tuple containing the credential definition id,

credential definition structure, and a boolean indicating whether it’s novel.

Return type:

Tuple[str, dict, bool]

Raises:

• BadLedgerRequestError – If there is no public DID available to publish the credential definition.

• LedgerError – If the ledger does not have the specified schema.

• LedgerObjectAlreadyExistsError – If the credential definition already exists in the wallet and on the ledger.

• LedgerError – If the ledger is in read-only mode and cannot write the credential definition.

abstractmethod async send_revoc_reg_def(revoc_reg_def: dict, issuer_did: str | None = None, write_ledger: bool = True, endorser_did: str | None = None) → dict

Publish a revocation registry definition to the ledger.

abstractmethod async send_revoc_reg_entry(revoc_reg_id: str, revoc_def_type: str, revoc_reg_entry: dict, issuer_did: str | None = None, write_ledger: bool = True, endorser_did: str | None = None) → dict

Publish a revocation registry entry to the ledger.

async send_schema_anoncreds(schema_id: str, schema_def: dict, write_ledger: bool = True, endorser_did: str | None = None) → Tuple[str, dict]

Send schema to the ledger.

This method sends a schema to the ledger for publication.

Parameters:

• schema_id (str) – The ID of the schema.

• schema_def (dict) – The definition of the schema.

• write_ledger (bool, optional) – Whether to write the schema to the ledger. Defaults to True.

• endorser_did (str, optional) – The DID of the endorser. Defaults to None.

Returns:

A tuple containing the schema ID and the schema definition.

Return type:

Tuple[str, dict]

Raises:

• BadLedgerRequestError – If there is no public DID available for publishing the schema.

• BadLedgerRequestError – If the public DID is not an IndyDID.

• LedgerError – If the ledger is in read-only mode or if the TAA is required and not accepted.

• LedgerError – If the ledger is in read-only mode.

• LedgerError – If parsing the schema sequence number from the ledger response fails.

• LedgerObjectAlreadyExistsError – If the schema already exists on the ledger.

taa_digest(version: str, text: str)

Generate the digest of a TAA record.

abstractmethod async txn_endorse(request_json: str, endorse_did: DIDInfo | None = None) → str

Endorse (sign) the provided transaction.

abstractmethod async txn_submit(request_json: str, sign: bool, taa_accept: bool | None = None, sign_did: ~acapy_agent.wallet.did_info.DIDInfo = <object object>, write_ledger: bool = True) → str

Write the provided (signed and possibly endorsed) transaction to the ledger.

abstractmethod async update_endpoint_for_did(did: str, endpoint: str, endpoint_type: EndpointType = EndpointType.ENDPOINT, write_ledger: bool = True, endorser_did: str | None = None, routing_keys: List[str] | None = None) → bool

Check and update the endpoint on the ledger.

Parameters:

• did – The ledger DID

• endpoint – The endpoint address

• endpoint_type – The type of the endpoint (default ‘endpoint’)

• write_ledger – Flag to write the endpoint to the ledger

• endorser_did – Optional DID of the endorser

• routing_keys – List of routing_keys if mediator is present

class acapy_agent.ledger.base.Role(*values)

Bases: Enum

Enum for indy roles.

ENDORSER = (101,)

NETWORK_MONITOR = (201,)

ROLE_REMOVE = ('',)

STEWARD = (2,)

TRUSTEE = (0,)

USER = (None, '')

static get(token: str | int = None) → Role

Return enum instance corresponding to input token.

Parameters:

token – token identifying role to indy-sdk: “STEWARD”, “TRUSTEE”, “ENDORSER”, “” or None

to_indy_num_str() → str

Return (typically, numeric) string value that indy-sdk associates with role.

Recall that None signifies USER and “” signifies a role undergoing reset.

token() → str

Return token identifying role to indy-sdk.

acapy_agent.ledger.endpoint_type module

Ledger utilities.

class acapy_agent.ledger.endpoint_type.EndpointType(*values)

Bases: Enum

Enum for endpoint/service types.

ENDPOINT = ('Endpoint', 'endpoint')

LINKED_DOMAINS = ('LinkedDomains', 'linked_domains')

PROFILE = ('Profile', 'profile')

static get(name: str) → EndpointType

Return enum instance corresponding to input string.

property indy

internally-facing, on ledger and in wallet.

Type:

Indy name of endpoint type

property w3c

externally-facing.

Type:

W3C name of endpoint type

class acapy_agent.ledger.endpoint_type.EndpointTypeName(w3c, indy)

Bases: tuple

indy

Alias for field number 1

w3c

Alias for field number 0

acapy_agent.ledger.error module

Ledger related errors.

exception acapy_agent.ledger.error.BadLedgerRequestError(*args, error_code: str | None = None, **kwargs)

Bases: LedgerError

The current request cannot proceed.

exception acapy_agent.ledger.error.ClosedPoolError(*args, error_code: str | None = None, **kwargs)

Bases: LedgerError

Indy pool is closed.

exception acapy_agent.ledger.error.LedgerConfigError(*args, error_code: str | None = None, **kwargs)

Bases: LedgerError

Base class for ledger configuration errors.

exception acapy_agent.ledger.error.LedgerError(*args, error_code: str | None = None, **kwargs)

Bases: BaseError

Base class for ledger errors.

exception acapy_agent.ledger.error.LedgerObjectAlreadyExistsError(message: str, obj_id: str, obj: T | None = None, *args, **kwargs)

Bases: LedgerError, Generic[T]

Raised when a ledger object already existed.

property message

Error message.

exception acapy_agent.ledger.error.LedgerTransactionError(*args, error_code: str | None = None, **kwargs)

Bases: LedgerError

The ledger rejected the transaction.

acapy_agent.ledger.indy_vdr module

Indy-VDR ledger implementation.

class acapy_agent.ledger.indy_vdr.IndyVdrLedger(pool: IndyVdrLedgerPool, profile: Profile)

Bases: BaseLedger

Indy-VDR ledger class.

BACKEND_NAME: str | None = 'indy-vdr'

async accept_txn_author_agreement(taa_record: dict, mechanism: str, accept_time: int | None = None)

Save a new record recording the acceptance of the TAA.

async build_and_return_get_nym_request(submitter_did: str | None, target_did: str) → str

Build GET_NYM request and return request_json.

async credential_definition_id2schema_id(credential_definition_id)

From a credential definition, get the identifier for its schema.

Parameters:

credential_definition_id – The identifier of the credential definition from which to identify a schema

async fetch_credential_definition(credential_definition_id: str) → dict | None

Get a credential definition from the ledger by id.

Parameters:

credential_definition_id – The cred def id of the cred def to fetch

async fetch_schema_by_id(schema_id: str) → dict

Get schema from ledger.

Parameters:

schema_id – The schema id (or stringified sequence number) to retrieve

Returns:

Indy schema dict

async fetch_schema_by_seq_no(seq_no: int) → dict

Fetch a schema by its sequence number.

Parameters:

seq_no – schema ledger sequence number

Returns:

Indy schema dict

async fetch_txn_author_agreement() → dict

Fetch the current AML and TAA from the ledger.

async get_all_endpoints_for_did(did: str) → dict

Fetch all endpoints for a ledger DID.

Parameters:

did – The DID to look up on the ledger or in the cache

async get_credential_definition(credential_definition_id: str) → dict

Get a credential definition from the cache if available, otherwise the ledger.

Parameters:

credential_definition_id – The schema id of the schema to fetch cred def for

async get_endpoint_for_did(did: str, endpoint_type: EndpointType | None = None) → str

Fetch the endpoint for a ledger DID.

Parameters:

• did – The DID to look up on the ledger or in the cache

• endpoint_type – The type of the endpoint. If none given, returns all

async get_key_for_did(did: str) → str | None

Fetch the verkey for a ledger DID.

Parameters:

did – The DID to look up on the ledger or in the cache

async get_latest_txn_author_acceptance() → dict

Look up the latest TAA acceptance.

async get_nym_role(did: str) → Role

Return the role of the input public DID’s NYM on the ledger.

Parameters:

did – DID to query for role on the ledger.

async get_revoc_reg_def(revoc_reg_id: str) → dict

Get revocation registry definition by ID.

async get_revoc_reg_delta(revoc_reg_id: str, timestamp_from=0, timestamp_to=None) → Tuple[dict, int]

Look up a revocation registry delta by ID.

:param revoc_reg_id revocation registry id :param timestamp_from from time. a total number of seconds from Unix Epoch :param timestamp_to to time. a total number of seconds from Unix Epoch

:returns delta response, delta timestamp

async get_revoc_reg_entry(revoc_reg_id: str, timestamp: int) → Tuple[dict, int]

Get revocation registry entry by revocation registry ID and timestamp.

async get_schema(schema_id: str) → dict

Get a schema from the cache if available, otherwise fetch from the ledger.

Parameters:

schema_id – The schema id (or stringified sequence number) to retrieve

async get_txn_author_agreement(reload: bool = False) → dict

Get the current transaction author agreement, fetching it if necessary.

async get_wallet_public_did() → DIDInfo

Fetch the public DID from the wallet.

async is_ledger_read_only() → bool

Check if ledger is read-only including TAA.

nym_to_did(nym: str) → str

Format a nym with the ledger’s DID prefix.

property pool_handle

Accessor for the ledger pool handle.

property pool_name: str

Accessor for the ledger pool name.

property read_only: bool

Accessor for the ledger read-only flag.

async register_nym(did: str, verkey: str, alias: str | None = None, role: str | None = None, write_ledger: bool = True, endorser_did: str | None = None) → Tuple[bool, dict]

Register a nym on the ledger.

Parameters:

• did – DID to register on the ledger.

• verkey – The verification key of the keypair.

• alias – Human-friendly alias to assign to the DID.

• role – For permissioned ledgers, what role should the new DID have.

• write_ledger – Whether to write the nym to the ledger.

• endorser_did – DID of the endorser to use for the transaction.

async rotate_public_did_keypair(next_seed: str | None = None) → None

Rotate keypair for public DID: create new key, submit to ledger, update wallet.

Parameters:

next_seed – seed for incoming ed25519 keypair (default random)

async send_revoc_reg_def(revoc_reg_def: dict, issuer_did: str | None = None, write_ledger: bool = True, endorser_did: str | None = None) → dict

Publish a revocation registry definition to the ledger.

async send_revoc_reg_entry(revoc_reg_id: str, revoc_def_type: str, revoc_reg_entry: dict, issuer_did: str | None = None, write_ledger: bool = True, endorser_did: str | None = None) → dict

Publish a revocation registry entry to the ledger.

async submit_get_nym_request(request_json: str) → str

Submit GET_NYM request to ledger and return response_json.

taa_rough_timestamp() → int

Get a timestamp accurate to the day.

Anything more accurate is a privacy concern.

async txn_endorse(request_json: str, endorse_did: DIDInfo | None = None) → str

Endorse (sign) the provided transaction.

async txn_submit(request_json: str, sign: bool, taa_accept: bool | None = None, sign_did: ~acapy_agent.wallet.did_info.DIDInfo = <object object>, write_ledger: bool = True) → str

Write the provided (signed and possibly endorsed) transaction to the ledger.

async update_endpoint_for_did(did: str, endpoint: str, endpoint_type: EndpointType | None = None, write_ledger: bool = True, endorser_did: str | None = None, routing_keys: List[str] | None = None) → bool

Check and update the endpoint on the ledger.

Parameters:

• did – The ledger DID

• endpoint – The endpoint address

• endpoint_type – The type of the endpoint

• write_ledger – Whether to write the endpoint to the ledger

• endorser_did – DID of the endorser to use for the transaction

• routing_keys – List of routing keys

class acapy_agent.ledger.indy_vdr.IndyVdrLedgerPool(name: str, *, keepalive: int = 0, cache: BaseCache | None = None, cache_duration: int = 600, genesis_transactions: str | None = None, read_only: bool = False, socks_proxy: str | None = None)

Bases: object

Indy-VDR ledger pool manager.

property cfg_path: Path

Get the path to the configuration file, ensuring it’s created.

async close()

Close the pool ledger.

async context_close()

Release the reference and schedule closing of the pool ledger.

async context_open()

Open the ledger if necessary and increase the number of active references.

async create_pool_config(genesis_transactions: str, recreate: bool = False)

Create the pool ledger configuration.

property genesis_hash: str

Get the hash of the configured genesis transactions.

property genesis_txns: str

Get the configured genesis transactions.

async open()

Open the pool ledger, creating it if necessary.

acapy_agent.ledger.routes module

acapy_agent.ledger.util module

Ledger utilities.

async acapy_agent.ledger.util.notify_register_did_event(profile: Profile, did: str, meta_data: dict)

Send notification for a DID post-process event.