refactor: align object names with KERIpy and add function docs #307

kentbull · 2025-01-27T05:01:09Z

This is a work in progress PR. Status will be updated to "Ready for Review" at the end of this week.

Goals of PR

Reduce cognitive overhead in comparing SignifyTS code to KERIpy code by aligning class, interface, function, and argument names with KERIpy.
Add documentation to everything involved in Signify key management.
Small refactorings to leverage type safety of Typescript's static typing where there is low hanging fruit for easy wins.

Overview

This PR does three main things:

Aligns names with KERIpy where possible or practical.
Adds function, class, and method documentation in many places.
Renames things like Keeper, SaltyKeeper, and RandyKeeper to names that more closely match the KERIpy implementation.

Example - Keeper to IdentifierManager

As an example, key management in KERIpy occurs in keeping.Manager, not keeping.Keeper, so the SignifyTS Keeper interface, which mimicked the keeping.Manager class in KERIpy, was renamed to be IdentifierManager. The keeping.Keeper class in KERIpy was used to store keys in the LMDB database whereas the Manager was used for creating keypairs, performing inception, rotation, and signing, among other responsibilities not ported to SignifyTS from KERIpy.

The name Manager is already taken in SignifyTS by the manager.Manager class, yet the responsibilities of the keeping.Manager class were being split across both the manager.Manager class and the keeping.Keeper class. So the existing keeping.Keeper class in SignifyTS was renamed to keeping.IdentifierManager since that seemed to be a descriptive, clear name describing the fact that implementations of this object perform key pair creation, inception, rotation, and signing.

Motivation

While reading the Signify source code recently to gain a deeper understanding of key management in Signify I have noticed again a number of naming differences between SignifyTS and KERIpy that are unnecessary and introduce questions of meaning and compatibility. This PR makes the code clear by aligning the codebase with the naming used in the KERIpy codebase.

The significant work of Phil and Kevin, and those who came after them, to port the style, names, and ideas from KERIpy is a strong influence on the motivation to continue that alignment and further it.

Future work to complete this PR

My current task is to understand the ways stems for Salty key generation and lookup work. I plan to document everything I read as I gain a complete understanding of that code.

Looking for comments

Please feel free to opine and share your thoughts on what naming policies or related ideas should make it into this PR.

kentbull · 2025-01-27T05:03:23Z

Another goal of this PR is to get ready to add CESR 2.0 and KERI 2.0 support.

codecov · 2025-01-27T05:20:37Z

Codecov Report

Attention: Patch coverage is 95.97315% with 6 lines in your changes missing coverage. Please review.

Project coverage is 83.69%. Comparing base (1e451d1) to head (5cc1e3c).

Files with missing lines	Patch %	Lines
src/keri/core/keeping.ts	94.23%	3 Missing ⚠️
src/keri/core/core.ts	93.33%	1 Missing ⚠️
src/keri/core/eventing.ts	85.71%	1 Missing ⚠️
src/keri/core/serder.ts	75.00%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #307      +/-   ##
==========================================
+ Coverage   83.64%   83.69%   +0.04%     
==========================================
  Files          48       48              
  Lines        4238     4269      +31     
  Branches     1055     1067      +12     
==========================================
+ Hits         3545     3573      +28     
- Misses        663      692      +29     
+ Partials       30        4      -26

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

edeykholt · 2025-01-27T14:00:23Z

Looks like great goals and work!
Since signify-browser-extension has a dependency on some of the exports of signify-ts main branch (as do others outside of WebOfTrust), and those exports might be changed with this commit, I'd like to see one of the following: 1) reassurance that signify-browser-extension is not affected; 2) signify-browser-extension is kept in sync as needed with a corresponding pull request; 3) signify-browser-extension is updated to reference a specific version (or commit hash) in its package.json; or 4) this commit happens on a signify-ts branch until these series of expected changes settle.

kentbull · 2025-01-27T21:05:05Z

Good points Ed. I'll take a look at the signify-browser-extension code to see what exports it depends on.

kentbull · 2025-01-27T21:12:02Z

@edeykholt item 3 of your notes above is addressed here: WebOfTrust/signify-browser-extension#229

kentbull · 2025-01-27T21:53:49Z

And @edeykholt , to your first point

reassurance that signify-browser-extension is not affected;

the results of a full text search on the signify-browser-extension repository for the names I changed here show that nothing in the browser extension depends on the names I changed here.

I will keep this in mind as I make further changes this week. If there are any refactorings that affect the browser extension then I will create a corresponding PR to that repo.

lenkan

Great work with all the cleanup and comments!

I added some minor nitpicking. But mostly, I am not sure about the IdentifierManager vs KeyManager naming. See the comment in the keeping.ts file. I read your rationale, but maybe I misunderstood.

lenkan · 2025-02-05T16:26:33Z

src/keri/core/keyState.ts

@@ -1,7 +1,7 @@
 import { Algos } from './manager';
 import { Tier } from './salter';

