dash-platform-sdk 1.5.0-dev.3 → 1.5.0-dev.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dash-platform-sdk",
-  "version": "1.5.0-dev.3",
+  "version": "1.5.0-dev.5",
   "main": "index.js",
   "description": "Lightweight SDK for accessing Dash Platform blockchain",
   "repository": {

package/src/keyPair/index.d.ts

@@ -1,6 +1,6 @@
 import { HDKey } from '@scure/bip32';
 import { Network } from '../../types.js';
-import { OrchardAddressWASM } from 'pshenmic-dpp';
+import { OrchardAddressWASM, PlatformAddressWASM, PrivateKeyWASM } from 'pshenmic-dpp';
 /**
  * Collection of functions to work with private keys and seed phrases
  *
@@ -65,6 +65,16 @@ export declare class KeyPairController {
      * @returns {string}
      */
     p2pkhAddress(publicKey: Uint8Array, network: Network): string;
+    /**
+     * Converts a public key to a transparent platform P2PKH address (DIP-18):
+     * the canonical `variantByte || Hash160(pubkey)` PlatformAddress.
+     *
+     * @param publicKey {Uint8Array}
+     * @param network {Network}
+     *
+     * @returns {PlatformAddressWASM}
+     */
+    platformAddress(publicKey: Uint8Array, network: Network): PlatformAddressWASM;
     /**
      * Derives a shielded (Orchard) address from a BIP-39 seed via ZIP-32
      * (m/32'/coinType'/account').
@@ -89,4 +99,56 @@ export declare class KeyPairController {
      * @returns {Uint8Array} 32-byte outgoing viewing key
      */
     deriveShieldedOutgoingViewingKey(seed: Uint8Array, network: Network, account: number): Uint8Array;
+    /**
+     * Derives the DIP-17 account-level extended public key (xpub) for the
+     * clear-funds key class: m/9'/coinType'/17'/account'/0'. The seed is only
+     * needed once per account — the returned xpub derives every address index
+     * publicly (see {@link derivePlatformAddressFromXpub}), with no further access
+     * to the seed.
+     *
+     * @param seed {Uint8Array} - BIP-39 seed bytes
+     * @param network {Network} - network (selects the SLIP-44 coin type)
+     * @param account {number} - DIP-17 account index
+     *
+     * @returns {Promise<string>} account-level extended public key
+     */
+    derivePlatformAccountXpub(seed: Uint8Array, network: Network, account: number): Promise<string>;
+    /**
+     * Derives a transparent platform P2PKH address from a BIP-39 seed via DIP-17
+     * (m/9'/coinType'/17'/account'/0'/index).
+     *
+     * @param seed {Uint8Array} - BIP-39 seed bytes
+     * @param network {Network} - network (selects the SLIP-44 coin type)
+     * @param account {number} - DIP-17 account index
+     * @param index {number} - address index
+     *
+     * @returns {Promise<PlatformAddressWASM>}
+     */
+    derivePlatformAddress(seed: Uint8Array, network: Network, account: number, index: number): Promise<PlatformAddressWASM>;
+    /**
+     * Derives a transparent platform P2PKH address from an account-level xpub (see
+     * {@link derivePlatformAccountXpub}). The address index is non-hardened, so
+     * public-only derivation reproduces the exact same address as the seed-based
+     * path — no seed required.
+     *
+     * @param xpub {string} - account-level extended public key
+     * @param network {Network} - network (selects the extended-key version bytes)
+     * @param index {number} - address index
+     *
+     * @returns {PlatformAddressWASM}
+     */
+    derivePlatformAddressFromXpub(xpub: string, network: Network, index: number): PlatformAddressWASM;
+    /**
+     * Derives the private key for a DIP-17 platform address by its index
+     * (m/9'/coinType'/17'/account'/0'/index). Used to sign a transfer that spends
+     * from that address.
+     *
+     * @param seed {Uint8Array} - BIP-39 seed bytes
+     * @param network {Network} - network (selects the SLIP-44 coin type)
+     * @param account {number} - DIP-17 account index
+     * @param index {number} - address index
+     *
+     * @returns {Promise<PrivateKeyWASM>}
+     */
+    derivePlatformAddressPrivateKey(seed: Uint8Array, network: Network, account: number, index: number): Promise<PrivateKeyWASM>;
 }

package/src/keyPair/index.js

@@ -3,7 +3,7 @@ import mnemonicToSeed from './mnemonicToSeed.js';
 import deriveChild from './deriveChild.js';
 import derivePath from './derivePath.js';
 import { p2pkh } from '@scure/btc-signer';
