Skip to content

fix(sdk): fix documentation examples #2710

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 14 commits into from
Jul 29, 2025
Merged

fix(sdk): fix documentation examples #2710

Show file tree
Hide file tree
Changes from 10 commits
Commits
Show all changes
14 commits
Select commit Hold shift + click to select a range
96d3d07
fix(wasm-sdk): fix nested examples in Get Identity Keys documentation
thephez Jul 28, 2025
6c47cab
fix(wasm-sdk): fix container structure for Get Identity Keys examples
thephez Jul 28, 2025
1329919
feat(wasm-sdk): update getDataContractHistory example with specific c…
thephez Jul 28, 2025
1b9032a
fix(wasm-sdk): fix getDataContractHistory serialization and remove WI…
thephez Jul 28, 2025
46306b1
feat(wasm-sdk): add third example for Get Identity Keys search functi…
thephez Jul 28, 2025
5e9345e
fix: make getIdentityKeys specific example work by disabling proofs i…
thephez Jul 28, 2025
6f9f401
fix: update getIdentityKeys search example
thephez Jul 28, 2025
3bc5bf5
fix: temporarily bypass get_token_perpetual_distribution_last_claim p…
thephez Jul 28, 2025
76b88f5
Merge branch 'v2.1-dev' into fix-wasm-sdk-examples
thephez Jul 29, 2025
673e92b
fix(wasm-sdk): fix getTokenPerpetualDistributionLastClaim raw bytes d…
thephez Jul 29, 2025
b32cd43
docs(wasm-sdk): add comprehensive documentation and validation for ra…
thephez Jul 29, 2025
71db515
trivial: minor cleanup
thephez Jul 29, 2025
e4447c4
docs: update example contract id
thephez Jul 29, 2025
243e31e
docs: revert change
thephez Jul 29, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
106 changes: 42 additions & 64 deletions packages/wasm-sdk/docs.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1035,15 +1035,23 @@ <h5>Parameters:</h5>
<h5>Example</h5>
<div class="example-code" id="code-getIdentityKeys">return await window.wasmFunctions.get_identity_keys(sdk, '5DbLwAxGBzUzo81VewMUwn4b5P4bpv9FNFybi25XB5Bk', 'all');</div>
<button class="run-button" id="run-getIdentityKeys" onclick="runExample('getIdentityKeys')">Run</button>
<div class="example-container">
<h5>Example 2 - Get Specific Keys</h5>
<div class="example-code" id="code-getIdentityKeys2">return await window.wasmFunctions.get_identity_keys(sdk, '5DbLwAxGBzUzo81VewMUwn4b5P4bpv9FNFybi25XB5Bk', 'specific', [0, 1, 2]);</div>
<button class="run-button" id="run-getIdentityKeys2" onclick="runExample('getIdentityKeys2')">Run</button>
<div class="example-result" id="result-getIdentityKeys2"></div>
</div>
<div class="example-result" id="result-getIdentityKeys"></div> </div>
</div>
<div class="operation">
<div class="example-result" id="result-getIdentityKeys"></div>
</div>

<div class="example-container">
<h5>Example 2 - Get Specific Keys</h5>
<div class="example-code" id="code-getIdentityKeys2">return await window.wasmFunctions.get_identity_keys(sdk, '5DbLwAxGBzUzo81VewMUwn4b5P4bpv9FNFybi25XB5Bk', 'specific', [0, 1, 2]);</div>
<button class="run-button" id="run-getIdentityKeys2" onclick="runExample('getIdentityKeys2')">Run</button>
<div class="example-result" id="result-getIdentityKeys2"></div>
</div>

<div class="example-container">
<h5>Example 3 - Search Keys by Purpose</h5>
<div class="example-code" id="code-getIdentityKeys3">return await window.wasmFunctions.get_identity_keys(sdk, '5DbLwAxGBzUzo81VewMUwn4b5P4bpv9FNFybi25XB5Bk', 'search', undefined, '{"0": {"0": "current"}, "1": {"0": "current"}}');</div>
<button class="run-button" id="run-getIdentityKeys3" onclick="runExample('getIdentityKeys3')">Run</button>
<div class="example-result" id="result-getIdentityKeys3"></div>
</div>
</div> <div class="operation">
<h4 id="query-getIdentitiesContractKeys">Get Identities Contract Keys</h4>
<p class="description">Get keys for multiple identities related to a specific contract</p>

