trac-msb 0.2.4 → 0.2.6

package/tests/unit/state/apply/adminRecovery/state.apply.adminRecovery.test.js

@@ -0,0 +1,439 @@
+import b4a from 'b4a';
+import adminRecoveryHappyPathScenario from './adminRecoveryHappyPathScenario.js';
+import {
+	setupAdminRecoveryScenario,
+	buildAdminRecoveryPayload,
+	assertAdminRecoveryFailureState,
+	assertAdminRecoverySuccessState,
+	applyAdminRecoveryViaValidator,
+	buildAdminRecoveryPayloadWithTxValidity,
+	applyWithMissingComponentBypass,
+	applyWithRoleAccessBypass,
+	applyWithRegisteredWriterKey,
+	applyWithIndexerSequenceFailure,
+	applyWithIndexerSequenceCorruption,
+	applyWithAdminEntryMutation,
+	applyWithAdminNodeEntryMutation,
+	cloneIndexers,
+	applyWithAdminEncodeFailure,
+	applyWithAdminBalanceDecodeFailure,
+	applyWithInvalidRequesterMessage,
+	applyWithInvalidValidatorMessage,
+	applyWithValidatorBalanceUpdateFailure,
+	applyWithAdminInsufficientBalance,
+	applyWithAdminFeeSubtractionFailure,
+	applyWithValidatorNodeDecodeFailure,
+	applyWithValidatorBalanceDecodeFailure,
+	applyWithValidatorFeeTransferFailure,
+	applyWithDuplicateOperation,
+	applyWithOldWriterKeyMissing,
+	applyWithNewWriterKeyPresent,
+	applyWithAdminNodeDecodeFailure
+} from './adminRecoveryScenarioHelpers.js';
+import RoleAccessOperationValidationScenario from '../common/access-control/roleAccessOperationValidationScenario.js';
+import PartialOperationValidationScenario, {
+	PartialOperationMutationStrategy
+} from '../common/payload-structure/partialOperationValidationScenario.js';
+import RequesterAddressValidationScenario from '../common/requesterAddressValidationScenario.js';
+import createRequesterPublicKeyValidationScenario from '../common/requesterPublicKeyValidationScenario.js';
+import InvalidHashValidationScenario from '../common/payload-structure/invalidHashValidationScenario.js';
+import OperationValidationScenarioBase from '../common/base/OperationValidationScenarioBase.js';
+import { safeDecodeApplyOperation, safeEncodeApplyOperation } from '../../../../../src/utils/protobuf/operationHelpers.js';
+import InvalidAddressValidationScenario from '../common/payload-structure/invalidAddressValidationScenario.js';
+import createAddressWithInvalidPublicKeyScenario from '../common/payload-structure/addressWithInvalidPublicKeyScenario.js';
+import TransactionValidityMismatchScenario from '../common/transactionValidityMismatchScenario.js';
+import IndexerSequenceStateInvalidScenario from '../common/indexer/indexerSequenceStateInvalidScenario.js';
+import ValidatorInactiveScenario from '../common/validatorConsistency/validatorInactiveScenario.js';
+import ValidatorEntryDecodeFailureScenario from '../common/validatorConsistency/validatorEntryDecodeFailureScenario.js';
+import ValidatorWriterKeyMismatchScenario from '../common/validatorConsistency/validatorWriterKeyMismatchScenario.js';
+import ValidatorConsistencyScenarioBase, {
+	ValidatorEntryMutation
+} from '../common/validatorConsistency/base/validatorConsistencyScenarioBase.js';
+import adminEntryUtils from '../../../../../src/core/state/utils/adminEntry.js';
+import addressUtils from '../../../../../src/core/state/utils/address.js';
+import nodeEntryUtils from '../../../../../src/core/state/utils/nodeEntry.js';
+
+adminRecoveryHappyPathScenario();
+
+new RoleAccessOperationValidationScenario({
+	title: 'State.apply adminRecovery rejects payloads when contract validation fails',
+	setupScenario: setupAdminRecoveryScenario,
+	buildValidPayload: buildAdminRecoveryPayload,
+	assertStateUnchanged: assertAdminRecoveryFailureState,
+	applyInvalidPayload: applyAdminRecoveryViaValidator,
+	expectedLogs: ['Contract schema validation failed.']
+}).performScenario();
+
+new PartialOperationValidationScenario({
+	title: 'State.apply adminRecovery rejects incomplete validator co-signatures',
+	setupScenario: setupAdminRecoveryScenario,
+	buildValidPayload: buildAdminRecoveryPayload,
+	assertStateUnchanged: assertAdminRecoveryFailureState,
+	strategy: PartialOperationMutationStrategy.MISSING_COMPONENT,
+	parentKey: 'rao',
+	applyInvalidPayload: applyWithMissingComponentBypass,
+	expectedLogs: ['Operation is not complete.']
+}).performScenario();
+
+new PartialOperationValidationScenario({
+	title: 'State.apply adminRecovery rejects payloads when nonces match',
+	setupScenario: setupAdminRecoveryScenario,
+	buildValidPayload: buildAdminRecoveryPayload,
+	assertStateUnchanged: assertAdminRecoveryFailureState,
+	applyInvalidPayload: applyAdminRecoveryViaValidator,
+	strategy: PartialOperationMutationStrategy.NONCE_MATCH,
+	parentKey: 'rao',
+	expectedLogs: ['Nonces should not be the same.']
+}).performScenario();
+
+new PartialOperationValidationScenario({
+	title: 'State.apply adminRecovery rejects payloads when validator shares requester address',
+	setupScenario: setupAdminRecoveryScenario,
+	buildValidPayload: buildAdminRecoveryPayload,
+	assertStateUnchanged: assertAdminRecoveryFailureState,
+	applyInvalidPayload: applyAdminRecoveryViaValidator,
+	strategy: PartialOperationMutationStrategy.ADDRESS_MATCH,
+	parentKey: 'rao',
+	expectedLogs: ['Addresses should be different.']
+}).performScenario();
+
+new PartialOperationValidationScenario({
+	title: 'State.apply adminRecovery rejects payloads when signatures duplicate',
+	setupScenario: setupAdminRecoveryScenario,
+	buildValidPayload: buildAdminRecoveryPayload,
+	assertStateUnchanged: assertAdminRecoveryFailureState,
+	applyInvalidPayload: applyAdminRecoveryViaValidator,
+	strategy: PartialOperationMutationStrategy.SIGNATURE_MATCH,
+	parentKey: 'rao',
+	expectedLogs: ['Signatures should be different.']
+}).performScenario();
+
+new RequesterAddressValidationScenario({
+	title: 'State.apply adminRecovery rejects invalid requester address',
+	setupScenario: setupAdminRecoveryScenario,
+	buildValidPayload: buildAdminRecoveryPayload,
+	assertStateUnchanged: assertAdminRecoveryFailureState,
+	applyInvalidPayload: applyAdminRecoveryViaValidator,
+	expectedLogs: ['Requester address is invalid.']
+}).performScenario();
+
+createRequesterPublicKeyValidationScenario({
+	title: 'State.apply adminRecovery rejects requester public key decode failures',
+	setupScenario: setupAdminRecoveryScenario,
+	buildValidPayload: buildAdminRecoveryPayload,
+	assertStateUnchanged: assertAdminRecoveryFailureState,
+	applyInvalidPayload: applyAdminRecoveryViaValidator,
+	expectedLogs: ['Error while decoding requester public key.']
+}).performScenario();
+
+new OperationValidationScenarioBase({
+	title: 'State.apply adminRecovery rejects invalid requester messages',
+	setupScenario: setupAdminRecoveryScenario,
+	buildValidPayload: buildAdminRecoveryPayload,
+	assertStateUnchanged: (t, context) => assertAdminRecoveryFailureState(t, context, { skipSync: true }),
+	mutatePayload: (_t, payload) => payload,
+	applyInvalidPayload: async (context, invalidPayload) =>
+		applyWithInvalidRequesterMessage(context, invalidPayload),
+	expectedLogs: ['Invalid requester message.']
+}).performScenario();
+
+new InvalidHashValidationScenario({
+	title: 'State.apply adminRecovery rejects requester message hash mismatch',
+	setupScenario: setupAdminRecoveryScenario,
+	buildValidPayload: buildAdminRecoveryPayload,
+	assertStateUnchanged: assertAdminRecoveryFailureState,
+	applyInvalidPayload: applyAdminRecoveryViaValidator,
+	expectedLogs: ['Message hash does not match the tx_hash.']
+}).performScenario();
+
+new OperationValidationScenarioBase({
+	title: 'State.apply adminRecovery rejects requester signature verification failures',
+	setupScenario: setupAdminRecoveryScenario,
+	buildValidPayload: buildAdminRecoveryPayload,
+	assertStateUnchanged: assertAdminRecoveryFailureState,
+	mutatePayload: (t, payload) => {
+		const decoded = safeDecodeApplyOperation(payload);
+		t.ok(decoded, 'fixtures decode');
+		if (decoded?.rao?.is) {
+			decoded.rao.is = b4a.alloc(decoded.rao.is.length);
+		}
+		return safeEncodeApplyOperation(decoded);
+	},
+	applyInvalidPayload: async (context, invalidPayload) => applyWithRoleAccessBypass(context, invalidPayload),
+	expectedLogs: ['Failed to verify requester message signature.']
+}).performScenario();
+
+new InvalidAddressValidationScenario({
+	title: 'State.apply adminRecovery rejects invalid validator address',
+	setupScenario: setupAdminRecoveryScenario,
+	buildValidPayload: buildAdminRecoveryPayload,
+	assertStateUnchanged: assertAdminRecoveryFailureState,
+	addressPath: ['rao', 'va'],
+	applyInvalidPayload: applyAdminRecoveryViaValidator,
+	expectedLogs: ['Failed to validate validator address.']
+}).performScenario();
+
+createAddressWithInvalidPublicKeyScenario({
+	title: 'State.apply adminRecovery rejects validator public key decode failures',
+	setupScenario: setupAdminRecoveryScenario,
+	buildValidPayload: buildAdminRecoveryPayload,
+	assertStateUnchanged: assertAdminRecoveryFailureState,
+	addressPath: ['rao', 'va'],
+	applyInvalidPayload: applyAdminRecoveryViaValidator,
+	expectedLogs: ['Failed to decode validator public key.']
+}).performScenario();
+
+new OperationValidationScenarioBase({
+	title: 'State.apply adminRecovery rejects invalid validator messages',
+	setupScenario: setupAdminRecoveryScenario,
+	buildValidPayload: buildAdminRecoveryPayload,
+	assertStateUnchanged: (t, context) => assertAdminRecoveryFailureState(t, context, { skipSync: true }),
+	mutatePayload: (_t, payload) => payload,
+	applyInvalidPayload: async (context, invalidPayload) =>
+		applyWithInvalidValidatorMessage(context, invalidPayload),
+	expectedLogs: ['Failed to verify validator message signature.']
+}).performScenario();
+
+new OperationValidationScenarioBase({
+	title: 'State.apply adminRecovery rejects validator signature verification failures',
+	setupScenario: setupAdminRecoveryScenario,
+	buildValidPayload: buildAdminRecoveryPayload,
+	assertStateUnchanged: assertAdminRecoveryFailureState,
+	mutatePayload: (t, payload) => {
+		const decoded = safeDecodeApplyOperation(payload);
+		t.ok(decoded, 'fixtures decode');
+		if (decoded?.rao?.vs) {
+			decoded.rao.vs = b4a.alloc(decoded.rao.vs.length);
+		}
+		return safeEncodeApplyOperation(decoded);
+	},
+	applyInvalidPayload: async (context, invalidPayload) => applyWithRoleAccessBypass(context, invalidPayload),
+	expectedLogs: ['Failed to verify message signature.']
+}).performScenario();
+
+new OperationValidationScenarioBase({
+	title: 'State.apply adminRecovery rejects payloads when writer key already exists',
+	setupScenario: setupAdminRecoveryScenario,
+	buildValidPayload: buildAdminRecoveryPayload,
+	assertStateUnchanged: (t, context) =>
+		assertAdminRecoveryFailureState(t, context, { skipSync: true }),
+	mutatePayload: (_t, payload) => payload,
+	applyInvalidPayload: async (context, invalidPayload) => applyWithRegisteredWriterKey(context, invalidPayload),
+	expectedLogs: ['Writer key already exists.']
+}).performScenario();
+
+new IndexerSequenceStateInvalidScenario({
+	title: 'State.apply adminRecovery rejects when indexer sequence state is invalid',
+	setupScenario: setupAdminRecoveryScenario,
+	buildValidPayload: buildAdminRecoveryPayload,
+	assertStateUnchanged: (t, context, validPayload, invalidPayload) =>
+		assertAdminRecoveryFailureState(t, context, { skipSync: true }),
+	applyInvalidPayload: applyWithIndexerSequenceFailure,
+	expectedLogs: ['Indexer sequence state is invalid.']
+}).performScenario();
+
+new TransactionValidityMismatchScenario({
+	title: 'State.apply adminRecovery rejects payloads when tx validity mismatches indexer state',
+	setupScenario: setupAdminRecoveryScenario,
+	buildValidPayload: buildAdminRecoveryPayload,
+	assertStateUnchanged: assertAdminRecoveryFailureState,
+	txValidityPath: ['rao', 'txv'],
+	rebuildPayloadWithTxValidity: ({ context, mutatedTxValidity }) =>
+		buildAdminRecoveryPayloadWithTxValidity(context, mutatedTxValidity),
+	applyInvalidPayload: applyAdminRecoveryViaValidator,
+	expectedLogs: ['Transaction was not executed.']
+}).performScenario();
+
+new ValidatorInactiveScenario({
+	title: 'State.apply adminRecovery rejects inconsistent validator entries',
+	setupScenario: setupAdminRecoveryScenario,
+	buildValidPayload: buildAdminRecoveryPayload,
+	assertStateUnchanged: (t, context) => assertAdminRecoveryFailureState(t, context, { skipSync: true }),
+	selectNode: context => context.adminRecovery.validatorPeer1,
+	expectedLogs: [{ anyOf: ['Validator consistency check failed.', 'Operation validator is not active'] }]
+}).performScenario();
+
+new ValidatorConsistencyScenarioBase({
+	title: 'State.apply adminRecovery rejects when validator entry is missing',
+	setupScenario: setupAdminRecoveryScenario,
+	buildValidPayload: buildAdminRecoveryPayload,
+	assertStateUnchanged: (t, context) => assertAdminRecoveryFailureState(t, context, { skipSync: true }),
+	mutateEntry: () => ValidatorEntryMutation.DELETE,
+	selectNode: context => context.adminRecovery.validatorPeer1,
+	expectedLogs: ['Incoming validator entry is null.']
+}).performScenario();
+
+new ValidatorEntryDecodeFailureScenario({
+	title: 'State.apply adminRecovery rejects when validator entry cannot be decoded',
+	setupScenario: setupAdminRecoveryScenario,
+	buildValidPayload: buildAdminRecoveryPayload,
+	assertStateUnchanged: (t, context) => assertAdminRecoveryFailureState(t, context, { skipSync: true }),
+	selectNode: context => context.adminRecovery.validatorPeer1
+}).performScenario();
+
+new ValidatorWriterKeyMismatchScenario({
+	title: 'State.apply adminRecovery rejects when validator writer key mismatches requester',
+	setupScenario: setupAdminRecoveryScenario,
+	buildValidPayload: buildAdminRecoveryPayload,
+	assertStateUnchanged: (t, context) => assertAdminRecoveryFailureState(t, context, { skipSync: true }),
+	selectNode: context => context.adminRecovery.validatorPeer1,
+	expectedLogs: ['Validator cannot be the same as requester.']
+}).performScenario();
+
+new OperationValidationScenarioBase({
+	title: 'State.apply adminRecovery rejects when admin entry cannot be decoded',
+	setupScenario: setupAdminRecoveryScenario,
+	buildValidPayload: buildAdminRecoveryPayload,
+	assertStateUnchanged: (t, context) => assertAdminRecoveryFailureState(t, context, { skipSync: true }),
+	mutatePayload: (_t, payload) => payload,
+	applyInvalidPayload: async (context, invalidPayload) =>
+		applyWithAdminEntryMutation(context, invalidPayload, () => ({ value: b4a.alloc(1) })),
+	expectedLogs: ['Failed to decode admin entry.']
+}).performScenario();
+
+new OperationValidationScenarioBase({
+	title: 'State.apply adminRecovery rejects when admin public key mismatches node key',
+	setupScenario: setupAdminRecoveryScenario,
+	buildValidPayload: buildAdminRecoveryPayload,
+	assertStateUnchanged: (t, context) => assertAdminRecoveryFailureState(t, context, { skipSync: true }),
+	mutatePayload: (_t, payload) => payload,
+	applyInvalidPayload: async (context, invalidPayload) => {
+		const otherAddress = context.adminRecovery.validatorPeer2.wallet.address;
+		const otherAddressBuffer = addressUtils.addressToBuffer(otherAddress);
+		const mutatedEntry = adminEntryUtils.encode(otherAddressBuffer, context.adminRecovery.oldAdminWriterKey);
+		return applyWithAdminEntryMutation(context, invalidPayload, () => ({ value: mutatedEntry }));
+	},
+	expectedLogs: ['Admin public key does not match the node public key.']
+}).performScenario();
+
+new OperationValidationScenarioBase({
+	title: 'State.apply adminRecovery rejects when admin entry encoding fails',
+	setupScenario: setupAdminRecoveryScenario,
+	buildValidPayload: buildAdminRecoveryPayload,
+	assertStateUnchanged: (t, context) => assertAdminRecoveryFailureState(t, context, { skipSync: true }),
+	mutatePayload: (_t, payload) => payload,
+	applyInvalidPayload: async (context, invalidPayload) =>
+		applyWithAdminEncodeFailure(context, invalidPayload),
+	expectedLogs: ['Invalid admin entry.']
+}).performScenario();
+
+new OperationValidationScenarioBase({
+	title: 'State.apply adminRecovery rejects when admin balance cannot be decoded',
+	setupScenario: setupAdminRecoveryScenario,
+	buildValidPayload: buildAdminRecoveryPayload,
+	assertStateUnchanged: (t, context) => assertAdminRecoveryFailureState(t, context, { skipSync: true }),
+	mutatePayload: (_t, payload) => payload,
+	applyInvalidPayload: async (context, invalidPayload) =>
+		applyWithAdminBalanceDecodeFailure(context, invalidPayload),
+	expectedLogs: ['Invalid admin balance.']
+}).performScenario();
+
+new OperationValidationScenarioBase({
+	title: 'State.apply adminRecovery rejects when admin balance is insufficient',
+	setupScenario: setupAdminRecoveryScenario,
+	buildValidPayload: buildAdminRecoveryPayload,
+	assertStateUnchanged: (t, context) => assertAdminRecoveryFailureState(t, context, { skipSync: true }),
+	mutatePayload: (_t, payload) => payload,
+	applyInvalidPayload: async (context, invalidPayload) =>
+		applyWithAdminInsufficientBalance(context, invalidPayload),
+	expectedLogs: ['Insufficient admin balance.']
+}).performScenario();
+
+new OperationValidationScenarioBase({
+	title: 'State.apply adminRecovery rejects when admin fee deduction fails',
+	setupScenario: setupAdminRecoveryScenario,
+	buildValidPayload: buildAdminRecoveryPayload,
+	assertStateUnchanged: (t, context) => assertAdminRecoveryFailureState(t, context, { skipSync: true }),
+	mutatePayload: (_t, payload) => payload,
+	applyInvalidPayload: async (context, invalidPayload) =>
+		applyWithAdminFeeSubtractionFailure(context, invalidPayload),
+	expectedLogs: ['Failed to apply fee.']
+}).performScenario();
+
+new OperationValidationScenarioBase({
+	title: 'State.apply adminRecovery rejects when validator node entry cannot be decoded after validation',
+	setupScenario: setupAdminRecoveryScenario,
+	buildValidPayload: buildAdminRecoveryPayload,
+	assertStateUnchanged: (t, context) => assertAdminRecoveryFailureState(t, context, { skipSync: true }),
+	mutatePayload: (_t, payload) => payload,
+	applyInvalidPayload: async (context, invalidPayload) =>
+		applyWithValidatorNodeDecodeFailure(context, invalidPayload),
+	expectedLogs: ['Invalid validator node entry.']
+}).performScenario();
+
+new OperationValidationScenarioBase({
+	title: 'State.apply adminRecovery rejects when validator balance cannot be decoded',
+	setupScenario: setupAdminRecoveryScenario,
+	buildValidPayload: buildAdminRecoveryPayload,
+	assertStateUnchanged: (t, context) => assertAdminRecoveryFailureState(t, context, { skipSync: true }),
+	mutatePayload: (_t, payload) => payload,
+	applyInvalidPayload: async (context, invalidPayload) =>
+		applyWithValidatorBalanceDecodeFailure(context, invalidPayload),
+	expectedLogs: ['Invalid validator balance.']
+}).performScenario();
+
+new OperationValidationScenarioBase({
+	title: 'State.apply adminRecovery rejects when validator fee transfer fails',
+	setupScenario: setupAdminRecoveryScenario,
+	buildValidPayload: buildAdminRecoveryPayload,
+	assertStateUnchanged: (t, context) => assertAdminRecoveryFailureState(t, context, { skipSync: true }),
+	mutatePayload: (_t, payload) => payload,
+	applyInvalidPayload: async (context, invalidPayload) =>
+		applyWithValidatorFeeTransferFailure(context, invalidPayload),
+	expectedLogs: ['Failed to transfer fee to validator.']
+}).performScenario();
+
+new OperationValidationScenarioBase({
+	title: 'State.apply adminRecovery rejects when validator balance update fails',
+	setupScenario: setupAdminRecoveryScenario,
+	buildValidPayload: buildAdminRecoveryPayload,
+	assertStateUnchanged: (t, context) => assertAdminRecoveryFailureState(t, context, { skipSync: true }),
+	mutatePayload: (_t, payload) => payload,
+	applyInvalidPayload: async (context, invalidPayload) =>
+		applyWithValidatorBalanceUpdateFailure(context, invalidPayload),
+	expectedLogs: ['Failed to update validator balance.']
+}).performScenario();
+
+new OperationValidationScenarioBase({
+	title: 'State.apply adminRecovery rejects duplicate operations',
+	setupScenario: setupAdminRecoveryScenario,
+	buildValidPayload: buildAdminRecoveryPayload,
+	assertStateUnchanged: (t, context) => assertAdminRecoveryFailureState(t, context, { skipSync: true }),
+	mutatePayload: (_t, payload) => payload,
+	applyInvalidPayload: async (context, invalidPayload) =>
+		applyWithDuplicateOperation(context, invalidPayload),
+	expectedLogs: ['Operation has already been applied.']
+}).performScenario();
+
+new OperationValidationScenarioBase({
+	title: 'State.apply adminRecovery rejects when old writer key is absent in indexer list',
+	setupScenario: setupAdminRecoveryScenario,
+	buildValidPayload: buildAdminRecoveryPayload,
+	assertStateUnchanged: (t, context) => assertAdminRecoveryFailureState(t, context, { skipSync: true }),
+	mutatePayload: (_t, payload) => payload,
+	applyInvalidPayload: async (context, invalidPayload) =>
+		applyWithOldWriterKeyMissing(context, invalidPayload),
+	expectedLogs: ['Old writer key is not in indexer list.']
+}).performScenario();
+
+new OperationValidationScenarioBase({
+	title: 'State.apply adminRecovery rejects when new writer key already sits in indexer list',
+	setupScenario: setupAdminRecoveryScenario,
+	buildValidPayload: buildAdminRecoveryPayload,
+	assertStateUnchanged: (t, context) => assertAdminRecoveryFailureState(t, context, { skipSync: true }),
+	mutatePayload: (_t, payload) => payload,
+	applyInvalidPayload: async (context, invalidPayload) =>
+		applyWithNewWriterKeyPresent(context, invalidPayload),
+	expectedLogs: ['New writer key is already in indexer list.']
+}).performScenario();
+
+new OperationValidationScenarioBase({
+	title: 'State.apply adminRecovery rejects when admin node entry cannot be decoded after writing key update',
+	setupScenario: setupAdminRecoveryScenario,
+	buildValidPayload: buildAdminRecoveryPayload,
+	assertStateUnchanged: async t => t.pass('state unchanged check skipped for decode failure'),
+	mutatePayload: (_t, payload) => payload,
+	applyInvalidPayload: async (context, invalidPayload) =>
+		applyWithAdminNodeDecodeFailure(context, invalidPayload),
+	expectedLogs: ['Failed to decode node entry.']
+}).performScenario();

