@obolnetwork/obol-sdk 1.0.9 → 1.0.12

package/dist/esm/src/constants.js

@@ -0,0 +1,79 @@
+export const CONFLICT_ERROR_MSG = "Conflict";
+export const EIP712_DOMAIN_NAME = "Obol";
+export const EIP712_DOMAIN_VERSION = "1";
+export const CreatorConfigHashSigningTypes = {
+    CreatorConfigHash: [{ name: "creator_config_hash", type: "string" }],
+};
+const EIP712Domain = [
+    { name: 'name', type: 'string' },
+    { name: 'version', type: 'string' },
+    { name: 'chainId', type: 'uint256' },
+];
+export const Domain = (chainId) => {
+    return {
+        name: EIP712_DOMAIN_NAME,
+        version: EIP712_DOMAIN_VERSION,
+        chainId,
+    };
+};
+export const CreatorTypedMessage = Object.assign({ EIP712Domain }, CreatorConfigHashSigningTypes);
+//A conflict once updateDefinition is merged
+export const EnrSigningTypes = {
+    ENR: [{ name: "enr", type: "string" }],
+};
+export const OperatorConfigHashSigningTypes = {
+    OperatorConfigHash: [{ name: "operator_config_hash", type: "string" }],
+};
+export const OperatorTypedMessage = Object.assign({ EIP712Domain }, OperatorConfigHashSigningTypes);
+export const ENRTypedMessage = Object.assign({ EIP712Domain }, EnrSigningTypes);
+export const signCreatorConfigHashPayload = (payload, chainId) => {
+    return {
+        types: CreatorTypedMessage,
+        primaryType: 'CreatorConfigHash',
+        domain: {
+            name: EIP712_DOMAIN_NAME,
+            version: EIP712_DOMAIN_VERSION,
+            chainId,
+        },
+        message: payload,
+    };
+};
+export const signOperatorConfigHashPayload = (payload, chainId) => {
+    return {
+        types: OperatorTypedMessage,
+        primaryType: 'OperatorConfigHash',
+        domain: {
+            name: EIP712_DOMAIN_NAME,
+            version: EIP712_DOMAIN_VERSION,
+            chainId,
+        },
+        message: payload,
+    };
+};
+export const signEnrPayload = (payload, chainId) => {
+    return {
+        types: ENRTypedMessage,
+        primaryType: 'ENR',
+        domain: {
+            name: EIP712_DOMAIN_NAME,
+            version: EIP712_DOMAIN_VERSION,
+            chainId,
+        },
+        message: payload,
+    };
+};
+export const dkg_algorithm = "default";
+export const config_version = "v1.7.0";
+export const SDK_VERSION = "1.0.7";
+export const DOMAIN_APPLICATION_BUILDER = '00000001';
+export const DOMAIN_DEPOSIT = '03000000';
+export const GENESIS_VALIDATOR_ROOT = '0000000000000000000000000000000000000000000000000000000000000000';
+// Flow used to create defintion
+export var DefinitionFlow;
+(function (DefinitionFlow) {
+    DefinitionFlow["Group"] = "LP-Group";
+    DefinitionFlow["Solo"] = "LP-Solo";
+    DefinitionFlow["Charon"] = "Charon-Command";
+})(DefinitionFlow || (DefinitionFlow = {}));
+export const DEFAULT_BASE_URL = "https://api.obol.tech";
+export const DEFAULT_CHAIN_ID = 1;

package/dist/esm/src/errors.js

@@ -0,0 +1,7 @@
+export class ConflictError extends Error {
+    constructor() {
+        super(`This Cluster has been already posted.`);
+        this.name = 'ConflictError';
+        Object.setPrototypeOf(this, ConflictError.prototype);
+    }
+}

package/dist/esm/src/hash.js