Expand Down Expand Up @@ -1366,8 +1374,8 @@ <h5>Parameters:</h5>

<div class="example-container">
<h5>Example</h5>
<div class="example-code" id="code-getDataContractHistory">return await window.wasmFunctions.get_data_contract_history(sdk, 'GWRSAVFMjXx8HpQFaNJMqBV7MBgMK4br5UESsB4S31Ec', 10, 0);</div>
<button class="run-button" id="run-getDataContractHistory" onclick="runExample('getDataContractHistory')">Run</button> <span style="color: #f39c12; margin-left: 10px;">🚧 Work in Progress</span>
<div class="example-code" id="code-getDataContractHistory">return await window.wasmFunctions.get_data_contract_history(sdk, 'HLY575cNazmc5824FxqaEMEBuzFeE4a98GDRNKbyJqCM', 10, 0);</div>
<button class="run-button" id="run-getDataContractHistory" onclick="runExample('getDataContractHistory')">Run</button>
<div class="example-result" id="result-getDataContractHistory"></div> </div>
</div>
<div class="operation">
Expand Down Expand Up @@ -2023,7 +2031,7 @@ <h5>Parameters:</h5>

<div class="example-container">
<h5>Example</h5>
<div class="example-code" id="code-getTokenPerpetualDistributionLastClaim">return await window.wasmFunctions.get_token_perpetual_distribution_last_claim(sdk, '5DbLwAxGBzUzo81VewMUwn4b5P4bpv9FNFybi25XB5Bk', 'EETVvWgohFDKtbB3ejEzBcDRMNYkc9TtgXY6y8hzP3Ta');</div>
<div class="example-code" id="code-getTokenPerpetualDistributionLastClaim">return await window.wasmFunctions.get_token_perpetual_distribution_last_claim(sdk, '5RG84o6KsTaZudDqS8ytbaRB8QP4YYQ2uwzb6Hj8cfjX', 'HEv1AYWQfwCffXQgmuzmzyzUo9untRTmVr67n4e4PSWa');</div>
<button class="run-button" id="run-getTokenPerpetualDistributionLastClaim" onclick="runExample('getTokenPerpetualDistributionLastClaim')">Run</button> <span style="color: #f39c12; margin-left: 10px;">🚧 Work in Progress</span>
<div class="example-result" id="result-getTokenPerpetualDistributionLastClaim"></div> </div>
</div>
Expand Down Expand Up @@ -2335,52 +2343,37 @@ <h4 id="transition-identityCreate">Identity Create</h4>
<div class="parameters">
<h5>Parameters:</h5>
<div class="parameter">
<span class="param-name">Asset Lock Proof</span>
<span class="param-type">string</span>
<span class="param-name">Seed Phrase</span>
<span class="param-type">textarea</span>
<span class="param-required">(required)</span>
<br><small>Hex-encoded JSON asset lock proof</small>
<br><small>Example: Enter seed phrase (12-24 words) or click Generate</small>
</div>
<div class="parameter">
<span class="param-name">Generate New Seed</span>
<span class="param-type">button</span>
<span class="param-optional">(optional)</span>
</div>
<div class="parameter">
<span class="param-name">Asset Lock Proof Private Key</span>
<span class="param-type">string</span>
<span class="param-name">Identity Index</span>
<span class="param-type">number</span>
<span class="param-required">(required)</span>
<br><small>WIF format private key</small>
</div>
<div class="parameter">
<span class="param-name">Public Keys</span>
<span class="param-type">string</span>
<span class="param-name">Key Selection Mode</span>
<span class="param-type">select</span>
<span class="param-required">(required)</span>
<br><small>JSON array of public keys</small>
<br><small>Options: Default (Recommended), Advanced</small>
</div>
<div class="parameter">
<span class="param-name">Keys to be added</span>
<span class="param-type">keyPreview</span>
<span class="param-optional">(optional)</span>
</div>
</div>