package/tests/unit/state/apply/appendWhitelist/appendWhitelistBanAndReapplyScenario.js

@@ -0,0 +1,78 @@
+import { test } from 'brittle';
+import b4a from 'b4a';
+import { eventFlush } from '../../../../helpers/autobaseTestHelpers.js';
+import nodeEntryUtils from '../../../../../src/core/state/utils/nodeEntry.js';
+import setupAppendWhitelistScenario, {
+	buildAppendWhitelistPayload,
+	buildBanWriterPayload,
+	selectReaderPeer,
+	assertReaderWhitelisted
+} from './appendWhitelistScenarioHelpers.js';
+
+export default function appendWhitelistBanAndReapplyScenario() {
+	test('State.apply appendWhitelist re-applies whitelisted role after ban without reallocating license', async t => {
+		const context = await setupAppendWhitelistScenario(t);
+		const adminNode = context.adminBootstrap;
+		const readerPeer = selectReaderPeer(context);
+
+		const initialWhitelistPayload = await buildAppendWhitelistPayload(
+			context,
+			readerPeer.wallet.address
+		);
+		await adminNode.base.append(initialWhitelistPayload);
+		await adminNode.base.update();
+		await eventFlush();
+
+		const { decodedEntry: initialWhitelistedEntry } = await assertReaderWhitelisted(
+			t,
+			adminNode.base,
+			readerPeer.wallet.address,
+			{ expectedLicenseCount: 2 }
+		);
+		const initialLicenseBuffer = b4a.from(initialWhitelistedEntry.license);
+
+		const banPayload = await buildBanWriterPayload(context, readerPeer.wallet.address);
+		await adminNode.base.append(banPayload);
+		await adminNode.base.update();
+		await eventFlush();
+
+		const readerEntryAfterBan = await adminNode.base.view.get(readerPeer.wallet.address);
+		t.ok(readerEntryAfterBan, 'reader entry persists after ban');
+		const decodedAfterBan = nodeEntryUtils.decode(readerEntryAfterBan.value);
+		t.ok(decodedAfterBan, 'reader entry decodes after ban');
+		t.is(decodedAfterBan.isWhitelisted, false, 'reader un-whitelisted after ban');
+		t.is(decodedAfterBan.isWriter, false, 'reader writer flag cleared after ban');
+		t.ok(
+			b4a.equals(decodedAfterBan.license, initialLicenseBuffer),
+			'license retained after ban'
+		);
+
+		const reapplyWhitelistPayload = await buildAppendWhitelistPayload(
+			context,
+			readerPeer.wallet.address
+		);
+		await adminNode.base.append(reapplyWhitelistPayload);
+		await adminNode.base.update();
+		await eventFlush();
+
+		const { decodedEntry: rewhitelistedEntry } = await assertReaderWhitelisted(
+			t,
+			adminNode.base,
+			readerPeer.wallet.address,
+			{ expectedLicenseCount: 2 }
+		);
+		t.ok(
+			b4a.equals(rewhitelistedEntry.license, initialLicenseBuffer),
+			'license reused when reader re-whitelisted'
+		);
+
+		await context.sync();
+
+		const syncedEntry = await readerPeer.base.view.get(readerPeer.wallet.address);
+		t.ok(syncedEntry, 'reader entry replicated on peer');
+		const decodedSyncedEntry = nodeEntryUtils.decode(syncedEntry.value);
+		t.ok(decodedSyncedEntry, 'replicated entry decodes');
+		t.is(decodedSyncedEntry.isWhitelisted, true, 'reader flagged as whitelisted after reapply');
+		t.ok(b4a.equals(decodedSyncedEntry.license, initialLicenseBuffer),'license stable across ban/reapply cycle');
+	});
+}

