@red-isbe/isbe-service-did-registry 1.0.0

package/dist/src/ServiceDidRegistryQueries.js

@@ -0,0 +1,226 @@
+/**
+* Copyright (c) 2025 Comunidad de Madrid & Alastria
+*
+* Licensed under the Apache License, Version 2.0 (the "License");
+* you may not use this file except in compliance with the License.
+*
+* You may obtain a copy of the License at
+* http://www.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law or agreed to in writing, software
+* distributed under the License is distributed on an "AS IS" BASIS,
+* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+* See the License for the specific language governing permissions and
+* limitations under the License.
+*/
+import { didToHex, hexToDid } from "./utils/did.utils.js";
+import { buildServiceDid, parseServiceDid, serviceDidToHex, signingKeyAddress, } from "./utils/serviceDid.utils.js";
+import { ServiceDidRegistryContext } from "./ServiceDidRegistryContext.js";
+import { parseServiceDocument, } from "./utils/serviceDocument.utils.js";
+/** secp256k1, the curve the Case network operates on. */
+export const ELLIPTIC_TYPE_SECP256K1 = 1;
+/** P-256, the curve the Bare network operates on. */
+export const ELLIPTIC_TYPE_P256 = 2;
+/**
+ * Read surface of the Service DID Registry, and the resolver for the
+ * `did:isbe:svc:` sub-namespace.
+ */
+export class ServiceDidRegistryQueries {
+    constructor(configManager) {
+        this.configManager = configManager;
+    }
+    /**
+     * Reads a service identity.
+     *
+     * Reverts on-chain for an identifier that was never registered; use
+     * `isServiceDidActive` to probe without an exception. Expired and deactivated
+     * records are returned verbatim, so the caller applies its own validity policy.
+     */
+    async getServiceDid(serviceDid) {
+        const iface = this.configManager.contract.interface;
+        const data = iface.encodeFunctionData("getServiceDid", [
+            serviceDidToHex(serviceDid),
+        ]);
+        const addr = await this.configManager.contract.getAddress();
+        const raw = await this.configManager.provider.call({ to: addr, data });
+        const [record] = iface.decodeFunctionResult("getServiceDid", raw);
+        return this.toRecord(record);
+    }
+    /**
+     * Lists the service identities of a controller.
+     *
+     * Pages start at one, matching the registry's other paginated getters, and `total`
+     * comes back alongside the page — which is why there is no separate count call.
+     */
+    async getServiceDidsByController(controllerDid, page = 1, pageSize = 10) {
+        const iface = this.configManager.contract.interface;
+        const data = iface.encodeFunctionData("getServiceDidsByController", [
+            didToHex(controllerDid),
+            page,
+            pageSize,
+        ]);
+        const addr = await this.configManager.contract.getAddress();
+        const raw = await this.configManager.provider.call({ to: addr, data });
+        const decoded = iface.decodeFunctionResult("getServiceDidsByController", raw);
+        return {
+            items: Array.from(decoded[0]).map((item) => this.toRecord(item)),
+            total: decoded[1].toString(),
+            howMany: decoded[2].toString(),
+            prev: decoded[3].toString(),
+            next: decoded[4].toString(),
+        };
+    }
+    /**
+     * Reports whether a service identity is usable right now.
+     *
+     * False for an unknown identifier as well as for one deactivated or past its expiry,
+     * so it never throws. It does not evaluate the parent: that cascade belongs to
+     * `toDidDocumentW3C`.
+     */
+    async isServiceDidActive(serviceDid) {
+        const fn = this.configManager.contract["isServiceDidActive"];
+        return await fn(serviceDidToHex(serviceDid));
+    }
+    /**
+     * Address derived from the signing key of a service identity.
+     *
+     * Only meaningful when the key is on the curve the network operates on. For any
+     * other curve no account can transact with it, and it must not be published as a
+     * `blockchainAccountId`.
+     */
+    async signingKeyAddressOf(serviceDid) {
+        const fn = this.configManager.contract["signingKeyAddressOf"];
+        return await fn(serviceDidToHex(serviceDid));
+    }
+    /**
+     * Reads the free-form fields of a service identity, or `null` when it has none.
+     *
+     * Also `null` against a registry deployed before documents existed, where the call
+     * itself fails: resolution keeps working there, it just has no extra fields to add.
+     */
+    async getServiceDocument(serviceDid) {
+        const fn = this.configManager.contract["getServiceDocument"];
+        if (typeof fn !== "function")
+            return null;
+        try {
+            return parseServiceDocument(await fn(serviceDidToHex(serviceDid)));
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Resolves a service identity into a W3C DID Document.
+     *
+     * Three things can make an identity resolve as no longer valid, and they are checked
+     * in this order: it was deactivated, it passed its expiry, or its controlling
+     * organisation stopped being operative. The last one is only evaluated when the
+     * caller supplies `isControllerActive`.
+     *
+     * The verification method depends on the curve, not on the network: a key on the
+     * network's own curve yields `EcdsaSecp256k1RecoveryMethod2020` with a
+     * `blockchainAccountId`, and any other curve yields `JsonWebKey2020` carrying the
+     * coordinates. Emitting a `blockchainAccountId` for a key no account can use would
+     * point a verifier at an address that can never sign.
+     *
+     * The service's free-form fields, if any, are added to the document. They can never
+     * override what the registry asserts: the identifier, the controller, the keys and
+     * the deactivation status always come from the record.
+     */
+    async toDidDocumentW3C(serviceDid, options = {}) {
+        const record = await this.getServiceDid(serviceDid);
+        const extra = await this.getServiceDocument(serviceDid);
+        // Spread first, so every member the registry derives is written over it.
+        const document = { ...(extra ?? {}), ...(await this.buildDocument(record)) };
+        const reason = await this.inactiveReason(record, options);
+        return reason ? { ...document, deactivated: true, reason } : document;
+    }
+    /** Derives the identifier a controller and nonce produce, without a network call. */
+    computeServiceDid(controllerDid, nonce) {
+        return buildServiceDid(controllerDid, nonce);
+    }
+    async inactiveReason(record, options) {
+        if (record.deactivated)
+            return "deactivated";
+        const expiresAt = BigInt(record.expiresAt);
+        const now = BigInt(options.now ?? Math.floor(Date.now() / 1000));
+        if (expiresAt !== 0n && now >= expiresAt)
+            return "expired";
+        if (options.isControllerActive) {
+            const active = await options.isControllerActive(record.controllerDid);
+            if (!active)
+                return "controller-inactive";
+        }
+        return undefined;
+    }
+    async buildDocument(record) {
+        const keyId = `${record.serviceDid}#key-1`;
+        const onNetworkCurve = record.ellipticType === this.configManager.networkEllipticType;
+        // The context has to follow the branch, not the other way round: neither
+        // `EcdsaSecp256k1RecoveryMethod2020` nor `blockchainAccountId` is defined by the
+        // JWS 2020 suite, and a strict JSON-LD processor drops terms it cannot resolve —
+        // a document that looks right as plain JSON would lose its key on expansion.
+        const verificationMethod = onNetworkCurve
+            ? {
+                id: keyId,
+                type: "EcdsaSecp256k1RecoveryMethod2020",
+                controller: record.serviceDid,
+                blockchainAccountId: `eip155:${(await this.configManager.provider.getNetwork()).chainId.toString()}:${record.signingKeyAddress}`,
+            }
+            : {
+                id: keyId,
+                type: "JsonWebKey2020",
+                controller: record.serviceDid,
+                publicKeyJwk: {
+                    kty: "EC",
+                    crv: record.ellipticType === ELLIPTIC_TYPE_P256
+                        ? "P-256"
+                        : "secp256k1",
+                    x: hexToBase64Url(record.pubKeyX),
+                    y: hexToBase64Url(record.pubKeyY),
+                },
+            };
+        const suiteContext = onNetworkCurve
+            ? "https://w3id.org/security/suites/secp256k1recovery-2020/v2"
+            : "https://w3id.org/security/suites/jws-2020/v1";
+        return {
+            "@context": ["https://www.w3.org/ns/did/v1", suiteContext],
+            id: record.serviceDid,
+            controller: [record.controllerDid],
+            verificationMethod: [verificationMethod],
+            authentication: [keyId],
+            assertionMethod: [keyId],
+        };
+    }
+    /**
+     * Maps the on-chain struct into the shape this library returns.
+     *
+     * The readable identifier is rebuilt from the controller and the nonce rather than
+     * from the record's own key: a service identifier is a full digest, so the DID string
+     * cannot be recovered from it. Storing the nonce is what makes this possible.
+     */
+    toRecord(decoded) {
+        const controllerDid = hexToDid(decoded.controllerDid, this.configManager.modelDeployId);
+        return {
+            serviceDid: buildServiceDid(controllerDid, BigInt(decoded.nonce)),
+            controllerDid,
+            pubKeyX: decoded.pubKeyX,
+            pubKeyY: decoded.pubKeyY,
+            signingKeyAddress: signingKeyAddress(decoded.pubKeyX, decoded.pubKeyY),
+            labelHash: decoded.labelHash,
+            expiresAt: decoded.expiresAt.toString(),
+            ellipticType: Number(decoded.ellipticType),
+            nonce: decoded.nonce.toString(),
+            deactivated: Boolean(decoded.deactivated),
+            exists: Boolean(decoded.exists),
+            registeredAt: decoded.registeredAt.toString(),
+            updatedAt: decoded.updatedAt.toString(),
+        };
+    }
+}
+/** Re-exported so a caller can parse a service DID without importing the utils path. */
+export { parseServiceDid, serviceDidToHex };
+function hexToBase64Url(hex) {
+    return Buffer.from(hex.slice(2), "hex").toString("base64url");
+}
+//# sourceMappingURL=ServiceDidRegistryQueries.js.map

package/dist/src/ServiceDidRegistryQueries.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ServiceDidRegistryQueries.js","sourceRoot":"","sources":["../../src/ServiceDidRegistryQueries.ts"],"names":[],"mappings":"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"}

package/dist/src/ServiceDidRegistryTransactions.d.ts

@@ -0,0 +1,90 @@
+/**
+* Copyright (c) 2025 Comunidad de Madrid & Alastria
+*
+* Licensed under the Apache License, Version 2.0 (the "License");
+* you may not use this file except in compliance with the License.
+*
+* You may obtain a copy of the License at
+* http://www.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law or agreed to in writing, software
+* distributed under the License is distributed on an "AS IS" BASIS,
+* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+* See the License for the specific language governing permissions and
+* limitations under the License.
+*/
+import { type ServiceDocument } from "./utils/serviceDocument.utils.js";
+import { ServiceDidRegistryContext } from "./ServiceDidRegistryContext.js";
+/**
+ * Builders for the write surface of the Service DID Registry.
+ *
+ * Every method returns an unsigned transaction. This library never holds a key and
+ * never broadcasts: the caller signs and sends. Authorisation is enforced on-chain —
+ * the registry requires the sender to hold an active capability invocation on a
+ * controller of the parent DID — so a transaction built for a DID the signer does not
+ * control simply reverts.
+ */
+export declare class ServiceDidRegistryTransactions {
+    private configManager;
+    constructor(configManager: ServiceDidRegistryContext);
+    /**
+     * Registers a service identity under an organisational DID.
+     *
+     * The identifier is derived on-chain from the parent and its next nonce, so it is
+     * not known until the transaction is mined: read it from the `ServiceDidRegistered`
+     * event. Two concurrent registrations by the same controller consume different
+     * nonces, which is why anticipating the value is not safe.
+     *
+     * @param controllerDid Parent DID, as did:isbe:<network>:<segment>
+     * @param publicKey Signing public key, 64 or 65 bytes hex
+     * @param ellipticType 1 = secp256k1, 2 = P-256
+     * @param label Human-readable label; only its digest reaches the chain
+     * @param expiresAt Unix timestamp of expiry, or 0 to never expire
+     * @param from Address that will sign, an active controller of `controllerDid`
+     * @param document Optional free-form fields of the service — an endpoint, a name, a
+     *        description — stored on-chain and added to its DID Document. Public and
+     *        permanent in the chain history. Without it, or with `{}`, the plain
+     *        `registerServiceDid` is used
+     * @throws ServiceDocumentError when `document` is not storable as given
+     */
+    buildRegisterServiceDidTx(controllerDid: string, publicKey: string, ellipticType: number, label: string | undefined, expiresAt: number | bigint | undefined, from: string, document?: ServiceDocument | null): Promise<object>;
+    /**
+     * Sets or replaces the free-form fields of a service identity.
+     *
+     * The whole document is replaced, not merged: send every field that should remain.
+     * `null` or `{}` clears it. The previous content stays in the chain history.
+     *
+     * @throws ServiceDocumentError when `document` is not storable as given
+     */
+    buildUpdateServiceDocumentTx(serviceDid: string, document: ServiceDocument | null, from: string): Promise<object>;
+    /**
+     * Replaces the signing key of a service identity.
+     *
+     * The replacement is atomic and has no overlap: signatures made with the previous
+     * key stop validating the moment the transaction is mined. The key rotated away from
+     * stays bound to this service's controller: its other services may still use it, a
+     * service of any other controller never can.
+     */
+    buildRotateSigningKeyTx(serviceDid: string, newPublicKey: string, newEllipticType: number, from: string): Promise<object>;
+    /**
+     * Changes the expiry of a service identity.
+     *
+     * A valid expiry is either 0 — never expires — or a timestamp in the future. Bringing
+     * an identity to an end right now is not possible this way; that is what
+     * `buildDeactivateServiceDidTx` is for, and it cannot be undone.
+     */
+    buildUpdateExpiryTx(serviceDid: string, newExpiresAt: number | bigint | undefined, from: string): Promise<object>;
+    /**
+     * Deactivates a service identity, permanently.
+     *
+     * There is no reactivation: a service that needs to come back is registered again
+     * and receives a fresh identifier.
+     */
+    buildDeactivateServiceDidTx(serviceDid: string, from: string): Promise<object>;
+    /**
+     * Stamps the facet version. Restricted to the diamond's default admin and callable
+     * once; it configures no state of its own.
+     */
+    buildInitializeServiceDidRegistryTx(from: string): Promise<object>;
+}
+//# sourceMappingURL=ServiceDidRegistryTransactions.d.ts.map

package/dist/src/ServiceDidRegistryTransactions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ServiceDidRegistryTransactions.d.ts","sourceRoot":"","sources":["../../src/ServiceDidRegistryTransactions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;EAcE;AAOF,OAAO,EAEL,KAAK,eAAe,EACrB,MAAM,kCAAkC,CAAC;AAC1C,OAAO,EAAE,yBAAyB,EAAE,MAAM,gCAAgC,CAAC;AAE3E;;;;;;;;GAQG;AACH,qBAAa,8BAA8B;IACzC,OAAO,CAAC,aAAa,CAA4B;gBAErC,aAAa,EAAE,yBAAyB;IAIpD;;;;;;;;;;;;;;;;;;;OAmBG;IACG,yBAAyB,CAC7B,aAAa,EAAE,MAAM,EACrB,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,MAAM,EACpB,KAAK,EAAE,MAAM,GAAG,SAAS,EACzB,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,EACtC,IAAI,EAAE,MAAM,EACZ,QAAQ,CAAC,EAAE,eAAe,GAAG,IAAI,GAChC,OAAO,CAAC,MAAM,CAAC;IA6BlB;;;;;;;OAOG;IACG,4BAA4B,CAChC,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,eAAe,GAAG,IAAI,EAChC,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,MAAM,CAAC;IAUlB;;;;;;;OAOG;IACG,uBAAuB,CAC3B,UAAU,EAAE,MAAM,EAClB,YAAY,EAAE,MAAM,EACpB,eAAe,EAAE,MAAM,EACvB,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,MAAM,CAAC;IAclB;;;;;;OAMG;IACG,mBAAmB,CACvB,UAAU,EAAE,MAAM,EAClB,YAAY,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,EACzC,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,MAAM,CAAC;IAUlB;;;;;OAKG;IACG,2BAA2B,CAC/B,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,MAAM,CAAC;IAUlB;;;OAGG;IACG,mCAAmC,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;CASzE"}

package/dist/src/ServiceDidRegistryTransactions.js

@@ -0,0 +1,134 @@
+/**
+* Copyright (c) 2025 Comunidad de Madrid & Alastria
+*
+* Licensed under the Apache License, Version 2.0 (the "License");
+* you may not use this file except in compliance with the License.
+*
+* You may obtain a copy of the License at
+* http://www.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law or agreed to in writing, software
+* distributed under the License is distributed on an "AS IS" BASIS,
+* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+* See the License for the specific language governing permissions and
+* limitations under the License.
+*/
+import { keccak256, toUtf8Bytes } from "ethers";
+import { buildRawTransaction } from "./utils/blockchain.utils.js";
+import { validateAndNormalizeHexPublicKey } from "./utils/blockchain.utils.js";
+import { didToHex } from "./utils/did.utils.js";
+import { serviceDidToHex } from "./utils/serviceDid.utils.js";
+import { serializeServiceDocument, } from "./utils/serviceDocument.utils.js";
+import { ServiceDidRegistryContext } from "./ServiceDidRegistryContext.js";
+/**
+ * Builders for the write surface of the Service DID Registry.
+ *
+ * Every method returns an unsigned transaction. This library never holds a key and
+ * never broadcasts: the caller signs and sends. Authorisation is enforced on-chain —
+ * the registry requires the sender to hold an active capability invocation on a
+ * controller of the parent DID — so a transaction built for a DID the signer does not
+ * control simply reverts.
+ */
+export class ServiceDidRegistryTransactions {
+    constructor(configManager) {
+        this.configManager = configManager;
+    }
+    /**
+     * Registers a service identity under an organisational DID.
+     *
+     * The identifier is derived on-chain from the parent and its next nonce, so it is
+     * not known until the transaction is mined: read it from the `ServiceDidRegistered`
+     * event. Two concurrent registrations by the same controller consume different
+     * nonces, which is why anticipating the value is not safe.
+     *
+     * @param controllerDid Parent DID, as did:isbe:<network>:<segment>
+     * @param publicKey Signing public key, 64 or 65 bytes hex
+     * @param ellipticType 1 = secp256k1, 2 = P-256
+     * @param label Human-readable label; only its digest reaches the chain
+     * @param expiresAt Unix timestamp of expiry, or 0 to never expire
+     * @param from Address that will sign, an active controller of `controllerDid`
+     * @param document Optional free-form fields of the service — an endpoint, a name, a
+     *        description — stored on-chain and added to its DID Document. Public and
+     *        permanent in the chain history. Without it, or with `{}`, the plain
+     *        `registerServiceDid` is used
+     * @throws ServiceDocumentError when `document` is not storable as given
+     */
+    async buildRegisterServiceDidTx(controllerDid, publicKey, ellipticType, label, expiresAt, from, document) {
+        // Validated before anything else: no point converting keys for a document that
+        // cannot be stored.
+        const serializedDocument = serializeServiceDocument(document);
+        const args = [
+            didToHex(controllerDid),
+            validateAndNormalizeHexPublicKey(publicKey),
+            ellipticType,
+            labelToHash(label),
+            expiresAt ?? 0,
+        ];
+        return serializedDocument
+            ? await buildRawTransaction(this.configManager.contract, "registerServiceDidWithDocument", [...args, serializedDocument], this.configManager.provider, from)
+            : await buildRawTransaction(this.configManager.contract, "registerServiceDid", args, this.configManager.provider, from);
+    }
+    /**
+     * Sets or replaces the free-form fields of a service identity.
+     *
+     * The whole document is replaced, not merged: send every field that should remain.
+     * `null` or `{}` clears it. The previous content stays in the chain history.
+     *
+     * @throws ServiceDocumentError when `document` is not storable as given
+     */
+    async buildUpdateServiceDocumentTx(serviceDid, document, from) {
+        return await buildRawTransaction(this.configManager.contract, "updateServiceDocument", [serviceDidToHex(serviceDid), serializeServiceDocument(document)], this.configManager.provider, from);
+    }
+    /**
+     * Replaces the signing key of a service identity.
+     *
+     * The replacement is atomic and has no overlap: signatures made with the previous
+     * key stop validating the moment the transaction is mined. The key rotated away from
+     * stays bound to this service's controller: its other services may still use it, a
+     * service of any other controller never can.
+     */
+    async buildRotateSigningKeyTx(serviceDid, newPublicKey, newEllipticType, from) {
+        return await buildRawTransaction(this.configManager.contract, "rotateSigningKey", [
+            serviceDidToHex(serviceDid),
+            validateAndNormalizeHexPublicKey(newPublicKey),
+            newEllipticType,
+        ], this.configManager.provider, from);
+    }
+    /**
+     * Changes the expiry of a service identity.
+     *
+     * A valid expiry is either 0 — never expires — or a timestamp in the future. Bringing
+     * an identity to an end right now is not possible this way; that is what
+     * `buildDeactivateServiceDidTx` is for, and it cannot be undone.
+     */
+    async buildUpdateExpiryTx(serviceDid, newExpiresAt, from) {
+        return await buildRawTransaction(this.configManager.contract, "updateExpiry", [serviceDidToHex(serviceDid), newExpiresAt ?? 0], this.configManager.provider, from);
+    }
+    /**
+     * Deactivates a service identity, permanently.
+     *
+     * There is no reactivation: a service that needs to come back is registered again
+     * and receives a fresh identifier.
+     */
+    async buildDeactivateServiceDidTx(serviceDid, from) {
+        return await buildRawTransaction(this.configManager.contract, "deactivateServiceDid", [serviceDidToHex(serviceDid)], this.configManager.provider, from);
+    }
+    /**
+     * Stamps the facet version. Restricted to the diamond's default admin and callable
+     * once; it configures no state of its own.
+     */
+    async buildInitializeServiceDidRegistryTx(from) {
+        return await buildRawTransaction(this.configManager.contract, "initializeServiceDidRegistry", [], this.configManager.provider, from);
+    }
+}
+/**
+ * Reduces a label to the digest the contract stores.
+ *
+ * The text itself is deliberately not sent: it is a search aid for the portal, not a
+ * security property, and keeping it off-chain makes the cost of a registration
+ * independent of how long the label is. An absent label hashes to the empty digest.
+ */
+function labelToHash(label) {
+    return keccak256(toUtf8Bytes(label ?? ""));
+}
+//# sourceMappingURL=ServiceDidRegistryTransactions.js.map

package/dist/src/ServiceDidRegistryTransactions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ServiceDidRegistryTransactions.js","sourceRoot":"","sources":["../../src/ServiceDidRegistryTransactions.ts"],"names":[],"mappings":"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"}

package/dist/src/ServiceDidTransactionExecutor.d.ts

@@ -0,0 +1,31 @@
+/**
+* Copyright (c) 2025 Comunidad de Madrid & Alastria
+*
+* Licensed under the Apache License, Version 2.0 (the "License");
+* you may not use this file except in compliance with the License.
+*
+* You may obtain a copy of the License at
+* http://www.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law or agreed to in writing, software
+* distributed under the License is distributed on an "AS IS" BASIS,
+* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+* See the License for the specific language governing permissions and
+* limitations under the License.
+*/
+import { ServiceDidRegistryContext } from "./ServiceDidRegistryContext.js";
+/**
+ * Broadcasts transactions that were signed elsewhere.
+ *
+ * Nothing in this package holds a key. The builders return an unsigned transaction, the
+ * caller signs it wherever the key lives, and this is the only place that touches the
+ * network — refusing anything not addressed to this registry.
+ */
+export declare class ServiceDidTransactionExecutor {
+    private context;
+    constructor(context: ServiceDidRegistryContext);
+    sendSignedTransaction(signedRawTransaction: string): Promise<string>;
+    /** Returns `null` when the timeout elapses: sent, not yet confirmed. */
+    waitForReceipt(tx_hash: string, timeout: number): Promise<any | null>;
+}
+//# sourceMappingURL=ServiceDidTransactionExecutor.d.ts.map

package/dist/src/ServiceDidTransactionExecutor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ServiceDidTransactionExecutor.d.ts","sourceRoot":"","sources":["../../src/ServiceDidTransactionExecutor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;EAcE;AAEF,OAAO,EAAE,yBAAyB,EAAE,MAAM,gCAAgC,CAAC;AAM3E;;;;;;GAMG;AACH,qBAAa,6BAA6B;IACxC,OAAO,CAAC,OAAO,CAA4B;gBAE/B,OAAO,EAAE,yBAAyB;IAIxC,qBAAqB,CAAC,oBAAoB,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAQ1E,wEAAwE;IAClE,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,GAAG,IAAI,CAAC;CAG5E"}

package/dist/src/ServiceDidTransactionExecutor.js

@@ -0,0 +1,37 @@
+/**
+* Copyright (c) 2025 Comunidad de Madrid & Alastria
+*
+* Licensed under the Apache License, Version 2.0 (the "License");
+* you may not use this file except in compliance with the License.
+*
+* You may obtain a copy of the License at
+* http://www.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law or agreed to in writing, software
+* distributed under the License is distributed on an "AS IS" BASIS,
+* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+* See the License for the specific language governing permissions and
+* limitations under the License.
+*/
+import { ServiceDidRegistryContext } from "./ServiceDidRegistryContext.js";
+import { sendSignedTransaction, waitForReceipt, } from "./utils/blockchain.utils.js";
+/**
+ * Broadcasts transactions that were signed elsewhere.
+ *
+ * Nothing in this package holds a key. The builders return an unsigned transaction, the
+ * caller signs it wherever the key lives, and this is the only place that touches the
+ * network — refusing anything not addressed to this registry.
+ */
+export class ServiceDidTransactionExecutor {
+    constructor(context) {
+        this.context = context;
+    }
+    async sendSignedTransaction(signedRawTransaction) {
+        return await sendSignedTransaction(signedRawTransaction, this.context.provider, this.context.contract);
+    }
+    /** Returns `null` when the timeout elapses: sent, not yet confirmed. */
+    async waitForReceipt(tx_hash, timeout) {
+        return await waitForReceipt(tx_hash, timeout, this.context.provider);
+    }
+}
+//# sourceMappingURL=ServiceDidTransactionExecutor.js.map

package/dist/src/ServiceDidTransactionExecutor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ServiceDidTransactionExecutor.js","sourceRoot":"","sources":["../../src/ServiceDidTransactionExecutor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;EAcE;AAEF,OAAO,EAAE,yBAAyB,EAAE,MAAM,gCAAgC,CAAC;AAC3E,OAAO,EACL,qBAAqB,EACrB,cAAc,GACf,MAAM,6BAA6B,CAAC;AAErC;;;;;;GAMG;AACH,MAAM,OAAO,6BAA6B;IAGxC,YAAY,OAAkC;QAC5C,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACzB,CAAC;IAED,KAAK,CAAC,qBAAqB,CAAC,oBAA4B;QACtD,OAAO,MAAM,qBAAqB,CAChC,oBAAoB,EACpB,IAAI,CAAC,OAAO,CAAC,QAAQ,EACrB,IAAI,CAAC,OAAO,CAAC,QAAQ,CACtB,CAAC;IACJ,CAAC;IAED,wEAAwE;IACxE,KAAK,CAAC,cAAc,CAAC,OAAe,EAAE,OAAe;QACnD,OAAO,MAAM,cAAc,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IACvE,CAAC;CACF"}