-import { OrchardAddressWASM, orchardOvkFromSeed } from 'pshenmic-dpp';
+import { OrchardAddressWASM, orchardOvkFromSeed, PlatformAddressWASM, PrivateKeyWASM } from 'pshenmic-dpp';
 const DASH_VERSIONS = {
     mainnet: { pubKeyHash: 0x4c, scriptHash: 0x10, bech32: 'dc', wif: 0xcc, private: 0x0488ade4, public: 0x0488b21e },
     testnet: { pubKeyHash: 0x8c, scriptHash: 0x13, bech32: 'dc', wif: 0xef, private: 0x04358394, public: 0x043587cf }
@@ -87,6 +87,20 @@ export class KeyPairController {
         const P2PKH = p2pkh(publicKey, DASH_VERSIONS[network]);
         return P2PKH.address;
     }
+    /**
+     * Converts a public key to a transparent platform P2PKH address (DIP-18):
+     * the canonical `variantByte || Hash160(pubkey)` PlatformAddress.
+     *
+     * @param publicKey {Uint8Array}
+     * @param network {Network}
+     *
+     * @returns {PlatformAddressWASM}
+     */
+    platformAddress(publicKey, network) {
+        const { hash } = p2pkh(publicKey, DASH_VERSIONS[network]);
+        // variant byte 0x00 = P2PKH
+        return PlatformAddressWASM.fromBytes(Uint8Array.from([0x00, ...hash]));
+    }
     /**
      * Derives a shielded (Orchard) address from a BIP-39 seed via ZIP-32
      * (m/32'/coinType'/account').
@@ -119,4 +133,85 @@ export class KeyPairController {
         const coinType = network === 'mainnet' ? 5 : 1;
         return orchardOvkFromSeed(seed, coinType, account);
     }
+    /**
+     * Derives the DIP-17 account-level extended public key (xpub) for the
+     * clear-funds key class: m/9'/coinType'/17'/account'/0'. The seed is only
+     * needed once per account — the returned xpub derives every address index
+     * publicly (see {@link derivePlatformAddressFromXpub}), with no further access
+     * to the seed.
+     *
+     * @param seed {Uint8Array} - BIP-39 seed bytes
+     * @param network {Network} - network (selects the SLIP-44 coin type)
+     * @param account {number} - DIP-17 account index
+     *
+     * @returns {Promise<string>} account-level extended public key
+     */
+    async derivePlatformAccountXpub(seed, network, account) {
+        const coinType = network === 'mainnet' ? 5 : 1;
+        const hdKey = this.seedToHdKey(seed, network);
+        const accountNode = await this.derivePath(hdKey, `m/9'/${coinType}'/17'/${account}'/0'`);
+        return accountNode.publicExtendedKey;
+    }
+    /**
+     * Derives a transparent platform P2PKH address from a BIP-39 seed via DIP-17
+     * (m/9'/coinType'/17'/account'/0'/index).
+     *
+     * @param seed {Uint8Array} - BIP-39 seed bytes
+     * @param network {Network} - network (selects the SLIP-44 coin type)
+     * @param account {number} - DIP-17 account index
+     * @param index {number} - address index
+     *
+     * @returns {Promise<PlatformAddressWASM>}
+     */
+    async derivePlatformAddress(seed, network, account, index) {
+        const coinType = network === 'mainnet' ? 5 : 1;
+        const hdKey = this.seedToHdKey(seed, network);
+        const childNode = await this.derivePath(hdKey, `m/9'/${coinType}'/17'/${account}'/0'/${index}`);
+        if (childNode.publicKey == null) {
+            throw new Error(`Could not derive platform address public key at index ${index}`);
+        }
+        return this.platformAddress(childNode.publicKey, network);
+    }
+    /**
+     * Derives a transparent platform P2PKH address from an account-level xpub (see
+     * {@link derivePlatformAccountXpub}). The address index is non-hardened, so
+     * public-only derivation reproduces the exact same address as the seed-based
+     * path — no seed required.
+     *
+     * @param xpub {string} - account-level extended public key
+     * @param network {Network} - network (selects the extended-key version bytes)
+     * @param index {number} - address index
+     *
+     * @returns {PlatformAddressWASM}
+     */
+    derivePlatformAddressFromXpub(xpub, network, index) {
+        const accountNode = HDKey.fromExtendedKey(xpub, DASH_VERSIONS[network]);
+        const childNode = accountNode.deriveChild(index);
+        if (childNode.publicKey == null) {
+            throw new Error(`Could not derive platform address public key at index ${index}`);
+        }
+        return this.platformAddress(childNode.publicKey, network);
+    }
+    /**
+     * Derives the private key for a DIP-17 platform address by its index
+     * (m/9'/coinType'/17'/account'/0'/index). Used to sign a transfer that spends
+     * from that address.
+     *
+     * @param seed {Uint8Array} - BIP-39 seed bytes
+     * @param network {Network} - network (selects the SLIP-44 coin type)
+     * @param account {number} - DIP-17 account index
+     * @param index {number} - address index
+     *
+     * @returns {Promise<PrivateKeyWASM>}
+     */
+    async derivePlatformAddressPrivateKey(seed, network, account, index) {
+        const coinType = network === 'mainnet' ? 5 : 1;
+        const hdKey = this.seedToHdKey(seed, network);
+        const path = `m/9'/${coinType}'/17'/${account}'/0'/${index}`;
+        const { privateKey } = await this.derivePath(hdKey, path);
+        if (privateKey == null) {
+            throw new Error(`Could not derive platform address key at ${path}`);
+        }
+        return PrivateKeyWASM.fromBytes(privateKey, network);
+    }
 }