package/tests/unit/state/apply/appendWhitelist/appendWhitelistExistingReaderHappyPathScenario.js

@@ -0,0 +1,98 @@
+import { test } from 'brittle';
+import b4a from 'b4a';
+import { eventFlush } from '../../../../helpers/autobaseTestHelpers.js';
+import nodeEntryUtils, { ZERO_LICENSE } from '../../../../../src/core/state/utils/nodeEntry.js';
+import { toTerm } from '../../../../../src/core/state/utils/balance.js';
+import { safeDecodeApplyOperation } from '../../../../../src/utils/protobuf/operationHelpers.js';
+import setupAppendWhitelistScenario, {
+	buildAppendWhitelistPayload,
+	selectReaderPeer,
+	assertReaderWhitelisted
+} from './appendWhitelistScenarioHelpers.js';
+import { buildBalanceInitializationPayload } from '../balanceInitialization/balanceInitializationScenarioHelpers.js';
+
+export default function appendWhitelistExistingReaderHappyPathScenario() {
+	test('State.apply appendWhitelist upgrades initialized readers without altering their balances', async t => {
+		const context = await setupAppendWhitelistScenario(t);
+		const adminNode = context.adminBootstrap;
+		const readerPeer = selectReaderPeer(context);
+		const initialReaderBalance = toTerm(75n);
+
+		const adminNodeEntryBefore = await adminNode.base.view.get(adminNode.wallet.address);
+		t.ok(adminNodeEntryBefore, 'admin node entry exists');
+		const decodedAdminBefore = nodeEntryUtils.decode(adminNodeEntryBefore.value);
+		t.ok(decodedAdminBefore, 'admin node entry decodes');
+		const adminBalanceSnapshot = decodedAdminBefore.balance && b4a.from(decodedAdminBefore.balance);
+
+		const balanceInitializationPayload = await buildBalanceInitializationPayload(
+			context,
+			readerPeer.wallet.address,
+			initialReaderBalance
+		);
+		await adminNode.base.append(balanceInitializationPayload);
+		await adminNode.base.update();
+		await eventFlush();
+
+		const readerEntryAfterInitialization = await adminNode.base.view.get(readerPeer.wallet.address);
+		t.ok(readerEntryAfterInitialization, 'reader entry created via balance initialization');
+		const decodedReaderBeforeWhitelist = nodeEntryUtils.decode(readerEntryAfterInitialization.value);
+		t.ok(decodedReaderBeforeWhitelist, 'reader entry decodes before whitelist');
+		t.ok(
+			b4a.equals(decodedReaderBeforeWhitelist.balance, initialReaderBalance),
+			'reader balance stored during initialization'
+		);
+		t.is(decodedReaderBeforeWhitelist.isWhitelisted, false, 'reader not whitelisted yet');
+		t.ok(
+			b4a.equals(decodedReaderBeforeWhitelist.license, ZERO_LICENSE),
+			'reader license absent before whitelist'
+		);
+
+		const appendWhitelistPayload = await buildAppendWhitelistPayload(
+			context,
+			readerPeer.wallet.address
+		);
+		const decodedPayload = safeDecodeApplyOperation(appendWhitelistPayload);
+		t.ok(decodedPayload, 'append whitelist payload decodes');
+		const whitelistTxHash = decodedPayload?.aco?.tx?.toString('hex');
+		t.ok(whitelistTxHash, 'whitelist tx hash extracted');
+
+		await adminNode.base.append(appendWhitelistPayload);
+		await adminNode.base.update();
+		await eventFlush();
+
+		const { decodedEntry: decodedReaderAfterWhitelist } = await assertReaderWhitelisted(
+			t,
+			adminNode.base,
+			readerPeer.wallet.address,
+			{ expectedLicenseCount: 2 }
+		);
+		t.ok(
+			b4a.equals(decodedReaderAfterWhitelist.balance, initialReaderBalance),
+			'reader balance preserved after whitelist append'
+		);
+
+		const adminNodeEntryAfter = await adminNode.base.view.get(adminNode.wallet.address);
+		const decodedAdminAfter = nodeEntryUtils.decode(adminNodeEntryAfter.value);
+		t.ok(decodedAdminAfter, 'admin node entry decodes after whitelist append');
+		t.ok(
+			b4a.equals(decodedAdminAfter.balance, adminBalanceSnapshot),
+			'admin balance remains unchanged while initialization enabled'
+		);
+
+		const txEntry = await adminNode.base.view.get(whitelistTxHash);
+		t.ok(txEntry, 'whitelist transaction recorded to prevent replays');
+
+		await context.sync();
+
+		const { decodedEntry: readerReplicaEntry } = await assertReaderWhitelisted(
+			t,
+			readerPeer.base,
+			readerPeer.wallet.address,
+			{ expectedLicenseCount: 2 }
+		);
+		t.ok(
+			b4a.equals(readerReplicaEntry.balance, initialReaderBalance),
+			'reader balance replicated with whitelist role'
+		);
+	});
+}

package/tests/unit/state/apply/appendWhitelist/appendWhitelistFeeAfterDisableScenario.js

@@ -0,0 +1,66 @@
+import { test } from 'brittle';
+import b4a from 'b4a';
+import { eventFlush } from '../../../../helpers/autobaseTestHelpers.js';
+import nodeEntryUtils from '../../../../../src/core/state/utils/nodeEntry.js';
+import { toBalance, BALANCE_FEE } from '../../../../../src/core/state/utils/balance.js';
+import setupAppendWhitelistScenario, {
+	buildAppendWhitelistPayload,
+	selectReaderPeer,
+	assertReaderWhitelisted
+} from './appendWhitelistScenarioHelpers.js';
+import {
+	buildDisableInitializationPayload,
+	assertInitializationDisabledState
+} from '../disableInitialization/disableInitializationScenarioHelpers.js';
+
+export default function appendWhitelistFeeAfterDisableScenario() {
+	test('State.apply appendWhitelist charges admin fee once initialization is disabled', async t => {
+		const context = await setupAppendWhitelistScenario(t);
+		const adminNode = context.adminBootstrap;
+		const readerPeer = selectReaderPeer(context);
+
+		const disablePayload = await buildDisableInitializationPayload(context);
+		await adminNode.base.append(disablePayload);
+		await adminNode.base.update();
+		await eventFlush();
+		await assertInitializationDisabledState(t, adminNode.base, disablePayload);
+
+		const adminEntryBefore = await adminNode.base.view.get(adminNode.wallet.address);
+		t.ok(adminEntryBefore, 'admin node entry exists after disabling initialization');
+		const decodedAdminBefore = nodeEntryUtils.decode(adminEntryBefore.value);
+		t.ok(decodedAdminBefore, 'admin node entry decodes before fee is applied');
+		const adminBalanceBefore = toBalance(decodedAdminBefore.balance);
+		t.ok(adminBalanceBefore, 'admin balance decodes');
+
+		const whitelistPayload = await buildAppendWhitelistPayload(
+			context,
+			readerPeer.wallet.address
+		);
+		await adminNode.base.append(whitelistPayload);
+		await adminNode.base.update();
+		await eventFlush();
+
+		await assertReaderWhitelisted(t, adminNode.base, readerPeer.wallet.address, {
+			expectedLicenseCount: 2
+		});
+
+		const adminEntryAfter = await adminNode.base.view.get(adminNode.wallet.address);
+		const decodedAdminAfter = nodeEntryUtils.decode(adminEntryAfter.value);
+		t.ok(decodedAdminAfter, 'admin node entry decodes after fee is applied');
+		const adminBalanceAfter = toBalance(decodedAdminAfter.balance);
+		t.ok(adminBalanceAfter, 'admin balance decodes after fee is applied');
+
+		const expectedBalance = adminBalanceBefore.sub(BALANCE_FEE);
+		t.ok(expectedBalance, 'fee subtraction succeeds');
+		t.ok(
+			b4a.equals(adminBalanceAfter.value, expectedBalance.value),
+			'admin balance reduced by BALANCE_FEE when initialization disabled'
+		);
+
+		await context.sync();
+
+		await assertReaderWhitelisted(t, readerPeer.base, readerPeer.wallet.address, {
+			expectedLicenseCount: 2
+		});
+	});
+}