ARCHIVE/xrpl-dev-portal
1
0
Fork 0
mirror of https://github.com/XRPLF/xrpl-dev-portal.git synced 2025-11-14 16:55:50 +00:00
Code Issues Packages Projects Releases Wiki Activity

add permissioned domain modular tutorial

Browse Source
This commit is contained in:
Oliver Eggert
2025-04-29 13:38:48 -07:00
parent 9befa993bf
commit cd539662c4
12 changed files with 757 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

11
_code-samples/modular-tutorials/account-support.js
View File

@@ -206,3 +206,14 @@ async function getTokenBalance() {
}
} // End of getTokenBalance()
// *******************************************************
// **************** Scroll Results ***********************
// *******************************************************
let results
async function updateResults() {
resultField.value += results;
resultField.scrollTop = resultField.scrollHeight;
}
// End of updateResults()

211
_code-samples/modular-tutorials/create-permissioned-domain.html Normal file
View File

@@ -0,0 +1,211 @@
<html>
<head>
<title>Create Permissioned Domain</title>
<link href='https://fonts.googleapis.com/css?family=Work Sans' rel='stylesheet'>
<link href="modular-tutorials.css" rel="stylesheet">
<script src='https://unpkg.com/xrpl@4.2.5/build/xrpl-latest.js'></script>
<script src="account-support.js"></script>
<script src='credential-manager.js'></script>
<script src='permissioned-domain-manager.js'></script>
</head>
<!-- ************************************************************** -->
<!-- ********************** The Form ****************************** -->
<!-- ************************************************************** -->
<body>
<h1>Create Permissioned Domain</h1>
<form id="theForm">
<span class="tooltip" tooltip-data="Choose the XRPL host server for your account.">
Choose your ledger instance:
</span>
&nbsp;&nbsp;
<input type="radio" id="dn" name="server" value="wss://s.devnet.rippletest.net:51233" checked>
<label for="dn">Devnet</label>
&nbsp;&nbsp;
<input type="radio" id="tn" name="server" value="wss://s.altnet.rippletest.net:51233">
<label for="tn">Testnet</label>
<br /><br />
<table>
<tr>
<td>
<button type="button" onClick="getNewAccount1()">Get New Account 1</button>
</td>
<td>
<button type="button" onClick="getAccountFromSeed1()">Get Account 1 From Seed</button>
</td>
<td>
<button type="button" onClick="getNewAccount2()">Get New Account 2</button>
</td>
<td>
<button type="button" onClick="getAccountFromSeed2()">Get Account 2 From Seed</button>
</td>
</tr>
<tr>
<td>
<span class="tooltip" tooltip-data="Arbitrary human-readable name for the account."><label for="account1name">Account 1 Name</label>
</span>
</td>
<td>
<input type="text" id="account1name" size="40"></input>
</td>
<td>
<span class="tooltip" tooltip-data="Arbitrary human-readable name for the account.">
<label for="account2name">Account 2 Name</label>
</span>
</td>
<td>
<input type="text" id="account2name" size="40"></input>
</td>
</tr>
<tr>
<td>
<span class="tooltip" tooltip-data="Identifying address for the account.">
<label for="account1address">Account 1 Address</label>
</span>
</td>
<td>
<input type="text" id="account1address" size="40"></input>
</td>
<td>
<span class="tooltip" tooltip-data="Identifying address for the account.">
<label for="account2address">Account 2 Address</label>
</span>
</td>
<td>
<input type="text" id="account2address" size="40"></input>
</td>
</tr>
<tr>
<td>
<span class="tooltip" tooltip-data="Seed for deriving public and private keys for the account.">
<label for="account1seed">Account 1 Seed</label>
</span>
</td>
<td>
<input type="text" id="account1seed" size="40"></input>
</td>
<td>
<span class="tooltip" tooltip-data="Seed for deriving public and private keys for the account.">
<label for="account2seed">Account 2 Seed</label>
</span>
</td>
<td>
<input type="text" id="account2seed" size="40"></input>
</td>
</tr>
</table>
<hr />
<table>
<tr valign="top">
<td align="right">
<span class="tooltip" tooltip-data="Name of the currently selected account.">
<label for="accountNameField">Account Name</label>
</span>
</td>
<td>
<input type="text" id="accountNameField" size="40" readonly></input>
<input type="radio" id="account1" name="accounts" value="account1">
<label for="account1">Account 1</label>
</td>
</tr>
<tr valign="top">
<td align="right">
<span class="tooltip" tooltip-data="Address of the currently selected account.">
<label for="accountAddressField">Account Address</label>
</span>
</td>
<td>
<input type="text" id="accountAddressField" size="40" readonly></input>
<input type="radio" id="account2" name="accounts" value="account2">
<label for="account2">Account 2</label>
</td>
</tr>
<tr valign="top">
<td align="right">
<span class="tooltip" tooltip-data="Seed of the currently selected account.">
<label for="accountSeedField">Account Seed</label>
</span>
</td>
<td>
<input type="text" id="accountSeedField" size="40" readonly></input>
<br>
</td>
</tr>
<tr>
<td align="right">
<span class="tooltip" tooltip-data="XRP balance for the currently selected account.">
<label for="xrpBalanceField">XRP Balance</label>
</span>
</td>
<td>
<input type="text" id="xrpBalanceField" size="40" readonly></input>
</td>
</tr>
<tr>
<td align="right">
<span class="tooltip" tooltip-data="Account receiving the credential.">
<label for="subjectField">Subject</label>
</span>
</td>
<td>
<input type="text" id="subjectField" size="40"></input>
<br>
</td>
<td align="left" valign="top">
<button type="button" onClick="createCredential()">Create Credential</button>
</td>
</tr>
<tr>
<td align="right">
<span class="tooltip" tooltip-data="Arbitrary data defining the type of credential this entry represents.">
<lable for="credentialTypeField">Credential Type</lable>
</span>
</td>
<td>
<input type="text" id="credentialTypeField" size="40"></input>
<br>
</td>
</tr>
<tr>
<td align="right">
<span class="tooltip" tooltip-data="The ledger entry ID of an existing permissioned domain to modify. If omitted, creates a new permissioned domain.">
<label for="domainIDField">Domain ID</label>
</span>
</td>
<td>
<input type="text" id="domainIDField" size="40"></input>
<br>
</td>
<td align="left" valign="top">
<button type="button" onClick="createDomain()">Create Permissioned Domain</button>
<button type="button" onClick="deleteDomain()">Delete Permissioned Domain</button>
</td>
</tr>
<tr>
<td colspan="2">
<p align="right">
<textarea id="resultField" cols="80" rows="20"></textarea>
</p>
</td>
<td align="left" valign="top">
<button type="button" onClick="gatherAccountInfo()">Gather Account Info</button><br/>
<button type="button" onClick="distributeAccountInfo()">Distribute Account Info</button>
</td>
</tr>
</table>
</form>
</body>
<script>
const radioButtons = document.querySelectorAll('input[type="radio"]');
radioButtons.forEach(radio => {
radio.addEventListener('change', function() {
if (this.value === 'account1') {
populate1()
} else if (this.value === 'account2') {
populate2()
}
});
});
</script>
</html>