package/src/platformAddresses/createStateTransition.d.ts

@@ -0,0 +1,12 @@
+import { StateTransitionWASM } from 'pshenmic-dpp';
+import { PlatformAddressTransitionParamsMap, PlatformAddressTransitionType } from '../../types.js';
+/**
+ * Helper function that assembles a {StateTransitionWASM} for Platform Address transitions
+ * out of already-built params. The builder is pure: it does not sign, broadcast or
+ * mutate the passed params. Producing witnesses / signatures stays the caller's
+ * responsibility (they are passed in via the `inputWitness` / `signature` params).
+ *
+ * @param type {string} type of transition
+ * @param params {PlatformAddressTransitionParamsMap[K]} params required by that transition type
+ */
+export default function createStateTransition<K extends PlatformAddressTransitionType>(type: K, params: PlatformAddressTransitionParamsMap[K]): StateTransitionWASM;

package/src/platformAddresses/createStateTransition.js

@@ -0,0 +1,62 @@
+import { IdentityCreditTransferToAddressesTransitionWASM, IdentityCreateFromAddressesTransitionWASM, IdentityTopUpFromAddressesTransitionWASM, AddressFundsTransferTransitionWASM, AddressFundingFromAssetLockTransitionWASM, AddressCreditWithdrawalTransitionWASM } from 'pshenmic-dpp';
+const platformAddressTransitionsMap = {
+    identityCreditTransferToAddresses: {
+        class: IdentityCreditTransferToAddressesTransitionWASM,
+        arguments: ['identityId', 'recipients', 'nonce', 'userFeeIncrease'],
+        optionalArguments: ['userFeeIncrease']
+    },
+    identityCreateFromAddresses: {
+        class: IdentityCreateFromAddressesTransitionWASM,
+        arguments: ['publicKeys', 'inputs', 'feeStrategy', 'userFeeIncrease', 'inputWitness', 'output'],
+        optionalArguments: ['userFeeIncrease', 'output']
+    },
+    identityTopUpFromAddresses: {
+        class: IdentityTopUpFromAddressesTransitionWASM,
+        arguments: ['identityId', 'inputs', 'feeStrategy', 'userFeeIncrease', 'inputWitness', 'output'],
+        optionalArguments: ['userFeeIncrease', 'output']
+    },
+    addressFundsTransfer: {
+        class: AddressFundsTransferTransitionWASM,
+        arguments: ['inputs', 'feeStrategy', 'userFeeIncrease', 'inputWitness', 'outputs'],
+        optionalArguments: ['userFeeIncrease']
+    },
+    addressFundingFromAssetLock: {
+        class: AddressFundingFromAssetLockTransitionWASM,
+        arguments: ['assetLockProof', 'inputs', 'feeStrategy', 'userFeeIncrease', 'inputWitness', 'outputs'],
+        optionalArguments: ['userFeeIncrease']
+    },
+    addressCreditWithdrawal: {
+        class: AddressCreditWithdrawalTransitionWASM,
+        arguments: ['inputs', 'feeStrategy', 'coreFeePerByte', 'pooling', 'outputScript', 'userFeeIncrease', 'inputWitness', 'output'],
+        optionalArguments: ['userFeeIncrease', 'output']
+    }
+};
+/**
+ * Helper function that assembles a {StateTransitionWASM} for Platform Address transitions
+ * out of already-built params. The builder is pure: it does not sign, broadcast or
+ * mutate the passed params. Producing witnesses / signatures stays the caller's
+ * responsibility (they are passed in via the `inputWitness` / `signature` params).
+ *
+ * @param type {string} type of transition
+ * @param params {PlatformAddressTransitionParamsMap[K]} params required by that transition type
+ */
+export default function createStateTransition(type, params) {
+    const { class: TransitionClass, arguments: classArguments, optionalArguments } = platformAddressTransitionsMap[type] ?? {};
+    if (TransitionClass == null) {
+        throw new Error(`Unimplemented transition type: ${type}`);
+    }
+    const [missingArgument] = classArguments
+        .filter((classArgument) => params[classArgument] == null &&
+        !optionalArguments.includes(classArgument));
+    if (missingArgument != null) {
+        throw new Error(`Platform address transition param "${missingArgument}" is missing`);
+    }
+    // userFeeIncrease is a required positional `number` in every WASM constructor,
+    // so coerce a missing value to 0 to keep the positional order intact.
+    const transitionParams = classArguments.map((classArgument) => classArgument === 'userFeeIncrease'
+        ? (params[classArgument] ?? 0)
+        : params[classArgument]);
+    // @ts-expect-error
+    const platformAddressTransition = new TransitionClass(...transitionParams);
+    return platformAddressTransition.toStateTransition();
+}