@@ -0,0 +1,165 @@
+import { ContainerType, ByteVectorType, UintNumberType, ListCompositeType, ByteListType, fromHexString, } from '@chainsafe/ssz';
+import { strToUint8Array } from './utils.js';
+//cluster-definition
+/**
+ * @param cluster The cluster configuration or the cluster definition
+ * @param configOnly a boolean to indicate config hash or definition hash
+ * @returns The config hash or the definition hash in of the corresponding cluster
+ */
+export const clusterConfigOrDefinitionHash = (cluster, configOnly) => {
+    const definitionType = clusterDefinitionContainerType(configOnly);
+    const val = hashClusterDefinition(cluster, configOnly);
+    return ('0x' + Buffer.from(definitionType.hashTreeRoot(val).buffer).toString('hex'));
+};
+export const hashClusterDefinition = (cluster, configOnly) => {
+    const definitionType = clusterDefinitionContainerType(configOnly);
+    const val = definitionType.defaultValue();
+    //order should be same as charon https://github.com/ObolNetwork/charon/blob/d00b31e6465a260a43ce40f15c47fb5a5b009042/cluster/ssz.go#L285
+    val.uuid = strToUint8Array(cluster.uuid);
+    val.name = strToUint8Array(cluster.name);
+    val.version = strToUint8Array(cluster.version);
+    val.timestamp = strToUint8Array(cluster.timestamp);
+    val.num_validators = cluster.num_validators;
+    val.threshold = cluster.threshold;
+    val.dkg_algorithm = strToUint8Array(cluster.dkg_algorithm);
+    val.fork_version = fromHexString(cluster.fork_version);
+    val.operators = cluster.operators.map((operator) => {
+        return configOnly
+            ? { address: fromHexString(operator.address) }
+            : {
+                address: fromHexString(operator.address),
+                enr: strToUint8Array(operator.enr),
+                config_signature: fromHexString(operator.config_signature),
+                enr_signature: fromHexString(operator.enr_signature),
+            };
+    });
+    val.creator = configOnly
+        ? { address: fromHexString(cluster.creator.address) }
+        : {
+            address: fromHexString(cluster.creator.address),
+            config_signature: fromHexString(cluster.creator.config_signature),
+        };
+    val.validators = cluster.validators.map((validator) => {
+        return {
+            fee_recipient_address: fromHexString(validator.fee_recipient_address),
+            withdrawal_address: fromHexString(validator.withdrawal_address),
+        };
+    });
+    if (!configOnly) {
+        val.config_hash = fromHexString(cluster.config_hash);
+    }
+    return val;
+};
+const operatorAddressWrapperType = new ContainerType({
+    address: new ByteVectorType(20),
+});
+const creatorAddressWrapperType = new ContainerType({
+    address: new ByteVectorType(20),
+});
+export const operatorContainerType = new ContainerType({
+    address: new ByteVectorType(20),
+    enr: new ByteListType(1024), // This needs to be dynamic, since ENRs do not have a fixed length.
+    config_signature: new ByteVectorType(65),
+    enr_signature: new ByteVectorType(65),
+});
+export const creatorContainerType = new ContainerType({
+    address: new ByteVectorType(20),
+    config_signature: new ByteVectorType(65),
+});
+export const validatorsContainerType = new ContainerType({
+    fee_recipient_address: new ByteVectorType(20),
+    withdrawal_address: new ByteVectorType(20),
+});
+const newCreatorContainerType = (configOnly) => {
+    return configOnly ? creatorAddressWrapperType : creatorContainerType;
+};
+const newOperatorContainerType = (configOnly) => {
+    return configOnly ? operatorAddressWrapperType : operatorContainerType;
+};
+/**
+ * @param configOnly a boolean to indicate config hash or definition hash
+ * @returns SSZ Containerized type of cluster definition
+ */
+export const clusterDefinitionContainerType = (configOnly) => {
+    let returnedContainerType = {
+        uuid: new ByteListType(64),
+        name: new ByteListType(256),
+        version: new ByteListType(16),
+        timestamp: new ByteListType(32),
+        num_validators: new UintNumberType(8),
+        threshold: new UintNumberType(8),
+        dkg_algorithm: new ByteListType(32),
+        fork_version: new ByteVectorType(4),
+        operators: new ListCompositeType(newOperatorContainerType(configOnly), 256),
+        creator: newCreatorContainerType(configOnly),
+        validators: new ListCompositeType(validatorsContainerType, 65536),
+    };
+    if (!configOnly) {
+        returnedContainerType = Object.assign(Object.assign({}, returnedContainerType), { config_hash: new ByteVectorType(32) });
+    }
+    return new ContainerType(returnedContainerType);
+};
+//cluster-lock
+/**
+ * @param cluster The published cluster lock
+ * @returns The lock hash in of the corresponding cluster
+ */
+export const clusterLockHash = (cluster) => {
+    const lockType = clusterLockContainerType();
+    const val = lockType.defaultValue();
+    //Check if we can replace with definition_hash 
+    val.cluster_definition = hashClusterDefinition(cluster.cluster_definition, false);
+    val.distributed_validators = cluster.distributed_validators.map(dVaidator => {
+        return {
+            distributed_public_key: fromHexString(dVaidator.distributed_public_key),
+            public_shares: dVaidator.public_shares.map(publicShare => fromHexString(publicShare)),
+            deposit_data: {
+                pubkey: fromHexString(dVaidator.deposit_data.pubkey),
+                withdrawal_credentials: fromHexString(dVaidator.deposit_data.withdrawal_credentials),
+                amount: parseInt(dVaidator.deposit_data.amount),
+                signature: fromHexString(dVaidator.deposit_data.signature),
+            },
+            builder_registration: {
+                message: {
+                    fee_recipient: fromHexString(dVaidator.builder_registration.message.fee_recipient),
+                    gas_limit: dVaidator.builder_registration.message.gas_limit,
+                    timestamp: dVaidator.builder_registration.message.timestamp,
+                    pubkey: fromHexString(dVaidator.builder_registration.message.pubkey),
+                },
+                signature: fromHexString(dVaidator.builder_registration.signature),
+            },
+        };
+    });
+    return '0x' + Buffer.from(lockType.hashTreeRoot(val).buffer).toString('hex');
+};
+const depositDataContainer = new ContainerType({
+    pubkey: new ByteVectorType(48),
+    withdrawal_credentials: new ByteVectorType(32),
+    amount: new UintNumberType(8),
+    signature: new ByteVectorType(96),
+});
+const builderRegistrationMessageContainer = new ContainerType({
+    fee_recipient: new ByteVectorType(20),
+    gas_limit: new UintNumberType(8),
+    timestamp: new UintNumberType(8),
+    pubkey: new ByteVectorType(48),
+});
+const builderRegistrationContainer = new ContainerType({
+    message: builderRegistrationMessageContainer,
+    signature: new ByteVectorType(96),
+});
+const dvContainerType = new ContainerType({
+    distributed_public_key: new ByteVectorType(48),
+    public_shares: new ListCompositeType(new ByteVectorType(48), 256),
+    deposit_data: depositDataContainer,
+    builder_registration: builderRegistrationContainer,
+});
+/**
+ * @returns SSZ Containerized type of cluster lock
+ */
+const clusterLockContainerType = () => {
+    return new ContainerType({
+        cluster_definition: clusterDefinitionContainerType(false),
+        distributed_validators: new ListCompositeType(dvContainerType, 65536),
+    });
+};

