diff --git a/_code-samples/use-tickets/README.md b/_code-samples/use-tickets/README.md index 2f52cb8680..a3f6b8172e 100644 --- a/_code-samples/use-tickets/README.md +++ b/_code-samples/use-tickets/README.md @@ -1,5 +1,5 @@ -# Tickets +# Use Tickets -Create a Ticket and use it to send a transaction out of the usual Sequence order. +Create a batch of Tickets and use one to send a transaction outside the normal Sequence order. -For more context, see the interactive [Use Tickets tutorial](https://xrpl.org/use-tickets.html). +For more context, see the [Use Tickets tutorial](https://xrpl.org/docs/tutorials/best-practices/transaction-sending/use-tickets). diff --git a/_code-samples/use-tickets/go/README.md b/_code-samples/use-tickets/go/README.md new file mode 100644 index 0000000000..3ccdfd0b60 --- /dev/null +++ b/_code-samples/use-tickets/go/README.md @@ -0,0 +1,17 @@ +# Use Tickets (Go) + +Demonstrates how to use Tickets for out-of-order transaction submission on the XRP Ledger. + +For more context, see the [Use Tickets tutorial](https://xrpl.org/docs/tutorials/best-practices/transaction-sending/use-tickets). + +## Setup + +```sh +go mod download +``` + +## Basic Ticket Usage + +```sh +go run main.go +``` diff --git a/_code-samples/use-tickets/go/go.mod b/_code-samples/use-tickets/go/go.mod index 7093fdab52..e1482aede1 100644 --- a/_code-samples/use-tickets/go/go.mod +++ b/_code-samples/use-tickets/go/go.mod @@ -1,21 +1,18 @@ module github.com/XRPLF -go 1.24.0 +go 1.24.3 -require github.com/Peersyst/xrpl-go v0.1.11 +require github.com/Peersyst/xrpl-go v0.1.18 require ( - github.com/FactomProject/basen v0.0.0-20150613233007-fe3947df716e // indirect - github.com/FactomProject/btcutilecc v0.0.0-20130527213604-d3a63a5752ec // indirect - github.com/btcsuite/btcd/btcec/v2 v2.3.4 // indirect + github.com/bsv-blockchain/go-sdk v1.2.9 // indirect github.com/decred/dcrd/crypto/ripemd160 v1.0.2 // indirect - github.com/decred/dcrd/dcrec/secp256k1/v4 v4.3.0 // indirect + github.com/decred/dcrd/dcrec/secp256k1/v4 v4.4.1 // indirect github.com/json-iterator/go v1.1.12 // indirect github.com/mitchellh/mapstructure v1.5.0 // indirect github.com/modern-go/concurrent v0.0.0-20180228061459-e0a39a4cb421 // indirect github.com/modern-go/reflect2 v1.0.2 // indirect - github.com/tyler-smith/go-bip32 v1.0.0 // indirect - github.com/tyler-smith/go-bip39 v1.1.0 // indirect + github.com/pkg/errors v0.9.1 // indirect github.com/ugorji/go/codec v1.2.11 // indirect golang.org/x/crypto v0.45.0 // indirect ) diff --git a/_code-samples/use-tickets/go/go.sum b/_code-samples/use-tickets/go/go.sum index 8cd644756f..19120c2a8e 100644 --- a/_code-samples/use-tickets/go/go.sum +++ b/_code-samples/use-tickets/go/go.sum @@ -1,22 +1,16 @@ -github.com/FactomProject/basen v0.0.0-20150613233007-fe3947df716e h1:ahyvB3q25YnZWly5Gq1ekg6jcmWaGj/vG/MhF4aisoc= -github.com/FactomProject/basen v0.0.0-20150613233007-fe3947df716e/go.mod h1:kGUqhHd//musdITWjFvNTHn90WG9bMLBEPQZ17Cmlpw= -github.com/FactomProject/btcutilecc v0.0.0-20130527213604-d3a63a5752ec h1:1Qb69mGp/UtRPn422BH4/Y4Q3SLUrD9KHuDkm8iodFc= -github.com/FactomProject/btcutilecc v0.0.0-20130527213604-d3a63a5752ec/go.mod h1:CD8UlnlLDiqb36L110uqiP2iSflVjx9g/3U9hCI4q2U= -github.com/Peersyst/xrpl-go v0.1.11 h1:P6r/gHxRnbAtAdPmzNHz/7zpsdfvwh0SS+QI2JNT44w= -github.com/Peersyst/xrpl-go v0.1.11/go.mod h1:CBRM3/soqNeeL2Jx6USVUtECqulZVUoq3UxZKMz9hdw= -github.com/btcsuite/btcd/btcec/v2 v2.3.4 h1:3EJjcN70HCu/mwqlUsGK8GcNVyLVxFDlWurTXGPFfiQ= -github.com/btcsuite/btcd/btcec/v2 v2.3.4/go.mod h1:zYzJ8etWJQIv1Ogk7OzpWjowwOdXY1W/17j2MW85J04= -github.com/cmars/basen v0.0.0-20150613233007-fe3947df716e h1:0XBUw73chJ1VYSsfvcPvVT7auykAJce9FpRr10L6Qhw= -github.com/cmars/basen v0.0.0-20150613233007-fe3947df716e/go.mod h1:P13beTBKr5Q18lJe1rIoLUqjM+CB1zYrRg44ZqGuQSA= +github.com/Peersyst/xrpl-go v0.1.18 h1:PUIEGvnkO9oQ4yZRr6EHjglay1xmrjFhujQNVkXynqs= +github.com/Peersyst/xrpl-go v0.1.18/go.mod h1:38j60Mr65poIHdhmjvNXnwbcUFNo8J7CBDot7ZWgrb8= +github.com/bsv-blockchain/go-sdk v1.2.9 h1:LwFzuts+J5X7A+ECx0LNowtUgIahCkNNlXckdiEMSDk= +github.com/bsv-blockchain/go-sdk v1.2.9/go.mod h1:KiHWa/hblo3Bzr+IsX11v0sn1E6elGbNX0VXl5mOq6E= github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38= github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c= github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38= -github.com/decred/dcrd/crypto/blake256 v1.0.1 h1:7PltbUIQB7u/FfZ39+DGa/ShuMyJ5ilcvdfma9wOH6Y= -github.com/decred/dcrd/crypto/blake256 v1.0.1/go.mod h1:2OfgNZ5wDpcsFmHmCK5gZTPcCXqlm2ArzUIkw9czNJo= +github.com/decred/dcrd/crypto/blake256 v1.1.0 h1:zPMNGQCm0g4QTY27fOCorQW7EryeQ/U0x++OzVrdms8= +github.com/decred/dcrd/crypto/blake256 v1.1.0/go.mod h1:2OfgNZ5wDpcsFmHmCK5gZTPcCXqlm2ArzUIkw9czNJo= github.com/decred/dcrd/crypto/ripemd160 v1.0.2 h1:TvGTmUBHDU75OHro9ojPLK+Yv7gDl2hnUvRocRCjsys= github.com/decred/dcrd/crypto/ripemd160 v1.0.2/go.mod h1:uGfjDyePSpa75cSQLzNdVmWlbQMBuiJkvXw/MNKRY4M= -github.com/decred/dcrd/dcrec/secp256k1/v4 v4.3.0 h1:rpfIENRNNilwHwZeG5+P150SMrnNEcHYvcCuK6dPZSg= -github.com/decred/dcrd/dcrec/secp256k1/v4 v4.3.0/go.mod h1:v57UDF4pDQJcEfFUCRop3lJL149eHGSe9Jvczhzjo/0= +github.com/decred/dcrd/dcrec/secp256k1/v4 v4.4.1 h1:5RVFMOWjMyRy8cARdy79nAmgYw3hK/4HUq48LQ6Wwqo= +github.com/decred/dcrd/dcrec/secp256k1/v4 v4.4.1/go.mod h1:ZXNYxsqcloTdSy/rNShjYzMhyjf0LaoftYK0p+A3h40= github.com/golang/mock v1.6.0 h1:ErTB+efbowRARo13NNdxyJji2egdxLGQhRaY+DUumQc= github.com/golang/mock v1.6.0/go.mod h1:p6yTPP+5HYm5mzsMV8JkE6ZKdX+/wYM6Hr+LicevLPs= github.com/google/gofuzz v1.0.0/go.mod h1:dBl0BpW6vV/+mYPU4Po3pmUjxk6FQPldtuIdl/M65Eg= @@ -28,29 +22,17 @@ github.com/modern-go/concurrent v0.0.0-20180228061459-e0a39a4cb421 h1:ZqeYNhU3OH github.com/modern-go/concurrent v0.0.0-20180228061459-e0a39a4cb421/go.mod h1:6dJC0mAP4ikYIbvyc7fijjWJddQyLn8Ig3JB5CqoB9Q= github.com/modern-go/reflect2 v1.0.2 h1:xBagoLtFs94CBntxluKeaWgTMpvLxC4ur3nMaC9Gz0M= github.com/modern-go/reflect2 v1.0.2/go.mod h1:yWuevngMOJpCy52FWWMvUC8ws7m/LJsjYzDa0/r8luk= +github.com/pkg/errors v0.9.1 h1:FEBLx1zS214owpjy7qsBeixbURkuhQAwrK5UwLGTwt4= +github.com/pkg/errors v0.9.1/go.mod h1:bwawxfHBFNV+L2hUp1rHADufV3IMtnDRdf1r5NINEl0= github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM= github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4= github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME= -github.com/stretchr/testify v1.1.5-0.20170601210322-f6abca593680/go.mod h1:a8OnRcib4nhh0OaRAV+Yts87kKdq0PP7pXfy6kDkUVs= github.com/stretchr/testify v1.3.0/go.mod h1:M5WIy9Dh21IEIfnGCwXGc5bZfKNJtfHm1UVUgZn+9EI= -github.com/stretchr/testify v1.8.4 h1:CcVxjf3Q8PM0mHUKJCdn+eZZtm5yQwehR5yeSVQQcUk= -github.com/stretchr/testify v1.8.4/go.mod h1:sz/lmYIOXD/1dqDmKjjqLyZ2RngseejIcXlSw2iwfAo= -github.com/tyler-smith/go-bip32 v1.0.0 h1:sDR9juArbUgX+bO/iblgZnMPeWY1KZMUC2AFUJdv5KE= -github.com/tyler-smith/go-bip32 v1.0.0/go.mod h1:onot+eHknzV4BVPwrzqY5OoVpyCvnwD7lMawL5aQupE= -github.com/tyler-smith/go-bip39 v1.1.0 h1:5eUemwrMargf3BSLRRCalXT93Ns6pQJIjYQN2nyfOP8= -github.com/tyler-smith/go-bip39 v1.1.0/go.mod h1:gUYDtqQw1JS3ZJ8UWVcGTGqqr6YIN3CWg+kkNaLt55U= +github.com/stretchr/testify v1.10.0 h1:Xv5erBjTwe/5IxqUQTdXv5kgmIvbHo3QQyRwhJsOfJA= +github.com/stretchr/testify v1.10.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY= github.com/ugorji/go/codec v1.2.11 h1:BMaWp1Bb6fHwEtbplGBGJ498wD+LKlNSl25MjdZY4dU= github.com/ugorji/go/codec v1.2.11/go.mod h1:UNopzCgEMSXjBc6AOMqYvWC1ktqTAfzJZUZgYf6w6lg= -golang.org/x/crypto v0.0.0-20170613210332-850760c427c5/go.mod h1:6SG95UA2DQfeDnfUPMdvaQW0Q7yPrPDi9nlGo2tz2b4= -golang.org/x/crypto v0.0.0-20190308221718-c2843e01d9a2/go.mod h1:djNgcEr1/C05ACkg1iLfiJU5Ep61QUkGW8qpdssI0+w= -golang.org/x/crypto v0.0.0-20200622213623-75b288015ac9/go.mod h1:LzIPMQfyMNhhGPhUkYOs5KpL4U8rLKemX1yGLhDgUto= golang.org/x/crypto v0.45.0 h1:jMBrvKuj23MTlT0bQEOBcAE0mjg8mK9RXFhRH6nyF3Q= golang.org/x/crypto v0.45.0/go.mod h1:XTGrrkGJve7CYK7J8PEww4aY7gM3qMCElcJQ8n8JdX4= -golang.org/x/net v0.0.0-20190404232315-eb5bcb51f2a3/go.mod h1:t9HGtf8HONx5eT2rtn7q6eTqICYqUVnKs3thJo3Qplg= -golang.org/x/sys v0.0.0-20190215142949-d0b11bdaac8a/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY= -golang.org/x/sys v0.0.0-20190412213103-97732733099d/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs= -golang.org/x/text v0.3.0/go.mod h1:NqM8EUOU14njkJ3fqMW+pc6Ldnwhi/IjpwHt7yyuwOQ= gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA= gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM= -launchpad.net/gocheck v0.0.0-20140225173054-000000000087 h1:Izowp2XBH6Ya6rv+hqbceQyw/gSGoXfH/UPoTGduL54= -launchpad.net/gocheck v0.0.0-20140225173054-000000000087/go.mod h1:hj7XX3B/0A+80Vse0e+BUHsHMTEhd0O4cpUHr/e/BUM= diff --git a/_code-samples/use-tickets/go/main.go b/_code-samples/use-tickets/go/main.go index ccf7d05098..47ef9c0bfd 100644 --- a/_code-samples/use-tickets/go/main.go +++ b/_code-samples/use-tickets/go/main.go @@ -8,116 +8,83 @@ import ( "github.com/Peersyst/xrpl-go/xrpl/faucet" "github.com/Peersyst/xrpl-go/xrpl/queries/account" "github.com/Peersyst/xrpl-go/xrpl/rpc" + rpctypes "github.com/Peersyst/xrpl-go/xrpl/rpc/types" "github.com/Peersyst/xrpl-go/xrpl/transaction" "github.com/Peersyst/xrpl-go/xrpl/wallet" ) func main() { - cfg, err := rpc.NewClientConfig( - "https://s.altnet.rippletest.net:51234/", - rpc.WithFaucetProvider(faucet.NewTestnetFaucetProvider()), - ) - if err != nil { - panic(err) - } + // Set up client and account + cfg, err := rpc.NewClientConfig( + "https://s.altnet.rippletest.net:51234/", + rpc.WithFaucetProvider(faucet.NewTestnetFaucetProvider()), + rpc.WithMaxRetries(30), + ) + if err != nil { + panic(err) + } + client := rpc.NewClient(cfg) - client := rpc.NewClient(cfg) + // Fund wallet + w, err := wallet.New(crypto.ED25519()) + if err != nil { + panic(err) + } + fmt.Println("Funding wallet...") + if err := client.FundWallet(&w); err != nil { + panic(err) + } + fmt.Println("Wallet funded") - w, err := wallet.New(crypto.ED25519()) - if err != nil { - panic(err) - } + // Create Tickets + ticketCreate := &transaction.TicketCreate{ + BaseTx: transaction.BaseTx{ + Account: w.GetAddress(), + }, + TicketCount: 10, + } + fmt.Println("Submitting TicketCreate transaction...") + tcResult, err := client.SubmitTxAndWait(ticketCreate.Flatten(), &rpctypes.SubmitOptions{ + Autofill: true, + Wallet: &w, + }) + if err != nil { + panic(err) + } + fmt.Printf("TicketCreate hash: %s, validated: %t\n", tcResult.Hash, tcResult.Validated) - fmt.Println("Funding wallet...") - if err := client.FundWallet(&w); err != nil { - panic(err) - } + // Check Available Tickets + objects, err := client.GetAccountObjects(&account.ObjectsRequest{ + Account: w.GetAddress(), + Type: account.TicketObject, + }) + if err != nil { + panic(err) + } + fmt.Printf("Found %d Tickets\n", len(objects.AccountObjects)) - fmt.Println("Wallet funded") - fmt.Println() + // Choose an arbitrary Ticket to use + useTicket, err := objects.AccountObjects[0]["TicketSequence"].(json.Number).Int64() + if err != nil { + panic(err) + } + fmt.Printf("Using Ticket Sequence: %d\n", useTicket) - info, err := client.GetAccountInfo(&account.InfoRequest{ - Account: w.GetAddress(), - }) - if err != nil { - panic(err) - } - - fmt.Println("Current wallet sequence:", info.AccountData.Sequence) - fmt.Println() - - fmt.Println("Submitting TicketCreate transaction...") - tc := &transaction.TicketCreate{ - BaseTx: transaction.BaseTx{ - Account: w.GetAddress(), - Sequence: info.AccountData.Sequence, - }, - TicketCount: 10, - } - - flatTc := tc.Flatten() - - if err := client.Autofill(&flatTc); err != nil { - panic(err) - } - - blob, _, err := w.Sign(flatTc) - if err != nil { - panic(err) - } - - res, err := client.SubmitTxBlobAndWait(blob, false) - if err != nil { - panic(err) - } - - fmt.Println("TicketCreate transaction submitted") - fmt.Printf("Hash: %s\n", res.Hash) - fmt.Printf("Validated: %t\n", res.Validated) - fmt.Println() - - objects, err := client.GetAccountObjects(&account.ObjectsRequest{ - Account: w.GetAddress(), - }) - if err != nil { - panic(err) - } - - fmt.Println("Account objects:", objects.AccountObjects[0]["TicketSequence"]) - - seq, err := objects.AccountObjects[0]["TicketSequence"].(json.Number).Int64() - if err != nil { - panic(err) - } - - fmt.Println("Submitting AccountSet transaction...") - as := &transaction.AccountSet{ - BaseTx: transaction.BaseTx{ - Account: w.GetAddress(), - Sequence: 0, - TicketSequence: uint32(seq), - }, - } - - flatAs := as.Flatten() - - if err := client.Autofill(&flatAs); err != nil { - panic(err) - } - - flatAs["Sequence"] = uint32(0) - - blob, _, err = w.Sign(flatAs) - if err != nil { - panic(err) - } - - res, err = client.SubmitTxBlobAndWait(blob, false) - if err != nil { - panic(err) - } - - fmt.Println("AccountSet transaction submitted") - fmt.Printf("Hash: %s\n", res.Hash) - fmt.Printf("Validated: %t\n", res.Validated) + // Use a Ticket + ticketedTx := &transaction.AccountSet{ + BaseTx: transaction.BaseTx{ + Account: w.GetAddress(), + Sequence: 0, + TicketSequence: uint32(useTicket), + }, + } + fmt.Println("Submitting ticketed AccountSet transaction...") + ticketedResult, err := client.SubmitTxAndWait(ticketedTx.Flatten(), &rpctypes.SubmitOptions{ + Autofill: true, + Wallet: &w, + }) + if err != nil { + panic(err) + } + fmt.Printf("Ticketed AccountSet hash: %s, validated: %t\n", ticketedResult.Hash, ticketedResult.Validated) } diff --git a/_code-samples/use-tickets/js/README.md b/_code-samples/use-tickets/js/README.md index 99c9b25a6f..ad4d2fe0f6 100644 --- a/_code-samples/use-tickets/js/README.md +++ b/_code-samples/use-tickets/js/README.md @@ -2,6 +2,8 @@ Demonstrates how to use Tickets for out-of-order transaction submission on the XRP Ledger. +For more context, see the [Use Tickets tutorial](https://xrpl.org/docs/tutorials/best-practices/transaction-sending/use-tickets). + ## Setup ```sh @@ -10,12 +12,6 @@ npm install ## Basic Ticket Usage -### Browser - -Open `demo.html` in a web browser and check the browser console to see the logs. - -Alternatively, you can run the code from the command line: - ```sh node use-tickets.js ``` diff --git a/_code-samples/use-tickets/js/demo.html b/_code-samples/use-tickets/js/demo.html deleted file mode 100644 index 287b80c068..0000000000 --- a/_code-samples/use-tickets/js/demo.html +++ /dev/null @@ -1,10 +0,0 @@ - - - - -Code Sample - Use Tickets - - - -Open your browser's console (F12) to see the logs. - diff --git a/_code-samples/use-tickets/js/package.json b/_code-samples/use-tickets/js/package.json index 58e2ddda32..81d810bdff 100644 --- a/_code-samples/use-tickets/js/package.json +++ b/_code-samples/use-tickets/js/package.json @@ -1,4 +1,5 @@ { + "type": "module", "dependencies": { "xrpl": "^4.0.0" } diff --git a/_code-samples/use-tickets/js/use-tickets-multisig.js b/_code-samples/use-tickets/js/use-tickets-multisig.js index 5f8eab07f1..eddc2efeef 100644 --- a/_code-samples/use-tickets/js/use-tickets-multisig.js +++ b/_code-samples/use-tickets/js/use-tickets-multisig.js @@ -1,129 +1,74 @@ -if (typeof module !== "undefined") { - // Use var here because const/let are block-scoped to the if statement. - var xrpl = require('xrpl') -} - // List which Tickets are outstanding against one’s own account and use Tickets to collect signatures for multisign transactions -// https://xrpl.org/use-tickets.html -// https://xrpl.org/signerlistset.html#signerlistset -// https://xrpl.org/multi-signing.html#multi-signing +import xrpl from 'xrpl' -async function main() { - // Connect to a testnet node - console.log("Connecting to Testnet...") - const client = new xrpl.Client('wss://s.altnet.rippletest.net:51233') - await client.connect() - - // Get account credentials from the Testnet Faucet - console.log("Requesting account credentials from the Testnet faucet, this may take awhile...") - const { wallet: main_wallet } = await client.fundWallet() +// Use Tickets with multi-signing: each Ticket holds a Sequence slot for a +// transaction while you collect signatures from multiple signers. - // Signer keys don't need to be funded on the ledger, it only needs to be cryptographically valid - // Thus, we could generate keys and set them as signers without the need to fund their accounts - // But we'll still fund them for testing purposes... - const { wallet: wallet_1 } = await client.fundWallet() - const { wallet: wallet_2 } = await client.fundWallet() - const { wallet: wallet_3 } = await client.fundWallet() +const client = new xrpl.Client('wss://s.altnet.rippletest.net:51233') +await client.connect() - console.log(" Main Account: ", main_wallet.address) - console.log(" Seed: ", main_wallet.seed) +// Set up the main account and three signers ------------------------------ +// Signer accounts only need cryptographically valid keys; the addresses +// don't need to be funded or exist on the ledger. +console.log('Funding main account from the faucet...') +const { wallet: mainWallet } = await client.fundWallet() +const signer1 = xrpl.Wallet.generate() +const signer2 = xrpl.Wallet.generate() +const signer3 = xrpl.Wallet.generate() +console.log(`Main account: ${mainWallet.address}`) - console.log("\n Signer 1: ", wallet_1.address) - console.log(" Signer 2: ", wallet_2.address) - console.log(" Signer 3: ", wallet_3.address) +// Configure the signer list (quorum 2 of 3) ------------------------------- +console.log('Submitting SignerListSet...') +const signerListResult = await client.submitAndWait({ + TransactionType: 'SignerListSet', + Account: mainWallet.address, + SignerQuorum: 2, + SignerEntries: [ + { SignerEntry: { Account: signer1.address, SignerWeight: 1 } }, + { SignerEntry: { Account: signer2.address, SignerWeight: 1 } }, + { SignerEntry: { Account: signer3.address, SignerWeight: 1 } } + ] +}, { wallet: mainWallet, autofill: true }) +console.log(`SignerListSet hash: ${signerListResult.result.hash}`) - // Send SignerListSet transaction - // Since each signer is given a signer weight of 1 and there are 3 signers, the maximum quorom would be 3 - // SignerQuorom is a target number for the signer weights - // A multisig from this list is valid only if the sum weights of the signatures provided is greater than or equal to the SignerQuorom - const signerLiSetSignerList_tx = { - TransactionType: "SignerListSet", - Account: main_wallet.classicAddress, - SignerEntries: [ - { - SignerEntry: { - Account: wallet_1.classicAddress, - SignerWeight: 1, - }, - }, - { - SignerEntry: { - Account: wallet_2.classicAddress, - SignerWeight: 1, - }, - }, - { - SignerEntry: { - Account: wallet_3.classicAddress, - SignerWeight: 1, - }, - } - ], - SignerQuorum: 2, - } +// Create Tickets ---------------------------------------------------------- +console.log('Submitting TicketCreate (3 Tickets)...') +const ticketCreateResult = await client.submitAndWait({ + TransactionType: 'TicketCreate', + Account: mainWallet.address, + TicketCount: 3 +}, { wallet: mainWallet, autofill: true }) +console.log(`TicketCreate hash: ${ticketCreateResult.result.hash}`) - const signerLiSetSignerList_tx_prepared = await client.autofill(signerLiSetSignerList_tx) - const SetSignerList_tx_signed = main_wallet.sign(signerLiSetSignerList_tx_prepared) - console.log(`\n SignerListSet Tx hash: ${SetSignerList_tx_signed.hash}`) - - const setsignerlist_submit = await client.submitAndWait(SetSignerList_tx_signed.tx_blob) - console.log(`\t Submit result: ${setsignerlist_submit.result.meta.TransactionResult}`) - - const CreateTicket_tx = await client.autofill({ - TransactionType: "TicketCreate", - Account: main_wallet.address, - TicketCount: 3 - }) - - const CreateTicket_tx_signed = main_wallet.sign(CreateTicket_tx) - console.log("\n CreateTicket Tx hash:", CreateTicket_tx_signed.hash) - - const ticket_submit = await client.submitAndWait(CreateTicket_tx_signed.tx_blob) - console.log(" Submit result:", ticket_submit.result.meta.TransactionResult) - - const ticket_response = await client.request({ - command: "account_objects", - account: main_wallet.address, - ledger_index: "validated", - type: "ticket" - }) +// Pick a Ticket ----------------------------------------------------------- +const ticketsResponse = await client.request({ + command: 'account_objects', + account: mainWallet.address, + type: 'ticket' +}) +const useTicket = ticketsResponse.result.account_objects[0].TicketSequence +console.log(`Using Ticket Sequence: ${useTicket}`) - console.log(`\n- Tickets issued by ${main_wallet.address}:\n`) - for (let i = 0; i < ticket_response.result.account_objects.length; i++) { - console.log(`Ticket ${i+1}: ${ticket_response.result.account_objects[i].TicketSequence}`) - } +// Prepare a multi-signed transaction that consumes the Ticket. +// Omit LastLedgerSequence so the transaction does not expire while +// signatures are being collected. +const preparedTx = await client.autofill({ + TransactionType: 'AccountSet', + Account: mainWallet.address, + TicketSequence: useTicket, + LastLedgerSequence: null, + Sequence: 0 +}, 3) // signersCount for multi-sig fee calculation - // We'll use this ticket on our tx - const ticket_1 = ticket_response.result.account_objects[0].TicketSequence - - console.log(`\n Ticket sequence ${ticket_1} will be used for our multi-sig transaction`) - - const Payment_tx = { - "TransactionType": "AccountSet", - "Account": main_wallet.address, - "TicketSequence": ticket_1, - "LastLedgerSequence": null, - "Sequence": 0 - } +// In a real workflow you would share preparedTx with each signer and +// receive their signed blobs back; here we sign in one process for clarity. +const { tx_blob: signedBlob1 } = signer1.sign(preparedTx, true) +const { tx_blob: signedBlob2 } = signer2.sign(preparedTx, true) +const { tx_blob: signedBlob3 } = signer3.sign(preparedTx, true) - const Payment_tx_prepared = await client.autofill(Payment_tx, signersCount=3) - - // Each signer will sign the prepared tx (AccountSet_tx) and their signatures will be combines into 1 multi-sig transaction - const { tx_blob: Payment_tx_signed_1 } = wallet_1.sign(Payment_tx_prepared, multisign=true) - const { tx_blob: Payment_tx_signed_2 } = wallet_2.sign(Payment_tx_prepared, multisign=true) - const { tx_blob: Payment_tx_signed_3 } = wallet_3.sign(Payment_tx_prepared, multisign=true) - - console.log("\n All signers have signed the transaction with their corresponding keys") +const multisignedBlob = xrpl.multisign([signedBlob1, signedBlob2, signedBlob3]) +console.log('Submitting multi-signed AccountSet...') +const multisigResult = await client.submitAndWait(multisignedBlob) +console.log(`Multi-sig hash: ${multisigResult.result.hash}, result: ${multisigResult.result.meta.TransactionResult}`) - // Combine 3 of the signers' signatures to form a multi-sig transaction - const multisignedTx = xrpl.multisign([Payment_tx_signed_1, Payment_tx_signed_2, Payment_tx_signed_3]) - - const multisig_submit = await client.submitAndWait(multisignedTx) - console.log("\n Multi-sig Submit result:", multisig_submit.result.meta.TransactionResult) - console.log("\n Multi-sig Tx Binary:", multisignedTx) - - client.disconnect() - - // End main() - } - - main() +// Disconnect when done (If you omit this, Node.js won't end the process) +await client.disconnect() diff --git a/_code-samples/use-tickets/js/use-tickets.js b/_code-samples/use-tickets/js/use-tickets.js index 2d618f4d28..dc0a3305bf 100644 --- a/_code-samples/use-tickets/js/use-tickets.js +++ b/_code-samples/use-tickets/js/use-tickets.js @@ -1,76 +1,44 @@ -// Dependencies for Node.js. -// In browsers, use a - +To complete this tutorial, you need: -This page provides JavaScript examples that use the [xrpl.js](https://js.xrpl.org/) library. See [Get Started Using JavaScript](../../get-started/get-started-javascript.md) for setup instructions. - -Since JavaScript works in the web browser, you can read along and use the interactive steps without any setup. +- A basic understanding of the XRP Ledger. +- A basic understanding of how [Sequence numbers](../../../references/protocol/data-types/basic-data-types.md#account-sequence) work in transactions. +- An XRP Ledger [client library](../../../references/client-libraries.md) set up. +- (Optional) A basic understanding of [multi-signing](../../../concepts/accounts/multi-signing.md), if you plan to combine it with Tickets. +- {% amendment-disclaimer name="TicketBatch" /%} +## Source Code +You can find the complete source code for this tutorial's examples in the [code samples section of this website's repository](https://github.com/XRPLF/xrpl-dev-portal/tree/master/_code-samples/use-tickets/). ## Steps -This tutorial is divided into a few phases: - -- (Steps 1-2) **Setup:** You need an XRP Ledger address and secret. For production, you can use the same address and secret consistently. For this tutorial, you can generate new test credentials as needed. You also need to be connected to the network. -- (Steps 3-6) **Create Tickets:** Send a transaction to set aside some Tickets. -- (Optional) **Intermission:** After creating Tickets, you can send various other transactions at any time before, during, and after the following steps. -- (Steps 7-10) **Use Ticket:** Use one of your set-aside Tickets to send a transaction. You can repeat these steps while skipping the previous parts as long as you have at least one Ticket remaining to use. - -### 1. Get Credentials - -To transact on the XRP Ledger, you need an address and secret key, and some XRP. For development purposes, you can get these on the [Testnet](../../../concepts/networks-and-servers/parallel-networks.md) using the following interface: - -{% partial file="/docs/_snippets/interactive-tutorials/generate-step.md" /%} - -When you're building production-ready software, you should use an existing account, and manage your keys using a [secure signing configuration](../../../concepts/transactions/secure-signing.md). - - -### 2. Connect to Network - -You must be connected to the network to submit transactions to it. Since Tickets are only available on Devnet so far, you should connect to a Devnet server. For example: +### 1. Install dependencies {% tabs %} - {% tab label="JavaScript" %} -{% code-snippet file="/_code-samples/use-tickets/js/use-tickets.js" from="// Connect to" before="// Get credentials" language="js" /%} -{% /tab %} +From the `_code-samples/use-tickets/js/` folder, use `npm` to install dependencies: +```sh +npm install +``` +{% /tab %} +{% tab label="Python" %} +From the `_code-samples/use-tickets/py/` folder, set up a virtual environment and use `pip` to install dependencies: + +```sh +python -m venv .venv +source .venv/bin/activate +pip install -r requirements.txt +``` +{% /tab %} +{% tab label="Go" %} +From the `_code-samples/use-tickets/go/` folder, install dependencies with Go modules: + +```sh +go mod download +``` +{% /tab %} {% /tabs %} -{% admonition type="info" name="Note" %}The code samples in this tutorial use JavaScript's [`async`/`await` pattern](https://javascript.info/async-await). Since `await` needs to be used from within an `async` function, the remaining code samples are written to continue inside the `main()` function started here. You can also use Promise methods `.then()` and `.catch()` instead of `async`/`await` if you prefer.{% /admonition %} +### 2. Set up client and account -For this tutorial, click the following button to connect: - -{% partial file="/docs/_snippets/interactive-tutorials/connect-step.md" /%} - - -### 3. Check Sequence Number - -Before you create any Tickets, you should check what [Sequence Number][] your account is at. You want the current Sequence number for the next step, and the Ticket Sequence numbers it sets aside start from this number. +Import the XRPL client library, connect to the network, and generate a test account funded by the [Testnet](../../../concepts/networks-and-servers/parallel-networks.md) faucet. Using a live test network lets you submit transactions without risking real XRP. {% tabs %} - {% tab label="JavaScript" %} -{% code-snippet file="/_code-samples/use-tickets/js/use-tickets.js" from="// Check Sequence" before="// Prepare and Sign TicketCreate" language="js" /%} +{% code-snippet file="/_code-samples/use-tickets/js/use-tickets.js" before="// Create Tickets" language="js" /%} +{% /tab %} +{% tab label="Python" %} +{% code-snippet file="/_code-samples/use-tickets/py/use-tickets.py" before="# Create Tickets" language="py" /%} +{% /tab %} +{% tab label="Go" %} +{% code-snippet file="/_code-samples/use-tickets/go/main.go" before="// Create Tickets" language="go" /%} {% /tab %} - {% /tabs %} -{% interactive-block label="Check Sequence" steps=$frontmatter.steps %} - - - -{% loading-icon message="Querying..." /%} - -
- -{% /interactive-block %} - - - -### 4. Prepare and Sign TicketCreate - -Construct a [TicketCreate transaction][] using the sequence number you determined in the previous step. Use the `TicketCount` field to specify how many Tickets to create. For example, to prepare a transaction that would make 10 Tickets: - -{% tabs %} - -{% tab label="JavaScript" %} -{% code-snippet file="/_code-samples/use-tickets/js/use-tickets.js" from="// Prepare and Sign TicketCreate" before="// Submit TicketCreate" language="js" /%} -{% /tab %} - -{% /tabs %} - -Record the transaction's hash and `LastLedgerSequence` value so you can [be sure whether or not it got validated](../../../concepts/transactions/reliable-transaction-submission.md) later. - - -{% interactive-block label="Prepare & Sign" steps=$frontmatter.steps %} - - -
- -{% /interactive-block %} - - - -### 5. Submit TicketCreate - -Submit the signed transaction blob that you created in the previous step. For example: - -{% tabs %} - -{% tab label="JavaScript" %} -{% code-snippet file="/_code-samples/use-tickets/js/use-tickets.js" from="// Submit TicketCreate" before="// Wait for Validation" language="js" /%} -{% /tab %} - -{% /tabs %} - -{% interactive-block label="Submit" steps=$frontmatter.steps %} - - - -{% loading-icon message="Sending..." /%} - -
- -{% /interactive-block %} - - -### 6. Wait for Validation - -Most transactions are accepted into the next ledger version after they're submitted, which means it may take 4-7 seconds for a transaction's outcome to be final. If the XRP Ledger is busy or poor network connectivity delays a transaction from being relayed throughout the network, a transaction may take longer to be confirmed. (For information on how to set an expiration for transactions, see [Reliable Transaction Submission](../../../concepts/transactions/reliable-transaction-submission.md).) - -{% tabs %} - -{% tab label="JavaScript" %} -{% code-snippet file="/_code-samples/use-tickets/js/use-tickets.js" from="// Wait for Validation" before="// Check Available" language="js" /%} -{% /tab %} - -{% /tabs %} - -{% partial file="/docs/_snippets/interactive-tutorials/wait-step.md" /%} - - -### (Optional) Intermission - -The power of Tickets is that you can carry on with your account's business as usual while you are getting Ticketed transactions ready. When you want to send a transaction using a Ticket, you can do that in parallel with other sending transactions, including ones using different Tickets, and submit a Ticketed transaction at any time. The only constraint is that each Ticket can only be used once. - -{% admonition type="success" name="Tip" %}You can come back here to send Sequenced transactions between or during any of the following steps, without interfering with the success of your Ticketed transaction.{% /admonition %} - -{% interactive-block label="Intermission" steps=$frontmatter.steps %} - - - - -
- -{% /interactive-block %} - - - -### 7. Check Available Tickets - -When you want to send a Ticketed transaction, you need to know what Ticket Sequence number to use for it. If you've been keeping careful track of your account, you already know which Tickets you have, but if you're not sure, you can use the [account_objects method][] to look up your available tickets. For example: - -{% tabs %} - -{% tab label="JavaScript" %} -{% code-snippet file="/_code-samples/use-tickets/js/use-tickets.js" from="// Check Available Tickets" before="// Prepare and Sign Ticketed" language="js" /%} -{% /tab %} - -{% /tabs %} - - -{% interactive-block label="Check Tickets" steps=$frontmatter.steps %} - - -
- -{% /interactive-block %} - -{% admonition type="success" name="Tip" %}You can repeat the steps from here through the end as long as you have Tickets left to be used!{% /admonition %} - -### 8. Prepare Ticketed Transaction - -Now that you have a Ticket available, you can prepare a transaction that uses it. - -This can be any [type of transaction](../../../references/protocol/transactions/types/index.md) you like. The following example uses a no-op [AccountSet transaction][] since that doesn't require any other setup in the ledger. Set the `Sequence` field to `0` and include a `TicketSequence` field with the Ticket Sequence number of one of your available Tickets. - -{% tabs %} - -{% tab label="JavaScript" %} -{% code-snippet file="/_code-samples/use-tickets/js/use-tickets.js" from="// Prepare and Sign Ticketed" before="// Submit Ticketed Transaction" language="js" /%} -{% /tab %} - -{% /tabs %} - -{% admonition type="success" name="Tip" %} -If you don't plan to submit the TicketCreate transaction right away, you should be sure not to set the `LastLedgerSequence` so that the transaction does not expire. The way you do this varies by library: - -- **xrpl.js:** Specify `"LastLedgerSequence": null` when auto-filling the transaction. -- **`rippled`:** Omit `LastLedgerSequence` from the prepared instructions. The server does not provide a value by default. +{% admonition type="info" name="Note" %} +When you're building production-ready software, use an existing account and manage your keys using a [secure signing configuration](../../../concepts/transactions/secure-signing.md). {% /admonition %} -{% interactive-block label="Prepare Ticketed Tx" steps=$frontmatter.steps %} +### 3. Create Tickets -
-