package/src/platformAddresses/index.d.ts

@@ -1,6 +1,6 @@
 import GRPCConnectionPool from '../grpcConnectionPool.js';
-import { PlatformAddressLike } from 'pshenmic-dpp';
-import { PlatformAddressInfo } from '../../types.js';
+import { PlatformAddressLike, StateTransitionWASM } from 'pshenmic-dpp';
+import { PlatformAddressInfo, PlatformAddressTransitionParamsMap, PlatformAddressTransitionType } from '../../types.js';
 export declare class PlatformAddressesController {
     /** @ignore **/
     grpcPool: GRPCConnectionPool;
@@ -19,4 +19,22 @@ export declare class PlatformAddressesController {
      * @return {Promise<PlatformAddressInfo[]>}
      */
     getAddressesInfos(addresses: PlatformAddressLike[]): Promise<PlatformAddressInfo[]>;
+    /**
+     * Helper function for creating {StateTransitionWASM} for Platform Address transitions
+     *
+     * Unlike identity transitions (which are signed after construction), address transitions carry
+     * their signature material as constructor input (the `inputWitness` param, and a `signature`
+     * setter on the asset-lock variant), so this builder is pure and only assembles the transition
+     * from already-built params - producing witnesses stays the caller's responsibility.
+     *
+     * Please refer to PlatformAddress.spec.ts or README for example commands
+     *
+     * @param type {string} type of transition, must be a one of ('identityCreditTransferToAddresses' |
+     * 'identityCreateFromAddresses' | 'identityTopUpFromAddresses' | 'addressFundsTransfer' |
+     * 'addressFundingFromAssetLock' | 'addressCreditWithdrawal')
+     * @param params {PlatformAddressTransitionParamsMap[K]} params required by that transition type
+     *
+     * @return {StateTransitionWASM}
+     */
+    createStateTransition<K extends PlatformAddressTransitionType>(type: K, params: PlatformAddressTransitionParamsMap[K]): StateTransitionWASM;
 }

package/src/platformAddresses/index.js

@@ -1,5 +1,6 @@
 import { getAddressInfo } from './getAddressInfo.js';
 import { getAddressesInfos } from './getAddressesInfos.js';
+import createStateTransition from './createStateTransition.js';
 export class PlatformAddressesController {
     /** @ignore **/
     grpcPool;
@@ -24,4 +25,24 @@ export class PlatformAddressesController {
     async getAddressesInfos(addresses) {
         return await getAddressesInfos(this.grpcPool, addresses);
     }
+    /**
+     * Helper function for creating {StateTransitionWASM} for Platform Address transitions
+     *
+     * Unlike identity transitions (which are signed after construction), address transitions carry
+     * their signature material as constructor input (the `inputWitness` param, and a `signature`
+     * setter on the asset-lock variant), so this builder is pure and only assembles the transition
+     * from already-built params - producing witnesses stays the caller's responsibility.
+     *
+     * Please refer to PlatformAddress.spec.ts or README for example commands
+     *
+     * @param type {string} type of transition, must be a one of ('identityCreditTransferToAddresses' |
+     * 'identityCreateFromAddresses' | 'identityTopUpFromAddresses' | 'addressFundsTransfer' |
+     * 'addressFundingFromAssetLock' | 'addressCreditWithdrawal')
+     * @param params {PlatformAddressTransitionParamsMap[K]} params required by that transition type
+     *
+     * @return {StateTransitionWASM}
+     */
+    createStateTransition(type, params) {
+        return createStateTransition(type, params);
+    }
 }

package/test/unit/KeyPair.spec.js

@@ -1,4 +1,4 @@
-import { OrchardAddressWASM } from 'pshenmic-dpp';
+import { OrchardAddressWASM, PlatformAddressWASM } from 'pshenmic-dpp';
 import { DashPlatformSDK } from '../../src/DashPlatformSDK.js';
 let sdk;
 let mnemonic;
@@ -63,4 +63,52 @@ describe('KeyPair', () => {
             expect(ovk).toEqual(sdk.keyPair.deriveShieldedOutgoingViewingKey(seed, 'testnet', account));
         });
     });
