# identity/actions
Documentation: next (source: develop).

Install the preview: `pnpm add @aephia/atlas-kit@next`. These docs follow develop and may include changes not yet published to npm.

Markdown source of https://develop.atlas-kit-docs.pages.dev/reference/identity/actions/ — see https://develop.atlas-kit-docs.pages.dev/ai/ for the full machine-readable surface.

## Interfaces

<a id="plancreateprofileoptions"></a>

### PlanCreateProfileOptions

Defined in: [packages/sage/src/identity/actions/create-profile.ts:38](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/identity/actions/create-profile.ts#L38)

Explicit storage funder, ordered keys, and protected Profile update threshold.
No permissions or threshold are selected automatically.

#### Example

```ts
declare const funder: Address;
declare const keys: readonly ProfileCreationKeyInput[];
const options: PlanCreateProfileOptions = {funder, keys, keyThreshold: 1};
```

#### Properties

<a id="funder"></a>

##### funder

```ts
readonly funder: Address;
```

Defined in: [packages/sage/src/identity/actions/create-profile.ts:39](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/identity/actions/create-profile.ts#L39)

<a id="keys"></a>

##### keys

```ts
readonly keys: readonly ProfileCreationKeyInput[];
```

Defined in: [packages/sage/src/identity/actions/create-profile.ts:40](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/identity/actions/create-profile.ts#L40)

<a id="keythreshold"></a>

##### keyThreshold

```ts
readonly keyThreshold: number;
```

Defined in: [packages/sage/src/identity/actions/create-profile.ts:41](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/identity/actions/create-profile.ts#L41)

***

<a id="planregistercharacteroptions"></a>

### PlanRegisterCharacterOptions

Defined in: [packages/sage/src/identity/actions/index.ts:31](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/identity/actions/index.ts#L31)

Address of the external signer that will fund Character account storage.
Character registration has no Profile-authority or faction signer role.

#### Example

```ts
declare const funder: Address;
const options:PlanRegisterCharacterOptions={funder};
```

#### Properties

<a id="funder-1"></a>

##### funder

```ts
readonly funder: Address;
```

Defined in: [packages/sage/src/identity/actions/index.ts:32](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/identity/actions/index.ts#L32)

***

<a id="planunlockresearchnodeoptions"></a>

### PlanUnlockResearchNodeOptions

Defined in: [packages/sage/src/identity/actions/research-unlock.ts:33](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/identity/actions/research-unlock.ts#L33)

Address-only options for one explicit research node unlock.
`system` names the Starbase where the Character's Starbase Player pays any
cargo cost; `level` is the level the node reaches, its current level plus one.

#### Example

```ts
declare const profile: Address, authority: Address, system: Address;
const options: PlanUnlockResearchNodeOptions = {
  authorization: { profile, authority, keyIndex: 0 },
  system,
  level: 1,
};
```

#### Properties

<a id="authorization"></a>

##### authorization

```ts
readonly authorization: PlanAuthorization;
```

Defined in: [packages/sage/src/identity/actions/research-unlock.ts:34](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/identity/actions/research-unlock.ts#L34)

<a id="level"></a>

##### level

```ts
readonly level: number;
```

Defined in: [packages/sage/src/identity/actions/research-unlock.ts:36](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/identity/actions/research-unlock.ts#L36)

<a id="system"></a>

##### system

```ts
readonly system: Address;
```

Defined in: [packages/sage/src/identity/actions/research-unlock.ts:35](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/identity/actions/research-unlock.ts#L35)

***

<a id="profilecreationkeyinput"></a>

### ProfileCreationKeyInput

Defined in: [packages/sage/src/identity/actions/create-profile.ts:22](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/identity/actions/create-profile.ts#L22)

One explicitly scoped key and its exact unsigned 64-bit permission mask.
`expiresAt` is a nonnegative Unix timestamp in seconds; omission means no expiry.
Profile AUTH keys must omit expiry and must be directly signing addresses.

#### Example

```ts
declare const authority: Address;
declare const playerProfileProgram: Address;
const key: ProfileCreationKeyInput = {address: authority, scope: playerProfileProgram, permissionsRaw: 1n};
```

#### Properties

<a id="address"></a>

##### address

```ts
readonly address: Address;
```

Defined in: [packages/sage/src/identity/actions/create-profile.ts:23](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/identity/actions/create-profile.ts#L23)

<a id="expiresat"></a>

##### expiresAt?

```ts
readonly optional expiresAt?: bigint;
```

Defined in: [packages/sage/src/identity/actions/create-profile.ts:26](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/identity/actions/create-profile.ts#L26)

<a id="permissionsraw"></a>

##### permissionsRaw

```ts
readonly permissionsRaw: bigint;
```

Defined in: [packages/sage/src/identity/actions/create-profile.ts:25](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/identity/actions/create-profile.ts#L25)

<a id="scope"></a>

##### scope

```ts
readonly scope: Address;
```

Defined in: [packages/sage/src/identity/actions/create-profile.ts:24](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/identity/actions/create-profile.ts#L24)

## Functions

<a id="plancreateprofile"></a>

### planCreateProfile()

```ts
function planCreateProfile(
   ctx, 
   profileAddress, 
input): Promise<Plan>;
```

Defined in: [packages/sage/src/identity/actions/create-profile.ts:200](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/identity/actions/create-profile.ts#L200)

Plans a new signer-created Profile with explicit scoped permissions.
The new Profile, storage funder, and every Player Profile AUTH key sign creation,
even when the editing threshold is lower. Other keys remain readonly.
The new Profile signer is needed only for creation unless explicitly listed
among the initial authority keys; creating the account does not grant it AUTH.
The threshold governs protected Profile updates; it is not a gameplay-wide multisig policy.
Existing target accounts and a Profile address equal to its funder are rejected.
No Game load, onboarding, funding top-up, key generation or signing is implicit.
Storage rent, balances and final creation remain chain-authoritative. Simulate
before requesting signatures; after confirmed execution, read `getProfile` and
verify the exact keys, scopes, permission masks and threshold.

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `ctx` | [`SageContext`](/reference/#sagecontext) |
| `profileAddress` | `Address` |
| `input` | [`PlanCreateProfileOptions`](/reference/identity/actions/#plancreateprofileoptions) |

#### Returns

`Promise`\<[`Plan`](/reference/planning/#plan)\>

#### Example

```ts
import {planCreateProfile} from '@aephia/atlas-kit/identity/actions';
declare const ctx: SageContext;
declare const profileAddress: Address;
declare const options: PlanCreateProfileOptions;
const plan = await planCreateProfile(ctx, profileAddress, options);
console.log(plan.summary, plan.requiredSigners);
```

***

<a id="planregistercharacter"></a>

### planRegisterCharacter()

```ts
function planRegisterCharacter(
   ctx, 
   profileAddress, 
input): Promise<Plan>;
```

Defined in: [packages/sage/src/identity/actions/index.ts:85](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/identity/actions/index.ts#L85)

Plans creation of an existing Profile's canonical Character in the configured Game.
Only the explicit storage funder signs. The Profile's authority and faction
enrollment are not prerequisites for this instruction. Planning never creates
an account, signs, submits, or retains a signer. Existing Characters are rejected;
reuse them through `getCharacterForProfile` or `maybeGetCharacterForProfile`.
New Plans bind the current Game-2 Character and Career XP creation intent.
The canonical accounts, absence, storage pricing, and funder balance are
revalidated before signing. Final creation remains chain-authoritative. Simulate
before signing and read the Character after confirmed execution to verify its
exact Profile/Game identity. Submission alone does not prove creation.

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `ctx` | [`SageContext`](/reference/#sagecontext) |
| `profileAddress` | `Address` |
| `input` | [`PlanRegisterCharacterOptions`](/reference/identity/actions/#planregistercharacteroptions) |

#### Returns

`Promise`\<[`Plan`](/reference/planning/#plan)\>

#### Example

```ts
import {planRegisterCharacter} from '@aephia/atlas-kit/identity/actions';
import type {SageContext,Address} from '@aephia/atlas-kit/client';
declare const ctx:SageContext;
declare const profileAddress:Address;
declare const funder:Address;
const plan=await planRegisterCharacter(ctx,profileAddress,{funder});
console.log(plan.summary,plan.requiredSigners);
```

***

<a id="planunlockresearchnode"></a>

### planUnlockResearchNode()

```ts
function planUnlockResearchNode(
   ctx, 
   nodeId, 
input): Promise<Plan>;
```

Defined in: [packages/sage/src/identity/actions/research-unlock.ts:120](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/identity/actions/research-unlock.ts#L120)

Plans one explicit research node unlock: the node's next level for the
Profile's Character, paid at one of its current Starbase Players.
Every required research tag, minimum category level, research point or
Renown cost, and ATLAS and Starbase Player cargo cost grown linearly with
the current level and rounded down, is checked from fresh accounts, with an
exact shortfall when one is missing. The Character's research and XP must
match the current Game definitions: the program resynchronizes a stale
Character itself when at most 8 node levels are pending, but its result
decides eligibility, so the planner refuses with the next step (any SAGE
action that validates the Character, or `syncCharacter`). Daily XP costs are
refused as unqualified. Uses a direct Profile AUTH key or a doResearch key
scoped to SAGE or the Game; certificates are unsupported. The program funds
the Character's storage growth, and any Starbase Player rent shortfall, from
the Profile vault with the signing key:
the Plan bounds that Profile lamport debit from the node's new entries, and
a positive debit needs Profile AUTH or a key that also holds drainSolVault,
plus Profile lamports above its own rent reserve. The Plan never chooses a
level, unlocks prerequisites, synchronizes the Character or signs.
Eligibility, definition sequences, the observed ATLAS debit and the Profile
storage debit are rechecked before signing; the ceilings are not atomic
on-chain caps. The program folds the node's tags and modifier into the
Character, and the resulting modifiers remain chain-authoritative: simulate
before signing and read the Character after confirmed execution. One unlock
per Character composes into a transaction.

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `ctx` | [`SageContext`](/reference/#sagecontext) |
| `nodeId` | `number` |
| `input` | [`PlanUnlockResearchNodeOptions`](/reference/identity/actions/#planunlockresearchnodeoptions) |

#### Returns

`Promise`\<[`Plan`](/reference/planning/#plan)\>

#### Example

```ts
import { planUnlockResearchNode } from '@aephia/atlas-kit/identity/actions';
declare const ctx: SageContext;
declare const profile: Address, authority: Address, system: Address;
const plan = await planUnlockResearchNode(ctx, 62, {
  authorization: { profile, authority, keyIndex: 0 },
  system,
  level: 1,
});
console.log(plan.describe());
```