Select a Ticket:

-
-
- -
+Send a [TicketCreate transaction][] and set the `TicketCount` field to the number of Tickets you want to create (up to 250 per account). Each new Ticket reserves a future [Sequence Number][] you can use later. Each Ticket also counts toward your account's [owner reserve](../../../concepts/accounts/reserves.md), which is released when the Ticket is used. Tickets stay reserved on the ledger until you consume them, regardless of any other transactions your account sends. -{% /interactive-block %} - - -### 9. Submit Ticketed Transaction - -Submit the signed transaction blob that you created in the previous step. For example: +Submit the transaction and wait for validation. For example, to create 10 Tickets: {% tabs %} - {% tab label="JavaScript" %} -{% code-snippet file="/_code-samples/use-tickets/js/use-tickets.js" from="// Submit Ticketed Transaction" before="// Wait for Validation (again)" language="js" /%} +{% code-snippet file="/_code-samples/use-tickets/js/use-tickets.js" from="// Create Tickets" before="// Check Available Tickets" language="js" /%} +{% /tab %} +{% tab label="Python" %} +{% code-snippet file="/_code-samples/use-tickets/py/use-tickets.py" from="# Create Tickets" before="# Check Available Tickets" language="py" /%} +{% /tab %} +{% tab label="Go" %} +{% code-snippet file="/_code-samples/use-tickets/go/main.go" from="// Create Tickets" before="// Check Available Tickets" language="go" /%} {% /tab %} - {% /tabs %} -{% interactive-block label="Submit Ticketed Tx" steps=$frontmatter.steps %} +{% admonition type="info" name="Note" %} +A transaction is not final until it is validated by [consensus](../../../concepts/consensus-protocol/index.md), which typically occurs 4-7 seconds after submission. The submit-and-wait call above (`submitAndWait` in xrpl.js, `submit_and_wait` in xrpl-py, `SubmitTxAndWait` in xrpl-go) blocks until validation completes, so the validated result is already available. - -
+For production code that needs to handle longer waits or transaction expiration, see [Reliable Transaction Submission](../../../concepts/transactions/reliable-transaction-submission.md). +{% /admonition %} -{% /interactive-block %} +### 4. Check available Tickets +To send a Ticketed transaction, you need a Ticket Sequence number. Use the [account_objects method][] to list your Tickets. See the method's [Response Format](../../../references/http-websocket-apis/public-api-methods/account-methods/account_objects.md#response-format) for the response shape. -### 10. Wait for Validation +{% tabs %} +{% tab label="JavaScript" %} +{% code-snippet file="/_code-samples/use-tickets/js/use-tickets.js" from="// Check Available Tickets" before="// Use a Ticket" language="js" /%} +{% /tab %} +{% tab label="Python" %} +{% code-snippet file="/_code-samples/use-tickets/py/use-tickets.py" from="# Check Available Tickets" before="# Use a Ticket" language="py" /%} +{% /tab %} +{% tab label="Go" %} +{% code-snippet file="/_code-samples/use-tickets/go/main.go" from="// Check Available Tickets" before="// Use a Ticket" language="go" /%} +{% /tab %} +{% /tabs %} -Ticketed transactions go through the consensus process the same way that Sequenced transactions do. +You can repeat the next step as long as you have unused Tickets. -{% partial file="/docs/_snippets/interactive-tutorials/wait-step.md" variables={label: "Wait Again"} /%} +### 5. Use a Ticket + +Now that you have a Ticket available, you can use it in a transaction. This can be any [type of transaction](../../../references/protocol/transactions/types/index.md). You can use Tickets in any order, but each can only be used once. For the multi-signing variant, see [With Multi-Signing](#with-multi-signing) below. + +{% admonition type="info" name="The Ticket pattern" %} +For any transaction that uses a Ticket, set the `Sequence` field to `0` and include a `TicketSequence` field with one of your available Ticket Sequence numbers. +{% /admonition %} + +The following example uses an [AccountSet transaction][] with no fields set, making it a no-op that requires no setup. Ticketed transactions go through the same [consensus](../../../concepts/consensus-protocol/index.md) process as Sequenced transactions. + +{% tabs %} +{% tab label="JavaScript" %} +{% code-snippet file="/_code-samples/use-tickets/js/use-tickets.js" from="// Use a Ticket" language="js" /%} +{% /tab %} +{% tab label="Python" %} +{% code-snippet file="/_code-samples/use-tickets/py/use-tickets.py" from="# Use a Ticket" language="py" /%} +{% /tab %} +{% tab label="Go" %} +{% code-snippet file="/_code-samples/use-tickets/go/main.go" from="// Use a Ticket" language="go" /%} +{% /tab %} +{% /tabs %} + +After the transaction is validated, the Ticket is consumed and removed from the ledger. To verify, re-run step 4, and the Ticket you used should no longer appear in the result. + +{% admonition type="success" name="Tip" %} +You can use this same pattern to cancel an unused Ticket — just send a no-op AccountSet using the Ticket you no longer need. +{% /admonition %} ## With Multi-Signing -One of the main use cases for Tickets is to be able to collect signatures for several [multi-signed transactions](../../../concepts/accounts/multi-signing.md) in parallel. By using a Ticket, you can send a multi-signed transaction as soon as it is fully signed and ready to go, without worrying about which one will be ready first. +Reserve a Ticket for each [multi-signed transaction](../../../concepts/accounts/multi-signing.md) to hold its slot while you collect signatures. Then submit each transaction as soon as its signatures are complete, in any order. -In this scenario, [step 8, "Prepare Ticketed Transaction"](#8-prepare-ticketed-transaction) is slightly different. Instead of preparing and signing all at once, you would follow the steps for [sending any multi-signed transaction](../../best-practices/key-management/send-a-multi-signed-transaction.md): first prepare the transaction, then circulate it among trusted signers to collect their signatures, and finally combine the signatures into the final multi-signed transaction. +In this scenario, [step 5: Use a Ticket](#5-use-a-ticket) becomes a multi-step process: prepare the transaction, circulate it among signers, and combine their signatures. See [Send a Multi-Signed Transaction](../../best-practices/key-management/send-a-multi-signed-transaction.md) for more details. -You could do this in parallel for several different potential transactions as long as each one uses a different Ticket. +For complete working examples that combine Tickets and multi-signing, see `use-tickets-multisig.js` (JavaScript) or `use-tickets-to-multisign.py` (Python) in the [code samples directory](https://github.com/XRPLF/xrpl-dev-portal/tree/master/_code-samples/use-tickets/). A Go variant isn't currently available. +You can prepare multiple multi-signed transactions simultaneously, each using a different Ticket. + +{% admonition type="success" name="Tip" %} +For this scenario, omit the `LastLedgerSequence` field so that the transaction does not expire while you collect signatures. How you do this varies by library: + +- **xrpl.js:** Specify `"LastLedgerSequence": null` when auto-filling the transaction. +- **xrpl-py:** Set `last_ledger_sequence=None` on the transaction. +- **xrpl-go:** Leave the field unset before signing. +- **`rippled` directly:** Omit the field from the prepared instructions. The server doesn't provide a default. +{% /admonition %} ## See Also - **Concepts:** - [Tickets](../../../concepts/accounts/tickets.md) - [Multi-Signing](../../../concepts/accounts/multi-signing.md) + - [Reliable Transaction Submission](../../../concepts/transactions/reliable-transaction-submission.md) - **Tutorials:** - [Set Up Multi-Signing](../../best-practices/key-management/set-up-multi-signing.md) - - [Reliable Transaction Submission](../../../concepts/transactions/reliable-transaction-submission.md) + - [Send a Multi-Signed Transaction](../../best-practices/key-management/send-a-multi-signed-transaction.md) - **References:** - [account_objects method][] - - [sign_for method][] - - [submit_multisigned method][] - [TicketCreate transaction][] - - [Transaction Common Fields](../../../references/protocol/transactions/common-fields.md) + - [Transaction Common Fields][common fields] {% raw-partial file="/docs/_snippets/common-links.md" /%}