package/dist/esm/src/index.js

@@ -0,0 +1,140 @@
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import { v4 as uuidv4 } from "uuid";
+import { Base } from './base.js';
+import { CONFLICT_ERROR_MSG, CreatorConfigHashSigningTypes, Domain, dkg_algorithm, config_version, OperatorConfigHashSigningTypes, EnrSigningTypes } from './constants.js';
+import { ConflictError } from './errors.js';
+import { clusterConfigOrDefinitionHash } from './hash.js';
+import { validatePayload } from './ajv.js';
+import { definitionSchema, operatorPayloadSchema } from './schema.js';
+export * from "./types.js";
+export * from "./services.js";
+/**
+ * Obol sdk Client can be used for creating, managing and activating distributed validators.
+ */
+export class Client extends Base {
+    /**
+     * @param config - Client configurations
+     * @param config.baseUrl - obol-api url
+     * @param config.chainId - Blockchain network ID
+     * @param signer - ethersJS Signer
+     * @returns Obol-SDK Client instance
+     *
+     * An example of how to instantiate obol-sdk Client:
+     * [obolClient](https://github.com/ObolNetwork/obol-sdk-examples/blob/main/TS-Example/index.ts#L29)
+     */
+    constructor(config, signer) {
+        super(config);
+        this.signer = signer;
+    }
+    /**
+     * Creates a cluster definition which contains cluster configuration.
+     * @param {ClusterPayload} newCluster - The new unique cluster.
+     * @returns {Promise<string>} config_hash.
+     * @throws On duplicate entries, missing or wrong cluster keys.
+     *
+     * An example of how to use createClusterDefinition:
+     * [createObolCluster](https://github.com/ObolNetwork/obol-sdk-examples/blob/main/TS-Example/index.ts)
+     */
+    createClusterDefinition(newCluster) {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (!this.signer)
+                throw "Signer is required in createClusterDefinition";
+            validatePayload(newCluster, definitionSchema);
+            const clusterConfig = Object.assign(Object.assign({}, newCluster), { fork_version: this.fork_version, dkg_algorithm: dkg_algorithm, version: config_version, uuid: uuidv4(), timestamp: new Date().toISOString(), threshold: Math.ceil((2 * newCluster.operators.length) / 3), num_validators: newCluster.validators.length });
+            try {
+                const address = yield this.signer.getAddress();
+                clusterConfig.creator = { address };
+                clusterConfig.config_hash = clusterConfigOrDefinitionHash(clusterConfig, true);
+                const creatorConfigSignature = yield this.signer.signTypedData(Domain(this.chainId), CreatorConfigHashSigningTypes, { creator_config_hash: clusterConfig.config_hash });
+                const clusterDefinition = yield this.request(`/dv`, {
+                    method: 'POST',
+                    body: JSON.stringify(clusterConfig),
+                    headers: {
+                        Authorization: `Bearer ${creatorConfigSignature}`,
+                        "fork-version": this.fork_version,
+                    }
+                });
+                return clusterDefinition === null || clusterDefinition === void 0 ? void 0 : clusterDefinition.config_hash;
+            }
+            catch (err) {
+                if ((err === null || err === void 0 ? void 0 : err.message) == CONFLICT_ERROR_MSG)
+                    throw new ConflictError();
+                throw err;
+            }
+        });
+    }
+    /**
+    * Approves joining a cluster with specific configuration.
+    * @param {OperatorPayload} operatorPayload - The operator data including signatures.
+    * @param {string} configHash - The config hash of the cluster which the operator confirms joining to.
+    * @returns {Promise<ClusterDefintion>} The cluster definition.
+    * @throws On unauthorized, duplicate entries, missing keys, not found cluster or invalid data.
+    *
+    * An example of how to use acceptClusterDefinition:
+    * [acceptClusterDefinition](https://github.com/ObolNetwork/obol-sdk-examples/blob/main/TS-Example/index.ts)
+    */
+    acceptClusterDefinition(operatorPayload, configHash) {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (!this.signer)
+                throw "Signer is required in acceptClusterDefinition";
+            validatePayload(operatorPayload, operatorPayloadSchema);
+            try {
+                const address = yield this.signer.getAddress();
+                const operatorConfigSignature = yield this.signer.signTypedData(Domain(this.chainId), OperatorConfigHashSigningTypes, { operator_config_hash: configHash });
+                const operatorENRSignature = yield this.signer.signTypedData(Domain(this.chainId), EnrSigningTypes, { enr: operatorPayload.enr });
+                const operatorData = Object.assign(Object.assign({}, operatorPayload), { address, enr_signature: operatorENRSignature, fork_version: this.fork_version });
+                const clusterDefinition = yield this.request(`/dv/${configHash}`, {
+                    method: 'PUT',
+                    body: JSON.stringify(operatorData),
+                    headers: {
+                        Authorization: `Bearer ${operatorConfigSignature}`,
+                    }
+                });
+                return clusterDefinition;
+            }
+            catch (err) {
+                throw err;
+            }
+        });
+    }
+    /**
+     * @param configHash - The configuration hash returned in createClusterDefinition
+     * @returns {Promise<ClusterDefintion>} The  cluster definition for config hash
+     * @throws On not found config hash.
+     *
+     * An example of how to use getClusterDefinition:
+     * [getObolClusterDefinition](https://github.com/ObolNetwork/obol-sdk-examples/blob/main/TS-Example/index.ts)
+     */
+    getClusterDefinition(configHash) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const clusterDefinition = yield this.request(`/dv/${configHash}`, {
+                method: 'GET',
+            });
+            return clusterDefinition;
+        });
+    }
+    /**
+     * @param configHash - The configuration hash in cluster-definition
+     * @returns {Promise<ClusterLock>} The matched cluster details (lock) from DB
+     * @throws On not found cluster definition or lock.
+     *
+     * An example of how to use getClusterLock:
+     * [getObolClusterLock](https://github.com/ObolNetwork/obol-sdk-examples/blob/main/TS-Example/index.ts)
+     */
+    getClusterLock(configHash) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const lock = yield this.request(`/lock/configHash/${configHash}`, {
+                method: 'GET',
+            });
+            return lock;
+        });
+    }
+}

