From 7001e27daddfc63aa94c7d66f82bc45b4cf1e8f6 Mon Sep 17 00:00:00 2001 From: thephez Date: Mon, 18 Aug 2025 15:24:52 -0400 Subject: [PATCH 1/4] fix(wasm-sdk): correct identity create/topup documentation parameters MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add sdk_params to api-definitions.json and update generate_docs.py to use them for accurate SDK documentation while preserving UI compatibility. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- packages/wasm-sdk/api-definitions.json | 52 +++++++++++++++++++++++++- packages/wasm-sdk/generate_docs.py | 45 ++++++++++++++++------ 2 files changed, 84 insertions(+), 13 deletions(-) diff --git a/packages/wasm-sdk/api-definitions.json b/packages/wasm-sdk/api-definitions.json index a2b91d2e6e..67e39c11d6 100644 --- a/packages/wasm-sdk/api-definitions.json +++ b/packages/wasm-sdk/api-definitions.json @@ -1235,7 +1235,31 @@ "label": "Keys to be added", "help": "These keys will be added to your new identity" } - ] + ], + "sdk_params": [ + { + "name": "assetLockProof", + "type": "string", + "label": "Asset Lock Proof", + "required": true, + "description": "Hex-encoded JSON asset lock proof" + }, + { + "name": "assetLockProofPrivateKey", + "type": "string", + "label": "Asset Lock Proof Private Key", + "required": true, + "description": "WIF format private key" + }, + { + "name": "publicKeys", + "type": "string", + "label": "Public Keys", + "required": true, + "description": "JSON array of public keys" + } + ], + "sdk_example": "// Asset lock proof is a hex-encoded JSON object\nconst assetLockProof = \"a9147d3b... (hex-encoded)\";\nconst assetLockProofPrivateKey = \"XFfpaSbZq52HPy3WWwe1dXsZMiU1bQn8vQd34HNXkSZThevBWRn1\"; // WIF format\n\n// Public keys array with proper key types\nconst publicKeys = JSON.stringify([\n {\n id: 0,\n type: 0, // ECDSA_SECP256K1 = 0, BLS12_381 = 1, ECDSA_HASH160 = 2\n purpose: 0, // AUTHENTICATION = 0, ENCRYPTION = 1, DECRYPTION = 2, TRANSFER = 3, etc.\n securityLevel: 0, // MASTER = 0, CRITICAL = 1, HIGH = 2, MEDIUM = 3\n data: \"A5GzYHPIolbHkFrp5l+s9IvF2lWMuuuSu3oWZB8vWHNJ\", // Base64-encoded public key\n readOnly: false\n },\n {\n id: 1,\n type: 0,\n purpose: 0,\n securityLevel: 2,\n data: \"AnotherBase64EncodedPublicKeyHere\", // Base64-encoded public key\n readOnly: false\n }\n]);\n\nconst result = await sdk.identityCreate(assetLockProof, assetLockProofPrivateKey, publicKeys);" }, "identityTopUp": { "label": "Identity Top Up", @@ -1249,7 +1273,31 @@ "placeholder": "Enter the identity ID to top up (base58)", "help": "The identity ID that will receive the credits from the asset lock proof" } - ] + ], + "sdk_params": [ + { + "name": "identityId", + "type": "string", + "label": "Identity ID", + "required": true, + "description": "Base58 format identity ID" + }, + { + "name": "assetLockProof", + "type": "string", + "label": "Asset Lock Proof", + "required": true, + "description": "Hex-encoded JSON asset lock proof" + }, + { + "name": "assetLockProofPrivateKey", + "type": "string", + "label": "Asset Lock Proof Private Key", + "required": true, + "description": "WIF format private key" + } + ], + "sdk_example": "const identityId = \"5DbLwAxGBzUzo81VewMUwn4b5P4bpv9FNFybi25XB5Bk\"; // base58\nconst assetLockProof = \"a9147d3b... (hex-encoded)\";\nconst assetLockProofPrivateKey = \"XFfpaSbZq52HPy3WWve1dXsZMiU1bQn8vQd34HNXkSZThevBWRn1\"; // WIF format\n\nconst result = await sdk.identityTopUp(identityId, assetLockProof, assetLockProofPrivateKey);" }, "identityUpdate": { "label": "Identity Update", diff --git a/packages/wasm-sdk/generate_docs.py b/packages/wasm-sdk/generate_docs.py index ea8b42ae40..5411cd2ab6 100755 --- a/packages/wasm-sdk/generate_docs.py +++ b/packages/wasm-sdk/generate_docs.py @@ -245,11 +245,15 @@ def generate_operation_entry(operation_key, operation, type_prefix):
Parameters:
''' + # Use sdk_params if available (for state transitions), otherwise use inputs + sdk_params = operation.get('sdk_params', []) inputs = operation.get('inputs', []) - if not inputs: + params_to_use = sdk_params if sdk_params else inputs + + if not params_to_use: html_content += '

No parameters required

' else: - for param in inputs: + for param in params_to_use: html_content += generate_parameter_entry(param) html_content += ''' @@ -297,7 +301,7 @@ def generate_operation_entry(operation_key, operation, type_prefix): html_content += f'\n
' else: # State transitions don't have run buttons - html_content += f'
{generate_transition_example(operation_key)}
' + html_content += f'
{generate_transition_example(operation_key, operation)}
' html_content += ''' @@ -312,7 +316,9 @@ def generate_parameter_entry(param): {param.get('type', 'text')} {required_text} ''' - if param.get('placeholder'): + if param.get('description'): + html_content += f'
{html_lib.escape(param.get("description"))}\n' + elif param.get('placeholder'): html_content += f'
Example: {html_lib.escape(param.get("placeholder"))}\n' elif param.get('name') == 'limit' and not param.get('required', False): html_content += '
Default: 100 (maximum items returned if not specified)\n' @@ -324,8 +330,12 @@ def generate_parameter_entry(param): html_content += ' \n' return html_content -def generate_transition_example(trans_key): +def generate_transition_example(trans_key, transition=None): """Generate example code for state transitions""" + # Check if there's a custom sdk_example + if transition and transition.get('sdk_example'): + return transition.get('sdk_example') + if trans_key == 'documentCreate': return '''const result = await sdk.document_create( identityHex, @@ -1670,18 +1680,28 @@ def generate_ai_reference_md(query_defs, transition_defs): md_content += f"\n**{transition.get('label', trans_key)}** - `{trans_key}`\n" md_content += f"*{transition.get('description', 'No description')}*\n\n" - # Parameters + # Parameters - use sdk_params if available, otherwise fall back to inputs + sdk_params = transition.get('sdk_params', []) inputs = transition.get('inputs', []) - if inputs: + params_to_use = sdk_params if sdk_params else inputs + + # Adjust parameter section header based on whether we're using SDK params + if sdk_params: + md_content += "Parameters:\n" + elif inputs: md_content += "Parameters (in addition to identity/key):\n" - for param in inputs: + + if params_to_use: + for param in params_to_use: req = "required" if param.get('required', False) else "optional" md_content += f"- `{param.get('name', 'unknown')}` ({param.get('type', 'text')}, {req})" if param.get('label') and param.get('label') != param.get('name'): md_content += f" - {param.get('label')}" - if param.get('placeholder'): + if param.get('description'): + md_content += f"\n - {param.get('description')}" + elif param.get('placeholder'): md_content += f"\n - Example: `{param.get('placeholder')}`" md_content += "\n" @@ -1689,8 +1709,11 @@ def generate_ai_reference_md(query_defs, transition_defs): # Example md_content += f"\nExample:\n```javascript\n" - # Generate specific examples - if trans_key == 'documentCreate': + # Check if there's a custom sdk_example + sdk_example = transition.get('sdk_example') + if sdk_example: + md_content += sdk_example + elif trans_key == 'documentCreate': md_content += '''const result = await sdk.document_create( identityHex, contractId, From 1e72c0c4d6b78d6a55a80aba9405c7ec8e264871 Mon Sep 17 00:00:00 2001 From: thephez Date: Mon, 18 Aug 2025 15:27:40 -0400 Subject: [PATCH 2/4] docs(wasm-sdk): regenerate documentation with corrected parameter descriptions MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Update generated docs.html and manifest to reflect accurate SDK method signatures for identity create/topup operations. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- packages/wasm-sdk/docs.html | 75 ++++++++++++++++++++-------- packages/wasm-sdk/docs_manifest.json | 2 +- 2 files changed, 54 insertions(+), 23 deletions(-) diff --git a/packages/wasm-sdk/docs.html b/packages/wasm-sdk/docs.html index 4eeaaba1ea..167b857b71 100644 --- a/packages/wasm-sdk/docs.html +++ b/packages/wasm-sdk/docs.html @@ -1952,37 +1952,52 @@

Identity Create

Parameters:
- Seed Phrase - textarea + Asset Lock Proof + string (required) -
Example: Enter seed phrase (12-24 words) or click Generate -
-
- Generate New Seed - button - (optional) +
Hex-encoded JSON asset lock proof
- Identity Index - number + Asset Lock Proof Private Key + string (required) +
WIF format private key
- Key Selection Mode - select + Public Keys + string (required) -
Options: Default (Recommended), Advanced -
-
- Keys to be added - keyPreview - (optional) +
JSON array of public keys
Example
-
const result = await sdk.identityCreate(identityHex, /* params */, privateKeyHex);
+
// Asset lock proof is a hex-encoded JSON object +const assetLockProof = "a9147d3b... (hex-encoded)"; +const assetLockProofPrivateKey = "XFfpaSbZq52HPy3WWwe1dXsZMiU1bQn8vQd34HNXkSZThevBWRn1"; // WIF format + +// Public keys array with proper key types +const publicKeys = JSON.stringify([ + { + id: 0, + type: 0, // ECDSA_SECP256K1 = 0, BLS12_381 = 1, ECDSA_HASH160 = 2 + purpose: 0, // AUTHENTICATION = 0, ENCRYPTION = 1, DECRYPTION = 2, TRANSFER = 3, etc. + securityLevel: 0, // MASTER = 0, CRITICAL = 1, HIGH = 2, MEDIUM = 3 + data: "A5GzYHPIolbHkFrp5l+s9IvF2lWMuuuSu3oWZB8vWHNJ", // Base64-encoded public key + readOnly: false + }, + { + id: 1, + type: 0, + purpose: 0, + securityLevel: 2, + data: "AnotherBase64EncodedPublicKeyHere", // Base64-encoded public key + readOnly: false + } +]); + +const result = await sdk.identityCreate(assetLockProof, assetLockProofPrivateKey, publicKeys);

Identity Top Up

@@ -1992,15 +2007,31 @@

Identity Top Up

Parameters:
Identity ID - text + string + (required) +
Base58 format identity ID +
+
+ Asset Lock Proof + string (required) -
Example: Enter the identity ID to top up (base58) +
Hex-encoded JSON asset lock proof +
+
+ Asset Lock Proof Private Key + string + (required) +
WIF format private key
Example
-
const result = await sdk.identityTopUp(identityHex, /* params */, privateKeyHex);
+
const identityId = "5DbLwAxGBzUzo81VewMUwn4b5P4bpv9FNFybi25XB5Bk"; // base58 +const assetLockProof = "a9147d3b... (hex-encoded)"; +const assetLockProofPrivateKey = "XFfpaSbZq52HPy3WWve1dXsZMiU1bQn8vQd34HNXkSZThevBWRn1"; // WIF format + +const result = await sdk.identityTopUp(identityId, assetLockProof, assetLockProofPrivateKey);

Identity Update

diff --git a/packages/wasm-sdk/docs_manifest.json b/packages/wasm-sdk/docs_manifest.json index 4de9028611..252a50417e 100644 --- a/packages/wasm-sdk/docs_manifest.json +++ b/packages/wasm-sdk/docs_manifest.json @@ -1,5 +1,5 @@ { - "generated_at": "2025-08-18T16:09:12.996174+00:00", + "generated_at": "2025-08-18T19:21:21.062910+00:00", "queries": { "getIdentity": { "category": "identity", From 06806c7f12f28b102be42193cb242911cebc2639 Mon Sep 17 00:00:00 2001 From: thephez Date: Mon, 18 Aug 2025 15:33:33 -0400 Subject: [PATCH 3/4] docs(wasm-sdk): update AI reference with corrected identity transition parameters MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Regenerate AI_REFERENCE.md to reflect accurate SDK method signatures and parameter descriptions for identity create/topup operations. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- packages/wasm-sdk/AI_REFERENCE.md | 60 +++++++++++++++++++++++-------- 1 file changed, 46 insertions(+), 14 deletions(-) diff --git a/packages/wasm-sdk/AI_REFERENCE.md b/packages/wasm-sdk/AI_REFERENCE.md index 57df8f64ce..dfd9f2eb94 100644 --- a/packages/wasm-sdk/AI_REFERENCE.md +++ b/packages/wasm-sdk/AI_REFERENCE.md @@ -757,29 +757,61 @@ const result = await sdk.{transition_name}(identityHex, ...params, privateKeyHex **Identity Create** - `identityCreate` *Create a new identity with initial credits* -Parameters (in addition to identity/key): -- `seedPhrase` (textarea, required) - Seed Phrase - - Example: `Enter seed phrase (12-24 words) or click Generate` -- `generateSeedButton` (button, optional) - Generate New Seed -- `identityIndex` (number, required) - Identity Index -- `keySelectionMode` (select, required) - Key Selection Mode -- `keyPreview` (keyPreview, optional) - Keys to be added +Parameters: +- `assetLockProof` (string, required) - Asset Lock Proof + - Hex-encoded JSON asset lock proof +- `assetLockProofPrivateKey` (string, required) - Asset Lock Proof Private Key + - WIF format private key +- `publicKeys` (string, required) - Public Keys + - JSON array of public keys + +Example: +```javascript +// Asset lock proof is a hex-encoded JSON object +const assetLockProof = "a9147d3b... (hex-encoded)"; +const assetLockProofPrivateKey = "XFfpaSbZq52HPy3WWwe1dXsZMiU1bQn8vQd34HNXkSZThevBWRn1"; // WIF format + +// Public keys array with proper key types +const publicKeys = JSON.stringify([ + { + id: 0, + type: 0, // ECDSA_SECP256K1 = 0, BLS12_381 = 1, ECDSA_HASH160 = 2 + purpose: 0, // AUTHENTICATION = 0, ENCRYPTION = 1, DECRYPTION = 2, TRANSFER = 3, etc. + securityLevel: 0, // MASTER = 0, CRITICAL = 1, HIGH = 2, MEDIUM = 3 + data: "A5GzYHPIolbHkFrp5l+s9IvF2lWMuuuSu3oWZB8vWHNJ", // Base64-encoded public key + readOnly: false + }, + { + id: 1, + type: 0, + purpose: 0, + securityLevel: 2, + data: "AnotherBase64EncodedPublicKeyHere", // Base64-encoded public key + readOnly: false + } +]); -Example: -```javascript -const result = await sdk.identityCreate(identityHex, /* params */, privateKeyHex); +const result = await sdk.identityCreate(assetLockProof, assetLockProofPrivateKey, publicKeys); ``` **Identity Top Up** - `identityTopUp` *Add credits to an existing identity* -Parameters (in addition to identity/key): -- `identityId` (text, required) - Identity ID - - Example: `Enter the identity ID to top up (base58)` +Parameters: +- `identityId` (string, required) - Identity ID + - Base58 format identity ID +- `assetLockProof` (string, required) - Asset Lock Proof + - Hex-encoded JSON asset lock proof +- `assetLockProofPrivateKey` (string, required) - Asset Lock Proof Private Key + - WIF format private key Example: ```javascript -const result = await sdk.identityTopUp(identityHex, /* params */, privateKeyHex); +const identityId = "5DbLwAxGBzUzo81VewMUwn4b5P4bpv9FNFybi25XB5Bk"; // base58 +const assetLockProof = "a9147d3b... (hex-encoded)"; +const assetLockProofPrivateKey = "XFfpaSbZq52HPy3WWve1dXsZMiU1bQn8vQd34HNXkSZThevBWRn1"; // WIF format + +const result = await sdk.identityTopUp(identityId, assetLockProof, assetLockProofPrivateKey); ``` **Identity Update** - `identityUpdate` From ac3858c6c94720b977b697f25a0fb393934f3900 Mon Sep 17 00:00:00 2001 From: thephez Date: Mon, 18 Aug 2025 15:57:38 -0400 Subject: [PATCH 4/4] style: improve rendering of multiline examples like identity create st --- packages/wasm-sdk/docs.css | 2 ++ 1 file changed, 2 insertions(+) diff --git a/packages/wasm-sdk/docs.css b/packages/wasm-sdk/docs.css index 35302b49ea..4af6d24309 100644 --- a/packages/wasm-sdk/docs.css +++ b/packages/wasm-sdk/docs.css @@ -270,6 +270,8 @@ h3 { font-size: 0.9em; margin-bottom: 10px; position: relative; + white-space: pre-wrap; + overflow-x: auto; } .run-button {