66
_code-samples/modular-tutorials/credential-manager.js Normal file
View File

@@ -0,0 +1,66 @@
// *******************************************************
// *********** Create Credential *************************
// *******************************************************
async function createCredential() {
let net = getNet()
const client = new xrpl.Client(net)
results = `\n\n===Creating Credential===\n\nConnecting to ${getNet()} ...`
updateResults()
await client.connect()
results = `\n\nConnected.`
updateResults()
try {
// Get account wallet from seed
const wallet = xrpl.Wallet.fromSeed(accountSeedField.value)
// Get subject
const subject = subjectField.value
// Get credential type - convert string to hex if needed
let credentialType = credentialTypeField.value;
if (!/^[0-9A-F]+$/i.test(credentialType)) {
let hex = '';
for (let i = 0; i < credentialType.length; i++) {
const charCode = credentialType.charCodeAt(i);
const hexCharCode = charCode.toString(16).padStart(2, '0');
hex += hexCharCode;
}
credentialType = hex.toUpperCase();
}
// Prepare transaction
const transaction = {
"TransactionType": "CredentialCreate",
"Account": wallet.address,
"Subject": subject,
"CredentialType": credentialType
}
results = `\n\n===Preparing and Sending Transaction===\n\n${JSON.stringify(transaction, null, 2)}`
updateResults()
// Submit transaction
const tx = await client.submitAndWait(transaction, {autofill: true, wallet: wallet})
if (tx.result.meta.TransactionResult == "tesSUCCESS") {
// Parse for credential info
const parsedResponse = JSON.parse(JSON.stringify(tx.result.meta.AffectedNodes, null, 2))
const credentialInfo = parsedResponse.find( node => node.CreatedNode && node.CreatedNode.LedgerEntryType === "Credential" )
results = `\n\n===Create Credential Result===\n\n${JSON.stringify(credentialInfo.CreatedNode, null, 2)}`
} else {
results = `\n\n===Error===\n\n${JSON.stringify(tx.result.meta.TransactionResult, null, 2)}: Check codes at https://xrpl.org/docs/references/protocol/transactions/types/credentialcreate#error-cases`
}
updateResults()
} catch (error) {
results = `\n\n===Error===\n\n${error}`
updateResults()
}
client.disconnect()
}