<div class="example-container">
<h5>Example</h5>
<div class="example-code">// 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);</div> </div>
<div class="example-code">const result = await sdk.identityCreate(identityHex, /* params */, privateKeyHex);</div> </div>
</div>
<div class="operation">
<h4 id="transition-identityTopUp">Identity Top Up</h4>
Expand All @@ -2390,30 +2383,15 @@ <h4 id="transition-identityTopUp">Identity Top Up</h4>
<h5>Parameters:</h5>
<div class="parameter">
<span class="param-name">Identity ID</span>
<span class="param-type">string</span>
<span class="param-required">(required)</span>
<br><small>Base58 format identity ID</small>
</div>
<div class="parameter">
<span class="param-name">Asset Lock Proof</span>
<span class="param-type">string</span>
<span class="param-type">text</span>
<span class="param-required">(required)</span>
<br><small>Hex-encoded JSON asset lock proof</small>
<br><small>Example: Enter the identity ID to top up (base58)</small>
</div>
<div class="parameter">
<span class="param-name">Asset Lock Proof Private Key</span>
<span class="param-type">string</span>
<span class="param-required">(required)</span>
<br><small>WIF format private key</small>
</div>

<div class="example-container">
<h5>Example</h5>
<div class="example-code">const identityId = "5DbLwAxGBzUzo81VewMUwn4b5P4bpv9FNFybi25XB5Bk"; // base58
const assetLockProof = "a9147d3b... (hex-encoded)";
const assetLockProofPrivateKey = "XFfpaSbZq52HPy3WWwe1dXsZMiU1bQn8vQd34HNXkSZThevBWRn1"; // WIF format

const result = await sdk.identityTopUp(identityId, assetLockProof, assetLockProofPrivateKey);</div> </div>
<div class="example-code">const result = await sdk.identityTopUp(identityHex, /* params */, privateKeyHex);</div> </div>
</div>
<div class="operation">
<h4 id="transition-identityUpdate">Identity Update</h4>
Expand Down
37 changes: 27 additions & 10 deletions packages/wasm-sdk/generate_docs.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -144,16 +144,16 @@ def generate_example_code(query_key, inputs):