package/dist/esm/src/schema.js

@@ -0,0 +1,69 @@
+export const operatorPayloadSchema = {
+    type: "object",
+    properties: {
+        version: {
+            type: "string"
+        },
+        enr: {
+            type: "string"
+        },
+    },
+    required: [
+        "version",
+        "enr",
+    ]
+};
+export const definitionSchema = {
+    type: "object",
+    properties: {
+        name: {
+            type: "string"
+        },
+        operators: {
+            type: "array",
+            minItems: 4,
+            uniqueItems: true,
+            items: {
+                type: "object",
+                properties: {
+                    address: {
+                        type: "string",
+                        minLength: 42,
+                        maxLength: 42
+                    }
+                },
+                required: [
+                    "address"
+                ]
+            }
+        },
+        validators: {
+            type: "array",
+            minItems: 1,
+            items: {
+                type: "object",
+                properties: {
+                    fee_recipient_address: {
+                        type: "string",
+                        minLength: 42,
+                        maxLength: 42
+                    },
+                    withdrawal_address: {
+                        type: "string",
+                        minLength: 42,
+                        maxLength: 42
+                    }
+                },
+                required: [
+                    "fee_recipient_address",
+                    "withdrawal_address"
+                ]
+            }
+        }
+    },
+    required: [
+        "name",
+        "operators",
+        "validators"
+    ]
+};

