@ibgib/core-gib 0.0.26 → 0.0.28

package/src/witness/keystone/keystone-types.mts

@@ -0,0 +1,200 @@
+/**
+ * @module keystone-types
+ */
+
+import { IbGibData_V1, IbGibRel8ns_V1, IbGib_V1 } from '@ibgib/ts-gib/dist/V1/types.mjs';
+import { IbGib, IbGibAddr, TransformResult } from '@ibgib/ts-gib/dist/types.mjs';
+
+import { WitnessWithContextData_V1, WitnessWithContextRel8ns_V1 } from '../witness-with-context/witness-with-context-types.mjs';
+import { WitnessCmdData, WitnessCmdIbGib, WitnessCmdRel8ns } from '../witness-cmd/witness-cmd-types.mjs';
+import { WitnessResultData, WitnessResultIbGib, WitnessResultRel8ns } from '../witness-types.mjs';
+// import { IbGibSpaceOptionsData } from '@ibgib/core-gib/dist/witness/space/space-types.mjs';
+
+import { GLOBAL_LOG_A_LOT } from '../../core-constants.mjs';
+import { IbGibSpaceAny } from '../space/space-base-v1.mjs';
+import { MetaspaceService } from '../space/metaspace/metaspace-types.mjs';
+import { IbGibKeystoneAny } from './keystone-base-v1.mjs';
+/**
+ * use for verbose logging.
+ */
+const logalot = GLOBAL_LOG_A_LOT;
+
+export type KeystoneScope = "any" | "transform";
+export type KeystoneSubScope = "any" | "";
+
+export type ExpirationFormat = "UTC";
+
+export interface KeystoneData_V1<TChallenges, TSolutions> extends WitnessWithContextData_V1 {
+    /**
+     * @optional setting, which if set, this keystone has internal knowledge of
+     * its use.
+     */
+    scope?: string;
+    /**
+     *
+     */
+    tjpGib?: string;
+    /**
+     * @optional formatting of expiration timestamp
+     */
+    expirationFormat?: ExpirationFormat,
+    /**
+     * @optional timestamp at which time the keystone will be invalid.
+     */
+    expiration?: string;
+    /**
+     * If truthy, then there is a limited number of uses that the keystone can
+     * be utilized (challenged/mutated).
+     *
+     * # intent
+     *
+     * temporary keystones could be used for finite, pre-known numbers of
+     * "transactions".
+     */
+    remainingUses?: number;
+    /**
+     * atom corresponding to the type of challenge.
+     *
+     * @example 'zkp'
+     * @example 'math'
+     * @example 'honor'
+     */
+    challengeAtom: string;
+    challenges: TChallenges;
+    solutions: TSolutions;
+}
+
+export interface KeystoneRel8ns_V1 extends WitnessWithContextRel8ns_V1 {
+}
+
+/**
+ * Base of the ibgib data for any keystone.
+ *
+ * concrete implementations of keystones should add customized data.
+ */
+export interface KeystoneIbGib_V1<KeystoneData_V1 extends IbGibData_V1, KeystoneRel8ns_V1 extends IbGibRel8ns_V1>
+    extends IbGib_V1<KeystoneData_V1, KeystoneRel8ns_V1> {
+
+}
+
+/**
+ * Cmds for interacting with ibgib spaces.
+ *
+ * Not all of these will be implemented for every space.
+ *
+ * ## todo
+ *
+ * change these commands to better structure, e.g., verb/do/mod, can/get/addrs
+ * */
+export type KeystoneCmd =
+    'challenge' | 'revoke';
+/** Cmds for interacting with ibgib spaces.  */
+export const KeystoneCmd = {
+    /**
+     * it's more like a grunt that is intepreted by context from the robbot.
+     *
+     * my initial use of this will be to extend a keystone.
+     */
+    ib: 'ib' as KeystoneCmd,
+    /**
+     * it's more like a grunt that is intepreted by context from the robbot.
+     *
+     * my initial use of this will be to validate a keystone.
+     */
+    gib: 'gib' as KeystoneCmd,
+    /**
+     * third placeholder command.
+     *
+     * my initial use of this will be to finalize a keystone.
+     */
+    ibgib: 'ibgib' as KeystoneCmd,
+}
+
+/*o
+ * Flags to affect the command's interpretation.
+ */
+export type KeystoneCmdModifier =
+    'final';
+/**
+ * Flags to affect the command's interpretation.
+ */
+export const KeystoneCmdModifier = {
+    /**
+     * If final, then the cmd will be the last of the stone.
+     *
+     * ## notes
+     *
+     * I think this may just signal the beginning of the end, there may actually
+     * technically be more commands executed by the witness. but they would be
+     * cleanup commands. the point is that after this option
+     */
+    final: 'final' as KeystoneCmdModifier,
+}
+
+/**
+ * Information commonly required for keystones.
+ */
+export interface KeystoneOptionsData extends WitnessCmdData<KeystoneCmd, KeystoneCmdModifier> {
+    spaceId?: string;
+    spaceAddr?: string;
+}
+
+export interface KeystoneOptionsRel8ns extends WitnessCmdRel8ns {
+}
+
+export interface KeystoneOptionsIbGib<
+    TIbGib extends IbGib = IbGib_V1,
+    TOptsData extends KeystoneOptionsData = KeystoneOptionsData,
+    TOptsRel8ns extends KeystoneOptionsRel8ns = KeystoneOptionsRel8ns,
+> extends WitnessCmdIbGib<TIbGib, KeystoneCmd, KeystoneCmdModifier, TOptsData, TOptsRel8ns> {
+    space: IbGibSpaceAny;
+    metaspace: MetaspaceService;
+}
+
+/**
+ * Optional shape of result data to witness interactions.
+ *
+ * This is in addition of course to {@link WitnessResultData}.
+ *
+ * ## notes
+ *
+ * * I'm not sure what to do with this atm, so I'm just stubbing out...
+ */
+export interface KeystoneResultData extends WitnessResultData {
+    /**
+     * redeclared from {@link WitnessResultData} for explicit focus. (i.e. not
+     * really necessary but it makes it more obvious that this is used.)
+     *
+     * ## when extending keystone
+     *
+     * new addrs added to the keystone dependency graph will be here.
+     */
+    addrs?: IbGibAddr[];
+}
+
+/**
+ * Marker interface rel8ns atm...
+ *
+ * I'm not sure what to do with this atm, so I'm just stubbing out...
+ */
+export interface KeystoneResultRel8ns extends WitnessResultRel8ns { }
+
+/**
+ * Shape of result ibgib if used for a robbot.
+ *
+ * I'm not sure what to do with this atm, so I'm just stubbing out...
+ */
+export interface KeystoneResultIbGib<
+    TIbGib extends IbGib_V1,
+    TResultData extends KeystoneResultData,
+    TResultRel8ns extends KeystoneResultRel8ns
+>
+    extends WitnessResultIbGib<TIbGib, TResultData, TResultRel8ns> {
+    /**
+     * In addition to the {@link WitnessResultIbGib} `ibGibs` property, this is
+     * provided for convenience which should differentiate between the most
+     * recent (newly created) keystone ibgib and the intermediate ibgibs created
+     * (e.g. dna).
+     */
+    resTransform: TransformResult<IbGibKeystoneAny>;
+}

