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

package/package.json

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

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/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) {