package/dist/esm/src/services.js

@@ -0,0 +1,28 @@
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import { isValidClusterLock } from "./verify.js";
+/**
+ * Verifies Cluster Lock's validity.
+ * @param lock - cluster lock
+ * @returns {Promise<{ result: boolean }> } boolean result to indicate if lock is valid
+ * @throws on missing keys or values.
+ *
+ * An example of how to use validateClusterLock:
+ * [validateClusterLock](https://github.com/ObolNetwork/obol-sdk-examples/blob/main/TS-Example/index.ts)
+ */
+export const validateClusterLock = (lock) => __awaiter(void 0, void 0, void 0, function* () {
+    try {
+        const isLockValid = yield isValidClusterLock(lock);
+        return isLockValid;
+    }
+    catch (err) {
+        throw err;
+    }
+});

package/dist/esm/src/types.js

@@ -0,0 +1,15 @@
+/**
+ * Permitted ChainID's
+ */
+export var FORK_MAPPING;
+(function (FORK_MAPPING) {
+    /** Mainnet. */
+    FORK_MAPPING[FORK_MAPPING["0x00000000"] = 1] = "0x00000000";
+    /** Goerli/Prater. */
+    FORK_MAPPING[FORK_MAPPING["0x00001020"] = 5] = "0x00001020";
+    /** Gnosis Chain. */
+    FORK_MAPPING[FORK_MAPPING["0x00000064"] = 100] = "0x00000064";
+    /** Holesky. */
+    FORK_MAPPING[FORK_MAPPING["0x01017000"] = 17000] = "0x01017000";
+})(FORK_MAPPING || (FORK_MAPPING = {}));
+;

package/dist/esm/src/utils.js

@@ -0,0 +1,6 @@
+export const hexWithout0x = (hex) => {
+    return hex.slice(2, hex.length);
+};
+export const strToUint8Array = (str) => {
+    return new TextEncoder().encode(str);
+};