package/src/witness/keystone/keystone.respec.mts

@@ -0,0 +1,9 @@
+/**
+ * @module keystone.respec.mts
+ *
+ * @see {@link './math-keystone/math-keystone.respec.mts'}
+ *
+ * In order to test the keystone at the base class, you have to create a mock.
+ * I've gone ahead and made a simplistic keystone at ./math-keystone which acts
+ * as this base keystone test.
+ */

package/src/witness/keystone/math-keystone/math-keystone-helper.mts

@@ -0,0 +1,47 @@
+import { pickRandom } from "@ibgib/helper-gib";
+
+import {
+    MathChallengeInfo, MathChallengeType, MathChallengeInfo_Add
+} from "./math-keystone-types.mjs";
+
+import { GLOBAL_LOG_A_LOT } from '../../../core-constants.mjs';
+/**
+ * use for verbose logging.
+ */
+const logalot = GLOBAL_LOG_A_LOT;
+
+/**
+ * creates a new simple math challenge. only does 'add' atow.
+ *
+ * @returns math challenge info
+ */
+export async function getMathChallenge({
+    challengeType,
+}: {
+    /**
+     * If provided, will create this type of challenge.
+     */
+    challengeType?: MathChallengeType,
+}): Promise<MathChallengeInfo> {
+    const lc = `[${getMathChallenge.name}]`;
+    try {
+        if (logalot) { console.log(`${lc} starting... (I: 75a805603968ca8a4b076caa2cf9bd23)`); }
+        if (challengeType && challengeType !== 'add') { throw new Error(`only 'add' implemented atow (E: 1e5bc2395395b8d48d61135b63a77923)`); }
+
+        // add
+        const x = Math.ceil(Math.random() * 999999);
+        const y = Math.ceil(Math.random() * 999999);
+        const challenge: MathChallengeInfo_Add = {
+            id: 'hmm',
+            op: 'add',
+            a: x,
+            b: y,
+        }
+        return challenge;
+    } catch (error) {
+        console.error(`${lc} ${error.message}`);
+        throw error;
+    } finally {
+        if (logalot) { console.log(`${lc} complete.`); }
+    }
+}

package/src/witness/keystone/math-keystone/math-keystone-types.mts

@@ -0,0 +1,115 @@
+/**
+ * @module math-keystone-types
+ */
+
+import { IbGibData_V1, IbGibRel8ns_V1, IbGib_V1 } from '@ibgib/ts-gib/dist/V1/types.mjs';
+import { IbGib } from '@ibgib/ts-gib/dist/types.mjs';
+
+import {
+    KeystoneData_V1, KeystoneRel8ns_V1,
+    KeystoneOptionsData, KeystoneOptionsRel8ns, KeystoneOptionsIbGib,
+    KeystoneResultData, KeystoneResultRel8ns, KeystoneResultIbGib,
+} from '../keystone-types.mjs';
+
+
+import { GLOBAL_LOG_A_LOT } from '../../../core-constants.mjs';
+/**
+ * use for verbose logging.
+ */
+const logalot = GLOBAL_LOG_A_LOT;
+
+export interface MathKeystoneData_V1 extends KeystoneData_V1<MathChallengeInfo[], MathSolutionInfo[]> {
+    challengeAtom: 'math';
+}
+
+export interface MathKeystoneRel8ns_V1 extends KeystoneRel8ns_V1 {
+}
+
+/**
+ * needed? yagni?
+ */
+export interface MathKeystoneAddlMetadata {
+    // atom: string;
+    // classnameIsh: string;
+    // nameIsh: string;
+    // idIsh: string;
+}
+
+/**
+ * keystone for math problem challenges.
+ *
+ * I'm using this largely as a test implementation, which both gives me a chance
+ * to futz around and learn, as well as help corroborate that unit tests are
+ * properly scoped.
+ */
+export interface MathKeystoneIbGib_V1<MathKeystoneData_V1 extends IbGibData_V1, MathKeystoneRel8ns_V1 extends IbGibRel8ns_V1>
+    extends IbGib_V1<MathKeystoneData_V1, MathKeystoneRel8ns_V1> {
+
+}
+
+export interface MathKeystoneOptionsData extends KeystoneOptionsData {
+}
+
+export interface MathKeystoneOptionsRel8ns extends KeystoneOptionsRel8ns {
+}
+
+export interface MathKeystoneOptionsIbGib extends KeystoneOptionsIbGib {
+}
+
+/**
+ * @see {@link WitnessResultData}
+ */
+export interface MathKeystoneResultData extends KeystoneResultData {
+}
+
+/**
+ */
+export interface MathKeystoneResultRel8ns extends KeystoneResultRel8ns { }
+
+/**
+ * Shape of result ibgib if used for a robbot.
+ *
+ * I'm not sure what to do with this atm, so I'm just stubbing out...
+ */
+export interface MathKeystoneResultIbGib
+    extends KeystoneResultIbGib<IbGib_V1, MathKeystoneResultData, MathKeystoneResultRel8ns> {
+}
+
+export type MathChallengeOperation = 'add' | 'subtract';
+
+/**
+ * info about our (simple atow) math challenge.
+ */
+export interface MathChallengeInfo {
+    /**
+     * operation to be performed on number's `a` and `b`.
+     */
+    op: MathChallengeOperation;
+    /**
+     * id of the challenge
+     */
+    id: string;
+    /**
+     * left hand side of math challenge expression.
+     */
+    a: number;
+    /**
+     * right hande side of math challenge expression.
+     */
+    b: number;
+}
+
+export interface MathChallengeInfo_Add extends MathChallengeInfo {
+}
+
+/**
+ * info about our (simple atow) math challenge's solution.
+ */
+export interface MathSolutionInfo {
+    challengeId: string;
+    solution: number;
+}
+
+export interface MathChallengeType {
+
+}

package/src/witness/keystone/math-keystone/math-keystone-v1.mts

@@ -0,0 +1,139 @@
+import { IbGib_V1 } from "@ibgib/ts-gib/dist/V1/types.mjs";
+import { WitnessWithContextBase_V1 } from "../../witness-with-context/witness-with-context-base-v1.mjs";
+import {
+    MathKeystoneOptionsData, MathKeystoneOptionsIbGib, MathKeystoneOptionsRel8ns,
+    MathKeystoneResultData, MathKeystoneResultIbGib, MathKeystoneResultRel8ns,
+    MathKeystoneData_V1, MathKeystoneRel8ns_V1, MathKeystoneIbGib_V1,
+    MathKeystoneAddlMetadata,
+    MathChallengeInfo, MathSolutionInfo,
+} from "./math-keystone-types.mjs";
+import { KeystoneBase_V1 } from "../keystone-base-v1.mjs";
+
+import { GLOBAL_LOG_A_LOT } from '../../../core-constants.mjs';
+const logalot = GLOBAL_LOG_A_LOT;
+
+/**
+ * witness for keystones that have math problems as the challenges.
+ *
+ * @see {@link MathKeystoneIbGib_V1}
+ */
+export class MathKeystoneWitness_V1 extends KeystoneBase_V1<
+    MathChallengeInfo[], MathSolutionInfo[],
+    MathKeystoneOptionsData, MathKeystoneOptionsRel8ns, MathKeystoneOptionsIbGib,
+    MathKeystoneResultData, MathKeystoneResultRel8ns, MathKeystoneResultIbGib,
+    MathKeystoneData_V1, MathKeystoneRel8ns_V1> {
+
+    protected parseAddlMetadataString<TParseResult>({ ib }: { ib: string; }): TParseResult {
+        // const addlMetadataText = `${atom}_${classnameIsh}_${nameIsh}_${idIsh}`;
+        if (!ib) { throw new Error(`ib required (E: f3883d3ce90c4c15907dffa1c46e77d6)`); }
+        const lc = `[${this.parseAddlMetadataString.name}]`;
+        try {
+            const [atom, classnameIsh, nameIsh, idIsh] = ib.split('_');
+            const result = { atom, classnameIsh, nameIsh, idIsh, } as MathKeystoneAddlMetadata;
+            return result as TParseResult; // i'm not liking the TParseResult...hmm
+        } catch (error) {
+            console.error(`${lc} ${error.message}`);
+            throw error;
+        }
+    }
+
+    /**
+     * this is the primary command handler when extending a keystone, i.e.  when
+     * signing some payload.
+     */
+    protected async extend({
+        arg,
+    }: {
+        arg: MathKeystoneOptionsIbGib,
+    }): Promise<MathKeystoneResultIbGib> {
+        const lc = `${this.lc}[${this.extend.name}]`;
+        try {
+            if (logalot) { console.log(`${lc} starting...`); }
+            // 1 .look at the specs for the keystone
+            // 2. determine requirements for keystone extension
+            //   * for now, this is just the default (i.e. we skip these steps)
+
+            let nextChallenges: MathChallengeInfo[] = await this.getNextChallenges({ arg });
+            // get the next challenges to solve
+            // prompt user (if required) solve challenges
+            let nextSolutions: MathSolutionInfo[] = await this.getNextSolutions({ arg, nextChallenges });
+
+            throw new Error(`not impl (E: 470834fb2562dd33b49b8ec6c9be9423)`);
+
+            // validate nextSolutions
+            // await this.validateNextSolutions({ arg, nextChallenges, nextSolutions });
+
+            // perform keystone graph extension
+            // now that we have solutions
+
+        } catch (error) {
+            console.error(`${lc} ${error.message}`);
+            throw error;
+        } finally {
+            if (logalot) { console.log(`${lc} complete.`); }
+        }
+    }
+
+    /**
+     * chooses the next challenge infos in order to extend the keystone
+     * timeline.
+     */
+    async getNextChallenges({
+        arg,
+    }: {
+        arg: MathKeystoneOptionsIbGib,
+    }): Promise<MathChallengeInfo[]> {
+        const lc = `${this.lc}[${this.getNextChallenges.name}]`;
+        try {
+
+            if (logalot) { console.log(`${lc} starting... (I: e5cf6a884a093eddc1f297b2a63dd123)`); }
+            throw new Error(`not impl (E: 602bdd6bfa38db5acbd798e60c861623)`);
+
+        } catch (error) {
+            console.error(`${lc} ${error.message}`);
+            throw error;
+        } finally {
+            if (logalot) { console.log(`${lc} complete.`); }
+        }
+    }
+
+    async getNextSolutions({
+        arg,
+        nextChallenges,
+    }: {
+        arg: MathKeystoneOptionsIbGib,
+        nextChallenges: MathChallengeInfo[],
+    }): Promise<MathSolutionInfo[]> {
+        const lc = `${this.lc}[${this.getNextSolutions.name}]`;
+        try {
+            if (logalot) { console.log(`${lc} starting... (I: f77696f021a32ec474de3ebc2c7d7823)`); }
+
+            throw new Error(`not impl (E: d727a9e378da4ddcb90d0be3a995daeb)`);
+        } catch (error) {
+            console.error(`${lc} ${error.message}`);
+            throw error;
+        } finally {
+            if (logalot) { console.log(`${lc} complete.`); }
+        }
+    }
+
+    async validateNextSolutions({
+        arg,
+    }: {
+        arg: MathKeystoneOptionsIbGib,
+    }): Promise<string[]> {
+        const lc = `${this.lc}[${this.validateNextSolutions.name}]`;
+        let errors: string[] = [];
+        try {
+            if (logalot) { console.log(`${lc} starting... (I: 49fda11783ede527b64bf20e8a9feb23)`); }
+
+            throw new Error(`not impl (E: 5407f3d0b3d9729ee361a64cd411ea23)`);
+
+        } catch (error) {
+            console.error(`${lc} ${error.message}`);
+            throw error;
+        } finally {
+            if (logalot) { console.log(`${lc} complete.`); }
+        }
+    }
+}

package/src/witness/keystone/math-keystone/math-keystone.respec.mts

@@ -0,0 +1,123 @@
+import * as pathUtils from 'path';
+
+import {
+    firstOfAll, firstOfEach, ifWe, ifWeMight, iReckon,
+    lastOfAll, lastOfEach, respecfully, respecfullyDear,
+} from '@ibgib/helper-gib/dist/respec-gib/respec-gib.mjs';
+const maam = `[${import.meta.url}]`, sir = maam;
+
+import { delay, extractErrorMsg, getTimestampInTicks, getUUID } from '@ibgib/helper-gib';
+import { Gib } from '@ibgib/ts-gib/dist/types.mjs';
+import { IbGib_V1 } from '@ibgib/ts-gib/dist/V1/types.mjs';
+
+import { KeystoneData_V1, KeystoneIbGib_V1, KeystoneRel8ns_V1 } from '../keystone-types.mjs';
+import { IbGibKeystoneAny } from '../keystone-base-v1.mjs';
+
+import { GLOBAL_LOG_A_LOT } from '../../../core-constants.mjs';
+import { WitnessWithContextBase_V1 } from '../../witness-with-context/witness-with-context-base-v1.mjs';
+
+const logalot: boolean | number = GLOBAL_LOG_A_LOT || true;
+
+const lcFile: string = `[${pathUtils.basename(import.meta.url)}]`;
+
+// #region math mock/test helper functions/types
+
+interface MathKeystoneData_V1 extends KeystoneData_V1<any, any> { }
+interface MathKeystoneRel8ns_V1 extends KeystoneRel8ns_V1 { }
+/**
+ * this keystone has math problems as its challenges
+ */
+interface MathKeystoneIbGib_V1 extends KeystoneIbGib_V1<MathKeystoneData_V1, MathKeystoneRel8ns_V1> {
+}
+type MathType = "arithmetic";
+interface MathKeystoneAddlMetadata {
+    atom: 'keystone_math';
+    mathType: MathType;
+    tjpGib: Gib;
+}
+export async function createKeystone(): Promise<IbGibKeystoneAny> {
+    const lc = `[${createKeystone.name}]`;
+    try {
+        if (logalot) { console.log(`${lc} starting... (I: ba9c092ad0b19a7fd1c5d98fb27b5923)`); }
+
+        throw new Error(`not impl (E: db37bc8b249841397316812a006bc223)`);
+
+    } catch (error) {
+        console.error(`${lc} ${error.message}`);
+        throw error;
+    } finally {
+        if (logalot) { console.log(`${lc} complete.`); }
+    }
+}
+
+/**
+ *
+ * @returns validation error if any, else returns null
+ */
+export async function validateKeystone({
+    keystoneLatest,
+}: {
+    /**
+     * the latest (i.e. "head") keystone in the keystone's timeline.
+     */
+    keystoneLatest?: IbGibKeystoneAny,
+    /**
+     * keystones are a graph, and the idea is
+     */
+    dependencyGraph?: { [addr: string]: IbGib_V1 },
+}): Promise<string[] | null> {
+    const lc = `[${validateKeystone.name}]`;
+    try {
+        throw new Error(`not imple yet (E: 2a80e8b2e6934b10a27df67395402c29)`);
+    } catch (error) {
+        console.error(`${lc} ${error.message}`);
+        throw error;
+    }
+}
+
+// #endregion math mock/test helper functions/types
+
+/**
+ * witness for keystones that have math problems as the challenges.
+ */
+class MathKeystoneWitness_V1
+    extends WitnessWithContextBase_V1<
+        any, any, any, // options
+        any, any, any, // result
+        MathKeystoneData_V1, MathKeystoneRel8ns_V1> {
+
+    protected parseAddlMetadataString<TParseResult>({ ib }: { ib: string; }): TParseResult {
+        // const addlMetadataText = `${atom}_${classnameIsh}_${nameIsh}_${idIsh}`;
+        if (!ib) { throw new Error(`ib required (E: f3883d3ce90c4c15907dffa1c46e77d6)`); }
+        const lc = `[${this.parseAddlMetadataString.name}]`;
+        try {
+            const [atom, classnameIsh, nameIsh, idIsh] = ib.split('_');
+            const result = { atom, classnameIsh, nameIsh, idIsh, } as unknown as MathKeystoneAddlMetadata;
+            return result as TParseResult; // i'm not liking the TParseResult...hmm
+        } catch (error) {
+            console.error(`${lc} ${error.message}`);
+            throw error;
+        }
+    }
+    protected witnessImpl(arg: any): Promise<any> {
+        throw new Error('Method not implemented.');
+    }
+
+}
+
+await respecfully(maam, lcFile, async () => {
+    let lc = lcFile.concat();
+
+    await respecfully(maam, `simple keystones (not composite)`, async () => {
+
+        await ifWe(maam, `createKeystone`, async () => {
+
+        });
+        await ifWe(maam, `validateKeystone`, async () => { });
+        await ifWe(maam, `iterateKeystone`, async () => { });
+        await ifWe(maam, `createKeystoneChallenge`, async () => { });
+        await ifWe(maam, `createKeystoneChallenge`, async () => { });
+
+    });
+
+}, { logalot: !!logalot });