129
_code-samples/modular-tutorials/permissioned-domain-manager.js Normal file
View File

@@ -0,0 +1,129 @@
// *******************************************************
// *********** Create Permissioned Domain ****************
// *******************************************************
async function createDomain() {
let net = getNet()
const client = new xrpl.Client(net)
results = `\n\n===Creating Permissioned Domain===\n\nConnecting to ${getNet()} ...`
updateResults()
await client.connect()
results = `\n\nConnected.`
updateResults()
try {
// Get account wallet from seed
const wallet = xrpl.Wallet.fromSeed(accountSeedField.value)
// Get Domain ID
const domainID = domainIDField.value
// Get credential type - convert string to hex if needed
let credentialType = credentialTypeField.value;
if (!/^[0-9A-F]+$/i.test(credentialType)) {
let hex = '';
for (let i = 0; i < credentialType.length; i++) {
const charCode = credentialType.charCodeAt(i);
const hexCharCode = charCode.toString(16).padStart(2, '0');
hex += hexCharCode;
}
credentialType = hex.toUpperCase();
}
// Prepare transaction
const transaction = {
"TransactionType": "PermissionedDomainSet",
"Account": wallet.address,
"AcceptedCredentials": [
{
"Credential": {
"Issuer": wallet.address,
"CredentialType": credentialType
}
}
]
}
if (domainID) {
transaction.DomainID = domainID
}
results = `\n\n===Preparing and Sending Transaction===\n\n${JSON.stringify(transaction, null, 2)}`
updateResults()
// Submit transaction
const tx = await client.submitAndWait(transaction, {autofill: true, wallet: wallet})
if (tx.result.meta.TransactionResult == "tesSUCCESS") {
// Parse for domain info
if (domainID) {
results = `\n\n===Create Permissioned Domain Result===\n\n${JSON.stringify(tx.result.tx_json, null, 2)}`
} else {
const parsedResponse = JSON.parse(JSON.stringify(tx.result.meta.AffectedNodes, null, 2))
const domainInfo = parsedResponse.find( node => node.CreatedNode && node.CreatedNode.LedgerEntryType === "PermissionedDomain" )
results = `\n\n===Create Permissioned Domain Result===\n\n${JSON.stringify(domainInfo.CreatedNode, null, 2)}`
}
} else {
results = `\n\n===Error===\n\n${JSON.stringify(tx.result.meta.TransactionResult, null, 2)}: Check codes at https://xrpl.org/docs/references/protocol/transactions/types/permissioneddomainset#error-cases`
}
updateResults()
} catch (error) {
results = `\n\n===Error===\n\n${error}`
updateResults()
}
client.disconnect()
}
// *******************************************************
// *********** Delete Permissioned Domain ****************
// *******************************************************
async function deleteDomain() {
let net = getNet()
const client = new xrpl.Client(net)
results = `\n\n===Delete Permissioned Domain===\n\nConnecting to ${getNet()} ...`
updateResults()
await client.connect()
results = `\n\nConnected.`
updateResults()
try {
// Get account wallet from seed
const wallet = xrpl.Wallet.fromSeed(accountSeedField.value)
// Get Domain ID
const domainID = domainIDField.value
// Prepare transaction
const transaction = {
"TransactionType": "PermissionedDomainDelete",
"Account": wallet.address,
"DomainID": domainID
}
results = `\n\n===Preparing and Sending Transaction===\n\n${JSON.stringify(transaction, null, 2)}`
updateResults()
// Submit transaction
const tx = await client.submitAndWait(transaction, {autofill: true, wallet: wallet})
if (tx.result.meta.TransactionResult == "tesSUCCESS") {
results = `\n\n===Delete Permissioned Domain Result===\n\nSuccessfully deleted the permissioned domain.`
} else {
results = `\n\n===Error===\n\n${JSON.stringify(tx.result.meta.TransactionResult, null, 2)}: Check codes at https://xrpl.org/docs/references/protocol/transactions/types/permissioneddomaindelete#error-cases`
}
updateResults()
} catch (error) {
results = `\n\n===Error===\n\n${error}`
updateResults()
}
client.disconnect()
}