+    describe('platform addresses', () => {
+        const account = 0;
+        // Reference values produced by the dash-platform-extension derivation utils
+        // (proven byte-identical to on-chain / desktop-wallet addresses) for the
+        // fixed mnemonic above, testnet, account 0.
+        const expectedXpub = 'tpubDH6WaqMU1YHJMbPG413my6Dx5DwnsuuL6EzbetEZQac6ixmkByzCGgiibue3HQmHX5JGVUm2fBHKGttJpVkx3NrK5Em9br8GyLd1fVGm7ud';
+        const expectedAddresses = [
+            'tdash1kr0xt5wj85ht5u464rfysjrq75rewz9mysjwf59p',
+            'tdash1kqgy7ngm2wf0zsv20k4mc62s5rapw26yeg6em4jq',
+            'tdash1kzlatzl0u06uxrqz8hkc7naz9d2g3v8g7gw83ew3'
+        ];
+        test('derives the DIP-17 account xpub matching the reference', async () => {
+            const seed = sdk.keyPair.mnemonicToSeed(mnemonic);
+            const xpub = await sdk.keyPair.derivePlatformAccountXpub(seed, 'testnet', account);
+            expect(xpub).toEqual(expectedXpub);
+        });
+        test('derives seed-based addresses matching the reference', async () => {
+            const seed = sdk.keyPair.mnemonicToSeed(mnemonic);
+            for (let index = 0; index < expectedAddresses.length; index++) {
+                const address = await sdk.keyPair.derivePlatformAddress(seed, 'testnet', account, index);
+                expect(address).toEqual(expect.any(PlatformAddressWASM));
+                expect(address.isP2PKH()).toBe(true);
+                expect(address.toBech32m('testnet')).toEqual(expectedAddresses[index]);
+            }
+        });
+        test('xpub-based public derivation reproduces the seed-based addresses', async () => {
+            const seed = sdk.keyPair.mnemonicToSeed(mnemonic);
+            const xpub = await sdk.keyPair.derivePlatformAccountXpub(seed, 'testnet', account);
+            for (let index = 0; index < expectedAddresses.length; index++) {
+                const fromXpub = sdk.keyPair.derivePlatformAddressFromXpub(xpub, 'testnet', index);
+                expect(fromXpub.toBech32m('testnet')).toEqual(expectedAddresses[index]);
+            }
+        });
+        test('private key derivation yields the same pubkey hash as the address', async () => {
+            const seed = sdk.keyPair.mnemonicToSeed(mnemonic);
+            for (let index = 0; index < expectedAddresses.length; index++) {
+                const privateKey = await sdk.keyPair.derivePlatformAddressPrivateKey(seed, 'testnet', account, index);
+                const address = await sdk.keyPair.derivePlatformAddress(seed, 'testnet', account, index);
+                expect(privateKey.getPublicKeyHash()).toEqual(Buffer.from(address.hash()).toString('hex'));
+            }
+        });
+        test('derives distinct addresses per network', async () => {
+            const seed = sdk.keyPair.mnemonicToSeed(mnemonic);
+            const mainnet = await sdk.keyPair.derivePlatformAddress(seed, 'mainnet', account, 0);
+            const testnet = await sdk.keyPair.derivePlatformAddress(seed, 'testnet', account, 0);
+            expect(mainnet.bytes()).not.toEqual(testnet.bytes());
+        });
+    });
 });

package/test/unit/PlatformAddress.spec.js

@@ -1,3 +1,5 @@
+import { AddressFundsFeeStrategyStepWASM, AddressWitnessWASM, AssetLockProofWASM, CoreScriptWASM, IdentityPublicKeyInCreationWASM, InputAddressWASM, OutputAddressWASM, OutputAddressNullableCreditsWASM, KeyType, OutPointWASM, PlatformAddressWASM, PrivateKeyWASM, Purpose, SecurityLevel, StateTransitionWASM } from 'pshenmic-dpp';
+import { base58 } from '@scure/base';
 import { DashPlatformSDK } from '../../src/DashPlatformSDK.js';
 let sdk;
 describe('PlatformAddress', () => {
@@ -19,4 +21,113 @@ describe('PlatformAddress', () => {
         const info = await sdk.platformAddresses.getAddressesInfos(addresses);
         expect(info).toHaveLength(addresses.length);
     });
+    describe('createStateTransition', () => {
+        const identityId = 'QMfCRPcjXoTnZa9sA9JR2KWgGxZXMRJ4akgS3Uia1Qv';
+        const addressA = PlatformAddressWASM.fromBech32m('tdash1kzg5azscav69z7m6dfzr9ner0a5vt7pn9ca4sz8d');
+        const addressB = PlatformAddressWASM.fromBech32m('tdash1kqr3cxhgel75ru0yrhj5eq8j8jt92m5enqrfajxw');
+        const inputs = [new InputAddressWASM(addressA, 0, 100000n)];
+        const outputs = [new OutputAddressWASM(addressB, 50000n)];
+        const recipients = [new OutputAddressWASM(addressB, 50000n)];
+        const nullableOutputs = [new OutputAddressNullableCreditsWASM(addressB)];
+        const feeStrategy = [AddressFundsFeeStrategyStepWASM.DeductFromInput(1)];
+        const inputWitness = [AddressWitnessWASM.P2PKH(new Uint8Array(65))];
+        const output = new OutputAddressWASM(addressA, 10000n);
+        const nonce = 1n;
+        const privateKey = PrivateKeyWASM.fromHex('a1286dd195e2b8e1f6bdc946c56a53e0c544750d6452ddc0f4c593ef311f21af', 'testnet');
+        const publicKeys = [
+            new IdentityPublicKeyInCreationWASM(0, Purpose.AUTHENTICATION, SecurityLevel.MASTER, KeyType.ECDSA_SECP256K1, false, privateKey.getPublicKey().bytes())
+        ];
+        const assetLockProof = AssetLockProofWASM.createChainAssetLockProof(1337, new OutPointWASM('61aede830477254876d435a317241ad46753c4b1350dc991a45ebcf19ab80a11', 0));
+        const withdrawalAddress = 'yjHVQ3dj37UJwXFmvMTKR9ZVfoJSc3opTD';
+        const outputScript = CoreScriptWASM.newP2PKH(base58.decode(withdrawalAddress).slice(1, 21));
+        test('should be able to create identityCreditTransferToAddresses', () => {
+            const stateTransition = sdk.platformAddresses.createStateTransition('identityCreditTransferToAddresses', {
+                identityId, recipients, nonce
+            });
+            expect(stateTransition).toEqual(expect.any(StateTransitionWASM));
+        });
+        test('should throw when identityCreditTransferToAddresses is missing recipients', () => {
+            // @ts-expect-error testing the runtime missing-param check
+            expect(() => sdk.platformAddresses.createStateTransition('identityCreditTransferToAddresses', {
+                identityId, nonce
+            })).toThrow('Platform address transition param "recipients" is missing');
+        });
+        test('should be able to create identityCreateFromAddresses', () => {
+            const stateTransition = sdk.platformAddresses.createStateTransition('identityCreateFromAddresses', {
+                publicKeys, inputs, feeStrategy, inputWitness
+            });
+            expect(stateTransition).toEqual(expect.any(StateTransitionWASM));
+        });
+        test('should throw when identityCreateFromAddresses is missing publicKeys', () => {
+            // @ts-expect-error testing the runtime missing-param check
+            expect(() => sdk.platformAddresses.createStateTransition('identityCreateFromAddresses', {
+                inputs, feeStrategy, inputWitness
+            })).toThrow('Platform address transition param "publicKeys" is missing');
+        });
+        test('should be able to create identityTopUpFromAddresses', () => {
+            const stateTransition = sdk.platformAddresses.createStateTransition('identityTopUpFromAddresses', {
+                identityId, inputs, feeStrategy, inputWitness
+            });
+            expect(stateTransition).toEqual(expect.any(StateTransitionWASM));
+        });
+        test('should throw when identityTopUpFromAddresses is missing identityId', () => {
+            // @ts-expect-error testing the runtime missing-param check
+            expect(() => sdk.platformAddresses.createStateTransition('identityTopUpFromAddresses', {
+                inputs, feeStrategy, inputWitness
+            })).toThrow('Platform address transition param "identityId" is missing');
+        });
+        test('should be able to create addressFundsTransfer', () => {
+            const stateTransition = sdk.platformAddresses.createStateTransition('addressFundsTransfer', {
+                inputs, feeStrategy, inputWitness, outputs
+            });
+            expect(stateTransition).toEqual(expect.any(StateTransitionWASM));
+        });
+        test('should throw when addressFundsTransfer is missing outputs', () => {
+            // @ts-expect-error testing the runtime missing-param check
+            expect(() => sdk.platformAddresses.createStateTransition('addressFundsTransfer', {
+                inputs, feeStrategy, inputWitness
+            })).toThrow('Platform address transition param "outputs" is missing');
+        });
+        test('should be able to create addressFundingFromAssetLock', () => {
+            const stateTransition = sdk.platformAddresses.createStateTransition('addressFundingFromAssetLock', {
+                assetLockProof, inputs, feeStrategy, inputWitness, outputs: nullableOutputs
+            });
+            expect(stateTransition).toEqual(expect.any(StateTransitionWASM));
+        });
+        test('should throw when addressFundingFromAssetLock is missing assetLockProof', () => {
+            // @ts-expect-error testing the runtime missing-param check
+            expect(() => sdk.platformAddresses.createStateTransition('addressFundingFromAssetLock', {
+                inputs, feeStrategy, inputWitness, outputs: nullableOutputs
+            })).toThrow('Platform address transition param "assetLockProof" is missing');
+        });
+        test('should be able to create addressCreditWithdrawal', () => {
+            const stateTransition = sdk.platformAddresses.createStateTransition('addressCreditWithdrawal', {
+                inputs, feeStrategy, coreFeePerByte: 1, pooling: 'Standard', outputScript, inputWitness
+            });
+            expect(stateTransition).toEqual(expect.any(StateTransitionWASM));
+        });
+        test('should be able to create addressCreditWithdrawal with optional output', () => {
+            const stateTransition = sdk.platformAddresses.createStateTransition('addressCreditWithdrawal', {
+                inputs, feeStrategy, coreFeePerByte: 1, pooling: 'Standard', outputScript, inputWitness, output
+            });
+            expect(stateTransition).toEqual(expect.any(StateTransitionWASM));
+        });
+        test('should throw when addressCreditWithdrawal is missing outputScript', () => {
+            // @ts-expect-error testing the runtime missing-param check
+            expect(() => sdk.platformAddresses.createStateTransition('addressCreditWithdrawal', {
+                inputs, feeStrategy, coreFeePerByte: 1, pooling: 'Standard', inputWitness
+            })).toThrow('Platform address transition param "outputScript" is missing');
+        });
+        test('should default userFeeIncrease to 0 when omitted', () => {
+            const stateTransition = sdk.platformAddresses.createStateTransition('addressFundsTransfer', {
+                inputs, feeStrategy, inputWitness, outputs
+            });
+            expect(stateTransition).toEqual(expect.any(StateTransitionWASM));
+        });
+        test('should throw on unimplemented transition type', () => {
+            expect(() => sdk.platformAddresses.createStateTransition(
+            // @ts-expect-error testing an unknown transition type
+            'unknownTransition', {})).toThrow('Unimplemented transition type: unknownTransition');
+        });
+    });
 });

package/types.d.ts

@@ -1,5 +1,5 @@
-import { AddressFundsFeeStrategyStepWASM, AssetLockProofWASM, CoreScriptWASM, DocumentWASM, GasFeesPaidByWASM, IdentifierLike, IdentifierWASM, InputAddressWASM, KeyType, OrchardAddressWASM, PlatformAddressLike, PlatformAddressWASM, PlatformVersionWASM, PoolingLike, PrivateKeyWASM, Purpose, SecurityLevel, SpendableNoteWASM, TokenEmergencyActionWASM, TokenPricingScheduleWASM } from 'pshenmic-dpp';
-export { CoreScriptWASM, DocumentWASM, GasFeesPaidByWASM, IdentifierWASM, KeyType, Purpose, SecurityLevel, TokenEmergencyActionWASM, TokenPricingScheduleWASM, StateTransitionWASM, BatchTransitionWASM, IdentityPublicKeyWASM, PrivateKeyWASM, DataContractUpdateTransitionWASM, IdentityWASM, IdentityUpdateTransitionWASM, IdentityCreditTransferWASM, MasternodeVoteTransitionWASM, IdentifierLike, PlatformAddressLike } from 'pshenmic-dpp';
+import { AddressFundsFeeStrategyStepWASM, AssetLockProofWASM, CoreScriptWASM, DocumentWASM, GasFeesPaidByWASM, IdentifierLike, IdentifierWASM, InputAddressWASM, KeyType, OrchardAddressWASM, PlatformAddressLike, PlatformAddressWASM, PlatformVersionWASM, PoolingLike, PrivateKeyWASM, Purpose, SecurityLevel, SpendableNoteWASM, TokenEmergencyActionWASM, TokenPricingScheduleWASM, AddressWitnessWASM, IdentityPublicKeyInCreationWASM, OutputAddressWASM, OutputAddressNullableCreditsWASM } from 'pshenmic-dpp';
+export { CoreScriptWASM, DocumentWASM, GasFeesPaidByWASM, IdentifierWASM, KeyType, Purpose, SecurityLevel, TokenEmergencyActionWASM, TokenPricingScheduleWASM, StateTransitionWASM, BatchTransitionWASM, IdentityPublicKeyWASM, PrivateKeyWASM, DataContractUpdateTransitionWASM, IdentityWASM, IdentityUpdateTransitionWASM, IdentityCreditTransferWASM, MasternodeVoteTransitionWASM, IdentifierLike, PlatformAddressLike, InputAddressWASM, OutputAddressWASM, OutputAddressNullableCreditsWASM, AddressFundsFeeStrategyStepWASM, AddressWitnessWASM, IdentityPublicKeyInCreationWASM, AssetLockProofWASM, IdentityCreditTransferToAddressesTransitionWASM, IdentityCreateFromAddressesTransitionWASM, IdentityTopUpFromAddressesTransitionWASM, AddressFundsTransferTransitionWASM, AddressFundingFromAssetLockTransitionWASM, AddressCreditWithdrawalTransitionWASM } from 'pshenmic-dpp';
 export type Network = 'mainnet' | 'testnet';
 export { DashPlatformSDK } from './src/DashPlatformSDK.js';
 export type MasternodeList = Record<string, MasternodeInfo>;
@@ -294,3 +294,60 @@ export interface ShieldedNullifierStatus {
     nullifier: Uint8Array;
     isSpent: boolean;
 }
+/**
+ * Fields shared by the address-funded transitions (the ones spending platform address inputs).
+ *
+ * The `inputWitness` arrays are produced by the client application (wallet / mobile / browser
+ * extension), which is where the address private keys live. The builders only assemble the
+ * transition - they never sign or hit the network.
+ */
+export interface AddressFundsBaseParams {
+    inputs: InputAddressWASM[];
+    feeStrategy: AddressFundsFeeStrategyStepWASM[];
+    inputWitness: AddressWitnessWASM[];
+    userFeeIncrease?: number;
+}
+/** Identity -> platform addresses (transition type 9). */
+export interface IdentityCreditTransferToAddressesParams {
+    identityId: IdentifierLike;
+    recipients: OutputAddressWASM[];
+    nonce: bigint;
+    userFeeIncrease?: number;
+}
+/** Platform addresses -> new identity (transition type 10). */
+export interface IdentityCreateFromAddressesParams extends AddressFundsBaseParams {
+    publicKeys: IdentityPublicKeyInCreationWASM[];
+    output?: OutputAddressWASM;
+}
+/** Platform addresses -> existing identity (transition type 11). */
+export interface IdentityTopUpFromAddressesParams extends AddressFundsBaseParams {
+    identityId: IdentifierLike;
+    output?: OutputAddressWASM;
+}
+/** Platform addresses -> platform addresses (transition type 12). */
+export interface AddressFundsTransferParams extends AddressFundsBaseParams {
+    outputs: OutputAddressWASM[];
+}
+/** Asset lock -> platform addresses (transition type 13). */
+export interface AddressFundingFromAssetLockParams extends AddressFundsBaseParams {
+    assetLockProof: AssetLockProofWASM;
+    outputs: OutputAddressNullableCreditsWASM[];
+}
+/** Platform addresses -> core L1 (transition type 14). */
+export interface AddressCreditWithdrawalParams extends AddressFundsBaseParams {
+    coreFeePerByte: number;
+    pooling: 'Standard' | 'Never' | 'IfAvailable';
+    outputScript: CoreScriptWASM;
+    output?: OutputAddressWASM;
+}
+/** Maps each platform address transition type to the params it requires. */
+export interface PlatformAddressTransitionParamsMap {
+    identityCreditTransferToAddresses: IdentityCreditTransferToAddressesParams;
+    identityCreateFromAddresses: IdentityCreateFromAddressesParams;
+    identityTopUpFromAddresses: IdentityTopUpFromAddressesParams;
+    addressFundsTransfer: AddressFundsTransferParams;
+    addressFundingFromAssetLock: AddressFundingFromAssetLockParams;
+    addressCreditWithdrawal: AddressCreditWithdrawalParams;
+}
+export type PlatformAddressTransitionType = keyof PlatformAddressTransitionParamsMap;
+export type PlatformAddressTransitionParams = PlatformAddressTransitionParamsMap[PlatformAddressTransitionType];

package/types.js

@@ -1,4 +1,4 @@
-export { CoreScriptWASM, DocumentWASM, GasFeesPaidByWASM, IdentifierWASM, KeyType, Purpose, SecurityLevel, TokenEmergencyActionWASM, TokenPricingScheduleWASM, StateTransitionWASM, BatchTransitionWASM, IdentityPublicKeyWASM, PrivateKeyWASM, DataContractUpdateTransitionWASM, IdentityWASM, IdentityUpdateTransitionWASM, IdentityCreditTransferWASM, MasternodeVoteTransitionWASM } from 'pshenmic-dpp';
+export { CoreScriptWASM, DocumentWASM, GasFeesPaidByWASM, IdentifierWASM, KeyType, Purpose, SecurityLevel, TokenEmergencyActionWASM, TokenPricingScheduleWASM, StateTransitionWASM, BatchTransitionWASM, IdentityPublicKeyWASM, PrivateKeyWASM, DataContractUpdateTransitionWASM, IdentityWASM, IdentityUpdateTransitionWASM, IdentityCreditTransferWASM, MasternodeVoteTransitionWASM, InputAddressWASM, OutputAddressWASM, OutputAddressNullableCreditsWASM, AddressFundsFeeStrategyStepWASM, AddressWitnessWASM, IdentityPublicKeyInCreationWASM, AssetLockProofWASM, IdentityCreditTransferToAddressesTransitionWASM, IdentityCreateFromAddressesTransitionWASM, IdentityTopUpFromAddressesTransitionWASM, AddressFundsTransferTransitionWASM, AddressFundingFromAssetLockTransitionWASM, AddressCreditWithdrawalTransitionWASM } from 'pshenmic-dpp';
 export { DashPlatformSDK } from './src/DashPlatformSDK.js';
 export var ContestedStateResultType;
 (function (ContestedStateResultType) {