# Map input names to test values
param_mapping = {
'id': f"'{test_data['data_contract_id']}'" if 'getDataContract' in query_key else f"'{test_data['identity_id']}'",
'identityId': f"'{test_data['specialized_balance_id']}'" if 'getPrefundedSpecializedBalance' in query_key else f"'{test_data['identity_id']}'",
'id': "'HLY575cNazmc5824FxqaEMEBuzFeE4a98GDRNKbyJqCM'" if 'getDataContractHistory' in query_key else f"'{test_data['data_contract_id']}'" if 'getDataContract' in query_key else f"'{test_data['identity_id']}'",
'identityId': f"'{test_data['specialized_balance_id']}'" if 'getPrefundedSpecializedBalance' in query_key else "'5RG84o6KsTaZudDqS8ytbaRB8QP4YYQ2uwzb6Hj8cfjX'" if 'getTokenPerpetualDistributionLastClaim' in query_key else f"'{test_data['identity_id']}'",
'ids': f"['{test_data['data_contract_id']}', '{test_data['token_contract_id']}']" if 'getDataContracts' in query_key else f"['{test_data['pro_tx_hash']}']" if 'Evonodes' in query_key else f"['{test_data['identity_id']}']",
'identitiesIds': f"['{test_data['identity_id']}']",
'identityIds': f"['{test_data['identity_id']}']",
'contractId': f"'{test_data['group_contract_id']}'" if ('group' in query_key.lower() or 'Group' in query_key) else f"'{test_data['token_contract_id']}'" if ('token' in query_key.lower() or 'Token' in query_key) and 'TokenBalance' not in query_key and 'TokenInfo' not in query_key else f"'{test_data['contract_id']}'",
'dataContractId': "'EETVvWgohFDKtbB3ejEzBcDRMNYkc9TtgXY6y8hzP3Ta'" if 'getTokenContractInfo' in query_key else f"'{test_data['data_contract_id']}'",
'publicKeyHash': f"'{test_data['public_key_hash_unique']}'" if 'ByPublicKeyHash' in query_key and 'NonUnique' not in query_key else f"'{test_data['public_key_hash_non_unique']}'",
'startProTxHash': f"'{test_data['pro_tx_hash']}'",
'tokenId': "'EETVvWgohFDKtbB3ejEzBcDRMNYkc9TtgXY6y8hzP3Ta'" if 'getTokenPerpetualDistributionLastClaim' in query_key else f"'{test_data['token_id']}'",
'tokenId': "'HEv1AYWQfwCffXQgmuzmzyzUo9untRTmVr67n4e4PSWa'" if 'getTokenPerpetualDistributionLastClaim' in query_key else f"'{test_data['token_id']}'",
'tokenIds': f"['{test_data['token_id']}', 'H7FRpZJqZK933r9CzZMsCuf1BM34NT5P2wSJyjDkprqy']" if 'getTokenStatuses' in query_key else "['H7FRpZJqZK933r9CzZMsCuf1BM34NT5P2wSJyjDkprqy']" if 'getTokenDirectPurchasePrices' in query_key else f"['{test_data['token_id']}']",
'documentType': f"'{test_data['document_type']}'",
'documentId': f"'{test_data['document_id']}'",
Expand Down Expand Up @@ -206,6 +206,10 @@ def generate_example_code(query_key, inputs):
elif query_key == 'getGroupActions':
# getGroupActions expects: sdk, contractId, groupContractPosition, status, startAtInfo (object or null), count
params = [f"'{test_data['group_contract_id']}'", "0", "'ACTIVE'", "null", "100"]
elif query_key == 'getDataContractHistory':
# getDataContractHistory expects: sdk, id, limit, offset, startAtMs
# Use the specific contract ID requested by the user
params = ["'HLY575cNazmc5824FxqaEMEBuzFeE4a98GDRNKbyJqCM'", "10", "0"]
else:
# Generate parameters normally
params = []
Expand Down Expand Up @@ -399,17 +403,30 @@ def generate_operation_entry(operation_key, operation, type_prefix):
html_content += ' <p class="info-note">This is an internal query used to wait for and retrieve the result of a previously submitted state transition. It requires a valid state transition hash from a prior operation.</p>'
else:
html_content += f' <button class="run-button" id="run-{operation_key}" onclick="runExample(\'{operation_key}\')">Run</button>'
if operation_key in ['getPathElements', 'getDataContractHistory', 'getContestedResourceVotersForIdentity', 'getTokenPerpetualDistributionLastClaim']:
if operation_key in ['getPathElements', 'getContestedResourceVotersForIdentity', 'getTokenPerpetualDistributionLastClaim']:
html_content += ' <span style="color: #f39c12; margin-left: 10px;">🚧 Work in Progress</span>'

# Add special examples and info
if operation_key == 'getIdentityKeys':
html_content += '''\n <div class="example-container">
<h5>Example 2 - Get Specific Keys</h5>
<div class="example-code" id="code-getIdentityKeys2">return await window.wasmFunctions.get_identity_keys(sdk, \'5DbLwAxGBzUzo81VewMUwn4b5P4bpv9FNFybi25XB5Bk\', \'specific\', [0, 1, 2]);</div>
<button class="run-button" id="run-getIdentityKeys2" onclick="runExample(\'getIdentityKeys2\')">Run</button>
<div class="example-result" id="result-getIdentityKeys2"></div>
</div>'''
html_content += f'''
<div class="example-result" id="result-{operation_key}"></div>
</div>

<div class="example-container">
<h5>Example 2 - Get Specific Keys</h5>
<div class="example-code" id="code-getIdentityKeys2">return await window.wasmFunctions.get_identity_keys(sdk, \'5DbLwAxGBzUzo81VewMUwn4b5P4bpv9FNFybi25XB5Bk\', \'specific\', [0, 1, 2]);</div>
<button class="run-button" id="run-getIdentityKeys2" onclick="runExample(\'getIdentityKeys2\')">Run</button>
<div class="example-result" id="result-getIdentityKeys2"></div>
</div>

<div class="example-container">
<h5>Example 3 - Search Keys by Purpose</h5>
<div class="example-code" id="code-getIdentityKeys3">return await window.wasmFunctions.get_identity_keys(sdk, \'5DbLwAxGBzUzo81VewMUwn4b5P4bpv9FNFybi25XB5Bk\', \'search\', undefined, \'{{"0": {{"0": "current"}}, "1": {{"0": "current"}}}}\');</div>
<button class="run-button" id="run-getIdentityKeys3" onclick="runExample(\'getIdentityKeys3\')">Run</button>
<div class="example-result" id="result-getIdentityKeys3"></div>
</div>
</div>'''
return html_content
elif operation_key == 'getPathElements':
html_content += generate_path_elements_info()

Expand Down
16 changes: 14 additions & 2 deletions packages/wasm-sdk/src/context_provider.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -45,9 +45,21 @@ impl ContextProvider for WasmContext {

fn get_token_configuration(
&self,
_token_id: &Identifier,
token_id: &Identifier,
) -> Result<Option<TokenConfiguration>, ContextProviderError> {
// Return None for now - this means the token config will be fetched from the network
// For WASM context without trusted provider, we need to fetch token configuration
// from the network. This is a simplified implementation that would need to be
// enhanced with actual network fetching logic in a production environment.

// TODO: Implement actual token configuration fetching from network
// For now, we'll return None which will cause the proof verification to fail
// with a clearer error message indicating missing token configuration

tracing::warn!(
token_id = %token_id,
"Token configuration not available in WASM context - this will cause proof verification to fail. Use trusted context builders for proof verification."
);

Ok(None)
}

Expand Down
6 changes: 3 additions & 3 deletions packages/wasm-sdk/src/queries/data_contract.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -59,7 +59,7 @@ pub async fn data_contract_fetch_with_proof_info(
#[derive(Serialize, Deserialize, Debug)]
#[serde(rename_all = "camelCase")]
struct DataContractHistoryResponse {
versions: BTreeMap<u64, serde_json::Value>,
versions: BTreeMap<String, serde_json::Value>,
}

#[wasm_bindgen]
Expand Down Expand Up @@ -94,7 +94,7 @@ pub async fn get_data_contract_history(

if let Some(history) = history_result {
for (revision, contract) in history {
versions.insert(revision, contract.to_json(platform_version)?);
versions.insert(revision.to_string(), contract.to_json(platform_version)?);
}
}

Expand Down Expand Up @@ -183,7 +183,7 @@ pub async fn get_data_contract_history_with_proof_info(

if let Some(history) = history_result {
for (revision, contract) in history {
versions.insert(revision, contract.to_json(platform_version)?);
versions.insert(revision.to_string(), contract.to_json(platform_version)?);
}
}

Expand Down
12 changes: 6 additions & 6 deletions packages/wasm-sdk/src/queries/identity.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -157,9 +157,9 @@ pub async fn get_identity_keys(
let request = GetIdentityKeysRequest {
version: Some(Version::V0(GetIdentityKeysRequestV0 {
identity_id: id.to_vec(),
prove: true,
limit: limit.map(|l| l.into()),
offset: offset.map(|o| o.into()),
prove: false,
limit: Some(limit.unwrap_or(100).into()), // Always provide a limit when prove=false
offset: None, // Offsets not supported when prove=false
request_type: Some(KeyRequestType {
request: Some(Request::SpecificKeys(SpecificKeys {
key_ids,
Expand Down Expand Up @@ -254,9 +254,9 @@ pub async fn get_identity_keys(
let request = GetIdentityKeysRequest {
version: Some(Version::V0(GetIdentityKeysRequestV0 {
identity_id: id.to_vec(),
prove: true,
limit: limit.map(|l| l.into()),
offset: offset.map(|o| o.into()),
prove: false,
limit: Some(limit.unwrap_or(100).into()), // Always provide a limit when prove=false
offset: None, // Offsets not supported when prove=false
request_type: Some(KeyRequestType {
request: Some(Request::SearchKey(SearchKey {
purpose_map,
Expand Down
Loading
Loading