BIN
docs/img/create-permissioned-domain-1.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 54 KiB

BIN
docs/img/create-permissioned-domain-2.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 63 KiB

BIN
docs/img/create-permissioned-domain-3.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 94 KiB

BIN
docs/img/create-permissioned-domain-4.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 89 KiB

BIN
docs/img/create-permissioned-domain-5.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 90 KiB

322
docs/tutorials/javascript/decentralized-finance/create-permissioned-domains.md Normal file
View File

@@ -0,0 +1,322 @@
---
seo:
description: Create a permissioned domain to restrict access to financial services that meet compliance requirements.
labels:
- Decentralized Finance
- Permissioned Domains
---
# Create Permissioned Domains
Permissioned domains are controlled environments within the broader ecosystem of the XRP Ledger blockchain. Domains restrict access to other features such as Permissioned DEXes and Lending Protocols, only allowing access to them for accounts with specific credentials.
This example shows how to:
1. Issue a credential to an account.
2. Create a permissioned domain with the issued credential.
3. Delete the permissioned domain.
[![Create Permissioned Domain Test Harness](/docs/img/create-permissioned-domain-1.png)](/docs/img/create-permissioned-domain-1.png)
Download the [Modular Tutorials](https://github.com/XRPLF/xrpl-dev-portal/tree/master/_code-samples/modular-tutorials/)<!-- {.github-code-download} --> folder.
{% admonition type="info" name="Note" %}
Without the Modular Tutorial Samples, you will not be able to try the examples that follow.
{% /admonition %}
## Get Accounts
To get test accounts:
1. Open `create-permissioned-domains.html` in a browser.
2. Get test accounts.
- If you copied the gathered information from another tutorial:
1. Paste the gathered information to the **Result** field.
2. Click **Distribute Account Info**.
- If you have an existing account seed:
1. Paste the account seed to the **Account 1 Seed** or **Account 2 Seed** field.
2. Click **Get Account 1 from Seed** or **Get Account 2 from Seed**.
- If you do not have existing accounts:
1. Click **Get New Account 1**.
2. Click **Get New Account 2**.
[![Created Accounts](/docs/img/create-permissioned-domain-2.png)](/docs/img/create-permissioned-domain-2.png)
## Issue a Credential
1. Click the **Account 1** radial button. This account will the credential issuer.
2. Copy the account 2 address into **Subject**.
3. Enter a **Credential Type**. For example, _KYC_.
4. Click **Create Credential**.
[![Created Credential](/docs/img/create-permissioned-domain-3.png)](/docs/img/create-permissioned-domain-3.png)
## Create a Permissioned Domain
1. Click **Create Permissioned Domain**.
2. Copy the _LedgerIndex_ value from the metadata response.
3. (Optional) Update the permissioned domain with a different credential.
1. Change the **Credential Type**.
2. Click **Create Credential**
3. Copy the _LedgerIndex_ value into **DomainID**.
4. Click **Create Permissioned Domain**.
[![Created Domain](/docs/img/create-permissioned-domain-4.png)](/docs/img/create-permissioned-domain-4.png)
## Delete a Permissioned Domain
1. Copy the _LedgerIndex_ value into **DomainID**.
2. Click **Delete Permissioned Domain**..
[![Deleted Domain](/docs/img/create-permissioned-domain-5.png)](/docs/img/create-permissioned-domain-5.png)
# Code Walkthrough
## credential-manager.js
### Create Credential
Define a function that issues a credential to a subject, converting strings to hex if necessary.
```javascript
async function createCredential() {
```
Connect to the XRP Ledger.
```javascript
let net = getNet()
const client = new xrpl.Client(net)
results = `\n\n===Creating Credential===\n\nConnecting to ${getNet()} ...`
updateResults()
await client.connect()
results = `\n\nConnected.`
updateResults()
```
Gather the issuer information, subject, and credential type. Convert the credential type value to a hex string if not already in hex. Wrap the code in a `try-catch` block to handle errors.
```javascript
try {
// Get account wallet from seed
const wallet = xrpl.Wallet.fromSeed(accountSeedField.value)
// Get subject
const subject = subjectField.value
// Get credential type - convert string to hex if needed
let credentialType = credentialTypeField.value;
if (!/^[0-9A-F]+$/i.test(credentialType)) {
let hex = '';
for (let i = 0; i < credentialType.length; i++) {
const charCode = credentialType.charCodeAt(i);
const hexCharCode = charCode.toString(16).padStart(2, '0');
hex += hexCharCode;
}
credentialType = hex.toUpperCase();
}
// Prepare transaction
const transaction = {
"TransactionType": "CredentialCreate",
"Account": wallet.address,
"Subject": subject,
"CredentialType": credentialType
}
```
Submit the `CredentialCreate` transaction and report the results. Parse the metadata response to return only relevant credential info.
```javascript
results = `\n\n===Preparing and Sending Transaction===\n\n${JSON.stringify(transaction, null, 2)}`
updateResults()
// Submit transaction
const tx = await client.submitAndWait(transaction, {autofill: true, wallet: wallet})
if (tx.result.meta.TransactionResult == "tesSUCCESS") {
// Parse for credential info
const parsedResponse = JSON.parse(JSON.stringify(tx.result.meta.AffectedNodes, null, 2))
const credentialInfo = parsedResponse.find( node => node.CreatedNode && node.CreatedNode.LedgerEntryType === "Credential" )
results = `\n\n===Create Credential Result===\n\n${JSON.stringify(credentialInfo.CreatedNode, null, 2)}`
} else {
results = `\n\n===Error===\n\n${JSON.stringify(tx.result.meta.TransactionResult, null, 2)}: Check codes at https://xrpl.org/docs/references/protocol/transactions/types/credentialcreate#error-cases`
}
updateResults()
} catch (error) {
results = `\n\n===Error===\n\n${error}`
updateResults()
}
client.disconnect()
}
```
## permissioned-domain-manager.js
### Create Permissioned Domain
Define a function that creates a permissioned domain.
```javascript
async function createDomain() {
```
Connect to the XRP Ledger.
```javascript
let net = getNet()
const client = new xrpl.Client(net)
results = `\n\n===Creating Permissioned Domain===\n\nConnecting to ${getNet()} ...`
updateResults()
await client.connect()
results = `\n\nConnected.`
updateResults()
```
Gather issuer information, credential type, and domain ID. Format the transaction depending on if the optional domain ID field is included. Wrap the code in a `try-catch` block to handle errors.
```javascript
try {
// Get account wallet from seed
const wallet = xrpl.Wallet.fromSeed(accountSeedField.value)
// Get Domain ID
const domainID = domainIDField.value
// Get credential type - convert string to hex if needed
let credentialType = credentialTypeField.value;
if (!/^[0-9A-F]+$/i.test(credentialType)) {
let hex = '';
for (let i = 0; i < credentialType.length; i++) {
const charCode = credentialType.charCodeAt(i);
const hexCharCode = charCode.toString(16).padStart(2, '0');
hex += hexCharCode;
}
credentialType = hex.toUpperCase();
}
// Prepare transaction
const transaction = {
"TransactionType": "PermissionedDomainSet",
"Account": wallet.address,
"AcceptedCredentials": [
{
"Credential": {
"Issuer": wallet.address,
"CredentialType": credentialType
}
}
]
}
if (domainID) {
transaction.DomainID = domainID
}
```
Submit the `PermissionedDomainSet` transaction and report the results. The metadata is formed differently if a domain ID was included; parse the response accordingly.
```javascript
results = `\n\n===Preparing and Sending Transaction===\n\n${JSON.stringify(transaction, null, 2)}`
updateResults()
// Submit transaction
const tx = await client.submitAndWait(transaction, {autofill: true, wallet: wallet})
if (tx.result.meta.TransactionResult == "tesSUCCESS") {
// Parse for domain info
if (domainID) {
results = `\n\n===Create Permissioned Domain Result===\n\n${JSON.stringify(tx.result.tx_json, null, 2)}`
} else {
const parsedResponse = JSON.parse(JSON.stringify(tx.result.meta.AffectedNodes, null, 2))
const domainInfo = parsedResponse.find( node => node.CreatedNode && node.CreatedNode.LedgerEntryType === "PermissionedDomain" )
results = `\n\n===Create Permissioned Domain Result===\n\n${JSON.stringify(domainInfo.CreatedNode, null, 2)}`
}
} else {
results = `\n\n===Error===\n\n${JSON.stringify(tx.result.meta.TransactionResult, null, 2)}: Check codes at https://xrpl.org/docs/references/protocol/transactions/types/permissioneddomainset#error-cases`
}
updateResults()
} catch (error) {
results = `\n\n===Error===\n\n${error}`
updateResults()
}
client.disconnect()
}
```
### Delete Permissioned Domain
Define a function to delete a permissioned domain.
```javascript
async function deleteDomain() {
```
Connect to the XRP Ledger.
```javascript
let net = getNet()
const client = new xrpl.Client(net)
results = `\n\n===Delete Permissioned Domain===\n\nConnecting to ${getNet()} ...`
updateResults()
await client.connect()
results = `\n\nConnected.`
updateResults()
```
Gather account information and domain ID values. Wrap the code in a `try-catch` block to handle errors.
```javascript
try {
// Get account wallet from seed
const wallet = xrpl.Wallet.fromSeed(accountSeedField.value)
// Get Domain ID
const domainID = domainIDField.value
// Prepare transaction
const transaction = {
"TransactionType": "PermissionedDomainDelete",
"Account": wallet.address,
"DomainID": domainID
}
```
Submit the `PermissionedDomainDelete` transaction and report the results.
```javascript
results = `\n\n===Preparing and Sending Transaction===\n\n${JSON.stringify(transaction, null, 2)}`
updateResults()
// Submit transaction
const tx = await client.submitAndWait(transaction, {autofill: true, wallet: wallet})
if (tx.result.meta.TransactionResult == "tesSUCCESS") {
results = `\n\n===Delete Permissioned Domain Result===\n\nSuccessfully deleted the permissioned domain.`
} else {
results = `\n\n===Error===\n\n${JSON.stringify(tx.result.meta.TransactionResult, null, 2)}: Check codes at https://xrpl.org/docs/references/protocol/transactions/types/permissioneddomaindelete#error-cases`
}
updateResults()
} catch (error) {
results = `\n\n===Error===\n\n${error}`
updateResults()
}
client.disconnect()
}
```

14
docs/tutorials/javascript/decentralized-finance/index.md Normal file
View File

@@ -0,0 +1,14 @@
---
top_nav_grouping: Article Types
seo:
description: XRP Ledger features to meet your defi needs.
labels:
- Decentralized Finance
metadata:
indexPage: true
---
# Decentralized Finance
Leverage the XRP Ledger for decentralized finance that also meets compliance requirements.
{% child-pages /%}

4
sidebars.yaml
View File

@@ -215,6 +215,10 @@
- page: docs/tutorials/javascript/compliance/index.md
items:
- page: docs/tutorials/javascript/compliance/verify-credential.md
- page: docs/tutorials/javascript/decentralized-finance/index.md
expanded: false
items:
- page: docs/tutorials/javascript/decentralized-finance/create-permissioned-domains.md
- page: docs/tutorials/python/index.md
expanded: false
items: