Skip to content

feat(wasm-sdk): implement four missing token transitions #2728

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 3 commits into from
Aug 19, 2025
Merged

feat(wasm-sdk): implement four missing token transitions #2728

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
8164265
feat(wasm-sdk): implement four missing token transitions
pauldelucia Aug 18, 2025
a1ee9cf
feat: add tests for new token transitions
pauldelucia Aug 18, 2025
b8a7ba5
fix(sdk): fix generate docs (#2730)
thephez Aug 19, 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
50 changes: 30 additions & 20 deletions packages/wasm-sdk/AI_REFERENCE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -758,9 +758,12 @@ const result = await sdk.{transition_name}(identityHex, ...params, privateKeyHex
*Create a new identity with initial credits*

Parameters:
- `assetLockProof` (string, required) - Asset lock proof (hex-encoded JSON)
- `assetLockProofPrivateKey` (string, required) - Private key for the asset lock proof (WIF format)
- `publicKeys` (string, required) - JSON array of public keys to add to the identity
- `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
Expand Down Expand Up @@ -795,15 +798,18 @@ const result = await sdk.identityCreate(assetLockProof, assetLockProofPrivateKey
*Add credits to an existing identity*

Parameters:
- `identityId` (string, required) - The identity ID to top up (base58 format)
- `assetLockProof` (string, required) - Asset lock proof (hex-encoded JSON)
- `assetLockProofPrivateKey` (string, required) - Private key for the asset lock proof (WIF format)
- `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 identityId = "5DbLwAxGBzUzo81VewMUwn4b5P4bpv9FNFybi25XB5Bk"; // base58
const assetLockProof = "a9147d3b... (hex-encoded)";
const assetLockProofPrivateKey = "XFfpaSbZq52HPy3WWwe1dXsZMiU1bQn8vQd34HNXkSZThevBWRn1"; // WIF format
const assetLockProofPrivateKey = "XFfpaSbZq52HPy3WWve1dXsZMiU1bQn8vQd34HNXkSZThevBWRn1"; // WIF format

Comment on lines +812 to 813
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue

Replace realistic-looking WIF with obvious placeholder

This sample key trips secret scanners (Gitleaks flagged it). Use a clearly fake placeholder to avoid CI noise and security confusion.

-const assetLockProofPrivateKey = "XFfpaSbZq52HPy3WWve1dXsZMiU1bQn8vQd34HNXkSZThevBWRn1"; // WIF format
+const assetLockProofPrivateKey = "WIF_PRIVATE_KEY_EXAMPLE"; // WIF format (example)
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
const assetLockProofPrivateKey = "XFfpaSbZq52HPy3WWve1dXsZMiU1bQn8vQd34HNXkSZThevBWRn1"; // WIF format
const assetLockProofPrivateKey = "WIF_PRIVATE_KEY_EXAMPLE"; // WIF format (example)
🧰 Tools
🪛 Gitleaks (8.27.2)

812-812: Detected a Generic API Key, potentially exposing access to various services and sensitive operations.

(generic-api-key)

🤖 Prompt for AI Agents 
In packages/wasm-sdk/AI_REFERENCE.md around lines 812 to 813, the example uses a
realistic-looking WIF private key which triggers secret scanners; replace the
current value with an obvious non-secret placeholder string (e.g.
REPLACE_WITH_WIF_PRIVATE_KEY or <WIF_PRIVATE_KEY_PLACEHOLDER>) and add a short
inline note that it is a dummy value to prevent CI secret detections.

const result = await sdk.identityTopUp(identityId, assetLockProof, assetLockProofPrivateKey);
```
Expand All @@ -813,7 +819,7 @@ const result = await sdk.identityTopUp(identityId, assetLockProof, assetLockProo

Parameters (in addition to identity/key):
- `addPublicKeys` (textarea, optional) - Keys to Add (JSON array)
- Example: `[{"type":0,"purpose":0,"securityLevel":2,"data":"base64_encoded_public_key","readOnly":false}]`
- Example: `[{"keyType":"ECDSA_HASH160","purpose":"AUTHENTICATION","data":"base64_key_data"}]`
- `disablePublicKeys` (text, optional) - Key IDs to Disable (comma-separated)
- Example: `2,3,5`

Expand Down Expand Up @@ -1114,13 +1120,14 @@ const result = await sdk.tokenConfigUpdate(identityHex, /* params */, privateKey
```

**Token Transfer** - `tokenTransfer`
*Transfer tokens to another identity*
*Transfer tokens between identities*

Parameters (in addition to identity/key):
- `contractId` (text, required) - Data Contract ID
- `tokenId` (text, required) - Token Contract Position
- `amount` (number, required) - Amount to Transfer
- `tokenPosition` (number, required) - Token Contract Position
- `amount` (text, required) - Amount to Transfer
- `recipientId` (text, required) - Recipient Identity ID
- `publicNote` (text, optional) - Public Note

Comment on lines +1123 to 1131
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue

Token Transfer params are correct; fix the example below (uses old tokenId and method name)

The parameter table shows tokenPosition and publicNote, but the example still uses token_transfer and tokenId. Update the example to match the exported JS name and parameters.

Apply this diff:

-```javascript
-const result = await sdk.token_transfer(
-    identityHex,
-    contractId,
-    tokenId,
-    1000000, // amount
-    recipientId,
-    privateKeyHex
-);
-```
+```javascript
+const result = await sdk.tokenTransfer(
+  contractId,          // data contract ID (base58)
+  tokenPosition,       // number
+  "1000000",           // amount as text
+  identityHex,         // sender identity (auth)
+  recipientId,         // recipient identity (base58)
+  privateKeyHex,       // signing key
+  /* publicNote? */     // optional
+);
+```
🤖 Prompt for AI Agents 
packages/wasm-sdk/AI_REFERENCE.md around lines 1091-1099: the example uses the
old token_transfer name and tokenId param but the docs list tokenPosition and
publicNote; update the example to call sdk.tokenTransfer with the new parameter
order: contractId, tokenPosition (number), amount as a string, identityHex
(sender auth), recipientId, privateKeyHex (signing key), and optionally
publicNote; replace the old snippet entirely with a JavaScript fenced example
reflecting these arguments and types.

Example:
```javascript
Expand All @@ -1135,38 +1142,41 @@ const result = await sdk.token_transfer(
```

**Token Freeze** - `tokenFreeze`
*Freeze tokens for an identity*
*Freeze tokens for a specific identity*

Parameters (in addition to identity/key):
- `contractId` (text, required) - Data Contract ID
- `tokenId` (text, required) - Token Contract Position
- `identityId` (text, required) - Identity ID to Freeze
- `tokenPosition` (number, required) - Token Contract Position
- `identityToFreeze` (text, required) - Identity ID to Freeze
- `publicNote` (text, optional) - Public Note

Example:
```javascript
const result = await sdk.tokenFreeze(identityHex, /* params */, privateKeyHex);
```

**Token Unfreeze** - `tokenUnfreeze`
*Unfreeze tokens for an identity*
*Unfreeze tokens for a specific identity*

Parameters (in addition to identity/key):
- `contractId` (text, required) - Data Contract ID
- `tokenId` (text, required) - Token Contract Position
- `identityId` (text, required) - Identity ID to Unfreeze
- `tokenPosition` (number, required) - Token Contract Position
- `identityToUnfreeze` (text, required) - Identity ID to Unfreeze
- `publicNote` (text, optional) - Public Note

Example:
```javascript
const result = await sdk.tokenUnfreeze(identityHex, /* params */, privateKeyHex);
```

**Token Destroy Frozen Funds** - `tokenDestroyFrozen`
**Token Destroy Frozen** - `tokenDestroyFrozen`
*Destroy frozen tokens*

Parameters (in addition to identity/key):
- `contractId` (text, required) - Data Contract ID
- `tokenId` (text, required) - Token Contract Position
- `identityId` (text, required) - Identity ID
- `tokenPosition` (number, required) - Token Contract Position
- `identityId` (text, required) - Identity ID whose frozen tokens to destroy
- `publicNote` (text, optional) - Public Note

Example:
```javascript
Expand Down
108 changes: 90 additions & 18 deletions packages/wasm-sdk/api-definitions.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand All @@ -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);"
},
Comment on lines +1278 to 1301
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue

Mask realistic-looking WIF in sdk_example to appease scanners

Replace the sample WIF with an obvious placeholder to prevent false positives.

-const assetLockProofPrivateKey = "XFfpaSbZq52HPy3WWve1dXsZMiU1bQn8vQd34HNXkSZThevBWRn1"; // WIF format
+const assetLockProofPrivateKey = "WIF_PRIVATE_KEY_EXAMPLE"; // WIF format (example)
🤖 Prompt for AI Agents 
In packages/wasm-sdk/api-definitions.json around lines 1278 to 1301, the
sdk_example contains a realistic-looking WIF sample which can trigger secret
scanners; replace that concrete WIF string with an obvious placeholder (e.g.
"WIF_PRIVATE_KEY" or "WIF_PLACEHOLDER") so the example remains clear but cannot
be mistaken for a real secret, and update any surrounding inline comment to
indicate it is a placeholder.

"identityUpdate": {
"label": "Identity Update",
Expand Down Expand Up @@ -1915,7 +1963,7 @@
},
"tokenTransfer": {
"label": "Token Transfer",
"description": "Transfer tokens to another identity",
"description": "Transfer tokens between identities",
"inputs": [
{
"name": "contractId",
Expand All @@ -1924,14 +1972,14 @@
"required": true
},
{
"name": "tokenId",
"type": "text",
"name": "tokenPosition",
"type": "number",
"label": "Token Contract Position",
"required": true
},
{
"name": "amount",
"type": "number",
"type": "text",
"label": "Amount to Transfer",
"required": true
},
Expand All @@ -1940,12 +1988,18 @@
"type": "text",
"label": "Recipient Identity ID",
"required": true
},
{
"name": "publicNote",
"type": "text",
"label": "Public Note",
"required": false
}
]
},
"tokenFreeze": {
"label": "Token Freeze",
"description": "Freeze tokens for an identity",
"description": "Freeze tokens for a specific identity",
"inputs": [
{
"name": "contractId",
Expand All @@ -1954,22 +2008,28 @@
"required": true
},
{
"name": "tokenId",
"type": "text",
"name": "tokenPosition",
"type": "number",
"label": "Token Contract Position",
"required": true
},
{
"name": "identityId",
"name": "identityToFreeze",
"type": "text",
"label": "Identity ID to Freeze",
"required": true
},
{
"name": "publicNote",
"type": "text",
"label": "Public Note",
"required": false
}
]
},
"tokenUnfreeze": {
"label": "Token Unfreeze",
"description": "Unfreeze tokens for an identity",
"description": "Unfreeze tokens for a specific identity",
"inputs": [
{
"name": "contractId",
Expand All @@ -1978,21 +2038,27 @@
"required": true
},
{
"name": "tokenId",
"type": "text",
"name": "tokenPosition",
"type": "number",
"label": "Token Contract Position",
"required": true
},
{
"name": "identityId",
"name": "identityToUnfreeze",
"type": "text",
"label": "Identity ID to Unfreeze",
"required": true
},
{
"name": "publicNote",
"type": "text",
"label": "Public Note",
"required": false
}
]
},
"tokenDestroyFrozen": {
"label": "Token Destroy Frozen Funds",
"label": "Token Destroy Frozen",
"description": "Destroy frozen tokens",
"inputs": [
{
Expand All @@ -2002,16 +2068,22 @@
"required": true
},
{
"name": "tokenId",
"type": "text",
"name": "tokenPosition",
"type": "number",
"label": "Token Contract Position",
"required": true
},
{
"name": "identityId",
"type": "text",
"label": "Identity ID",
"label": "Identity ID whose frozen tokens to destroy",
"required": true
},
{
"name": "publicNote",
"type": "text",
"label": "Public Note",
"required": false
}
]
}
Expand Down
2 changes: 2 additions & 0 deletions packages/wasm-sdk/docs.css
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -270,6 +270,8 @@ h3 {
font-size: 0.9em;
margin-bottom: 10px;
position: relative;
white-space: pre-wrap;
overflow-x: auto;
}

.run-button {
Expand Down
Loading
Loading