-export interface State {
+export interface KeyState {


I feel this is a bit backwards. Isn't this more the IdentifierState?

Then the SaltyState below is more of a SaltyKeyState, i.e., the state for the specific salty key.

The reason I called this KeyState is because that aligns with what KERIpy seems to use with things like KeyStateRecord objects.

I refrained from changing SaltyState, RandyState, and GroupState since they seemed specific enough, yet on second thought it sounds good. I'll make that change.

lenkan · 2025-02-05T16:30:37Z

src/keri/core/manager.ts

-        transferable = true,
-        temp = false,
-    }: ManagerInceptArgs): [Array<Verfer>, Array<Diger>] {
+    incept(mgrIcpArgs: ManagerInceptArgs): [Array<Verfer>, Array<Diger>] {


Imo, just args is sufficient here. It is obvious from the context that it is the arguments of the incept method of the manager. mgrIcpArgs is more confusing in my opinion.

Same for the other methods here

src/keri/core/salter.ts

src/keri/core/manager.ts

lenkan · 2025-02-05T16:39:21Z

src/keri/core/keeping.ts

+ * Interface for KERI identifier (prefix) creation, rotation, and signing.
+ * @param T Type of the key keeper
+ */
+export interface IdentifierManager<


Isn't this more of a KeyManager than an IdentifierManager ? You use it to create keys, which you in turn use to create identifiers.

The reason I called it IdentifierManager is because that name communicates the broader scope of the class. An identifier can do incept, rotate, and sign. A key can sign, yet, not the other things. So that's why I picked IdentifierManager instead of KeyManager.

kentbull · 2025-02-07T01:27:11Z

@lenkan thanks for the comments! I made corresponding changes or added rationale for context.

kentbull force-pushed the enhance-docs-and-tests branch from a6965fe to 482c023 Compare January 27, 2025 05:01

kentbull force-pushed the enhance-docs-and-tests branch 2 times, most recently from 83ea85c to 0ddf614 Compare January 27, 2025 05:15

refactor: align object names with KERIpy and add function docs

5996d11

kentbull force-pushed the enhance-docs-and-tests branch from 0ddf614 to 5996d11 Compare January 27, 2025 05:18

kentbull marked this pull request as ready for review February 4, 2025 20:22

docs: add key management and siginput docs

da4f5c3

kentbull force-pushed the enhance-docs-and-tests branch from a4f60d2 to da4f5c3 Compare February 4, 2025 20:24

kentbull requested review from lenkan and 2byrds February 5, 2025 15:30

lenkan reviewed Feb 5, 2025

View reviewed changes

kentbull added 4 commits February 6, 2025 18:11

fix: npm audit failure fix; some tsconfig excludes

1067662

docs: Add PubPath docs

2a8ab97

docs: correct Salter constructer args docs

b654a0f

refactor: change key state interface names and add docs

5cc1e3c

kentbull force-pushed the enhance-docs-and-tests branch from 500fa11 to 5cc1e3c Compare February 7, 2025 01:25

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

refactor: align object names with KERIpy and add function docs #307

refactor: align object names with KERIpy and add function docs #307

kentbull commented Jan 27, 2025 •

edited

Loading

kentbull commented Jan 27, 2025

codecov bot commented Jan 27, 2025 •

edited

Loading

edeykholt commented Jan 27, 2025

kentbull commented Jan 27, 2025

kentbull commented Jan 27, 2025

kentbull commented Jan 27, 2025

lenkan left a comment

lenkan Feb 5, 2025

kentbull Feb 7, 2025

lenkan Feb 5, 2025

lenkan Feb 5, 2025

lenkan Feb 5, 2025 •

edited

Loading

kentbull Feb 7, 2025

kentbull commented Feb 7, 2025

refactor: align object names with KERIpy and add function docs #307

Are you sure you want to change the base?

refactor: align object names with KERIpy and add function docs #307

Conversation

kentbull commented Jan 27, 2025 • edited Loading

Goals of PR

Overview

Example - Keeper to IdentifierManager

Motivation

Future work to complete this PR

Looking for comments

kentbull commented Jan 27, 2025

codecov bot commented Jan 27, 2025 • edited Loading

Codecov Report

edeykholt commented Jan 27, 2025

kentbull commented Jan 27, 2025

kentbull commented Jan 27, 2025

kentbull commented Jan 27, 2025

lenkan left a comment

Choose a reason for hiding this comment

lenkan Feb 5, 2025

Choose a reason for hiding this comment

kentbull Feb 7, 2025

Choose a reason for hiding this comment

lenkan Feb 5, 2025

Choose a reason for hiding this comment

lenkan Feb 5, 2025

Choose a reason for hiding this comment

lenkan Feb 5, 2025 • edited Loading

Choose a reason for hiding this comment

kentbull Feb 7, 2025

Choose a reason for hiding this comment

kentbull commented Feb 7, 2025

kentbull commented Jan 27, 2025 •

edited

Loading

codecov bot commented Jan 27, 2025 •

edited

Loading

lenkan Feb 5, 2025 •

edited

Loading